6.4. Your first module

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

There are different types of modules, for example:

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.