widgets/ml_msp.h

   1 /* Monolith server-parsed pages (.msp's).
   2  * - by Richard W.M. Jones <rich@annexia.org>
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Library General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Library General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Library General Public
  15  * License along with this library; if not, write to the Free
  16  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  17  *
  18  * $Id: ml_msp.h,v 1.4 2003/02/22 15:34:33 rich Exp $
  19  */
  20
  21 #ifndef ML_MSP_H
  22 #define ML_MSP_H
  23
  24 #include "monolith.h"
  25
  26 struct ml_msp;
  27 typedef struct ml_msp *ml_msp;
  28
  29 /* Function: new_ml_msp - monolith server-parsed pages (.msp)
  30  *
  31  * Monolith server-parsed pages (@code{.msp} files) are ordinary
  32  * HTML files which contain additional markup for embedding other
  33  * monolith widgets and a few other useful features like server-side
  34  * includes.
  35  *
  36  * A @code{msp} widget is a layout widget which can, like any other
  37  * widget, be embedded anywhere. However, normally you will not be
  38  * using the @code{msp} widget directly, but instead will use the
  39  * @code{msp.so} application (in the @code{apps/} directory). You
  40  * use the @code{msp.so} application by placing the following lines
  41  * in the rws host configuration file:
  42  *
  43  * @code{begin rewrite}
  44  *
  45  * @code{ ...}
  46  *
  47  * @code{^/(.*\\.msp)$  /so-bin/msp.so?page=$1  last}
  48  *
  49  * @code{end rewrite}
  50  *
  51  * @code{msp root: /var/www/html}
  52  *
  53  * When the user requests @code{/dir/file.msp}, this is internally
  54  * rewritten to a request for @code{/so-bin/msp.so?page=/dir/file.msp}.
  55  * The @code{msp.so} program creates the @code{msp} widget with the
  56  * arguments @code{rootdir = /var/www/html} and
  57  * @code{filename = dir/file.msp}.
  58  *
  59  * The @code{msp} widget fetches @code{/var/www/html/dir/file.msp},
  60  * interprets any special markup, and displays the page.
  61  *
  62  * The following special markup can appear in @code{msp} files:
  63  *
  64  * @code{<% widget [libfile.so|-] new_fn [param1 [param2 [...]]] %>}: Place a
  65  * monolith widget here. The widget is loaded from file
  66  * @code{libfile.so} which can either be a name (relative to
  67  * the current widget path) or a pathname. To load a widget
  68  * from core or the msp library itself, there is no need
  69  * to specify the library file. Just use the special name
  70  * @code{-}. Function @code{new_fn} is called to create the widget
  71  * with the list of parameters given. Each parameter can either be
  72  * a string (in "double quotes"), an integer, or one of the
  73  * special identifiers @code{pool} or @code{session}.
  74  *
  75  * @code{<% widgetpath dir1 [dir2 [dir3 [...]]] %>}: Adds the directories
  76  * listed to the current path which is searched for widget libraries. The
  77  * standard library directories (eg. @code{/usr/lib}, @code{/lib} and
  78  * others depending on the platform) are automatically included.
  79  *
  80  * @code{<% include file %>} includes a file. The file is searched
  81  * for in the document root, starting at the same directory as the
  82  * @code{.msp} file, and going up one directory at a time until we
  83  * reach the document root. For security reasons, the filename
  84  * cannot contain @code{/} or begin with a dot. The contents of the
  85  * file can contain @code{msp} directives.
  86  *
  87  * @code{new_ml_msp} creates a new @code{msp} widget. The @code{rootdir}
  88  * parameter is the document root. @code{msp} promises never to attempt
  89  * to read or include a file outside the document root, although other
  90  * types of file such as widget libraries can come from outside the
  91  * document root. The @code{filename} parameter is the name of the
  92  * @code{msp} file, taken relative to @code{rootdir}. For security
  93  * reasons @code{filename} cannot contain any @code{..} elements, else
  94  * @code{new_ml_msp} returns @code{NULL}.
  95  *
  96  * An @code{msp} widget is really just a specialised form of flow
  97  * layout (see @ref{new_ml_flow_layout(3)}).
  98  */
  99 extern ml_msp new_ml_msp (pool pool, ml_session session, const char *conninfo, const char *rootdir, const char *filename);
 100
 101 #endif /* ML_MSP_H */