Chapter 15. An Example Module

15.1. Hello World Widget

15.1. Hello World Widget

This section demonstrates the creation of a module that provides a widget that displays "Hello World". To create the required components, perform the following steps. For further details about specific topics, refer to the linked documentation.

  1. Create a skeletal module structure in the folder sites/all/modules:

  2. Create the hello/module.ini module definition file:

    version                     = 1.0
    description                 = A module that prints out Hello World.
    tags                        = hello, world
    name                        = Perforce Software
    email                       =
    url                         =
    all.href                    = hello.css
    world.label                 = Hello
    world.description           = This demo widget says hello.
    world.controller            = widget
    world.defaults.hellotext    = Hello, World

    The first eight lines of this file specify its version, provide a description, list the tags used for filtering modules, and identify the maintainer of the module.

    The [stylesheets] section includes the CSS stylesheet hello.css in the generated HTML to ensure that the widget is styled correctly.

    The [widgets] section specifies that this module provides a widget identified as world and labelled as Hello, with an appropriate description. It also specifies that the controller supporting this widget is named widget, which translates to the controller filename WidgetController.php. Finally, it specifies that the field name hellotext has the default value of Hello, World.

    At this point, the module is listed on the Manage Modules page, though it doesn't do anything yet.

    For details about module configuration details, see Section 14.1, “Configuration File - module.ini.

  3. Create the hello/controllers/WidgetController.php file:

    class Hello_WidgetController extends P4Cms_Widget_ControllerAbstract
         * Hello World dummy prep to demonstrate setup for our view script.
        public function indexAction()
            $this->view->response = array(
                'text' => $this->getOption('hellotext')
         * Get config sub-form to present additional options when
         * configuring a widget of this type.
         * @param   P4Cms_Widget            $widget  the widget instance being
         *                                           configured.
         * @return  Zend_Form_SubForm|null  the sub-form to integrate into the
         *                                  default widget config form or null
         *                                  for no sub-form.
        public static function getConfigSubForm($widget)
            return new Hello_Form_Widget;

    This controller responds to requests made to the widget, using the indexAction method. It retrieves the option hellotext from its configuration (which is specified in the form) and assigns it to a view variable named response.

    The getConfigSubForm methods provides a sub-form to assist with configuring modules.

    For more details about controllers, see Section 14.4, “Controllers”.

  4. Create the hello/forms/Widget.php configuration sub-form file:

    class Hello_Form_Widget extends P4Cms_Form_SubForm
         * Defines the elements that make up the config form.
         * Called automatically when the form object is created.
        public function init()
            // add a required field to collect some text
                'text', 'hellotext',
                    'label'         => 'Hello Required Text',
                    'required'      => true,
                    'description'   => 'Enter some text to display here.'

    The preceding are form elements. All HTML form input types are permissible. For details about the options for building your elements, see the Zend Form documentation.

  5. Create the hello/resources/hello.css CSS file:

    #region-features .widget-container .widget.widget-hello-world {
        border: 2px solid red;
        margin: 6px;
        padding: 2px 4px;
    .widget-hello-world span {
        font-weight: bold;

    CSS classes are inserted into your module's output by Perforce Chronicle based on the contents of hello/module.ini.

    The CSS class widget-hello-world is composed of three parts:

    • widget - identifies this as a widget class
    • module - the module providing this widget, in this case hello.
    • identifier - the widget's identifier, as specified in the module configuration file, in this case world.
    [Note] CSS Specifier

    The specifier beginning with #region-features is included to ensure correct styling in any of the default theme's regions. Normally, theme styles override module styles.

    For more details about resources, see Section 11.2, “Resources”. Resources for modules are identical to resources for themes, but are stored in the module's folder structure.

  6. Create the hello/views/scripts/widget/index.phtml view script:

    <? foreach ($this->response as $name => $text) : ?>
        <span>TEXT: <?= $text ?></span><br/>
    <? endforeach; ?>

    The $this object in the view script is the direct Zend_View object that is referenced and populated in the controller. In this case, only the response array is used. However, variables, other arrays, and methods in the Zend_View object are also available and in scope.

    For more information, see the Zend_View documentation.

  7. Try the new module!

    You now have a functional module that you can enable in Chronicle. To make it available to the page editor, perform the following steps:

    1. Log into your instance of Chronicle.
    2. To enable the Hello module, follow the instructions in Section 19.3, “Enabling and Disabling Modules”.
    3. Click Back to Website.
    4. Click Widgets.
    5. Click a plus icon in one of the available regions.
    6. Choose the Hello widget from the list of widgets. The Configuration dialog is displayed, containing the sub-form.
    7. Enter the requested values and click Save. Chronicle displays a red-bordered box, containing TEXT: plus the text you entered in the sub-form.

    Congratulations! You have successfully created your first module for Chronicle.

Perforce Chronicle - Release: 2012.2/486814