Let’s start with the highest level, creating an HTML Writer Object and getting the results from the object. For this, Legato has several functions:

  handle = HTMLCreateWriterObject ( );
  int = HTMLWriterToFile ( handle hObject, string name );
  string = HTMLWriterToString ( handle hObject );

The HTMLCreateWriterObject function returns a handle to the object. After using the object, either the HTMLWriterToFile function will write a file with the HTML or the HTMLWriterToString function will return the HTML as a string. With these functions we now have the base to create HTML and then save it as needed. With that out of the way we can break the rest of the functions down into several categories: document, paragraphs, text, tables, and styles.

Let’s take a look at the document functions:

  int = HTMLSetDTD ( handle hObject, [dword type] );
  int = HTMLSetEncoding ( handle hObject, int type );
  int = HTMLAddHead ( handle hObject, [string title, string font, string size] );
  int = HTMLAddFoot ( handle hObject );

The HTMLSetDTD function sets the DTD or Document Type Definition of the HTML file. If this function is not called, the default will be HTML 5. The HTMLSetEncoding function sets the text encoding of the HTML. The default is ANSI but, regardless, character entities can be used to display characters outside of the document’s encoding. The HTMLAddHead and HTMLAddFoot functions can be used to add a header or footer to the resulting HTML. The HTMLAddHead function has extra options for the title of the document and the font face and size for the body tag.

Next let’s talk about text and paragraphs.

The paragraph functions are as follows:

  int = HTMLAddPara ( handle hObject, string text, [string | dword align] );
  int = HTMLBeginPara ( handle hObject );
  int = HTMLBeginPara ( handle hObject, string | dword first, string | dword left, [string| dword gutter] );
  int = HTMLCompletePara ( handle hObject );
  int = HTMLParaOpen ( handle hObject, [string | dword align] );
  int = HTMLParaClose ( handle hObject );

The HTMLAddPara function writes a paragraph with the given text as content. The optional align parameter allows for the paragraph alignment to be set. The HTMLBeginPara and HTMLParaOpen functions are very similar as they both start a paragraph to which text can be added using the text functions. However, the main difference is the HTMLParaOpen function does not allow for any inline styling. The HTMLBeginPara function can be used to easily create paragraphs with inline HTML styling. The HTMLBeginPara function also supports hanging paragraphs through the option function parameters. The paragraphs must be closed with either the HTMLCompletePara function for paragraphs started with HTMLBeginPara or the HTMLParaClose function for paragraphs started with HTMLParaOpen. Additionally, calling either the HTMLBeginPara or HTMLParaOpen functions will close the previously opened paragraph if any.

We have the means to add paragraphs to the document but unless we use HTMLAddPara there is no way to add text to the paragraphs. Let’s look at the text functions:

  int = HTMLAddText ( handle hObject, string data, [dword style | string style] );
  int = HTMLAddLinkedText ( handle hObject, string text, string link, [string target], [string rel] );
  int = HTMLGetTextMode ( handle hObject );
  int = HTMLSetTextMode ( handle hObject, boolean mode, [boolean utf-8] );

The HTMLGetTextMode and HTMLSetTextMode functions deal with the text mode of the HTML Writer Object. If the text mode is true, the strings passed to HTMLAddText or HTMLAddLinkedText must be properly encoded. This allows for great flexibility as with the text mode turned on any HTML coding can be added into the HTML stream. When the text mode is turned off, data is automatically encoded properly for HTML. This includes protected characters such as <, >, and & as well as characters outside of the document encoding. The HTMLAddText function adds text to the current paragraph or table cell. The HTMLAddLinkedText function also adds text to the current paragraph or table cell but also makes that text a hyperlink. Note that the HTMLAddText function allows for a style parameter. This parameter takes a CSS style string that will be applied to the current text but keep in mind it only works with managed blocks like those started with HTMLBeginPara. The HTML Writer Object will consolidate styles for a complete block when it is closed in order to reduce coding.

Consider the following example:

   h = HTMLCreateWriterObject();
   HTMLBeginPara(h);
   HTMLAddText(h, "This text is bold and ", "font-weight: bold");
   HTMLAddText(h, "italic",                 "font-weight: bold; font-style: italic;");
   HTMLAddText(h, " for a single word.",    "font-weight: bold");
   HTMLCompletePara(h);
   AddMessage(HTMLWriterToString(h));

All the text that has been added to the paragraph has “font-weight: bold” so the resulting HTML code appears as follows:

<P STYLE="font-weight: bold">This text is bold and <I>italic</I> for a single word.</P>

The “font-weight” property has been promoted to the paragraph tag since all the content in the paragraph is bold. This reduced the code for the paragraph as multiple bold tags are not used. Additionally, the style parameter must be valid CSS; if there are any errors in the CSS string the style property will be ignored.

The next class of functions has to do with tables. The HTML Writer Object allows for two ways to write tables, managed and unmanaged. Unmanaged tables work very similarly to paragraphs as a tag is opened, content is added, and then the tag is closed. The managed table functions allow for a table to be created with random access. That is to say cells can be written in any order as long as the positions are specified. Let’s look at the unmanaged table functions:

  int = HTMLTableOpen ( handle hObject, [string width | dword width], [string align | dword align], [int border] );
  int = HTMLTableClose ( handle hObject );
  int = HTMLRowOpen ( handle hObject );
  int = HTMLRowClose ( handle hObject );
  int = HTMLCellOpen ( handle hObject, [int colspan], [string | dword align], [bool no_wrap]);
  int = HTMLCellClose ( handle hObject );
  int = HTMLAddCell ( handle hObject, string text, [int colspan], [string | dword align],[bool no_wrap] );

The HTMLTableOpen function starts a table with the given properties while the HTMLTableClose will close the table. Likewise the HTMLRowOpen and HTMLRowClose functions will open and close table rows. For adding cells to the table there are two methods much like the paragraph functions. The HTMLAddCell function creates a complete cell using the text parameter for the contents, whereas the HTMLCellOpen starts a cell to which text can be added using the text functions above. The opened cell must be closed using the HTMLCellClose function or by calling the HTMLCellOpen again.

As you can see the unmanaged table functions are very similar to the paragraph functions. However it is important to note that table rows and columns will not automatically be closed so the appropriate closing functions must be called. Additionally, unmanaged tables also allow paragraphs to be written into the table cells by using the paragraph functions when a cell has been opened.

Lastly, let’s look at the managed table functions:

  int = HTMLBeginTable ( handle hObject, [int rows], [int columns] );
  int = HTMLCompleteTable ( handle hObject );
  int = HTMLColumnSetWidth ( handle hObject, int column, pvalue width | string width );
  int = HTMLBeginRow ( handle hObject );
  int = HTMLCompleteRow ( handle hObject );
  int = HTMLBeginCell ( handle hObject, [int span], [int row], [int column] );
  int = HTMLCompleteCell ( handle hObject );

The HTMLBeginTable and HTMLCompleteTable functions are used to start and end the table creation. The rows and columns parameters are optional as the table will expand as needed. The HTMLColumnSetWidth function is used to add a width to the column on the table. If this function is not used widths are divided evenly among the columns. The HTMLBeginRow and HTMLCompleteRow functions start and end rows. It is important to note that these functions are not required if the table is built completely using random access. The HTMLBeginCell and HTMLCompleteCell functions starts and end table cells. The HTMLBeginCell function takes an optional span parameter as well as the position of the cell. If the position is omitted it is assumed to be the next cell in the order of the table. The HTMLBeginRow function will set the current position to the next row. It is also important to note that not every cell needs to be filled out as the HTML Writer Object will fill in any empty cells with non-breaking spaces. The following code illustrates the difference between using random access to create a table and using linear construction:

   string s1;
   handle h;
   h = HTMLCreateWriterObject();

   HTMLAddPara(h, "Linear Table");

   HTMLBeginTable(h);
   HTMLBeginCell(h);
   HTMLAddText(h, "Cell 0, 0");
   HTMLBeginCell(h);
   HTMLAddText(h, "Cell 0, 1");
   HTMLBeginRow(h);
   HTMLBeginCell(h);
   HTMLAddText(h, "Cell 1, 0");
   HTMLBeginCell(h);
   HTMLAddText(h, "Cell 1, 1");
   HTMLCompleteTable(h);

   HTMLAddPara(h, "Random Table");

   HTMLBeginTable(h);
   HTMLBeginCell(h, 1, 1, 1);
   HTMLAddText(h, "Cell 1, 1");
   HTMLBeginCell(h, 1, 0, 0);
   HTMLAddText(h, "Cell 0, 0");
   HTMLBeginCell(h, 1, 1, 0);
   HTMLAddText(h, "Cell 1, 0");
   HTMLBeginCell(h, 1, 0, 1);
   HTMLAddText(h, "Cell 0, 1");
   HTMLCompleteTable(h);

   s1 = GetTempFile(".htm");
   HTMLWriterToFile(h, s1);
   RunProgram(s1);

This code will create a simple HTML file with two identical tables. The first table is made using linear cells where the second is made using random access. Both methods have advantages and disadvantages so choose the method that works best for any situation.

It is also important to note that because of the way the HTML Writer handles managed tables you cannot use the paragraph functions inside table cells. The HTML Writer waits until the table is finished before creating any HTML code, so any paragraphs opened would occur before the table in the resulting output. If paragraphs need to be put into table cells use the unmanaged table functions or turn the text mode to allow raw code and insert the HTML coding manually.

As you can see the HTML Writer Object has many functions to help write tables and paragraphs. Using these functions stylized HTML can be created in Legato without having to deal with tags and attributes which is always a huge plus. The HTML Writer Object also supports adding classes to the resulting HTML tags. For more information on this see the Legato documentation. As always, Legato offers many tools to help you solve your problems.

David Theis has been developing software for Windows operating systems for over fifteen years. He has a Bachelor of Sciences in Computer Science from the Rochester Institute of Technology and co-founded Novaworks in 2006. He is the Vice President of Development and is one of the primary developers of GoFiler, a financial reporting software package designed to create and file EDGAR XML, HTML, and XBRL documents to the U.S. Securities and Exchange Commission.

Additional Resources

Novaworks’ Legato Resources

Legato Script Developers LinkedIn Group

Primer: An Introduction to Legato