Frequently Asked Questions

Dynamator is a language for transforming HTML into server pages, implemented by a tool that performs the transformation. Instead of copying file x.html (or x.xml) to x.jsp and inserting program logic into x.jsp, developers who use Dynamator leave x.html more-or-less alone and write a Dynamator file named x.dyn. A Dynamator file is an XML file containing the same program logic that would go into a server page, indexed by locations in the HTML page. Dynamator merges the Dynamator file with the HTML file, inserting the program logic at the referenced locations, to create a server pages file.

The server pages maintenance problem originates from the composite nature of a server page. A server page contains static content, often created and maintained by an HTML author, and program logic, created and maintained by a software developer. Since HTML authors and software developers have drastically different skill sets and job roles, conflicts occur when server pages need to be maintained. Usually the software developer maintains the page, even if the requested changes are just HTML tweaks. There are many reasons for this. The software developer may have the page checked out; the HTML author may not be able to view the page correctly without deploying it; the HTML author may actually be in a different organization that does not have access to program logic; etc.

If your development process uses different people for HTML authorship and software development, you probably have the server pages maintenance problem. You know you have it if software developers are spending time tweaking HTML, or if HTML authors can't test their changes without deploying them to a server, or if you have the same program logic in multiple server pages.

Check the project page.

java dynamate -v

Dynamator is the name of the language. dynamate is the name of the tool.

It started out as "Dynatator" for "Dynamic Annotator", since the tool applied a "Dynamic Annotations File" to a template file. But that name generated images of tyrannosaurs chomping on Tator Tots. "Dynamator" is derived from "Dynamic Animator"; the tool brings static content to life by adding program logic.

Dynamator is released under a BSD-style open source license. Anyone can use Dynamator without charge. Users assume all responsibility and liability for using Dynamator. Anyone can redistribute Dynamator, as long as they retain the copyright information and give credit if binaries are used. Anyone can use source code from Dynamator in any other product without charge.

Dynamator provides two levels of support for server pages technologies. Dynamator provides basic support for all server pages technologies. Basic support provides all constructs except for iteration and selection, which can be coded manually within the Dynamator file within <before> and <after> elements.

Dynamator provides complete support for JSP, XSL, PHP, ASP, and Java (using out.println()). Complete support adds <for>, <foreach>, and <if> constructs, and makes the <content> element language-aware.

Complete support for other technologies is awaiting developers who would like to contribute. If you'd like to create a language plugin, visit the Dynamator project site.

Because the resulting server page file is not pure HTML. It can't be directly displayed in a browser, it can't be validated, and it is subject to dual maintenance because it mixes elements provided by people in different development roles.

Also see the next FAQ.

It's certainly not as big an issue as if you were on a large project. But you still might benefit from total separation of program logic from HTML. The ability to view server pages in a browser and to maintain a static demonstration site may still be valuable to you in your HTML-authoring role. The ability to create multiple versions of static content (for internationalization, client configuration, or multi-channel presentation) may still be valuable to you in your developer role.

Simply delete the .dyn files and start maintaining the generated server pages.

Certainly. Just remember to remove the HTML 4.0 locator attributes and elements from the generated code using the appropriate Dynamator directives.

Yes, as long as you treat them as text, just like you would in a server page. If you want a DOM interface to HTML or XML, you should consider XMLC.

No. Dynamator supports HTML only because it is possible to convert HTML into XML.

Yes. Server-side include directives may be placed in the original HTML or in the Dynamator file. Dynamator retains Server-Side Include directives for processing by the server.

Both products solve the server pages maintenance problem.

Both products have the same effects on HTML and on the interface between HTML authors and software developers. An HTML author wouldn't be able to tell which technology is being used.

But the products are fundamentally different, and there are major differences in the products' effects on architecture and development:

• XMLC transforms HTML and XML into Java classes. Programmers use a Java DOM runtime API to manipulate static content and add dynamic content. Dynamator transforms HTML and XML into server pages or programs. Programmers use Dynamator editing directives to manipulate static content and to add source code that can produce dynamic content.
• XMLC supports a single run-time architecture: a Java XML API. Dynamator is technology-neutral, capable of generating to any language.
• XMLC requires a run-time library that must be distributed to each execution environment. Dynamator has no execution-environment footprint.
• XMLC page generation is much less efficient than code generated by Dynamator. XMLC creates an in-memory tree of objects representing DOM nodes in the template document. Each change to the template requires runtime manipulation of the associated document nodes. Dynamator performs many of these manipulations at compile time, minimizing runtime overhead. In addition, most Dynamator target languages are inherently more efficient, simply treating template text as data to be output.
• XMLC uses a more familiar programming model than Dynamator. XML provides a straightforward object-oriented program API in a familiar language. Dynamator uses a declarative programming model and requires that developers learn Dynamator's XML annotation file syntax.
• Dynamator is a smaller language than XMLC. Dynamator has less than 25 language elements. XMLC requires knowledge of the DOM API, which is quite large.
• XMLC and Dynamator have different behaviors when referencing markers in the HTML. With XMLC, a reference to a marker not found in the HTML generates a compile-time error, ensuring that every intended adaptation is performed. Dynamator silently ignores references in the Dynamator file to markers that aren't found in the HTML, allowing the same Dynamator file to be applied to multiple HTML files requiring similar behavior.
• With XMLC, Java syntax errors are detected in the development environment during compilation. With Dynamator, coding error detection depends on the target language. With most server pages languages, syntax errors are detected in the execution environment.

Dynamator can be used with ASP.NET now that Dynamator allows tags to be renamed. Currently Dynamator provides only the default level of language support for ASP.NET, meaning that programmatic value substitutions and iteration and selection constructs must be coded manually.

In general, the performance of a server page generated using Dynamator is identical to the performance of an equivalent hand-coded server page. The only case where this is not true is in selection logic: Dynamator doesn't support 'else', so a test may have to be performed twice. If the test is expensive then it should be performed once and the result stored in a temporary variable.

Dynamator's 'if' directive is used to cause a template element to be output only if a condition is found to be true at runtime. The only possible use of an 'else' directive would be to cause the following template element to be output only if the condition is found to be false. This would be the only case where Dynamator would act on a different element than the one located. It would be the only case where Dynamator would require a sequence relationship between two peer template elements. It would complicate reuse of Dynamator files, and impose unnecessary constraints on templates.

No. Dynamator supports forward generation only. Existing server pages have to be converted to Dynamator by hand. Once converted, all maintenance can be performed in the source files (HTML/XML template and Dynamator file); there is never a need to maintain server pages generated by Dynamator.

Because XML is not friendly to program logic. To make the Dynamator file valid XML, each element that contains an ampersand (&) or a less-than (<) would have to be manually enclosed in a CDATA section, like this:

<table>
<if>
  <![CDATA[x < y && y < z]]>
</if>

Standard XML does not provide the ability to declare an element as containing CDATA. Dynamator automatically treats elements that may contain program logic as CDATA. This simplifies coding, at the expense of XML validity.

This is the same decision that most server pages and template technologies have made, for the same reason. Unlike other technologies, Dynamator does not invalidate the HTML or XML template.

Because XSL can't produce most varieties of server pages, since they are not compatible with standard XML or HTML. And because an XSL stylesheet used to specify server pages transformations quickly becomes unmaintainable. Don't take my word for it: try writing an XSL stylesheet for any of the Dynamator examples.

Actually, the first prototype of Dynamator was written in XSLT. But a large number of problems were encountered. For one thing, most server pages languages are invalid HTML or XML, so a post-processor was needed. For another, this application seemed to exceed XSL's complexity ceiling. The result was going to be a tool that was unmaintainable, non-extensible, difficult to use, and inefficient.

An HTML author who already knows HTML 4.0 doesn't need to learn any new syntax. An HTML author who doesn't know HTML 4.0 needs to learn two attributes and two elements. However, the recommended approach is for software developers to add the HTML 4.0 markers; HTML authors just need to know enough not to remove them or copy them to inappropriate locations.

HTML authors don't have to learn Dynamator. But they do have to learn about HTML 4.0 markers, and they have to be able to understand their new importance when used with Dynamator. This will require some training and acclimation. In general, any HTML author who understands cascading style sheets can handle using HTML 4.0 markers with Dynamator.

Most of the problems HTML authors may appear to have with Dynamator are really problems with understanding the behavior of web applications, which are much more complex than static web sites.

A typical software developer should be able to be productive with Dynamator within a day or two. A practical minimum would be 4 hours to read the syntax documentation and run some experiments. The concepts are straightforward, and the Dynamator file syntax isn't that hard for developers who have been exposed to XML.

Developers who are used to breaking up page content into smaller modules, each outputting a portion of the page, may have to rethink their approach to server page design. With Dynamator, the granularity is the complete HTML page.

Yes. Dynamator allows you to put server pages code in a different file, but it's still server pages code.

Probably. Dynamator can make it harder to understand the structure of the server page, because the program logic is separate from the static content. After you feel comfortable with server pages syntax and the interplay between program logic and static content (including selection and iteration), give Dynamator a try.

Having said that, you should use Dynamator on your first real server pages project, unless the code won't be maintained.

You need a Java runtime compatible with Sun's Java Runtime Environment version 1.1.6 or higher. If you are using a JDK earlier than 1.4, you need Xerces 1.1.3 or higher. If you will be using Dynamator with HTML, you need JTidy. (If you're using JDK 1.1, make sure you have a version of JTidy dated 2000/11/1 or later.) And you'll need the Dynamator runtime.

It depends on your learning style. If you like to jump in, see the 20 Minute Guide and the Quick Start. If you prefer a more gentle and comprehensive introduction, download the Dynamator documentation and read the Dynamator tutorial.

Use the text editor of your choice :-).

The links in the demo site refer to HTML pages, but the links in the production site need to refer to server pages. You don't want to add a locator to every link and hard-code the server page name.

You can refer to an attribute value within the content element that refers to it by using the magic string [[@]]. You can perform a simple edit on the attribute value using the syntax [[@/a/b]], which replaces all occurrences of the string 'a' with 'b'. (For multiple edits, use syntax [[@/a/b/+/c/d/...]]. Regular expressions are not supported.)

So if you are using Dynamator with JSP, you could use the following to change all hrefs on the page from '.html' to '.jsp' and encode the user's session (which you also probably need to do):

<tag tag="a" with-attr="href">
  <attr name="href">
    <content>
      response.encodeURL("[[@/.html/.jsp]]")
    </content>
  </attr>
</tag>

It's easy to repeat a single <tr>: just use <foreach>. But if you want to output more than one row for any single element, you need a way to group the <tr>'s in the template. If you attempt to put the <tr>'s inside a <div> element, Tidy will generate the error message "<div> isn't allowed in <table> elements".

Starting with Dynamator 1.3, you can identify arbitrary blocks of text within the template file using a comment div. Dynamator treats a comment div as if it were a div tag. And it's still pure HTML, because it's a comment. Here's an example:

<table>
  <!-- div id="multi-row" -->
    <tr>
      <td>Row one</td>
    </tr>
    <tr>
      <td>Row two</td>
    </tr>
  <!-- /div -->
</table>

Dynamator can be used as a simple HTML or XML manipulation language. It's not as powerful as XSL, but it's easier to use in simple cases.

<html>
<head>
  <title></title>
</head>
<body>
<table width="600" align="left"><tr><td>
  (standard header)
  <hr>
  <div id="body">
  </div>
  <hr>
  (standard footer)
  </td></tr></table>
</body>
</html>

<dynamator template="template.html">
  <tag tag="title">
    <content>
      My Title
    </content>
  </id>
  <id name="body">
    <content>
      (content of my page goes here)
    </content>
  </id>
</dynamator>

dynamate mypage.dyn

If you want the generated program to output XHTML:

java dynamate -X my.xhtml

If you want the generated program to output HTML (i.e. not XML-compliant):

java dynamate -H my.xhtml

Add the following to the <head> of the HTML file:

 <style type="text/css" class="Discard">
   <!--
    .Invisible {display: none}
   -->
 </style>

Then use class="Invisible" for every element that should not be displayed on the page.

There are three ways:

• Have the HTML author create both the input field and the read-only field within the HTML. The HTML author will need to use CSS to make the read-only fields invisible. The program selects which field to use at runtime.
• Have the HTML author create only input fields. Use JavaScript to prevent a user from changing the field value. The appropriate JavaScript routine (either a field edit or a field input inhibitor) can be specified within the Dynamator file. (Note that this won't work if the end-user turns off JavaScript.)
• Have the HTML author create only input fields. In the Dynamator file, add <if> logic to determine if the input field should be displayed. Use a <before> or <after> element to specify the text to be rendered, including any HTML.

The class attribute can specify multiple classes. Separate each with a space:

<element-name class="class-1 class-2 class-3">

Some older browsers (notably Netscape 4.x) expect exactly one class. To remove a class that was added only for Dynamator:

<attr name="class">
  <content>[[@/ class-name//]]</content>
</attr>

where class-name is the name of the class to be removed. Note that this is just textual substitution. This code assumes that the class name to be removed is preceded by a space in the HTML class attribute value.

(Thanks to Chris Felaco for suggesting this FAQ)