More Advanced Procedures > Using Variables > The power of editable variables

Help & Manual's variables have two 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

These two 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!

Key Information

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.

Note that you can redefine both user-defined variables and global variables on a per-topic basis with this method.

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 tab 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.

The value you enter for the variable in the tab will be used in all output formats, but only in the current topic. This is rather trivial when you are just using variables in your topic text but becomes very powerful in HTML templates.

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:

Using the Redefining variables 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>Redefining variables</title>

<%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 tab, 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 Redefining variables as its value and use it like this:

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%>:

<%JS_USERPOLL%>

</head>

3.	To redefine the code for an individual topic select the topic in the Project Explorer and select the tab. 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%>:

</head>

4.	To select a different JavaScript file for an individual topic select the topic in the Project Explorer and select the tab. 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 tab, 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 Redefining variables (normally returns the TOC caption of the topic), More Advanced Procedures > Using Variables > Redefining variables (the path to the current topic in the TOC of the project) and Redefining variables (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.