+1 571-297-6383 | info@sonjara.com

Chapter 7: Events

Fakoli CMS strives to minimize the interdependence of components so that a missing or disabled component won't break the application. This decoupling is achieved through the use of event handling.

An event is a call that is not user-initiated but rather internal to the CMS pipeline. When pages execute, they can fire an event, sending a call to components that an event is taking place. Components that want to participate in that event would register for the event in their manifest.inc file. With their registration, they provide a callback function for gathering the data in the prescribed format as the event requires.

For example, the "Page" drop-down list on the Menu Item Form page is shown below. The data in this drop down is retrieved using the event called "EnumerateItems."

CMS Page Event

The drop-down list is added to the menu item form using the Fakoli field renderer CMSItemSelectFieldRenderer which is instantiated with the call:

$identifierSelect = new CMSItemSelectFieldRenderer($form, "identifier", "Page", null);

where $form is the script's AutoForm class object, "identifier" is the name of the field we want to display in the drop-down list, and "Page" is the label we want to appear on the form. The final parameter is null because we have no callback function for the onchange event.

The class CMSItemSelectFieldRenderer gathers all the pages for the drop down by putting out a call to components that subscribe to the event "Enumerate Items" as follows:

$itemsByType = ComponentManager::fireEvent("EnumerateItems", $itemsByType);

In a default Fakoli site, the following components are registered with this event in their manifest.inc file:

  • blog
  • calendar
  • component
  • image
  • link_picker
  • page

The code in the "page" component manifest that subscribes it to the EnumerateItems event follows:

static function subscribeToEvents()
	return array("EnumerateItems" => array(PageManager, enumeratePages));

The above example shows that the page component is only subscribed to one event but any number of event subscriptions can be added to the array. The subscription states that when EnumerateItems is fired, that the caller should execute the static function enumeratePages within the class PageManager. The callback for an event must be a static function. The function PageManager::enumeratePages follows:

static function enumeratePages(&$items)
	$pages = Query::create(Page, "ORDER BY page_title")->execute();
	$items["Pages"] = $pages;
	return $items;

The function returns the items to the CMSItemSelectFieldRenderer in the required format.

Once all items are retrieved, the CMSItemSelectFieldRenderer loops through all items to create an array for the drop down.

Using the event model, we offload the specifics of data retrieval and presentation to the components that own and manage them. When a component is removed or disabled, the CMSItemSelectFieldRenderer would no longer present its pages. When a new component is added and subscribes to the EnumerateItems event, then the CMSItemSelectFieldRenderer will include its pages.

Chapter 8: Sections » « Chapter 6: Actions