5. Other Services
*****************

5.1. Tag utils
==============

The child package *Utils*, see Templates_Parser.Utils contains a
routine to encode a Tag variable into a string and the inverse routine
that build a Tag given it’s string representation. This is useful for
example, in the context of AWS to store a Tag into a session variable.
See the AWS project.

5.2. XML representation
=======================

The child package *XML*, see Templates_Parser.XML contains routines to
save a *Translation_Set* into an XML document or to create a
*Translation_Set* by loading an XML document. The XML document must
conform to a specific *DTD* (see the Ada spec file).

5.3. Templates2Ada
==================

*templates2ada* is a tool that will generate a set of Ada packages
from a templates file. These Ada packages can then be used in your
application to avoid hard-coded strings, and help maintain the
templates and the code synchronized.

One of its goal is to ensure that you are only setting tags that
actually exist in the template (and thus prevent, as much as possibly,
typos in the name of tags); also, when combined with other tools, to
help ensure that all tags needed by the template are properly set.

Templates2ada also has special knowledge about HTTP constructs and
will generate Ada constants for the HTTP parameters you might receive
in return. Once more the goal is to help avoid typos in the Ada code.

For instance, we will consider a simple template file, found in a
local file "resources/block1.thtml". This template contains the
following simple html code:

}

When you run "templates2ada" (as described in the following
subsection), the following Ada package will be generated. Note that
this is only the default output of "templates2ada", which can be fully
tailored to your needs:

   package Templates.Block1 is
      pragma Style_Checks (Off);

      Template : constant string := "resources/block1.thtml";

      Tag1 : constant String := "TAG1";
      Tag2 : constant String := "TAG2";

      package Http is
         Param1 : constant String := "PARAM1";
         Param2 : constant String := "PARAM2";
      end Http;
   end Templates.Block1;

*templates2ada* knows about special constructs in the template file.
Such templates are generally associated with html pages. It is
possible to specify within the template itself what the url associated
with the template is, so that it provides a convenient link between
the two. Likewise, you can also define explicitly what the possible
HTTP parameters are when loading that page. This is mostly useful when
those parameters do not correspond to some form fields within the page
itself. The syntax for these two is the following:

   --  HTTP_URL(the_url): any comment you want
   --  HTTP_GET(param1_name): description of the parameter
   --  HTTP_GET(param2_name): description of the parameter

and that results in the following constants in the generated Ada
package:

   package Templates.Block1 is
      URL : constant String := "the_url";

      package Http is
         Param1_Name : constant String := "param1_name";
         Param2_Name : constant String := "param2_name";
      end Http;
   end Templates.Block1;

The templates parser API lets you define your own custom filters. It
is often useful for those filters to take parameters, just like the
predefined filters do. However, it is also useful for these parameters
to be able to check the value of other tags. One convention for doing
this is to start the name of the parameter with “@”. See for example
the example in User defined filters. As a reminder, the template would
look like:

The *templates2ada* tool knows about this special convention, and
would generate the following Ada package from this example:

   package Templates.Block1 is
      Selected_Status : constant String := "SELECTED_STATUS";
      Status : constant String := "STATUS";
   end Templates.Block1;

5.3.1. Running templates2ada
----------------------------

This tool parses all the template files found in a directory, and then
generate an output file from these, based on a template file (a
default example of which is provided as "templates.tads"). The latter
contains in fact two examples, depending on whether one Ada package
should be generated per template, or whether a single package should
be build. In the former case, if you are using the GNAT compiler, you
should run *gnatchop* on the resulting file. Here is an example to run
this tool for the example we described above.

   $ rm -f src/templates/*.ads
   $ templates2ada -d resources/ -o src/templates/generated -r
   $ cd src/templates; gnatchop -w -q generated
   $ rm -f src/templates/generated}

If, in you Ada code, you no longer use hard-coded strings but only the
constants found in the output packages, this will ensure that you are
not trying to set tags that are never used in the template.

The other check that impacts the quality of your code is to ensure
that all tags that are used by the templates are properly set. This
cannot be ensured by the compiler only, but using an external tool it
is relatively to do.

For instance, if you are using GNAT, we recommend the following
additional targets in your "Makefile":

   unset_tags:
     gnat xref -u main.adb | fgrep templates-

This checks for all unused entities in files called "templates-*",
which are the files generated by "templates2ada".

"templates2ada" can be used in other situations as well. For instance,
one possible use is to generate, as output, a new template file that
itself contains a series of *@@SET@@* commands. This generated file
can then be included (*@@INCLUDE@@*) in your own templates. We have
used it with some success when implementation a web server: it is
often the case that hyper links refer to other pages in the same
server. We have avoided hard-coding the URLs and the names of their
HTTP GET parameters, by fetching these names from the generated file
we were talking above.

The templates parser comes with an example file, called
"all_urls.thtml", which can be used with the *-t* switch to
*templates2ada*, and will generated a template file as output. You
would use it as:

   @@INCLUDE@@ all_urls.html

and this ensures the link is valid.

"templates2ada" supports a number of command line switches:

* -d <dir>

  This switch specifies the directory in which the templates file are
  searched for.

* -o <file>

  This switch specifies the output file name

* -e <ext>

  This file specifies the file name extension for template files. All
  files in the directory that have this extension will be processed by
  templates2ada.

* -t <tmplt>

  This file specifies the template file to be used for the output
  file. The templates parser comes with an example for such a file,
  called "templates.tads", that you can adapt to your own needs.

* -r

  Sub directories of the one specified by *-d* will also be searched.

* -v

  Activate the verbose mode. This will output a warning when an http
  parameter has a name made only of template parser tags, since no
  matching entry can then be created for it in the output file.

5.3.2. Customizing templates2ada
--------------------------------

As was mentioned before, the output of templates2ada is a single file
that results from parsing a template file. An example of such a file
is provided in the templates2ada distribution, as "templates.tads".

You are strongly encouraged to modify this file to adapt it to your
needs, and then use the *-t* switch to "templates2ada" to make use of
your modified file.

This file contains extensive comments on how to make use, and
customize, it. This documentation is not duplicated here

5.4. Templatespp
================

*templatespp* is a pre-processor based on the template parser. It is
generally used from scripts to process files and generate other files.
One of the possible uses, for instance, is to write the CSS (style-
sheet) of a web site as a template file (for instance "mycss.tcss"),
and use template parser structures in there. This is a good way to
share colors for instance, or to name constants, as is often done in
Ada code.

Here is a small example of such a CSS:

   @@SET@@ COLOR1=blue
   @@SET@@ COLOR2=red
   @@SET@@ LENGTH1=10

   body {background:@_COLOR1_@}
   div  {background:@_COLOR2_@}
   ul.class {background:@_COLOR1_@}  /* same color as body */

   ul   {width:@_ADD(3):LENGTH1_@px} /* ul 3 pixels wider than li */
   li   {width:@_LENGTH1_@px}

Such a file would be processed with the following command line:

   $ templatespp -o mycss.css mycss.tcss

5.5. Debug
==========

A set of routines to help to debug the *Templates_Parser* engine, see
Templates_Parser.Debug. For example, *Debug.Print_Tree* will display,
to the standard output, a representation of the internal semantic tree
for a template file.
