The App Directory Structure

An app is a collection of folders and files contained within the inc/app folder of a Sitellite installation.  Each folder therein is a separate app.  The core folders and files within an app are as follows:

boxes

The boxes folder contains the main PHP scripts that together comprise the functionality of the app.  A box is a folder within the boxes folder which contains at least an index.php file, and optionally access.php and settings.php files as well.

The index.php file is the PHP script that the box runs when called by the App Loader.  It is called from within the App Loader namespace, so it does not have direct access to global variables and objects, but it can import the ones it needs.  It does have two arrays defined within its namespace which are $parameters and $box.

$parameters contains a list of the parameters passed to the box.  $box contains the properties of that box, such as the context in which it is being called (ie. as an action, meaning directly from the URL, or inline, meaning embedded within a web page in the Sitellite Web Pages collection, or normal, meaning from another box or template.

When a box is called as an action, the $parameters array contains an exact list of the variables from the URL (duplicated in the global $cgi object), and from any other context, it contains only the parameters explicitly passed to the box.  This is explained in further detail in my article "Sitellite Boxes".

The access.php file contains access control settings for a box or set of boxes.  Its values are explained in the above mentioned article as well.

The settings.php file contains settings for a box, such as its name, author, version number, a description of its purpose, and any parameters it accepts.  The parameter list contained here will be used in Sitellite 4.2 to auto-generate forms to insert embedded boxes into web pages, via a Box Chooser button in Xed (the WYSIWYG editor).  The values contained herein are also discussed in totality in the "Sitellite Boxes" article.

The access.php and settings.php files are in INI format, which Sitellite uses a lot, because it is easy to parse (parse_ini_file() anyone?), easy to write, easy to understand without having to learn a whole new configuration format (Sendmail, Apache, OpenLDAP anyone?), still flexible enough to express most configuration needs naturally, and also nice and short.

I believe this is one of Sitellite's strong points as a development platform compared to other PHP-based systems, which often choose PHP itself as a configuration format, or worse, XML.  Nobody needs the overhead of parsing an entire XML document every page request (although you could serialize and cache it...), and nobody should have to sift through PHP code to make a configuration change.  So instead with Sitellite, we thought it was best to build on the unique strengths of PHP, and use its built-in parse_ini_file() function.  Anyway, I digress.

conf

The conf folder contains all of the configuration files for your app, of which there are two by default (you can add custom configuration files as needed all you like).  These two files are config.ini.php, which contains information about your app (name, author, description, and some basic information for the App Loader), and properties.php, which is used to store properties that are used repeatedly throughout your app (ie. a list of countries for use in select boxes).

The config.ini.php file is, predictably, in the INI format as well, however, the properties.php file is an ordinary PHP file, but can easily include additional INI formatted conf files.

data

Miscellaneous data goes here.  For example, file uploads from users.  Handy to have, often used, we figured we might as well standardize the name.

docs

This is where both the end-user help files as well as the API documentation live.  Both of these can be generated via the AppDoc app from the Sitellite Control Panel.  Just make sure Sitellite has write permissions to your docs folder.

End-user help files are accessible via the help app, which is linked to from the "Help" link in the Sitellite top bar.  The end-user help is multi-lingual and searchable, making it one of the most powerful built-in help solutions of any CMS.

The API documentation is accessible from the same place in AppDoc that it is generated from.  The API documentation for each app has a similarly themed UI to Sitellite itself, making the API browsing a seamless experience.

Sitellite's core API documentation is available separately however, at http://www.sitellite.org/docs/

forms

Forms are very much like boxes, including having the index.php, access.php, and settings.php files.  The difference is that within each form you define a class that extends the MailForm class, which is your form object and handles both drawing and handling your form.  The settings.php file in this case is used primarily to define the form widgets you want to use.  For more information about writing forms, see my article "MailForm: The Sitellite Form API".

html

This is where your app's templates live.  Template files are usually in the SimpleTemplate format, because they usually don't need the previewability offered by XT, and end in the extension .spt  These templates are called from within your boxes to format the resulting data from a box call.

install

The install folder contains any installation procedures and files for your app.  Mainly, this includes the install-mysql.sql file to define any database tables used by your app, a changes.txt file to describe changes between versions of your app (a change log), any collection definitions which would be copied into the inc/app/cms/conf/collections folder, any upgrade SQL scripts, scheduled tasks for copying into the inc/app/scheduler/tasks folder, and instructions (an INSTALL file).

lang

Here is where the various translations for your app live.  These would also be added via the AppDoc app instead of by hand, so make sure your lang folder is writeable by Sitellite.

lib

The lib folder is where any classes you define as part of your app should be placed.  In order to generate API documentation for them, make sure you include proper PHPDoc comments.

pix

This is where any image files used by your app should be stored.  Typically, this will include at least an icon.gif file, which is used by the Sitellite Control Panel to link to your app.

That's pretty much it.  You should now have a better understanding of the structure of an app, which will make it easier to read through existing apps for examples, as well as for writing your own apps now.  Be sure to check out my article "Sitellite Boxes" for an introduction to writing boxes for your app, which are the basic building blocks of an app.

Page 1: Sitellite is not just a great CM...
Page 2: The App Directory Structure

Home   More Applications Stories