Difference between revisions of "Wizard Engine Service"

Revision as of 14:50, 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

Examples

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 no${VAR}."
 
    name_variable: !STRING = "NAME"
    var_variable: !STRING = "VAR"

Execute the following

example ("Eiffel User", 10)

to produce

Hello Eiffel User
You passed the index no10.

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.