Chapter 3 Working with Dynamo Web Sites

Working with templates

Templates in a PowerDynamo Web site are HTML documents that may include embedded instructions. This section describes how to create, edit, and delete Dynamo templates.

For information about scripts, which are the other kind of dynamic Web content managed by PowerDynamo, see "Writing DynaScripts".

Creating a template

This section describes how to add a template to your Web site. The example describes a template displaying a table of information about current products sold by the company.

To create a template:

Use Sybase Central to connect to a Web site.
In the left pane, select the folder where you want to create the new template. You may have to expand the Web site container to do this.
In the right pane, double-click Add Template.
On the first page of the wizard enter a name for the template, for example, Products. Do not use spaces. Click Next.
Enter an optional description for the template and click Next.
If your Web site has more than one connection, select a default connection for this template. For more information about connections, see "Working with connections".
On the Add SQL Query page, click Select and enter the query using the query tab window. You can enter a query manually if you wish.
Select HTML or XML as the type of document to create.
Specify the type of formatting you would like. These options are different depending on the choice you made in the previous step.

If you chose HTML as the document output, you must provide the type of HTML format you wish to use for the output.

If you chose XML as the document output you are asked to provide tags for the output or to select existing tags.
Click Finish to add the template to the Web site.

You can view the contents of the template in several ways, as described in "Viewing and editing templates".

Selecting an HTML output format for your template

The Add Template wizard provides you with a list of formats to choose from.

Tables Tables, with or without headings, are useful for queries returning several columns of results.
The default table has a border to separate the data fields. After you have completed the wizard, you can customize the attributes of the table using a Web authoring tool or Sybase Central.
Definition List A definition list displays queries with two columns, as a list. Each list item has a term and a description. For example, you might use a definition list for a glossary:
```
<DL>
<DT>Otley
<DD>A market town in Wharfedale
<DT>Wharfedale
<DD>A valley in Yorkshire, U.K.
</DL>
```
If you use the definition list format for a query with more than two columns, any extra columns are concatenated into the description.
Ordered and unordered lists These types of lists are useful primarily for queries that return a single column. Markings for an ordered and unordered list are dependent on the browser but in most cases an unordered list is marked by bullets and an ordered list is marked by numbers.
Detail This is useful for queries with any number of columns. Each field is shown on a separate line.
Link This is most useful for three-column queries. An unordered list of links is created such that column 1 is the link's URL, column 2 is the text that gets displayed for the link (the part that is usually underlined in the browser), and column 3 (and onward) become the text that is displayed after the link.
Paragraph This is useful primarily for single column queries: each row of the result set is placed in a separate paragraph.

Viewing and editing templates

You can view and edit templates in several ways from within Sybase Central and from a Web client:

You can inspect and alter the template source--the HTML together with the embedded instructions--in the Sybase Central syntax-highlighting editor.
You can view the output of a document in the Sybase Central editor.
You can use a Web client together with the personal Web server to view the template as users will see it.
You can export the template to a file and use an HTML editor to alter it, and then import the file back into the database.

Viewing template source in the Sybase Central editor

To view or alter the source of a template:

Use Sybase Central to connect to a Web site.
In the left pane, open the appropriate folders until you see the template you want to work with in the right pane of Sybase Central.
In the right pane, right-click on the template, and select Open. The template source displays in the Sybase Central syntax highlighting editor.
Make any changes to the template, then save it.

Viewing template output in the Sybase Central editor

You can check that your query result contains the data you expect by viewing the output in the Sybase Central editor.

To view the output HTML of a template:

Use Sybase Central to connect to a Web site.
In the left pane, click the Site folder. You may have to expand the Web site container to do this.
In the right pane, right-click on a Template, and select View Output from the menu. The Sybase Central editor displays the HTML of the document as it would be received by a Web client.

The instructions embedded in the template are not present in the output HTML document. Instead, the results of those instructions are displayed along with the HTML tags.

Viewing template output in a Web browser

You can check that your query result contains the data you expect without leaving Sybase Central, and check the formatting of a template, by viewing the output in your Web browser.

To view template output in a browser:

Use Sybase Central to connect to a Web site.
In the left panel, open the appropriate folders until you see the required template in the right pane.
In the right pane, right-click on a template, and select Browse Execution Output from the menu. The document output is displayed in the browser as it would be received by a Web client.

The instructions embedded in the template are not present in the output HTML document. Instead, the results of those instructions and HTML are displayed.

Limitations of browsing output
The document output is sent to a file, which is then loaded into your Web browser. Consequently, any links to relative addresses will not work, and any graphics that are given relative addresses are not displayed. It is recommended to use relative addresses and tolerate the discrepancies in output appearance when accessed in this manner. To view output exactly as it would appear to a user, use the Personal Web Server with a browser.

Using a Web authoring tool with PowerDynamo

Web authoring tools (HTML editors) work with HTML files, while PowerDynamo templates are stored in a database. However, you can edit PowerDynamo templates using a Web authoring tool.

This tutorial shows you how to customize the formatting of the template that you generated in the previous tutorial. You must have a Web authoring tool other than the Sybase Central editor.

To edit a template using a Web authoring tool or text editor:

Use Sybase Central to locate the template you want to edit.
Right-click the template and select Export from the menu.
Enter a file name for the exported template.
Open the file in your Web authoring tool or text editor.
Make any changes to the template. Save it, and close your Web authoring tool or text editor.
From Sybase Central, right-click the folder where your template resides and select Import from the menu to bring the file back into the database.
From Sybase Central, right-click the template and select View Output from the popup menu. This shows the HTML output of the template, including the changes you have made.

When you open the template in a Web authoring tool, the query is not shown. PowerDynamo stores queries in HTML templates as specially marked HTML comments. Storing queries in this manner allows editing by any HTML editor, without interfering with the query.

When you open the template in a Web authoring tool, only the headings and one empty row of the table is shown. PowerDynamo uses specially marked HTML comments to indicate formatting information, and these comments are ignored by Web authoring tools. The single row containing apparently empty cells actually contains the following HTML comment:
```

```
Storing formatting in this manner allows editing by any HTML editor, including formatting of the table containing the output.

Embedding instructions in a template

Instructions are embedded in a template as HTML comments rather than as HTML tags.

Embedding SQL in a template

A SQL statement is contained inside an HTML comment. HTML comments are of the following form:

<!-- this is a commment -->

All material inside the angle brackets is ignored by an HTML parser such as that included inside a Web client. Thus, a Web client can view a template, and it will ignore the material inside the comment tags. If you edit the template using an HTML authoring tool it will ignore the embedded instructions. Of course, the SQL statements are not seen by a Web client, as they are interpreted and executed by the PowerDynamo Application Server.

SQL statements are embedded in an HTML document as follows:

<!--SQL 
    sql-statement 
-->

The SQL statement itself can continue over several lines. It should start on a separate line from the SQL comment tag.

Example

The following HTML fragment contains a simple query.

<!--SQL
    SELECT name, color, size, unit_price
    FROM "dba".product
-->

Naming a SQL statement

You can provide an identifying name for an embedded query. This is useful, for example, if you have more than one SQL statement in a template.

To name a SQL statement, provide a name for a SQL statement as the NAME attribute for the SQL comment tag. The following SQL statement has a name of ProductQuery:

<!--SQL NAME=ProductQuery
    SELECT name, color, size, unit_price
    FROM "dba".product
 -->

The SQL statement itself must start on a separate line from the NAME attribute.

Formatting query results

If the embedded SQL statement is a query, then the Application Server inserts the results of the query into the output document. PowerDynamo allows you to describe the formatting of a query using a formatting comment tag.

The HTML tags for formatting instructions are slightly different from the tags used for SQL statements. To allow an HTML editor to modify and refine the actual formatting, the formatting description is not inside a comment. Instead, comment tags are used for placeholders for the data, which are replaced on processing by the actual data.

Start and end formatting comment tags

All data placeholders must be between formatting start and end comment tags. The formatting start comment tag is of the form

<!--FORMATTING-->

The formatting end comment tag is of the form

<!--/FORMATTING-->

Formatting using scripts
In addition to using formatting comment tags, you can use embedded scripts to format output. The flexibility of scripts allows more varied formatting than the formatting comment tags.

For more information on formatting using scripts, see the chapter "Writing DynaScripts".

As these are HTML comments, there is no restriction on the HTML that can be included between the tags. The formatting comment tags have no effect on HTML that occurs between them; they affect just the embedded instructions.

For more information on Dynamo Tags, see the chapter "Dynamo Tags" in PowerDynamo Reference.

Passing variables from one document to another

You can use text replacement macros, or text substitution macros, to include values provided by a Web client in document output. For example, a document in your Web site may ask a user to enter their name in an HTML form. Their name can then be used in documents returned from the Web server.

Example

This example includes the following:

A sample form asking the user to enter their first and last names, and submitting them to the Web server.
A reply document that uses the supplied names to address the user.

To create the documents for the example:

In Sybase Central, connect to the sample Web site and move to the main contents folder.

Create a new template named form.stm, without entering any query. Then edit the document so that it has the following content:

<HTML>
<HEAD>
<TITLE>
    Test of text substitution
</TITLE>
</HEAD>
<BODY>
<FORM ACTION="reply.stm" NAME="log" METHOD="GET">
<p>Please enter your name.
<ul>
<li>First name: 
<INPUT TYPE="text"     NAME="firstname" SIZE="15">
<li>Last name: 
<INPUT TYPE="text" NAME="lastname" SIZE="15">
</ul>
<p><Center>
<INPUT TYPE="Submit" VALUE="Register">
</Center></p>
</FORM>
</BODY>
</HTML>

This HTML document contains a form, but contains no Dynamo-specific instructions. The <FORM> tag tells the browser to retrieve reply.stm when the user clicks Register.

Create a new template named reply.stm, without entering any query. Then edit the document so that it has the following content:
```
<HTML>
<HEAD>
<TITLE>Test of text substitution</TITLE>
</HEAD>
<BODY>
Dear $firstname $lastname,
Thank you for using our text substitution facility.

Yours

TextSub Corporation.
</BODY>
</HTML>
```
The $firstname and $lastname entries are text substitution macros. They are replaced by the values entered in the form when reply.stm is processed.

To run the example:

Start the Personal Web Server from the Utilities folder in Sybase Central. You will see the Personal Web Server tray icon at the end of your start bar once it is running.
Start your browser, and open the URL for the HTML form. If you created the form in the main contents folder of the sample Web site, the address is as follows:
```
http://localhost/Site/form.stm
```
Enter your first and last names into the fields, and click Register. The entry is sent to the Web server in the URL in the following form:
```
http://localhost/Site/reply.stm?firstname=first-name&lastname=last-name
```
The reply.stm document is returned, with the proper values placed in for the name. If you entered a name of Simon James, the reply would be:
```
Dear Simon James,
Thank you for using our text substitution facility. 
Yours 
TextSub Corporation. 
```

Text replacement macros in scripts

Text replacement macros can be accessed inside scripts, but are accessed in a different manner. The argument is a property of the document object, which is a predefined object. The actual value of an argument named firstname can be accessed inside a script as:

document.value.firstname

For information about using text replacement macros in scripts, see "Passing variables from one document to another".