Caudium HOWTO
Prev | Chapter 6. Developing with Caudium | Next

# 6.4. Your first module

With a custom module you can do all sorts of things:

- You can create a professional quality administration center very easily.

- You don't need any more "&" symbols in the URL.

- You can also use `per user variables`, also known as `session variables`.

- You'll get better performance since the module is part of the server.

- You can separate big projects into different modules, and do calls between different modules. This way, your project is not a big complex of messy code, but a set of simple, easy to extend code modules.

- You can separate data from code by using tags and containers. This also allows you to delegate the appearance to your webmaster, and lets you focus on the important code.

- You can easily share your code with the Caudium community. If your code is good and useful, it can become part of the Caudium distribution. This way more people will test it, you will have more feedback, and some people may help you with your project, and may even maintain it.

There are different types of modules, for example:

- Location:

  This is the most common module, your code is called when the user hits the URL you specify in the mount point.

- Parser:

  Your code is called when Caudium parse a file containing the tags and/or containers you define.

- Authentication:

  Used to authenticate users with, for example, LDAP, shadow, or SQL.

- Directory:

  For indexing files in a directory.

- First module:

  Module that is called just after the authentication module, thus letting you handle the whole request before normal processing.

There are other module types. For a complete reference see the Roxen 1.3 Programmer's Guide at http://caudium.info/.

For an example on how to write a container, see `fnord.pike` in `/Caudium/sources`. Because the location module is a must, here is another example:

Example 6-6. A sample module.

    // It is intended to show a simple example of a location module.

    // This module output the result of the who(1) command. It is not meant to
    // be really useful since it would be better to do a <who /> tag thus
    // having data in the HTML files and code here

    // This variable is shown in the configuration interface as the
    // version of the module.
    string CVS_version = "$Id";

    // Tell Caudium that this module is 'thread safe', that is, there is no
    // request-specific data in global variables.
    int thread_safe=1;

    #include <module.h>
    inherit "module";
    // for the http_string_answer API
    inherit "caudiumlib";

    // Documentation:

    constant module_type = MODULE_LOCATION;
    constant module_name = "Who";
    constant module_doc  = "Send the result of the who(1) command ";
    constant module_unique = 1;

    // The constructor of this module.
    // This function is called each time you/Caudium load the module
    void create()
    {
      defvar("location", "/who", "Mount point", TYPE_LOCATION,
      "The mount point of this module");
      /* each string have to be on a single
       line, don't do: "The mount point of
       this module".
       You can however do "The mount point of "
       "this module";
       */
      defvar("path2who", "/usr/bin/who",
      "Path to the who command", TYPE_FILE);
      defvar("options2who", "-a",
      "Options given to who", TYPE_STRING);
      defvar("codebeforewho", "<html><body><p>",
      "The code to output before who", TYPE_STRING);
      defvar("codeafterwho", "</p></body></html>", "The code to output after who",
      TYPE_STRING);
    }

    // This function is called when a user access mount point
    // path is the path to the URL he used
    // id contains Caudium global variables such as browser name,...
    mixed find_file(string path, object id)
    {
      // get the contents of the CIF. variables path2who and options2who
      // and put a single space between it.
      string command = QUERY(path2who)+" "+QUERY(options2who);
      // this will write the result of command to the debug log file
      // very useful for debug
      write(sprintf("command=%s\n", command));
      string result = Process.popen(command);
      // replacing \n by \n<br /> for better output
      result = replace(result, "\n","\n<br />");
      return http_string_answer(QUERY(codebeforewho)+result+QUERY(codeafterwho));
    }

Put this code in `../local/modules/who.pike` relative to `/usr/local/caudium/server` in our example. Log into the CIF., if it is not the case and go into the main `Action` tab -> `Cache` -> `Flush caches`. Check the `Module cache` check the box and press `Next`, then `OK`.

Come back to the main `Virtual servers` tab and choose one of your servers. Do `Add module` and select the `who` module. If you don't have the who module, check your events log.

You don't need to compile to have a working module. You don't even need to restart the web server. When you develop a module and change the code every 30 seconds, you just have to push the `Reload` button to get the changes. It takes about one second and if there was a compilation error the old copy remains for users.

Prev | Home | Next
Your first Pike script | Up | How to use a backtrace