Associating CSS with XML
Introduction
Layout Developer provides three ways to associate CSS properties with XML content which can be used together to accumulate CSS style definitions to apply to the elements in the target XML content:
• tcss3 — the tcss3 macro works in a similar manner to the tcontext macro in that you specify the content stream and the CSS tag to associate with it
• The <?xml-stylesheet> processing instruction at the very top of an XML instance
• A stream property cssStart that points to a function that must return CSS definitions
These are explained in detail in this Topic.
The order in which ALD gathers the definitions from these different sources is tcss3 first, then the xml-stylesheet PI, then the cssStart. It is important to remember this order as later definitions may affect the earlier ones.
CSS can be used together with tag matching and context matching (context control streams). If used with other methods, CSS styles are applied on the outside (first going in to a context, last on the way out), followed by contexts and then tag matching.
tcss3
The tcss3 macro is used to associate a CSS stylesheet tag (.cs, type 70) with an XML tag (either .xm or .xd). The macro has an fStream equivalent — fStream.cssStylesheet — which also points to a .cs tag.
Executing the macro without parameters brings up the following dialog box:
In this dialog box, the user specifies the XML stream and the CSS tag to use to make the association. The macro can also take those as arguments, for example:
tcss3 "css_test_001" "css_stylesheet_001"
If only the first argument is used, the dialog will appear with the Stream field populated.
After the association is made, tag information in the browse tags dialog box shows a new CSS Stylesheet line:
The xml-stylesheet processing instruction
It is common for XML to use a processing instruction to associate a stylesheet with the content. In ALD, the xml-stylesheet processing instruction can be used to make this association. For example:
<?xml-stylesheet type="text/css" href="C:/work/myStylesheet.css"?>
In this example the href attribute points to a CSS stylesheet at the specified location. If no path is used, the loading defaults to look in the instal folder ({@}). Loading stylesheets like this creates a tag with a link to the external file, so if changes are made to that file, then the link will need to be refreshed.
Additionally, the href attribute can point to a tag inside the ALD document. This is the recommended method as then the CSS can travel with the document. That can be done as follows:
<?xml-stylesheet type="text/css" href="{0}css_stylesheet_001"?>
This uses the {0} area to point to the current document. Note that no extension is used as ‘css_stylesheet_001’ is a tag name.
The CSS styling definitions collected by the xml-stylesheet processing instruction are applied after those from tcss3 which means that they will override the values of the same properties set by tcss3.
In order to use the xml-stylesheet processing instruction, a document preference must be set:
The ‘Load CSS from xml-stylesheet PI’ preference must be turned on for it to work. This preference is also available via the Formatting Object Model via the fTemplatePreferencesXML.processXMLStylesheetPI Boolean property. Use
template.preferences.XML.processXMLStylesheetPI = true;
cssStart
When using HTML, for example, CSS definitions may be set within the HTML file or they may be linked. For example:
<html>
<head>
<link href="myStylesheet.css" rel="stylesheet" type="text/css"/>
<style type="text/css">
body {font-size: 12px; color: orange}
span {font-size: 18px; font-style: italic; font-weight: bold;}
</style>
</head>
<body>
In this case, a tool is needed to gather all the CSS definitions from the linked file and the <style> element content. The tool we provide for this is a new fStream property, cssStart, which is a function that returns a string containing CSS definitions. It is up to the user to create the function and assign it to the fStream object, which can, in this case, be the ‘html’ tag in the ALD document or can be the stream holding the HTML content.
The _css object has a pre-declared function which can be used for HTML. _css.HTMLStart is a function which:
• Reads and collects CSS definitions from html_base.css the location of which defaults to the install folder but can be configured in the css_config.js file
• Reads and collects CSS definitions from any <link> elements in the content
• Reads can collects CSS definitions from any <style> elements in the content
This function can be used by creating a tag called ‘html’ and associating the function with it using something like:
var htmlTag = content.getStream("html");
htmlTag.cssStart = _css.HTMLStart;
If changes are made to the function, then the association must be made again as the assignment does not reference the function.
CSS definitions collected by cssStart are applied after those collected by tcss3 and the xml-stylesheet processing instruction and will therefore override them. The cssStart must be used only once and at the very start of a content stream being formatted. If a cssStart function is run more than once, the subsequent collection of CSS styling will replace that of the previous cssStart collection.
Using inline properties
In HTML it is common for style properties to be applied on the element itself, for example:
<span style="color: red; font-size: 16pt; vertical-align: text-top;">
In this case, one would want to apply that styling using the CSS functionality in ALD. This can be achieved using fFormatting.applyCSS() method.
The fFormatting.applyCSS() method requires the following arguments:
• The CSS properties to apply, as a string
• The mode — the CSS implementation executes functions for both the ‘onEnter’ and ‘onExit’ events for nodes. The node ‘onEnter’ event will process the ‘onEnter’ functions for each of the properties, and the ‘onExit’ event will process the ‘onExit’ functions for the properties. The mode part of applyCSS() tells ALD whether to process the ‘onEnter’ or ‘onExit’ functions for properties using the values declared on the fFormatting.CSSModes constant:
◦ fFormatting.CSS_ONENTER — use the ‘onEnter’ functions
◦ fFormatting.CSS_ONEXIT — use the ‘onExit’ functions
• A Boolean argument to determine whether to call the ‘display wrapper’ functions. See the Architecture section for more information. The ‘display wrapper’ functions consist of functions run in the ‘onEnter’ and ‘onExit’ states both before and after the property functions are executed. Running these ensures that the correct objects are set up to apply styling.
• A ‘displayMode’ to apply — this argument is a string which tells the CSS processing code the display type to apply — inline, block etc.
So, consider the following example in some XML:
<spanTest style="color: red; font-size: 16pt; vertical-align: text-top;">Text</spanTest>
The code to handle this looks like this:
• In the start tag:
var styleTest = arguments[0].attributes.style;
formatting.applyCSS(styleTest, fFormatting.CSS_ONENTER, true, "block");
• In the end tag:
var styleTest = formatting.evaluateXPath('string(@style)')
formatting.applyCSS(styleTest, fFormatting.CSS_ONEXIT, true, "block");
In this example, the ‘spanTest’ element is being forced to be styled as a ‘block’. But it can equally be styled inline.
