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