XI (doc) – IPM Unleashed

By KudzuIntraWeb Archive

XI (doc) – IPM Unleashed

In the past we’ve blogged about IPM and its ability to serve static content. IPM however goes way beyond that and allows for dynamic content as well.

Internal Content

IPM makes uses of internal content files, and can also be hooked toDelphi code directly. Such internal content cotnains one ore more # characters inthe filename and is protectedfrom direct user access. An example project might look like this:

This is the beginnings of a demo that will be made available withXI. In its final form it will likely be more advanced than it currentlyis and thus may appear differently. It is available live (we check itin frequently as we work on it) from the IW XI Demos project at Codeplex.

Tags

IPM content consists of any content in the wwwroot. For now I wantto discuss IWP (IW Pages) files which have an .html extension. We chosean .html extension so that the files would be readily recognized byHTML editors and the Delphi IDE as HTML files. They are however notlimited to static content and can contain a variety of IW tags. IW Tagsare of the format:

{%TagType.TagName%}

Tags are case insensitive and can optionally also containattributes. For an example of an attribute, see Escaping Tags. We usedthe {% and %} markers insteadof < > so that your markup can be seen in any HTML editor. Thesetags are used for visible content as well as invisible content, andallows for easy editing without resorting to editing only in HTMLsource view.

Tag types consists of one of the following:

  • Template – Only usable from within templates (aka skins).
  • Sys – A system variable such as time, year, etc.
  • Var – A variable as a html or text file in the content path.
  • User – User defined variables to be handled by an event, or aregistered handler class.

The TagName specifies the actual tag to use. For example {%Sys.Year%} would be replaced with thecurrent year. “(C) {%Sys.Year%}- Our Company” would become “(C) 2010 – Our Company” in the user’sbrowser.

Unrecognized Tags

Any unrecognized tag will be replaced with an empty string. No error will occur.

Escaping Tags

If the tags need to be displayed directly to the browser such as isseen on this page they can be escaped in the following manner. Todisplay:

{%var.Phone%}

use

{%%var.Phone%}

The double %% tells IntraWeb it is not a tag and should be displayed rather than processed. Only one % will be displayed to the user.

Variables

Given a target of Jack.html and a variable named Phone the following search pattern will be used:

  1. Target Directory Only
    1. Jack#.var – Format of this file is discussed later.
    2. Jack#Phone.html
    3. Jack#Phone.txt
  2. Target and Parent Directories up to and including wwwroot
    1. #Phone.html
    2. #Phone.txt

After a match isfound, no more searching is performed. If no match is found, the variable is replaced with an emptystring.

For .html files, the content between the body tags is extracted and used. For .txt files, the entire contents is used.

Searching and Overriding

For variable files and templates the following search method is used.

  1. The directory of the target IWP file is searched.
  2. If no match, the next directory higher is searched.
  3. Step 2 is repeated until the wwwroot directory is reached. Thewwwroot directory is searched, but for security reasons the search willnot continue any higher as this is the wwwroot. Higher searches wouldallow access to the application and or system directories.
  4. If no matches are found, an empty string is used.

Because paths are searched, overriding behavior can be defined. Forexample a variable named Phone could be represented by Phone.var#.txt.IWP pages or templates could reference its contents as {%var.Phone%}. For example imagine thefollowing structure:

  • wwwroot
    • #Phone.txt – Contains 555-1212
    • index.html
    • contact.html
    • About
      • index.html
    • Legal
      • index.html
      • #Phone.txt – Contains 555-1212 x666
    • Sales
      • index.html
      • contact.html
      • #Phone.txt – Contains 1-800-456-7890

Now lets assume every IWP (.html file) contains a reference to {%var.Phone%} either directly or via itstemplate. In place of {%var.Phone%}the following URLs would display the following values:

Path Value Displayed
/
/index.html 555-1212
/contact.html 555-1212 /About/
/About/index.html
555-1212 /Legal/
/Legal/index.html
555-1212 x666 /Sales/
/Sales/index.html 1-800-456-7890 /Sales/contact.html 1-800-456-7890

Values in individual IWP pages can be overridden using a VAR file.

VAR files

VAR files use the extension #.var. That is for Jack.html a VAR file would be named Jack#.var. The VAR file is a text format containing single line name=value pairs. For example:

Name=Jack Smith
;Acting CEO, but for public we use just CEO
Title=CEO

Any line starting with a ; is ignored and treated as a comment. In the future VAR files will optionally be able to use XML as well.

Templates

IPM Templates are independent of templates used with IW Forms. Templates allow you to define a common look for your pages, aka a skin. A template is an .html file that contains at minimum a {%Template.Body%} tag. It can also use {%Template.Title%} tag which will contain the target documents extracted Title attribute. Templates can also reference variables and other tags, but the tags will be treated as if they are contained in the target document. If no template is specified in the .CFG file, Default.tmpl#.html is searched for starting in the directory of the target IWP file.

CFG Files

Config files (example Jack#.cfg) contain extra information about the IWP file or template. This allows easier editing of such attributes rather than embedding them in HTML headers within the documents. Templates and IWP files have different options available in their associated .CFG files.

Cascading Templates

Templates can be cascaded that is re-embedded into another template. This allows customization of the body of another template without losing or needing to replicate features brought in by another template. To use this feature the following entries need to be made in the .CFG file:

[Main]
Cascade=True
; This next line is not necessary, it defaults to the same name
; , but can be used to alter the template used for cascading.
CascadeParent=Default

Its format is similar to an INI file, however INI routines are not used to read it so there are some differences in format. This is intentional.

Order of Operations

  1. URL is resolved and matched against content in the wwwroot andsubdirectories. If its extension is .html, it is treated as an IW Page.If not, processing is stopped and the file is served as static content.
  2. A default template is searched for if one is not specified in the.cfg file.
  3. The IWP and Template files are merged.
  4. If the Template file is cascading, the templates are merged untilno more cascading parents are found.
  5. Tags are processed.
  6. Resulting HTML is sent to the browser.