Script Samples: Included Text

Purpose

These macros show how to have text that is shared among several pages automatically.

How It Works

Including text is conceptually a little like including images in an Web page. Instead of the actual text being part of the page, there is a link to the file where the text resides. However, unlike images, browsers do not support included text, so instead we do the inclusion when the document is opened.

The macros in these examples show the simplest form of included text, a single instance of inline text inside a SPAN tag. The ID of the span connects to the ID of a LINK tag, which in turn has a link to the file where the text to be included is.

The use of the LINK tag has an additional benefit: HoTMetaL's site management features will keep track of the included text files for you, so for example, you can be informed if the link to the included text file becomes broken.

More sophisticated usage of included text is certainly possible. For example: adding macros to help create included text; allowing included content inside DIV as well as SPAN; providing a way to refresh the included text during an editing session, etc.

Since any edits that a user makes to the included text will be lost the next time the document is opened, it would be a good idea to mark the included text as read-only as described in the Template Helpers.

How To Use

Copy the macros in macros.txt into the hotmetal.mcr file found in the Macros folder of your HoTMetaL PRO application folder.

Put a SPAN tag in the place you want included text. Set the CLASS attribute to "SQ-IncludedText". Set the ID to some name that uniquely identifies the text.

Then add a LINK tag to the HEAD of the document. Set its HREF to point to the text file to be included and its ID to be "LINK_" followed by the ID that you used in the SPAN tag. (We prepend the "LINK_" because ID values are meant to be unique within a document.

On_Document_Open_Complete

This is the macro that gets called when the document has just been opened, but before the user has a chance to edit it. This is a good time to get the included text and insert it into the right places.

The macro works by looking first for all SPAN tags that have special CLASS attribute "SQ-IncludedText". When it finds one, it gets its ID value. It then looks for a LINK tag with a matching ID value. When it finds one, it gets the HREF attribute to find where the file is that contains the included text. The file is then read in to replace the contents of the SPAN tag.

<MACRO name="On_Document_Open_Complete" lang="JScript"><![CDATA[

  function Do_On_Document_Open_Complete() {
    // Include any included text
    var rng = ActiveDocument.Range;
    var magicClass = "SQ-IncludedText";
    var i, j;

    // Look for SPAN tag marked for included text
    var nodeList = ActiveDocument.getElementsByTagName("SPAN");
    for (i = 0; i < nodeList.length; i++) {
      var node = nodeList.item(i);
      if (node.getAttribute("CLASS") == magicClass) {

        // Look for a LINK with a matching ID
        var idLink = "LINK_" + node.getAttribute("ID");
        var linkList = ActiveDocument.getElementsByTagName("LINK");
        for (j = 0; j < linkList.length; j++) {
          var linkNode = linkList.item(j);
          if (linkNode.getAttribute("ID") == idLink) {

            // Get the path to the file with the included text
            var fileURL = linkNode.getAttribute("HREF");
            var filePath = Application.URLToPath(fileURL, ActiveDocument.Path + "\\");

            // Replace the contents of SPAN with the included text
            rng.SelectBeforeNode(node);
            rng.MoveToElement("SPAN");
            rng.SelectContainerContents();
            var str = Application.FileToString(filePath);
            rng.TypeText(str);
          }
        }
      }
    }
  }

  var viewWYSIWYG = 0;
  var viewTagsOn = 1;
  var viewSource = 2;
  if (ActiveDocument.ViewType == viewWYSIWYG || ActiveDocument.ViewType == viewTagsOn) {
    Do_On_Document_Open_Complete();
  }
]]></MACRO>