Exported HTML templates define the HTML that is generated by PortWeb in response to a request. They can contain virtually any HTML code of which you can conceive.
PortWeb does not analyze the HTML you enter, other than to verify that you have used legitimate macro names. Therefore, any HTML you can create can be used, including JavaScript, DHTML, XML, etc.
There are three key aspects to an Export HTML template that are unique to PortWeb: Template Blocks, Template Macros, and Macro Blocks.
Template Blocks
PortWeb’s HTML templates are made up of three blocks. You can define HTML for the Header, Item, and Footer. The Header section is placed at the beginning of each generated page, the item section is inserted into each table cell, and the footer is placed at the end of each generated page. In Portfolio’s Edit Template dialog, you can either type the HTML directly into each block or paste it in using Paste from the Edit menu.
The following rules apply to each block in a PortWeb template:
Header:
The header must contain the <HTML> tag and the <BODY> tag.
Because the grid layout is generated as a table, the Header must end with a <TABLE> tag.
Footer:
The Footer must start by closing out the table with a </TABLE> tag.
The Footer should close out with </BODY> and </HTML> tags.
Item:
The item block should contain all of the formatting for a particular table cell, including the opening <TD> tag and the closing </TD> tag.
PortWeb will generate the row tags (<TR> and </TR>) on its own, based upon the grid dimensions. Do not include these tags in any of the cells (unless you are adding your own rows at the top or bottom of the table).
Template Macros
Portfolio uses a macro language in the HTML Templates to allow substitution of variable data at the time the HTML files are actually generated. All macros start and end with a % sign, so the proper use would be %macro%. To display a “%” sign in the actual HTML, use two consecutive % signs in the template (i.e. “%%” in the template produces one “%” in the generated output). Macros are case-insensitive.
The complete list of acceptable macros is shown in the table below.
|
PortWeb HTML Template Macros |
|
|
Macro Name |
Description |
|
%fieldname% |
Any field available to the user can be inserted into the item block. At the time of export, the value of the field for the particular record being processed is substituted for the macro. |
|
%thumbnail% |
Substitutes a thumbnail request. Note that this is different functionality than the existing Export HTML mechanism (which was putting a path to disk). |
|
%RID% |
Inserts the Record ID for the particular record. The Record ID is unique in the catalog and is used by commands such as Thumbnail, Add, and Remove to reference specific records in the catalog. |
|
%prev% |
Substitutes a relative link to the previous HTML file generated in the series. If the file being generated is the first file, an empty string is substituted. |
|
%next% |
Substitutes a relative link to the next HTML file to be generated in the series. If the file being generated is the last file, an empty string is substituted. |
|
%pagelist% |
Generates HTML for a set of page number links (i.e. 1 2 3 4 5 ) |
|
%page% |
Inserts the number of the current page into the HTML. |
|
%totalpages% |
Inserts the count of the total number of pages that could be generated, given the grid size and the count of the found record set. |
|
%totalitems% |
Inserts the count of the total number of found records for the submitted query. |
|
%collectionadd% |
Generates the HTML for a Collection Add request. |
|
%collectionremove% |
Generates the HTML for a Collection Remove request. |
|
%collectionshow% |
Generates the HTML for a Collection Show request. |
Special Macros
A few sets of macros behave differently, depending on whether the Portfolio client or PortWeb is generating the results.
Page Macros
[%prev%, %next%, and %pagelist%]
The HTML generated by the Portfolio client for %Prev%, %Next%, and %PageList% macros generate links to other HTML pages on disk. When these macros are handled by PortWeb, the generated HTML is instead new quickfind or query commands with the appropriate offset parameter.
For example, a template that generates two rows by four columns will use the following macro:
|
<A HREF = "%Next%"> |
to generate this HTML:
|
<A HREF=".PortWeb?quickfind=test&catalog=Sample&template=Simple&offset=8"> |
The catalog name, quickfind value, template name, and offset are all automatically determined based on the original request. When the user clicks on the link, a new quickfind command is submitted to PortWeb that instructs PortWeb to start generating results with the ninth item. This powerful feature means PortWeb only generates results for one page at a time, meaning response times are kept to a minimum.
While you could conceivably create these links manually, Portfolio automates all of this for you.
Thumbnail Macro
[%thumbnail%]
The %thumbnail% macro, when handled by PortWeb, generates a Thumbnail command and fills in the appropriate parameters.
For example, a template that contains the following macro:
|
<IMG SRC="%thumbnail%"> |
will generate the following HTML.
|
<IMG SRC="PortWeb.dll?thumbnail=20&catalog=WebTest"> |
The Record ID specified for the catalog and the catalog name are automatically determined based on the original request.
The thumbnail request is used to request a JPEG data stream of a particular thumbnail. This allows PortWeb to stream thumbnail data from a particular record in a catalog back to the web browser without ever having to write the data to disk first. Typically, these requests will be embedded in the HTML results from the query request. This will cause the browser to submit these requests back to PortWeb, allowing it to return each thumbnail as an individual JPEG stream.
The thumbnail command should always be part of an image link:
|
<IMG SRC="PortWeb.dll?thumbnail=80&catalog=WebTest"> |
The two parameters that must be supplied are shown below.
|
Thumbnail Command |
|
|
Parameter |
Description |
|
thumbnail |
Specifies the record’s unique ID in the catalog. This parameter must appear first when doing a GET request. |
|
catalog |
Specifies the alias of the catalog is to be used. The alias is mapped via the settings file to either a catalog on disk or a catalog being served by a Portfolio server. |
Usage
There are two Export HTML macros you can use to supply the record id: %thumbnail% and %rid%. The %thumbnail% macro provides the entire path for the image’s SRC parameter, while the %RID% supplies only the record’s id. Examples:
|
<IMG SRC="%thumbnail%"> |
|
<IMG SRC="PortWeb.dll?thumbnail=%rid%&catalog=Sample"> |
Normally it is easier to use the %thumbnail% macro, since it automatically encodes the RID and catalog name, but there may be times when you want to use the additional flexibility of manually establishing the other parameters.
Collection Macros
[%CollectionAdd%, %CollectionRemove%, and %CollectionShow%]
These commands have no purpose when using Export HTML with the Portfolio client, as they are dynamic commands that are built so that PortWeb can remember users’ selections. For more information on using these commands with PortWeb, refer to Collections.
Macro Blocks
Export HTML allows for markers to delineate the beginning and end of “macro blocks.” Macro blocks define the beginning and end of a section of HTML that surrounds a Portfolio macro. If the macro evaluates to an empty value, then none of the HTML text within the macro block is generated. Macro blocks are defined using HTML comment tags in the following structure:
|
<!--Port4-%macro%--> and <!--/Port4-%macro%--> |
where the first comment opens the block and the second comment closes the block. As PortWeb processes the template, each time it encounters an open comment, it evaluates the macro defined within. If the macro has a value of nil (for example, if the field is empty), PortWeb skips the HTML code until the corresponding close comment is found (or the end of the section is reached).
The most common use for the macro blocks is the “Previous” and “Next” macros, so that additional information does not get generated. Take the following example:
|
<!--Port4-%prev%--> <A HREF="%prev%">Previous Page</A> <!--/Port4-%prev%--> |
When PortWeb processes this section for page one of a search, if it were on the first page, the %prev% macro would evaluate to “nothing.” Therefore, PortWeb would not generate any text until the close comment is encountered.
Another example would be to add a field name in front of a field macro, but not display the field name if there was no value for the field:
|
<!--Port4-%filename%--> File Name: %filename% <BR> <!--/Port4-%filename%--> |
A more elaborate possibility would use the macro of one field as a logic flag for determining whether to display a completely different piece of information:
|
<!--Port4-%HasSource%--> <A HREF="%path%">%filename%</A> <!--/Port4-%HasSource%--> |
The preceding example would insert a hyperlink to the source file, but only if there was a value in the field “HasSource.”
Note that it is possible to nest macro blocks, but it may result in unanticipated results if the blocks are not properly nested or if the blocks are not properly terminated with a close comment, since PortWeb simply stops generating text until it encounters the appropriate close block or the end of the section.
Special Macro Blocks
Several macro blocks are set to evaluate to empty in particular situations:
%prev% will evaluate to empty if the page being generated is the first page in a record set. This is useful for omitting a “Previous” link from the first page of a set.
%next% will evaluate to empty if the page being generated is the last page in a record set. This is useful for omitting a “Next” link from the last page of a set.
%collectionadd%, %collectionremove%, and %collectionshow% will evaluate to empty if the page is being generated by the Portfolio 5.0 client. Since these commands only work with PortWeb, this can allow you to use the same templates with both the Portfolio client and PortWeb.
%totalitems% will evaluate to empty if no items are returned by a request. This is useful for generating HTML when there is a found set and you want to hide text, formatting, or buttons when no records are returned by a search.
Working with Templates on Disk
The Portfolio 5.0 client has the capability to save Portfolio’s HTML Templates to disk. This is particularly useful if you are working with larger amounts of HTML code, as you can then edit the HTML in an HTML-savvy text editor. In addition, it makes it much easier to move templates between catalogs or share templates with other users. Note that Portfolio’s custom formatting makes it difficult to work with these templates in visual page editors, such as Macromedia Dreamweaver or Adobe PageMill.
Template File Structure
When templates are written to files on disk, Portfolio inserts specific comment tags to define the beginning and end of the three template blocks. The tags are:
|
Header |
Start |
<!—Port4-Header--> |
|
End |
<!—/Port4-Header--> |
|
|
Item |
Start |
<!—Port4-Item--> |
|
End |
<!—/Port4-Item--> |
|
|
Footer |
Start |
<!—Port4-Footer--> |
|
End |
<!—/Port4-Footer--> |
In between each set of tags is the contents of each block. Other than these block tags, the HTML is identical to the HTML displayed in the Edit HTML dialog.
When the template is imported, Portfolio looks for the same tag pairs to determine into which blocks to place the HTML code. The tags themselves are stripped.
Exporting Templates
To export a template, simply click the Export&ldots; button in the Edit HTML dialog. You will be prompted to name the file. Once it is exported, you can open the file in any text editor.
Importing Templates
To import a template, simply click the Import&ldots; button in the Edit HTML dialog. You will be prompted to locate a file to import. Once you select a file, Portfolio scans it for the block tags and imports the information into the appropriate fields. If the appropriate start and end tags are not found, Portfolio will not import any of the data. All three sections do not need to be present in the file; if a section is missing, the block in the Edit HTML dialog will be untouched.
Note: Portfolio uses the "%" sign to denote special macros, and will not handle "%" symbols that may be part of your HTML (such as "width=100%"). When importing HTML generated by other applications, convert each "%" sign in the HTML source file to two consecutive "%" signs in the template (i.e. "width=100%" in the source file should be changed to "width=100%%" in the template).
Using Collection Macros
The three collection macros are %collectionadd%, %collectionremove%, and %collectionshow%. These macros behave differently depending on whether they are placed in the Item block or in the Header or Footer blocks.
Collection Macros in the Item Block
When the macros are placed in the Item block, a partial GET request is generated.
For example, entering the %collectionadd% macro results in the following HTML being generated:
|
.PortWeb?add&rid=75&catalog=Sample |
For this to be useful, the macro needs to be inserted into an anchor of some type. For example, consider the following template code:
|
<A HREF = "%collectionadd%&template=myCart">Add to Cart</A> |
The resulting generated HTML is:
|
<A HREF = ".PortWeb?add&rid=75&catalog=Sample&template=myCart">Add to Cart</A> |
This is then a valid link that, when clicked, would add Record ID 75 to the user’s collection and display the contents of the cart using the “myCart template.” Note that the “&template=myCart” parameter had to be specified separately, as the system does not know what template you want to use to display the cart. If the template parameter had been omitted, the default 4x4 thumbnail response would have been used. For more details on the parameters that are used by each collection command, refer to Collection Commands.
The %collectionremove% and %collectionshow% macros behave in much the same way when placed in the Item block. The %collectionremove% macro will automatically generate the rid and catalog parameters; you must supply the template and other optional parameters. The %collectionshow% macro will automatically generate the catalog parameter; again, you must supply the template and other optional parameters.
Collection Macros in the Header and Footer Blocks
When the collection macros are placed in the Header or Footer blocks, the generated HTML is different. This is because these commands have different meaning in this context, because there are no particular records that can be referenced from these locations.
Instead, PortWeb generates the start of an HTML Form block. For example, placing the %collectionadd% macro in the header results in the following HTML being generated:
|
<FORM ACTION=".PortWeb?add" METHOD=POST> <INPUT TYPE=HIDDEN NAME=catalog VALUE="Sample"> |
While at first glance this may not appear particularly useful, this is actually a very valuable feature. Because PortWeb is capable of handling multiple items in an Add add or Remove remove command, you can set up the template so that multiple records can be submitted in one form. For example, add the following line to the item block:
|
<INPUT TYPE="checkbox" NAME="rid" VALUE=%rid%>Add to Cart |
And then place a Submit button and a close Form tag in the footer:
|
<INPUT TYPE="submit" NAME="send" VALUE="Add Selected Items"> <INPUT TYPE=HIDDEN NAME=template VALUE="Sample"> </FORM> |
The generated HTML will have a checkbox for each item. If you check a set of these boxes and click the “Add Selected Items” button, all of the checked records will be added to the shopping cart and the results will be displayed using the “Sample” template.