quisp: creating dynamic graphics and plots

quick server pages
| Manual page for creating(dynamic)

## Creating dynamic graphics and plots

QUISP allows dynamic creation of data graphics, charts, and plots using an embedded instance of the ploticus data display engine.`` This is done using quisp_pl, an graphic-enabled instance of QUISP (see the quisp download page).`` The recommended strategy is to create a temporary image file (eg. PNG), then have the browser display it using `<img src=..>`.`` More about quisp_pl and getting graphics to work..``

## #graphic - #endgraphic

Graphic specifics are encapsulated within`#graphic` and `#endgraphic` directives.`` Ploticus prefabs or script code can be used.`` Ploticus command line arguments may be specified using `#arg` (see examples below).`` Usage:

       #graphic  resulttype   resultfilename
         #arg  commandline args 1
         #arg  commandline args 2
         ...
         ploticus script code
       #endgraphic

resulttype is `png`, `gif`, `svgz` etc.`` resultfilename is the pathname of a file where the image will be written.`` The `#arg` directive (described below) supplies ploticus command line arguments.`` `#endgraphic` terminates the construct; when the interpreter reaches the `#endgraphic` line the graphic result file is actually generated and written to disk.`` To display the graphic, use an `<img>` tag (after the `#endgraphic`) containing a URL which references the image file.``

## #arg

Set one ploticus command line argument or argument pair.`` `#arg` must be used before any ploticus code is referenced.`` All arguments are supported except `-f` and `-ver`.``

## Examples

The dynamic graphic demo on sourceforge is a good first example. Here are some others:

1. Invoke a ploticus prefab

        #set UNIQ = $uniquename()
        #set FILENAME =  @UNIQ ".png"
        #graphic  png  @HTMLPATH/tmp/@FILENAME
          #arg  -prefab  vbars
          #arg  -scale 0.8
          #arg  data=@datafile
          #arg  x=1
          #arg  y=2
        #endgraphic
        <img src="@HTMLURL/tmp/@FILENAME">

2. Execute a ploticus script via `#include`.`` The ploticus script can reference quisp variables.``

        #set UNIQ = $uniquename()
        #set FILENAME =  @UNIQ ".png"
        #graphic  png  @HTMLPATH/tmp/@FILENAME
          #arg  -scale 0.8
          #include plscripts/try3.pl
        #endgraphic
        <img src="@HTMLURL/tmp/@FILENAME">

3. Execute an embedded ploticus script. The ploticus script can reference quisp variables (eg. `@datafile`).`` The args will make debug output visible in the browser.``

        #set UNIQ = $uniquename()
        #set FILENAME =  @UNIQ ".png"
        #graphic  png  @HTMLPATH/tmp/@FILENAME
          #arg -debug
          #arg -diagfile stdout

          #proc getdata
            file: @datafile
          ...
          #proc areadef
           rectangle: 1 1 4 4
          ...
          #proc pie
          ...
        #endgraphic
        <img src="@HTMLURL/tmp/@FILENAME">

## quisp_pl build notes

In order to produce embedded graphics and charts, you'll need quisp_pl.`` This can be built from source code or downloaded in precompiled binary form for linux and solaris.`` See the quisp download page.`` To quisp_pl use `Makefile_pl`, a simple makefile that you can edit if needed.`` The executable is named `quisp_pl` by default.``

libploticus may be configured and built to produce PNG files, JPEG, pseudo-GIF, etc.`` All except pseudo-GIF require additional libraries such as ZLIB. This is explained on the ploticus download page and in the ploticus `Makefile_api`.``

## Getting graphics to work..

If you use graphics on your site you can use quisp_pl for all your pages, or use quisp_pl for graphic pages and quisp for other pages. The size and memory footprint of the quisp_pl executable is several times bigger than that of the quisp executable.``

Beginners should stick with the names `quisp` and `quisp_pl` but advanced users can choose other names if necessary.``

You'll need to set HTMLURL, HTMLPATH, CGIPROG and CGIPROG_PL explicitly in your project `config` file. Here's what I used for the quisp sourceforge web site:

      varvalue:       HTMLURL=
      varvalue:       HTMLPATH=/home/groups/q/qu/quisp/htdocs
      varvalue:       CGIPROG=/cgi-bin/quisp
      varvalue:       CGIPROG_PL=/cgi-bin/quisp_pl

Your internal HTML links must use @CGIPROG or @CGIPROG_PL when linking between plain and graphic-enabled pages.``

The recommended approach (as used in the above examples) is to write the PNG (or whatever) result to your project `./tmp` directory.`` So that your web server can find the image file, you'll need to set up a soft link from your html directory to the project `./tmp` directory. The link may be named anything, (the canned example assumes `tmp`).``

If you need to use a ploticus config file the way to do this is to set the PLOTICUS_CONFIG environment variable in your quisp config file like this:

      putenv:  PLOTICUS_CONFIG=/home/john/plconfig

The ploticus config file and the quisp config file are two different things.``

You can see what libploticus version you have by printing the variable @PLVERSION after `#endgraphic`.``
quick server pages
Copyright Steve Grubb

Markup created by unroff 1.0, `` `` May 13, 2004.