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.