Help+Manual's variables have several features that make them extremely powerful and flexible:
•You can define variables as HTML variables or as plain-text variables
•You can redefine user variables on a per-topic basis
•You can redefine user variables for your entire project with publishing tasks
These features are particularly powerful when you are generating HTML-based output. For example, you can perform search engine optimization on a per-topic basis and you can add individual JavaScript code to the HTML templates of every topic. We are sure that you will come up with additional uses for this powerful feature – experiment!
HTML variables only insert HTML code in HTML templates and HTML code objects. If you insert an HTML variable in the body of your topic only the text portion of the variable value will be used. |
Only redefine user-defined variables with this method. Although redefining global variables can sometimes work, this is not guaranteed and it should generally be avoided. Instead of redefining a global variable, define a user variable for your chosen purpose and insert the global variable as the original definition of the user variable. Then you can redefine the user variable when necessary. 1.Define an HTML or plain-text variable. 2.Insert the variable in a topic, an HTML template or an HTML code object. 3.Select a topic in the Project Explorer, select the Topic Options tab on the left of the main editor window and redefine the variable in the Topic Variables table – just click on the + button, select the variable you want to redefine and then enter a new value for it.  Tip: You can insert multiple variables at the same time by selecting them with SHIFT+Click and CTRL+Click in the list displayed when you click on the + button. The value you enter for the variable in the Topic Options tab will only be used in the current topic. |
When you publish your project with publishing tasks you can also redefine any user-defined variables in your project for individual tasks. See Automating Publishing Jobs for full details on working with tasks. See Redefining variables for full details on the various methods available for redefining variables. 1.Define a publish task with one or more publishing actions for the output format(s) and destination(s) you want to create. 2.Double-click on the publishing action in the task list to edit it and select the Custom Variables tab. 3.Edit the values of the variables you want to change. Per-topic redefinitions have priority over publishing redefinitions! |
All your topic keywords are automatically included in your topic page head section in a <meta> keywords tag. However you may want to add additional meta information yourself to fine-tune your site's search engine performance. You can do this with editable HTML variables. This simple example shows you how to do this. 1.Define an HTML variable and enter the HTML code for your meta tag as the variable's value, for example: <meta name="description" content="<%TOPIC_HEADER_TEXT%>" />  Using the <%TOPIC_HEADER_TEXT%> variable as the default value for the content attribute means that you won't have to edit the description for every single topic, just for the topics where you want to include additional information in the description. 2.Insert the variable in the <head> section of your HTML topic page template in the position where you want to insert the meta tag (see Using HTML Templates for details). Let's assume you have called the variable <%METADSCR%>: <head> <title><%TOPICTITLE%></title> <meta name="generator" content="Help & Manual" /> <%METADSCR%> ... If you do nothing else every topic will now contain the text from the topic header as the meta description text. Next you want to redefine this text for individual topics. 3.In the Project Explorer select the topic for which you want to redefine the meta tag. Select the Topic Options tab on the left of the main editor window, click on +, select the <%METADSCR%> variable from the list and then enter the new code that you want to insert. That's it. (Using words defined as keywords in the description is often helpful.) This is a very simple example that just demonstrates the basic principle. Variables are so flexible that you can find a number of different ways of doing this: For example, instead of using an HTML variable for the entire line of code you could define <%METADSCR%> as a plain-text variable, enter <%TOPIC_HEADER_TEXT%> as its value and use it like this: <meta name="description" content="<%METADSCR%>" /> If you do nothing the topic header text is still inserted as the description. To redefine the content for individual topics you then just need to enter the new description text, not the entire line of code. |
When you add your own JavaScript functions to your topics it is generally good practice to add the functions to the <head> section of your HTML page template and call the functions from within the topic with HTML code objects inserted in the topic. If you need different code functions in individual topics you can achieve this with editable variables. Variables containing the actual code:This assumes that you are going to insert the entire body of your JavaScript code in the <head> section of your HTML topic page template. 1.Define an HTML variable and paste your entire JavaScript code block in as the variable value, including the opening and closing <script> tags if appropriate. You can insert as much code as you like but it cannot include line breaks so you must use semicolons to terminate all statements and then remove all line breaks in your editor with search and replace before copying and pasting. 2.Insert the variable in the appropriate position in your HTML topic page template (see Using HTML Templates for details). For example, suppose you want to add a block of code with a variable called <%JS_USERPOLL%>: <meta http-equiv="Content-Style-Type" content="text/css" /> <link type="text/css" href="<%STYLESHEET%>" rel="stylesheet" /> <%JS_USERPOLL%> </head> 3.To redefine the code for an individual topic select the topic in the Project Explorer and select the Topic Options tab on the left of the main editor window. Then click on +, select the <%JS_USERPOLL%> variable from the list and paste in the new code that you want to insert as the new variable value. That's it. Of course, you could also use variables within your JavaScript code to replace just part of the code on a per-topic basis. Variables containing a reference to a .js file:This assumes your code is contained in an external .js file that you are referencing in your HTML topic page template. 1.Save the different versions of your JavaScript code in text files with the extension .js and add all the files to your Baggage Files to ensure that they will be exported correctly when you publish your project. 2.Define a plain-text variable and enter the name of the main JavaScript file (the one that will be used in most topics) as the variable value. 3.Add the include reference to your HTML topic page template (see Using HTML Templates for details) and use the variable instead of the name of the JavaScript file . For example, suppose the variable is called <%JS_FUNCS%>: <meta http-equiv="Content-Style-Type" content="text/css" /> <link type="text/css" href="<%STYLESHEET%>" rel="stylesheet" /> <script type="text/javascript" src="<%JS_FUNCS%>"></script> </head> 4.To select a different JavaScript file for an individual topic select the topic in the Project Explorer and select the Topic Options tab on the left of the main editor window. Then click on +, select the <%JS_FUNCS%> variable from the list and enter the name of the alternative JavaScript file as the new variable value. That's it. |
The <title> tag:You can redefine the current topic's <title> tag directly in the Topic Options tab on the left of the main editor window, in the <TITLE> Tag: field. The contents of this field are normally the same as the topic caption from the Table of Contents but if you edit it here the edited version will be inserted in the <title> tag in your HTML-based output, and this too can be useful for search engine optimization. Other redefinable template variables:Note that you can also redefine a number of HTML template variables on a per-topic basis with the Topic Variables section in . For example you can also redefine <%TOPICTITLE%> (normally returns the TOC caption of the topic), <%TOPIC_TITLE_PATH%> (the path to the current topic in the TOC of the project) and <%TOPIC_HEADER_TEXT%> (the text from the header box above the editor). See HTML template variables in the Reference section for more details of the specialized HTML template variables available. |
You can also take redefining variables a step further: You can redefine all the variables in your entire project when you publish with a project skin or variable definition file. For full details on this see Transforming your output with skins and Skins & redefining variables. The skins method can be used from the Publish dialog and it can also apply a completely different layout and style to your entire project. The variable definition file method can only be used from the command line but it can also be used to redefine global variables, which is not possible with the skin method. |
See also:
Transforming your output with skins
HTML template variables (reference)
