Contents:

page
env
page parameters
page components
page text
get-env
id/get-id
get-cgi
include
include with no arguments
include with a single "page" argument
include with named sections
include with environment modifications
use-include
reuse
use

WHIFF provides a configuration template file format which may be used to specify how to build an application using other applications, middlewares, environment variables and other parameters. These configuration files usually have the extension FILENAME.whiff and WHIFF directories are often configured to interpret the templates.

Configuration templates are only one form of template which may be used with WHIFF -- WHIFF may also be used with other template formats. For example a WHIFF page may be implemented using the very terse, fast, popular, and convenient Mako template format. Please see the Standard Middleware documentation for discussion of the standard embedding of Mako within WHIFF.

The following sections describes how to build a WHIFF configuration template and the configuration directives which may occur in templates.

A configuration template file defines a WSGI application to produce a stream of bytes from a WSGI environment dictionary and (optionally) additional external parameters. ‡  

Configuration templates are primarily designed as a convenient way to wire together applications, middlewares, resources, and environment parameters. ‡  

Configuration templates are designed to be "safe" in the sense that it is not possible to inject executable code into a server using a configuration template without the help of a poorly implemented external component. ‡  

A page is the highest level construct for a configuration template. Each template constitutes a page. ‡   Pages also occur as components in other constructs. A page specifies configuration parameters followed by a sequence of components. When a page is evaluated as a response to a request the page components are converted into the byte sequence delivered as the response.

page syntax

A page consists of three optional components: an environment modifier, a list of parameters, and a sequence of page components. ‡  

page example

In the example below everything between the start of the include and the end marker {{/include}} constitutes a page.

whiff source	generated page	formatted output
temp content

page discussion

Pages may take arguments and also may request to modify their environment. The body of a page consists of a sequence of page components. The WHIFF configuration interpreter converts the component sequence into the byte sequence interpretation of the page. The components may refer to the parameters and environment.

In the example above the "Noop" no-operation middleware wraps the example page in a page component. This allows the mini-page to parse inside the larger page that generated the document you are reading. ‡  

The env environment directive for a page allows a page to specify that entries be added or overwritten in the WSGI environment dictionary.

env syntax

Note that the environment modification may introduce any structure expressible as a JSON literal value ‡   -- including floats, lists, dictionaries, lists of dictionaries, and so forth. ‡  

env example

Below the page argument to the Noop middleware specifies a first name, last name and address in the environment modification and then uses these values in the body of the page.

whiff source	generated page	formatted output
temp content

env discussion

Changes made by the page to its environment are only seen by the page making the modification and the components of that page. ‡   Ancestor pages and unrelated pages do not see the changes.

Page parameters specify external inputs to a page and may provide default values for those inputs for use in case the inputs are missing. The external inputs may be either configuration parameters or CGI form values.

page parameters syntax

page parameters example

In the example below the page argument to Noop specifies a default value of Greetings Earthling for the page argument named GREETING and also provides a default value of Human for the form input argument named SPECIES.

whiff source	generated page	formatted output
temp content

page parameters discussion

Page parameters may specify either configuration parameters or cgi-default HTML form input argument defaults. If the page is invoked with an explicit GREETING argument provided the provided value is used and the default is ignored. Similarly if the page is invoked with an environment that defines the CGI form argument SPECIES, the default value provided by the page is not used.

If there is a cgi-prefix in effect the cgi-default name will be adjusted with the prefix. In the example given above if the prefix PREFIX_ is in effect then the global form argument name associated with the cgi-default statement above is PREFIX_SPECIES.

The body of a page consists of a sequence of any number of page components.

page components syntax

page components example

The page body fragment below consists of text components and a get-env component.

whiff source	generated page	formatted output
temp content

page components discussion

The sequence of page components for a page expands into the response generated by a page. The different constructs used to create page components are discussed in more detail in their respective sections below.

Any characters outside of matched double curly brackets are considered as part of a text component in a page and are not modified by the default WHIFF interpretations of the page -- they are passed to the output of the page as written, except that }$} and {${ are replaced by }} and {{ respectively.

page text syntax

page text example

whiff source	generated page	formatted output
temp content

page text discussion

Text components allow developers to add static text to an application configuration.

The get-env construct allows a page to extract an entry from it's environment using the exact name of the entry ‡  

get-env syntax

The optional PAGE may be used to specify a default value to use if the environment contains no such entry.

The indexed name syntax allows get-env directives to extract subcomponents of structures in the environment, such as named entries in dictionaries and indexed locations in lists. ‡  

get-env example

A number of simple examples of get-env are shown above. The following is a more sophisticated example

whiff source	generated page	formatted output
temp content

get-env discussion

In the example above the environment includes a list of dictionaries kids. The whiff_middleware/repeat middleware iterates over the members of the list and places each in turn into the environment entry kid. The page argument to whiff_middleware/repeat formats each of the entries using get-env directives and indexed names. ‡  

The id and get-id directives allow a page component to get names and environment entries relative to the current CGI-prefix for the page. ‡  

id/get-id syntax

The optional PAGE may be used to specify a default value to use if the environment contains no such entry.

id/get-id example

In the example below the same configuration fragment pasted twice in different context does different things because the cgi prefix is different.

whiff source	generated page	formatted output
temp content

id/get-id discussion

This contrived example shows that by using a different whiff.cgi_prefix in different locations we can get the same page fragment to extract different entries from the environment. This is very useful when you have a complex HTML form or javascript fragment which must be used several times in a larger page. The id directive extracts a name relative to the current prefix and the get-id directive extracts a value in the environment associated with the name.

The get-cgi construct extracts a value submitted via a form input element. The get-cgi construct always extracts a name adjusted by the current cgi-prefix if set.

get-cgi syntax

get-cgi example

whiff source	generated page	formatted output
temp content

get-cgi discussion

The example above says hello to the USER_NAME provided as a form argument. If no such form argument is available the page uses default value NOBODY defined by the cgi-default directive.

The environment directive

directs the WHIFF configuration interpreter to find and extract any form parameters available in the application environment. The get-cgi construct will raise an exception if the cgi parameters have been not been parsed.

The include directive allows a template to use and configure another application and insert the output of that application in the byte stream. ‡  

include syntax

include example

whiff source	generated page	formatted output
temp content

include discussion

In the example above the include directive uses the whiff_middleware/quoteHtml middleware to "quote" the angle brackets in an HTML text fragment so that the HTML tags are visible when the text is formatted.

This example sends a single page argument to the quoteHtml middleware. There are several other ways that an include construct can parameterize an application or middleware as described below.

Sometimes an external application does not require any configuration. In this case you can refer to the application using the "no arguments" variant of the include directive.

include with no arguments syntax

Note the trailing slash /}} -- it's required.

include with no arguments example

whiff source	generated page	formatted output
temp content

include with no arguments discussion

In this example we use the whiff_middleware/debugDump application to show the environment for the page. The debugDump application requires no arguments.

Many middlewares require a single argument. Since single arguments are very common, WHIFF provides a special short-hand syntax for the single argument case

include with a single "page" argument syntax

Middlewares must use {{use NAME_OF_ARGUMENT/}} (or similar) with an explicit argument name in order to use their arguments. For this reason a single page argument is always named simply page automatically and the middleware may refer to the argument using {{use page/}} (or similar).

include with a single "page" argument example

whiff source	generated page	formatted output
temp content

include with a single "page" argument discussion

The whiff_middleware/absPath middleware translates a relative URL to an absolute URL path relative to the current server. The whiff_middleware/absPath middleware only requires one argument.

A include may include using specifications to pass more than one explicitly named arguments.

include with named sections syntax

include with named sections example

For the purposes of illustrating the use of the using directive inside a include we introduce the following simple external middleware configuration stock defined in the file stock.whiff with content as follows The stock middleware formats a simple table containing information about a company using parameters for the company information.

The following page fragment uses the stock middleware three times with the aid of the using directive to define the named parameters.

whiff source	generated page	formatted output
temp content

include with named sections discussion

In the example above we could not use the "single argument" convention because the stock middleware required three arguments. Instead we use the using directive to define the named parameters to the stock middleware.

A include may pass a modified environment to an included application or middleware in three ways that are directly supported by configuration syntax (and external middlewares may implement other ways as well).

include with environment modifications syntax

The optional ENV PAIRS above may modify globally named environment parameters passed to an application or middleware.



The set-id directive may add or override environment parameters named relative to the current CGI prefix.



The set-cgi directive may add or override a form input value named relative to the current CGI prefix.

include with environment modifications example

For the purpose of illustrating environment modifications within the include directive we introduce the application intro configured using the file intro.whiff containing the following content. The intro application is contrived to simply display some information about its environment.

The following page fragment uses the intro application twice, providing different CGI prefix specifications.

whiff source	generated page	formatted output
temp content

Please note that the set-id directive expects a JSON value -- which is why the filenames are surrounded by quotation marks.

include with environment modifications discussion

The environment modifications passed to an application will also be passed to any descendent applications used by the application.

The use-include directive is a short-hand convenience which passes an external application as an argument to a used application without modifying the passed value.

use-include syntax

use-include example

For the purposes of this example we use a static text file cyan.txt containing information about Cyanotech corporation. We use the use-include directive to pass the file cyan.txt as the description to the stock middleware discussed earlier.

whiff source	generated page	formatted output
temp content

use-include discussion

It is very often the case that configuration templates "wire together" other components in simple ways. The use-include directive provides a terse syntax to make simple wiring simple to write.

The reuse directive is a short-hand convenience which passes an argument of the current page to a used application without modifying the argument.

reuse syntax

reuse example

The example below passes a page argumetn information to the stock middleware as the description using.

whiff source	generated page	formatted output
temp content

reuse discussion

It is very often the case that configuration templates "wire together" other components in simple ways. The reuse directive provides a terse syntax to make simple wiring simple to write.

The use directive inserts the value of a page argument.

use syntax

The use directive is very similar to the include directive, except that use uses an internal argument to the page whereas the include directive uses an external application or middleware.

use example

This example contains a page which defines a simple middleware argument display for formatting a table. The page content uses the middleware twice to format verses from Lewis Carrolls "Mad Gardener's Song".

whiff source	generated page	formatted output
temp content

use discussion

Both the display middleware and the main page in the example above demonstrate the use of the use directive. The display middleware use shows the single argument form and the use inside the display middleware shows the no-argument form of the directive.