docs/PHPDoc and the written system documentation reside in this directory. The generated API documentation (from code comments) is stored in a module html directory so it can be accessed through the webserver. I intend to convert to an SGML documentation source shortly.
user/conf/This directory contains all of the systemic configuration files for binarycloud:
defined_constants.confis loaded at startup, and defines all of the necessary path and configuration constants. Be very familiar with this file.file_permissions.confcontrols access to files in htdocs. If a file in htdocs isn’t listed here, it won’t be executed. This file also contains an array of directory names, so breadcrumbs and other apps can use a ‘nice’ looking string instead of a path.prepend.inc– it all starts with the prepend. Our prepend file loads the execution timer, and defined_constants. Based on the settings in defined_constants it then loads prepend_exclude.conf, and checks to see if the file being executed in htdocs/ is excluded from binarycloud. If it is not, prepend then loads debugging, our error handler, error codes, authentication, and permissions.prepend_exclude.confcontains an array of files in htdocs which should not be controlled by binarycloud.append.incstops the execution timer, and prints the execution time – it uses append_exclude.conf in the same way that prepend.inc does – we set it up this way because we can foresee the need to append more logic.append_exclude.confis exactly the same as prepend_exclude.conf, but for the appended logic.php.ini– we like to keep it here, but it isn’t strictly necessary.
user/db/schema/This is where all of the xml schema files for the database are stored. Metabase uses a simple xml format for doing schema definition, which greatly simplifies the task of creating database tables. This directory also contains files with the .before extension – these files are extremely important. When you install a schema file in a database, Metabase writes out a .before file, which is a copy of your current schema definition file. When you change the schema file, and install it in the database a second time, Metabase checks to see if there is a .before file. If the .before file is present, Metabase updates the database table. If no .before file is present, Metabase tries to create the table. If the table doesn’t exist in the database, the table is created – but if the table already exists, and there is no .before file present, you’ll get errors.
user/db/objects/This is where all the data access objects are stored. As a general rule, we like to have one .schema file in
user/db/schema/ for every table, and one dbobject for every table. However, there are no hard-and-fast rules associated with querying multiple tables from a dbobject. Database access objects are central to the binarycloud system design: because we use Vdbobjects to talk to the database, we can change abstraction layers, revise sql, etc., without ever having to touch application logic.
user/db/dump/This directory is where db dump files go. Metabase can extract all of the data from a database table, and spit it out into an XML file. That XML file can be loaded back up into another database.
user/mod/This is where 80% of your work will take place – the directory where modules are stored.
A module is a piece of logic, usually fairly simple (we like to keep complex logic in libs)
that presents some markup to the client. All modules are stored in subdirectories. An
“application” is a group of associated modules that share the same markup templates
(the knowledgebase app is a good example of this concept).
If you have a look in a few of the module directories you’ll notice modules are always pure
logic. They include whatever markup they need, and populate that markup with data, but they
never contain markup. If markup was integrated with the module logic, changing the look and
feel of a module would be nightmarish, and upgrading to a new version would be nearly
impossible. With external template files, we can tell the module to use a different markup
template depending on the context in htdocs. For example, if you have sections of your website
that use different colors and graphics, but you need to use the same module in three different
locations, you can make three markup templates and pass the right template to the module at
runtime.
logic. They include whatever markup they need, and populate that markup with data, but they
never contain markup. If markup was integrated with the module logic, changing the look and
feel of a module would be nightmarish, and upgrading to a new version would be nearly
impossible. With external template files, we can tell the module to use a different markup
template depending on the context in htdocs. For example, if you have sections of your website
that use different colors and graphics, but you need to use the same module in three different
locations, you can make three markup templates and pass the right template to the module at
runtime.
user/tmpl/This contains an arbitrary hierarchy of markup, which is globally accessible. There is no particular structure imposed, but it’s a good idea to keep things in directories. Markup that is stored in module directories should be unique to that module. If you think the markup will be used by more than one module, put it here.
