Elements

Elements are dynamically generated snippets of HTML inserted into the pages generated by the Haplo web application. They’re similar to ‘widgets’ and ‘gadgets’ in other systems.

The primary uses of Elements are to build the application home page, and to allow plugins to display extra information on object pages. For example, in the default schema, the Organisation type is configured to use an Element to display a list of people who work for an organisation on the organisation’s page.

Plugins declare the Elements they implement, then the application is configured to use them in the System management web interface. By convention, plugins include the plugin name in the Element name, for example, example_plugin:home, to avoid two Plugins implementing an Element with the same name.

When a plugin is asked to render an Element, it returns some HTML and a title for that Element. The title is displayed above the HTML in a style appropriate for the context. If the title is an empty string, the title is omitted.

Implementing an Element

Two hooks are used to implement Elements, hElementDiscover and hElementRender. However, the JavaScript API provides an interface which is easier to use, through the element() function in the Plugin interface.

Here’s a simple example:

P.element("test", "Simple test element",
    function(L) {
        L.render({
            title: "Simple Element",
            example: "Hello World!"
        });
    }
);

This will define an element named example_plugin:test. The title is "Simple Element", and the HTML for the element will be obtained by rendering the template named test.

The final argument to the element() function is an anonymous function used to render the Element. When an Element needs to be displayed, this renderer function is passed a PluginElementRenderer object to provide information about the context in which the Element is being rendered. The function is called with this set to the Plugin object.

The render() function is very similar to the rendering support for request handling. The values for the title and example keys in the view object will be available to the template.

Links on home page

A common use of Elements is to include links to Plugin functionality on the application home page. The renderLinks() function is provided to make this easier.

P.element("home", "Home page links for Example Plugin",
    function(L) {
        L.renderLinks([
                ['/do/example/action_one', 'Action One'],
                ['/do/example/action_two', 'Action Two']
            ],
            "Example Plugin"    // Title of Element
        );
    }
);

When this Element is added to the home page, it will display styled links to ‘Action One’ and ‘Action Two’ under the heading ‘Example Plugin’.