Plugin skeleton

The following is the standard for plugin structure in Elgg as of Elgg 2.0.

Example Structure

The following is an example of a plugin with standard structure. For further explanation of this structure, see the details in the following sections. Your plugin may not need all the files listed

The following files for plugin example would go in /mod/example/

actions/
    example/
        action.php
        other_action.php
classes/
    VendorNamespace/
        PluginNamespace/
            ExampleClass.php
languages/
    en.php
vendors/
    example_3rd_party_lib/
views/
    default/
        example/
          component.css
          component.js
          component.png
        forms/
            example/
                action.php
                other_action.php
        object/
            example.php
            example/
                context1.php
                context2.php
        plugins/
            example/
                settings.php
                usersettings.php
        resources/
            example/
                all.css
                all.js
                all.php
                owner.css
                owner.js
                owner.php
        widgets/
            example_widget/
                content.php
                edit.php
elgg-plugin.php
CHANGES.txt
COPYRIGHT.txt
INSTALL.txt
LICENSE.txt
README.txt
composer.json

Required Files

Plugins must provide a composer.json file in the plugin root in order to be recognized by Elgg.

Therefore the following is the minimally compliant structure:

mod/example/
    composer.json

Actions

Plugins should place scripts for actions an actions/ directory, and furthermore should use the name of the action to determine the location within that directory.

For example, the action my/example/action would go in my_plugin/actions/my/example/action.php. This makes it very obvious which script is associated with which action.

Similarly, the body of the form that submits to this action should be located in forms/my/example/action.php. Not only does this make the connection b/w action handler, form code, and action name obvious, but it allows you to use the elgg_view_form() function easily.

Text Files

Plugins may provide various *.txt as additional documentation for the plugin. These files must be in Markdown syntax and will generate links on the plugin management sections.

README.txt

should provide additional information about the plugin of an unspecified nature

COPYRIGHT.txt

If included, must provide an explanation of the plugin’s copyright.

LICENSE.txt

If included, must provide the text of the license that the plugin is released under.

INSTALL.txt

If included, must provide additional instructions for installing the plugin if the process is sufficiently complicated (e.g. if it requires installing third party libraries on the host machine, or requires acquiring an API key from a third party).

CHANGES.txt

If included, must provide a list of changes for their plugin, grouped by version number, with the most recent version at the top.

Plugins may include additional *.txt files besides these, but no interface is given for reading them.

Pages

To render full pages, plugins should use resource views (which have names beginning with resources/). This allows other plugins to easily replace functionality via the view system.

Note

The reason we encourage this structure is

  • To form a logical relationship between urls and scripts, so that people examining the code can have an idea of what it does just by examining the structure.

  • To clean up the root plugin directory, which historically has quickly gotten cluttered with the page handling scripts.

Classes

Elgg provides PSR-0 autoloading out of every active plugin’s classes/ directory.

You’re encouraged to follow the PHP-FIG standards when writing your classes.

Note

Files with a “.class.php” extension will not be recognized by Elgg.

When organizing you classes Elgg does not require a specific structure. Use what works best for your plugin but keep in mind that it should be easy to read, funtionality should be easy to find and having seperated functions into different classes will improve maintainability and testability.

Vendors

Included third-party libraries of any kind should be included in the vendors/ folder in the plugin root. Though this folder has no special significance to the Elgg engine, this has historically been the location where Elgg core stores its third-party libraries, so we encourage the same format for the sake of consistency and familiarity.

Views

In order to override core views, a plugin’s views can be placed in views/, or an elgg-plugin.php config file can be used for more detailed file/path mapping. See Views.

Javascript and CSS will live in the views system. See JavaScript.