Advanced Usage

Owned by Kim Stimpson
Last updated: 27 Apr, 2016 by Andrew Bailey
5 min read


Conditional Blocks

From versions 5.2.16 & 5.4.12

##ConditionBlock.StringEquals.Start## and ##ConditionBlock.End## tags can be used in the Address Search Results Template to compare the results of two strings to perform one condition if they are equal and another if they aren't. The two strings are specified using the ##ConditionBlock.Property.One.Start and .End tags and the ##ConditionBlock.Property.Two.Start and .End tags as described in the sample syntax below. The ##ConditionBlock.Result.True.Start## and .End tags and ##ConditionBlock.Result.False.Start## and .End tags are used to describe the action to perform if the comparison is True or False respectively.

##ConditionBlock.StringEquals.Start##
    ##ConditionBlock.Property.One.Start##abc##ConditionBlock.Property.One.End##
    ##ConditionBlock.Property.Two.Start##def##ConditionBlock.Property.Two.End##
    ##ConditionBlock.Result.True.Start##
        ... Code to run on true condition
    ##ConditionBlock.Result.True.End##
    ##ConditionBlock.Result.False.Start##
        ... Code to run on false condition
    ##ConditionBlock.Result.False.End##
##ConditionBlock.End##

The following is an example of displaying different information depending upon whether or not the ##PreviousURL## is blank or not.

##ConditionBlock.StringEquals.Start##
	##ConditionBlock.Property.One.Start####PreviousURL####ConditionBlock.Property.One.End##
    ##ConditionBlock.Property.Two.Start####ConditionBlock.Property.Two.End##
    ##ConditionBlock.Result.True.Start##
        <a href="publisher.aspx?RequestType=ParseTemplate&template=addresssearch">Search again</a>
    ##ConditionBlock.Result.True.End##
    ##ConditionBlock.Result.False.Start##
        <a href="##PreviousURL##">Back</a>
    ##ConditionBlock.Result.False.End##
##ConditionBlock.End##

PreviousURL & HistoryID Tags

With the introduction of the new ##PrevousURL##, you can automatically create links with an ID included in order that it goes back to the previous page is a security concious method. Publisher automatically creates the entire link and replaces the ##PrevousURL## tag with it.

http://localhost/iShare/n.n/Web/publisher.aspx?requesttype=parsetemplate&template=AddressSearch_Results.tmplt&filter=%5eName%5e+ILIKE+%27%25+1%25%27%5e&pagerecs=10&useSearch=true&order=DATEAPRECV:ASCENDING&pageno=2&maxrecords=100&basepage=publisher.aspx&history=93958fed020f411d8326864cd71a6b8b

 

The downside of this is that it's sometimes advantageous to be able to craft you own custom links, but it wasn't possible to add the new ID to the link. Hence, the introduction of the ##HistoryID## tag.
Now you can now create your own custom link and have the History ID automatically inserted into it by using something like:

 

http://localhost/iShare/n.n/Web/publisher.aspx?template=AddressSearch_Results.tmplt&requestType=parseTemplate&history=##HistoryID##

 

Which would produce something like the following:

 

http://localhost/iShare/n.n/Web/publisher.aspx?template=AddressSearch_Results.tmplt&requestType=parseTemplate&history=93958fed020f411d8326864cd71a6b8b

 

Template parameters

From version 4.4

:PARAM

To pass values into Publisher template pages you can use querystring parameters with names that end :PARAM. These can be specified directly in a link or in form fields (using method="GET").

Example :PARAM
<p>Calculate distance from:
    <label for="X">Easting</label><input type="text" id="X" name="X:PARAM" value="100000"/>
    <label for="Y">Northing</label><input type="text" id="Y" name="Y:PARAM" value="100000"/>
</p>

Form Action Tags

(New in 4.4)

Magic 'RESUBMIT' template name

If the template name in the SearchResultsForm tag is RESUBMIT then the current template is used again and any options from the original search are reused, unless specified again in the tag.

All :PARAM parameters are reused and resubmitted. Any new values specified elsewhere in the form will be in addition to those already present.

Magic 'RESUBMITNOPARAMS' template name

This functions identically to using RESUBMIT with the exception that no :PARAM parameters are reused.

Parameter Tags

From version 4.4

Param

Values of :PARAM parameters in a request can be used in a page using ##Param.XXX## tags. For example this can pass parameters through from one page to another via a third or simply show the values in a page. The following examples are used when the request includes &easting:PARAM=100000&northing:PARAM=100000 to pass co-ordinates from one page to another via a Publisher URL in an intermediary:

Example
<!-- This is SecondPageTemplate, X:PARAM and Y:PARAM are from request from FirstPageTemplate -->
<a href="##HTMLFieldLink.IDFIELD.ThirdPageTemplate.IDFIELD##&easting:PARAM=##Param.X##&northing:PARAM=##Param.Y##">##Field.Name##</a>

The parameter names do not have to stay the same.

To display the coordinates:

Display Coordinates Example
<p>Distance from (##Param.easting##, ##Param.northing##)</p>

As these tags are replaced in the text at an early stage in the template processing, they can be used to pass values into other tags, see Using parameters with Recordsets below.

ParamBlock

##ParamBlock.NAME.Start## and ##ParamBlock.NAME.End## tags can be used to block out a section of the template that is only used if a :PARAM parameter is found (i.e. is present and has a value). In the following example, the paragraph is only shown if both the easting and northing parameters are present:

ParamBlock Example
##ParamBlock.easting.Start##
    ##ParamBlock.northing.Start##
<p>The distance was calculated from (##Param.easting##, ##Param.northing##)</p>
    ##ParamBlock.northing.End##
##ParamBlock.easting.End##

 

It is important to make sure the blocks are nested correctly otherwise results will not be as expected and start/end tags may be displayed in the page.

##ParamBlock.Not.NAME.Start## and ##ParamBlock.Not.NAME.End## blocks are the reverse - the template between them will only be used if the parameter is not found e.g.:

ParmBlock.Not Example
##ParamBlock.Not.easting.Start##
    <p>No easting supplied!</p>
##ParamBlock.Not.easting.End##
##ParamBlock.Not.northing.Start##
    <p>No northing supplied!</p>
##ParamBlock.Not.northing.End##

SearchQuery

The q:LIKE parameter contains the value to be used in the Lucene free-text search. It may be useful to display in the context of the current search results and this can be achieved through use of the ##SearchQuery## tag:

SearchQuery Example
Your search for: <strong>##SearchQuery###</strong> returned the following results:
<!--results go here-->

Like the ##Param.name## tags in that the ##SearchQuery## tag is replaced early and can be used by later parts of the template process.

SearchQueryBlock

This functions in a similar manner to the ##ParamBlock## tag outlined above. There is also a corresponding ##SearchQueryBlock.Not## tag block.

Recordsets

From version 4.4

FieldBlock

##FieldBlock.FIELD.Start## and ##FieldBlock.FIELD.End## tags can be used to block out a section of a RecordSet part of a template that is only used if a field has a value in the record.

FieldBlock Example
##FieldBlock.AdditionalInfo.Start##
<p>The following additional information may be useful: ##Field.AdditionalInfo##</p>
##FieldBlock.AdditionalInfo.End##

If the field does not exist, then the ##FieldBlock## tags will be shown in the page, this is in line with the way ##Field## tags work.

 

##FieldBlock.Not.FIELD.Start## and ##FieldBlock.Not.FIELD.End## blocks work in the opposite way - the template between them will only be used if the field does not have a value in the current record.

FieldBlock.Not Example
##FieldBlock.Not.AdditionalInfo.Start##
<p>The following additional information may be useful: 
##DataShare.MoreInfo.RecordSetStart##
  ##Field.Information</p>
##DataShare.MoreInfo.RecordSetEnd##
##FieldBlock.Not.AdditionalInfo.End##

Here the additional information is retrieved from another DataSource (filtered by the same criteria as its parent) when not available in the outer recordset.

WithParameter

Internal Function DataSources can be used to create recordsets, but they must have parameters specified and passed in the correct order. This is done through the use of ##WithParameter.name## tags.

Not only is the order important, but the type is too. As templates are purely string-based, any other types must be explicitly cast in the WithParameter tag. This is moderately flexible but may not be able to handle any conversion from one type to another, which should be borne in mind when designing the DataSource function.

Parameters quoted with caret (‘^’) characters are static values and are passed through directly to the function, all others dynamic and will take their value from a :PARAM parameter from the page’s querystring.

WithParameter Example
<table>
##DataShare.DistanceCalculator.RecordSetStart##
    ##WithParameter.^points_of_interest^##
    ##WithParameter.^17^::int##
    ##WithParameter.easting::int##
    ##WithParameter.northing::int##
    <tr>
        <td>##Field.name##</td>
        <td>##Field.description##</td>
        <td>##Field.distance##</td>                             
    </tr>
##DataShare.DistanceCalculator.RecordSetEnd##
</table>

In the above example, easting and northing are picked up from :PARAM querystring parameters but ‘points_of_interest’ and ‘17’ are actual values.

This will result in a PostgreSQL function call similar to the following:

Example SQL
SELECT * FROM DistanceCalculator('points_of_interest', 17, 150000, 450000) 
AS results (name varchar, description text, distance numeric) 

Using parameters with Recordsets

From version 4.4

As ##Param## substitution occurs early in the template processing - (see Processing Order), their values are already replaced by the time the ##Filter## and ##OrderBy## tags are used. This means that, for example, the filter’s field name, filter value, sort field’s name and sort direction can be dynamically updated through use of parameters, e.g.:

Example
##DataShare.datasource.RecordSetStart##
    ##Filter.^##Param.FilterField##^='##Param.FilterValue##'##
    ##OrderBy.##Param.SortField##.##Param.SortDirection####
    <tr>
        <td>##Field.fieldname1##</td>
        <td>##Field.fieldname1##</td>
        <td>##Field.fieldname1##</td>                               
    </tr>