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

hello/
    controllers/
    forms/
    resources/
    views/
        scripts/
            widget/

Create the hello/module.ini module definition file:

version                     = 1.0
description                 = A module that prints out Hello World.
tags                        = hello, world

[maintainer]
name                        = Perforce Software
email                       = support@perforce.com
url                         = http://www.perforce.com/

[stylesheets]
all.href                    = hello.css

[widgets]
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”.

Create the hello/controllers/WidgetController.php file:

<?php
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”.

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

<?php
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
        $this->addElement(
            'text', 'hellotext',
            array(
                '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.

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

.widget-hello-world,
#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:

	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.

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.

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:

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