FreePBX API: Modules GUI API

This GUI API is implemented in Modules API version 2. Part of the ApiDocs.

Intro

A file named admin.menuitem.php is used to hold the GUI code (user.menuitem.php for UserPortal). menuitem is the display variable in the URL, and is specified in modules.xml?.

The GUI is made up of a class with the same name as menuitem. Within this class, a funtion is created for each method used (which is controlled by the method variable in the URL, and defaults to "index" if not specified), and that method is called to generate the page.

Hello World Example

A simple hello world module will look as follows:

admin.hello.php

class hello { 
    function index() {
        echo "hello world";
    }
}

A bit more extensive (but preliminary example): GUI Example 1

Magic Methods

A number of "magic" (or special) methods are available. They have a suffix that tells freePBX they have special functionality.

_form()

method_form()

This method will be called, if it exists, and is expected to return a QuickForm object. This is used to create a form.

See QuickForm for further information on creating forms.

Example: ApiModulesGui/Example1

menuitem_form() with menuitem()

freePBX will normally take care of displaying the form. However, if both a menuitem_form() method and menuitem() method exist, menuitem() will be called with a single parameter, containing:

  array(
    'form' => &$form,                  // the QuickForm object
    'formhtml' => $renderer->toHtml()  // the HTML output of the form
  )

menuitem() is then expected to display the form. This allows for advanced processing that takes places after other modules have possibly added more elements to the form.

_process()

method_process($values)

The 'menuitem'_process()method is called when using a _form() method, and the form has been submitted and successfully validated. The controller is expected to process the form (eg, add or update a database entry) and call redirect() to send the user somewhere more approriate. This method should not output anything.

_load()

method_load($id, $form)

The 'menuitem'_load() method is called when using a _form() method, when an id is passed to the page (eg, when editing). The function should load values for the item specified by $id and call $form->setDefaults() (and/or possibly $form->setConstants()) to populate the form.

Note, it may be desirable to use input filtering? to ensure valid data and prevent SQL injection. For example:

   $sql = "SELECT * FROM users WHERE userid = ".input::clean($id,IN_NUMERIC);

_validate()

method_validate($values)

The 'menuitem'_validate() method is called when using a _form() method, when a form is submitted for processing. This method is automatically added as a form validation rule. The purpose is to check things that form field rules can't check on their own, such as checking for duplicate entries in the database or validating values against other tables.

_before() and _after()

'method'_before() 'method'_after()

These methods are displayed before and after (respectivly) the output of the page or form (eg, they can be used with either 'method'() or 'method'_form() )

_filter() not yet implemented

Not 100% sure if this will go in or not, but it executes after everything else.

Hooks

Hooks are implemented as classes, named:

modulename_hook_targetmodule

Hook methods

_form()

method'_form(&$form)

This works similarly to the _form() method in modules, but is passed the quickform object as a parameter.

It can then modify the form using the QuickForm addElement(), insertElementBefore(), elementExists(), getElement(), removeElement(), etc functions. See Creating a basic form in the QuickForm manual for more info.

_before(), _after(), _filter()

These functions work exactly as above, and allow inserting content before/after the page content.

Hook Example

The following hello world example displays at the top of the user page edit form:

class test1_hook_users {
    function edit_before() {
        echo "Hello world!<br />"
    }
}