Click here to go back to the previous section: Getting Started

Please note that this documentation relates to Vanilla 1

All pages in Vanilla follow a similar order of execution, as outlined below:

1. Include Configuration Array & Global Constants
2. Initialize the Page
3. Instantiate Context Object
4. Define the Language
5. Instantiate Page Object
6. Define Generic Page Controls
7. Include Enabled Extensions
8. Validate User Permissions for the Current Page
9. Further define Head, Menu & Panel Controls for Page-Specific Purposes
10. Instantiate & Define Page-Specific Controls
11. Fire All Page Object Events

The configuration settings & global constants can be located in the appg/settings.php file. It is worth noting that the “appg” folder is short form for “application global”, implying that any files in the appg folder will likely be included on all pages of the application.

This file should *never* be edited by anyone other than the Vanilla devlopment team. The final line of this file is an include of conf/settings.php. The purpose of this is to allow you to override any default settings contained in appg/settings.php in your custom conf/settings.php file. ONLY change configuration settings in the conf/settings.php file. As you develop extensions, if you need to add a configuration setting, add it to the conf/settings.php file. This file will never be overwritten - even when the user upgrades to newer versions of Vanilla.

At this point the page will include one of the three initialization files depending on the page’s purpose: init_people.php, init_vanilla.php or init_ajax.php. These three different initialization includes are used to load core libraries that will be used throughout the execution of the page and instantiate any objects required for page processing.

All files within the ajax folder use the appg/init_ajax.php file. This initialization file, unlike the others, does not instantiate a Page object since it will never be rendered to the screen. Ajax files are used to set or retrieve small bits of data as dynamic actions are performed in Vanilla. If you write an extension that performs any kind of ajax processing, this is the initialization file you should use when those dynamic actions are performed.

The people.php file in the root of Vanilla is the only file that uses the appg/init_people.php file. This initialization file is custom to the sign in, sign up, and password retrieval forms.

Any other pages in Vanilla will use the appg/init_vanilla.php initialization file.

Once more, as an extension developer you should never touch these initialization files, but you should be aware of what they do and how they do it, as you’ll see below.

The context object is instantiated within each of the initialization files. It is, by far, one of the most important objects in Vanilla. It is a central object that is included and passed through every single control in Vanilla. When the Context object is instantiated, it’s constructor will:

• Initialize all properties & set some default values where applicable.
• Add the default “Text” StringFormatter to the StringManipulator object.
• Create a new MySql implementation of the Database object and open it’s connection to MySql.

It is definitely worth your time to open up this class and take a look around. The class file can be found in library/Framework/Framework.Class.Context.php

After the context object has been instantiated within the initialization file, Two very important things take place:

1. The database structure is added to the context object. This structure definition can be found in the appg/database.php file. The file contains two arrays, one which defines all of the tables used by Vanilla, and another which defines all of the columns within those tables. These are associative arrays, and they allow you to customize your tables and columns in Vanilla in any way you wish.
2. Now that the tables have been defined, the StartSession method of the Context is called. This method will instantiate a session object: creating a PHP session, checking for autologin cookies, and querying the database for information about the user viewing the page.

Depending on the LANGUAGE configuration variable (the default is “English”), the defined language file will now be included. The language file can be found in languages/Language_Name/definitions.php and contains codes and their translations for the defined “Language_Name”. By default Vanilla comes with English. Other language definitions are available online through http://lussumo.com/addons.

The Page object is a very simple object that gathers controls into a collection and renders them as particular events are thrown. The Page object’s events are defined in the appg/settings.php file (and can be overridden in the conf/settings.php file) as an array. By default, there are three events in the Page object and they are thrown in the following order:

1. Page_Init
2. Page_Render
3. Page_Unload

The general rule for the Page’s events is that if you create a control that needs to be rendered to the screen, it should be added to the Page_Render event. If you create a control that doesn’t need to render to the screen, it should be added to the Page_Init event.

99% of the time you will be adding controls to the render event, and we’ve created a method in the Page object to do this:

$Page->AddRenderControl($Control, $ControlPosition);

The $ControlPosition variable is meant to imply the order in which your control should be rendered in relation to the other controls in the page. The page controls (Head, Menu, Panel, etc) are all added to specific numeric positions as defined by CONTROL_POSITION configuration variables. These control positions are defined as follows:

$Configuration['CONTROL_POSITION_HEAD'] = '100';
$Configuration['CONTROL_POSITION_MENU'] = '200';
$Configuration['CONTROL_POSITION_BANNER'] = '200';
$Configuration['CONTROL_POSITION_PANEL'] = '300';
$Configuration['CONTROL_POSITION_BODY_ITEM'] = '400';
$Configuration['CONTROL_POSITION_FOOT'] = '500';
$Configuration['CONTROL_POSITION_PAGE_END'] = '600';

To see which control position a particular control uses, view the source of that page. For example, the index.php page adds it’s controls to the page like so:

$Page->AddRenderControl($Head, $Configuration['CONTROL_POSITION_HEAD']);
$Page->AddRenderControl($Menu, $Configuration['CONTROL_POSITION_MENU']);
$Page->AddRenderControl($Panel, $Configuration['CONTROL_POSITION_PANEL']);
$Page->AddRenderControl($DiscussionGrid, $Configuration['CONTROL_POSITION_BODY_ITEM']);
$Page->AddRenderControl($Foot, $Configuration['CONTROL_POSITION_FOOT']);
$Page->AddRenderControl($PageEnd, $Configuration['CONTROL_POSITION_PAGE_END']);

So, if you had a control that you wanted to place between the $Menu and the $Panel, you could add your control like this:

$Page->AddRenderControl($MyControl, $Configuration['CONTROL_POSITION_MENU'] + 1);

By now you’re definitely wondering what a Control is. A control in Vanilla is a simple object with a couple of standard methods and properties. Extension writers can extend the control class to write controls of their own. There are two different types of base controls:

Any controls that are written as custom controls must be extended from one of these two control types (or must implement the common interface). The class definitions for these controls can be found in library/Framework/Framework.Class.Control.php.

All controls written in Vanilla have been extended from one of these two control types. At this point in the order-of-execution, the following controls have are instantiated by the app/init_vanilla.php file:

• Head
• Menu
• Panel
• Foot
• PageEnd

Once these controls have been instantiated, the appg/init_vanilla.php file adds the basic javascript and css files to the Head control, and adds the standard tabs to the menu control.

When an extension is enabled by the “Settings Tab” > “Manage Extensions” form, a line is added to the conf/extensions.php file to include that extension-file on all page loads. At this point in the order-of-execution, the conf/extensions.php file is included in the page, so any extensions which have been included in that appg/extensions.php file will be included and parsed by PHP.

At this point the init_*.php files have been completely parsed and we are now looking at the contents of individual forum pages. For example, if you were to open up the index.php file, the next directive to be processed is on line 20:

$Context->Session->Check($Context);

This is a permission check where we make sure that the user viewing the page has a valid session. If the user doesn’t, they are kicked out to the sign-in page.

From this point forward in the order of operations, we get very page specific.

Now that we are in an individual page, we can further define the Generic page controls which were instantiated in the init_*.php file. For example, we define which tab should be highlighted in the menu.

Next we can instantiate the controls specific to this page and perform any operations on them that we need to, and add them to the page object.

Finally, we call the Page object’s FireEvents method. This method will loop through all of the controls now contained within the page object and call the render method on each one. Once this is complete and all controls have been rendered the Context object is unloaded by the page object and all database connections, sessions, and hefty page objects are cleared from memory. The page processing is complete.

Click here to read the next section on developing new extensions: Formatters