Dynamator Pure HTML for every page generation technology.
           

Frequently Asked Questions


General
1.1 What is Dynamator?
1.2 What is the server pages maintenance problem?
1.3 What is the current version of Dynamator?
1.4 What version of Dynamator do I have?
1.5 Is it Dynamator or Dynamate?
1.6 Where did the name come from?

Is it for me?
2.1 What is the Dynamator license?
2.2 What server pages technologies does Dynamator support?
2.3 I use JSP Model II with beans and taglibs, so my server pages don't contain any program logic. Why don't you think that's good enough?
2.4 I maintain my own HTML. Why should I use Dynamator?
2.5 Once I migrate everything to Dynamator, how hard is it to migrate back to server pages?
2.6 Can I use Dynamator with XML?
2.7 Can I use Dynamator to dynamically build HTML or XML structures?
2.8 Can I use Dynamator with non-XML template formats?
2.9 Can I use Dynamator with Server-Side Includes?
2.10 How does Dynamator compare with XMLC?
2.11 Does Dynamator support ASP.NET?
2.12 What is Dynamator's impact on server page performance?
2.13 Why doesn't Dynamator support 'else'?
2.14 Does Dynamator support round-trip server page development?

Design Decisions
3.1 Why isn't the Dynamator file valid XML?
3.2 Why not specify transformations using XSLT?
3.3 Why not implement Dynamator using XSLT instead of Java?

Learning
4.1 How much syntax does an HTML author need to learn in order to create HTML that can be used by Dynamator?
4.2 How hard is it for HTML authors to learn Dynamator?
4.3 How hard is it for software developers to learn Dynamator?
4.4 Do I need to learn server pages to learn Dynamator?
4.5 I'm just learning server pages. Should I wait to learn Dynamator?

Getting Started
5.1 What do I need to run Dynamator?
5.2 What's the best way to get started with Dynamator?
5.3 What IDEs support Dynamator?

How To's
6.1 When converting a demo site to server pages, how can I avoid hard-coding page names?
6.2 How do I repeat more than one table row within an iteration?
6.3 How do I remove all HTML 4.0 markers from the server page?
6.4 How do I use Dynamator to generate HTML instead of a server page?
6.5 How do I process an XHTML template?
6.6 How do I make something invisible on a static HTML page?
6.7 How do I handle a field that is editable by some users but read-only by others?
6.8 How do I associate an HTML element with multiple classes?



General

1.1 What is Dynamator?

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.


1.2 What is the server pages maintenance problem?

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.


1.3 What is the current version of Dynamator?

Check the project page.


1.4 What version of Dynamator do I have?

java dynamate -v


1.5 Is it Dynamator or Dynamate?

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


1.6 Where did the name come from?

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.


Is it for me?

2.1 What is the Dynamator license?

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.


2.2 What server pages technologies does Dynamator support?

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.


2.3 I use JSP Model II with beans and taglibs, so my server pages don't contain any program logic. Why don't you think that's good enough?

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.


2.4 I maintain my own HTML. Why should I use Dynamator?

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.


2.5 Once I migrate everything to Dynamator, how hard is it to migrate back to server pages?

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


2.6 Can I use Dynamator with XML?

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


2.7 Can I use Dynamator to dynamically build HTML or XML structures?

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.


2.8 Can I use Dynamator with non-XML template formats?

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


2.9 Can I use Dynamator with Server-Side Includes?

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.


2.10 How does Dynamator compare with XMLC?

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.

2.11 Does Dynamator support ASP.NET?

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.


2.12 What is Dynamator's impact on server page performance?

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.


2.13 Why doesn't Dynamator support 'else'?

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.


2.14 Does Dynamator support round-trip server page development?

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.


Design Decisions

3.1 Why isn't the Dynamator file valid XML?

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.


3.2 Why not specify transformations using XSLT?

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.


3.3 Why not implement Dynamator using XSLT instead of Java?

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.


Learning

4.1 How much syntax does an HTML author need to learn in order to create HTML that can be used by Dynamator?

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.


4.2 How hard is it for HTML authors to learn Dynamator?

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.


4.3 How hard is it for software developers to learn Dynamator?

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.


4.4 Do I need to learn server pages to learn Dynamator?

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


4.5 I'm just learning server pages. Should I wait to learn Dynamator?

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.


Getting Started

5.1 What do I need to run Dynamator?

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.


5.2 What's the best way to get started with Dynamator?

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.


5.3 What IDEs support Dynamator?

Use the text editor of your choice :-).


How To's

6.1 When converting a demo site to server pages, how can I avoid hard-coding page names?

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>

6.2 How do I repeat more than one table row within an iteration?

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>

6.3 How do I remove all HTML 4.0 markers from the server page?
<tag tag="*" with-attr="id">
  <attr name="id"><discard/></attr>
</tag>
<tag tag="*" with-attr="class">
  <attr name="class"><discard/></attr>
</tag>
<tag tag="div">
  <discard-tag/>
</tag>
<tag tag="span">
  <discard-tag/>
</tag>

6.4 How do I use Dynamator to generate HTML instead of a server page?

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.

1. Create an HTML template file, complete with markers for locations you may wish to override.
template.html
<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>
2. Create a .dyn file specifying that HTML file as the template file. Either do not specify a language or specify language="none".
mypage.dyn
<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>
3. Create the file by running dynamate on the .dyn file:
dynamate mypage.dyn
This will generate mypage.html.

6.5 How do I process an XHTML template?

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

6.6 How do I make something invisible on a static HTML page?

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.


6.7 How do I handle a field that is editable by some users but read-only by others?

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.

6.8 How do I associate an HTML element with multiple classes?

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)