Making Your First Module - xenocrat/chyrp-lite GitHub Wiki

Modules are the most powerful and general-purpose of the four types of extensions, but a module does not have to be complicated for it to be useful. This article will teach you how to make a very simple module that greets the user with a message when they log in to your site.

The Basics

The bare minimum required to make a functioning module is this: a sub-directory located in your installation's modules directory containing a PHP file with a matching name. For this example, we will create a directory named my_awesome_module that contains a file named my_awesome_module.php. The contents of the file are as follows:

<?php
    class MyAwesomeModule extends Modules {
        public function user_logged_in() {
            Flash::notice(__("Hello!", "my_awesome_module"));
        }
    }

The most important thing to note in this file is that it extends the Modules class with a class named after the file and its containing directory (using camelization rules). The class has only one public function; this is a trigger responder that will be executed when the user logs in and the call "user_logged_in" is triggered. The function uses Chyrp Lite's Flash class to display a notice to the user; the notice is defined using the __() helper that will translate the greeting into the blog's chosen language if our module has a suitable translation file installed (more on that below).

Here's the structure of our module:

• modules
  • my_awesome_module
    • my_awesome_module.php

That's all we need to make the most basic module, but we can add some niceties.

The Niceties

We can add a file named info.php to our module's directory. This is a PHP file that contains metadata about our module, some of which will be displayed when the module is listed in the admin console. The contents are as follows:

<?php
return array(
    "name"          => __("My Awesome Module", "my_awesome_module"),
    "url"           => "http://example.com/",
    "version"       => "1.0",
    "description"   => __("Greetings, user!", "my_awesome_module"),
    "author"        => array(
        "name"      => "Anonymous Coward",
        "url"       => "http://myhomepage.com/"
    )
);

This file is particularly useful if you plan to distribute your module for other people to use. The other nicety that can be useful for distribution is a .pot file. The .pot file is a template that can be used to create translation files for your module. To generate one of these, first you need to create the directory structure to contain it:

• modules
  • my_awesome_module
    • my_awesome_module.php
    • info.php
    • locale
      • en_US
        • LC_MESSAGES
          • (empty)

Now you can visit the URL [your domain]/[chyrp path]/tools/gettext.php in your web browser to scan the installation and create .pot files for all translated strings. Once this is done you will find a new file in your module:

• modules
  • my_awesome_module
    • my_awesome_module.php
    • info.php
    • locale
      • en_US
        • LC_MESSAGES
          • my_awesome_module.pot

Modules can do much more than we've seen here, but this should get you started!