HTML and Java Macros

This essay is about a suggested student project in Java programming. This essay gives a rough overview of how it might work. It does not describe an actual complete program. I have no source, object, specifications, file layouts or anything else useful to implementing this project. Everything I have to say to help you with this project is written below. I am not prepared to help you implement it; I have too many other projects of my own.

I do contract work for a living, which could include writing a program such as this. However, I don’t do people’s homework for them. That just robs them of an education.

You have my full permission to implement this project any way you please.

This project lets you generate standard patterns of HTML. This is done statically, i.e. the results are uploaded to the website. The macros need not be simple variable text replacement, though one of your custom expanders may do just that. The logic that generates the expanded HTML from the list of variables can be as complicated as you want. The Book Refer project would be an example of complex expansion logic. I also show there an example of an embedded macro and its expansion. It inserts dashes in ISBNs, finds images and discovers their sizes as well as doing the ordinary macro fill-in-the blanks style replacement.

Basically, a custom expander takes a list of variables and associated string values and composes some HTML that gets inserted in the document. The problem comes if the custom expander is later modified. You must rerun it on all previous expansions, removing the old expanded code, and replacing it with the new generated code.

Your job is to write the framework in which the custom expanders run. Your manager parses the lists of parameters and values in the HTML stream. It hands them to the appropriate custom generator using the class.forName feature to dynamically load the relevant custom expander code, and then inserts the results in the stream. It must mark the begin and end of the generated code so that it can later be removed and replaced. The raw data has to be left in the stream, hidden inside comment delimiters i.e.  so that it can be reused later if the expansion need to be refreshed.

The expanders are embedded in the HTML much like Applets, except they are invoked by your manager, not by the the browser. The browser is completely unaware of them. It just sees mechanically generated, ordinary HTML.

Once you have completed this project, you could do a variant for Java source code. You might create a library of useful routines for the custom expanders to use. You might also do a variant that runs on a server that generates HTML on the fly much the way JSP or Freemarker does.

This project is a generalisation of the Boilerplate Refresher. The boilerplate refresher takes a name and replaces it with the contents of a file by that name. It deals with the same problems of how to refresh the inserted boilerplate text.

All the various amanuenses projects could benefit from a macro manager. Without it, any time the expansions change, you must manually regenerate all the mechanically generated HTML or Java source. With it, you just run all the code through your manager again and all the expansions are refreshed.

What sort of syntax should you use to invoke your macros and mark the expansions so they can later be removed. There are two basic approaches:

Create new HTML tags. Most browsers will happily ignore them. You could have the misfortune of having one of your tags snaffled later for an official purpose. HTML Validators will of course pour our reams of error messages when they see them.
Use magic comments. These are more verbose, however they are safer.

Perhaps you might consider letting the end user decide. Ideally you would want something totally invisible to the browsers that you could insert absolutely anywhere in the code, even inside comments and other tags. The syntax for invoking might look something like this:

and after expansion would look like this:

or you might do it like this with comment-style markers:

For your first cut, presume there will be no nesting, e.g. macros don’t generate more macros to expand. It is simplest to discard all generated text and regenerate everything from scratch than it is to try to just generate the recently added or recently modified macros.

You might tackle it by reading the entire HTML file into ram, then first removing the old expansions bracketed by <!-- generated comments. To parse the parameters to the macros, you will need to deal with \\ and \" quoting.

How might you pass the parameters to the macro generators themselves? You might just pass the values (but not the names) as strings to a main method and have the generator squirt text to System.out which you redirect. You might use reflection to pass the parameters. Then you could provide them in the desired order if if they were not specified that way. You might pass your macro generator a PrintWriter to emit the output on.

M4 is a non-embedded Macro language for HTML. Seeing what it can do may inspire you. OpenJava is a preprocessor for Java that lets you extend the language with your own abbreviations. It is using the same sort of philosophy I have described here but implemented a different way.

Here is a sample Include macro I wrote for such a framework.

My macro processor is generic. In one pass it regenerates all manner of macro types. I have written the following modules for it:

Include	to just insert bulk text from another file.
BestBrowsers	to generate HTML to recommend good browsers and help you download them.
Book	to provide links to bookstores to recommend a book.
LL	to format data about people involved with Living Love.
Reunion	to format data about people to came to my high school reunion.
Picture	to fill in height and width of images automatically.

I plan one next to generate the CurrCon Applet code.

HTML static macros

	Please email your feedback for publication, errors, omissions, broken/redirected link reports and suggestions to improve this page to Roedy Green :
	Canadian Mind Products
	mindprod.com IP:[65.110.21.43]
	Your face IP:[38.103.63.18]
	You are visitor number 4,336.
	You can get a fresh copy of this page from:	or possibly from your local J: drive (Java virtual drive/Mindprod website mirror)
	http://mindprod.com/project/htmlmacros.html	J:\mindprod\project\htmlmacros.html