example — Plugin demonstrating how to write plugins

Example Plugin

This plugin is meant to demonstrate how to write new plugins for PyCI. It has the following methods:

• HelloWorld: Renders, ‘Hello, world!’ using a basic Mako template that inherits from the theme’s base.mako file.
• jqGridExample: Demonstrates how to use PyCI’s jqGrid helper functions.
• NotificationExample: Demonstrates how to use PyCI’s user notification functions (pop-up and validation messages).

It is highly recommended that you examine the source code of this plugin and its templates in order to better understand how PyCI handles plugins.

class Example

An example plugin.

HelloWorld()

Render a basic page using a Mako template that says ‘Hello, world!’:

@require(has_read('Example'))
def HelloWorld(self):
    page_template = plugin_template(self, "templates/helloworld.mako")
    help=_("<p>This is the example plugin's 'Hello, world!' page.</p>")
    return self.standard_render(
        template=page_template,
        help=help,
        long_name=_('Example Plugin: Hello, world!'),
        description=_("An example plugin for developers (Hello, world!)."),
    )

A couple things are going on in the code above:

@require(has_read('Example'))

The @require() decorator sets the permissions plugin methods. In this example, it requires the user have read permission to the Example plugin.

page_template = plugin_template(self, "templates/helloworld.mako")

This line sets our template to templates/helloworld.mako which exists in our Example plugin directory. The plugin_template() function is pretty much the same as Mako’s lookup_template() function except that it is smart enough to know when a template is inside of a plugin’s zip archive.

return self.standard_render(...

Every subclass of Plugin gets standard_render() for free: It is similar to Mako’s render() function except that it automatically takes care of the following:

• It injects the _() gettext function into the template’s namespace using the proper language settings.
• It injects some standard PyCI variables (plugin_name, plugin_object, and language) into the template namespace.
• All keyword arguments passed to standard_render() other than ‘template’ will get added to your template’s namespace in a dictionary named, “plugin_dict” (more on this later).

Lastly, ‘help’, ‘long_name’, and ‘description’ are special variables used by the plugin_base.mako template that your template will likely inherit from. Try changing them to see where they’re changed on the page.

NotificationExample()

This page demonstrates how to display useful messages within PyCI.

index()

The index() method in any Plugin is called when the user navigates directly to the plugin instead of one of the plugin’s sub-methods. PyCI doesn’t have any navigation elements that would lead a user here but it is a good idea in case the user types in the URL directly like so: http://192.168.1.20/Example/

In this example plugin, index() just calls self.HelloWorld().

jqGridExample()

This example plugin page demonstrates how to use jqGrid.

jqgrid_example_json(rows=None, sidx=None, _search=None, searchField=None, searchOper=None, searchString=None, page=None, sord=None, nd=None)

Returns /etc/hosts in a json format that’s compatible with jqGrid.

notification_test(number)

Returns a success message if ‘number’ is an integer, an error message if not.

This method is used by the NotificationExample() page to display the result from the form submission (by way of an AJAX call using the jQuery Form plugin).

validate_integer(number)

Checks whether or not the passed parameters are integers.

list_etc_hosts()

Returns /etc/hosts as a list of lists. Suitable for things like jqgrid and spreadsheet output