The Template Knowledge Base

Here you'll find some useful information on some magic to be used in a template -------------------------------------------------------------------------------

• There are two major ways to layout your template: Either you know how many data sets go to each graph (in which case the template gives hints to the application on what kind of data to put into which set) or you don't (here, the application decides how many and which datasets go to which graph). In either case, the number of graphs per page is fixed and the number of pages depends on the number of graphs to be written.

• VARIABLES are written as $NAME or ${[CONTEXT::[CONTEXT::[..]]]NAME[:DEFAULT]} (simplest form is ${CONTEXT::NAME:DEFAULT}, stuff in [] is optional, [..] denotes further contexts)

• Any context automatically uses variables from the surrounding context (i.e. a set uses those from the graph it's in) unless it has a variable with the same name.
  VARIABLE expansion will always match a variable defined in the current context (Gx or Gx::Sy) - a variable in the page context is accessible using "::NAME". To address another set in the same or another graph, "Sx::NAME" or "Gy::Sx::NAME" can be used, respectively.

• VARIABLES of a certain graph can be accessed as $NAME or ${NAME} from within that graph and with ${Gx::NAME} from text objects (x is the graph number).

• Most global variables are set by the application. Useful variables to be set could be $file, $path, $ext, etc.

• Some global variables are set by GraceTMPL itself, these are:
  • $p is the number of the page, starting with 1
  • $pz is also the number of the page, but with leading zeros (enough to reach the number of digits needed by the largest pagenum - this is very useful when used for filename templates, i.e. "output-$pz.agr")
  • $P is the number of pages, or files, to be saved
  • $filename is the name of the current output file

• Autoscaling can be turned off for a specific graph axis by placing two space at the beginning and the end of the axis title, i.e. " TITLE ". If there is to be no title, use four spaces: " "

• Normally, the application sets the legend string for a certain dataset.

• There are certain ways to change that behavior by adding one of the following to the legend string:
  • $' : take the legend string as given in the template
  • $! : keep this dataset, don't overwrite it from the app - this is quite useful to include reference data in the template

• Data can be copied from one set to another. Just append the following to the legend string of the destination set with x and y being the graph and set number of the source set:
  • $'<Gx.Sy : take the legend string as specified for this dataset
  • $=<Gx.Sy : take the legend string as specified in the source set
  Please note that literal data cannot be copied this way. It's not much sense anyway, better use XmGrace's "Edit/Set operations.../Copy" mechanism instead

• Information interpretable by the application can be set by adding one of the following to the legend string:
  • $'INFO : take the legend string as given in the template, pass INFO to the application
  • $=INFO : only pass INFO to the application, legend string is provided by the application
  All template dataset information can be queried calling the method GraceTMPL::Save::templateDataRequestInfo() - the information for dataset S in graph G is represented by the string templateDataRequestInfo()[G][S].

---