Difference between revisions of "Wizard Engine Service"

Latest revision as of 14:22, 17 October 2008

The Wizard Engine Service is currently in it's nascency but provides a full template rendering engine for consuming tokenized templates (either from files or in-memory) and rendering them using a variable table. The results are just as flexible as the consumption, the rendered text may be generated into a in-memory representation or stored into a file.

The service makes use of an internal core engine called the Code Templates Engine, which performs actual rendering and is vastly more structured and verbose to work with. This same engine is also used by the Code Templates Catalog Service, ensuring all manner of templates are defined and rendered in the same fashion though out EiffelStudio. The purpose of the Wizard Engine Service is to facilitate quick and easy translation of code templates without the overhead involved when using the Code Template Engine directly.

Template Text

Template are simple text blobs tokenized with variable declarations. The variables will be expanded with those specified in a table passed to the service's rendering functions.

A variable is tokenized with a $ specified followed by an Eiffel-like identifier. By convention all variables are specified in uppercase characters in the template. Variables are not actual case-sensitive so this is by convention only. For example, here is the simplest form of a variable declaration:

$VARIABLE_NAME

When inserting variables adjacent to template text the variable declaration name may be blurred. To be more explicit with variable declarations, wrapped the variable name in curly braces ({...}). The token specifier $ must remain before the opening {:

${VARIABLE_NAME}

Due to the special meaning of $ it might be necessary to escape it to use in the template text itself. To escape the token specifier use $$, which will be expanded (or shrunk) to $ in the rendered template.

Service API

Template Rendering

The Wizard Engine Service supports rendering of templates in-memory or to/from disk via a text file. All possible combinations are supported; in-memory template to rendering in-memory, file template to rendering in-memory, in-memory template to rendering file, and file template to rendering file:

• render_template: Renders a text template in memory.
• render_template_from_file: Renders a in-memory text template from a file.
• render_template_to_file: Renders a in-memory text template to a destination file.
• render_template_from_file_to_file: Renders a text template from a file to a destination file.

For all of the template functions a table of variable name indexed values are required. This table is used to expand the tokenized template text's variables with the associated values. The variable names used in the table are not case sensitive so mismatches in case between the variable index name in the supplied table and the variable name in the tokenized template text is non-relevant. The associated values can be any Eiffel object, reference, expanded or otherwise. A conversion will be performed on the object to retrieve the string value representation of the object when it comes time to render the template.

Example

Here is snippet of code containing an example of how to render an in-memory template using the Wizard Engine Service's template rendering functions:

feature {NONE} -- Helpers
 
    wizard_engine: !SERVICE_CONSUMER [WIZARD_ENGINE_S]
            -- Access to the wizard engine service.
        once
            create Result
        end
 
feature -- Basic operation
 
    example (a_name: !READABLE_STRING_32; a_index: NATURAL_8)
            -- Example code.
        require
            not_a_name_is_empty: not a_name.is_empty
        local
            l_text: !STRING_32
            l_params: DS_HASH_TABLE [!ANY, !STRING]
        do
            if wizard_engine.is_service_available then
                create l_params.make (2)
                l_params.force_last (a_name, name_variable)
                l_params.force_last (a_index, var_variable)
 
                    -- Render text.
                l_text := wizard_engine.service.render_template (
                    template,
                    l_params)
 
                    -- Print rendered text.
                print (l_text)
            end
 
feature {NONE} -- Constants
 
    template: !STRING = 
        "Hello $NAME!%N%
        %You passed the index $VAR, which can be used like th${VAR}is too."
 
    name_variable: !STRING = "NAME"
    var_variable: !STRING = "VAR"

Execute the following

example ("Eiffel User", 10)

to produce

Hello Eiffel User
You passed the index 10, which can be used like th10is too.

Notice the Wizard Engine Service's rendering functions can use variable values of any type, not just string representations. In the above example a STRING and a NATURAL_8 objects were passed to the render_template function.

Template Files

Common Locations

When working with templates in EiffelStudio, most templates are located under a common template folder, in the EiffelStudio installation.

If using template files, and installing the template files under the EiffelStudio templates folder, you are encouraged to support User Replaceable Files, so end-users are free to redefine the templates in their own way. Extra precaution needs to be taken however because user files are more susceptible to changes and updates which may result in erroneous rendering.