Creating your first new topic

The next step is to create a new topic. Let's create a new topic for Web Monitor for the System Requirements of Web Monitor.

Start by highlighting the parent topic in the Tree display - in this case the West Wind Web Monitor root topic. Right click and select New Topic or press Alt-N, or use the New Topic toolbar button. You'll see the New Topic Wizard pop up.

You get a few options in this dialog:

  • Topic Type
    Topic types determine which template Help Builder uses to render a topic, and also what icon is associated with the topic. Different topic types render slightly different output. Common topic types are the basics, TOPIC, HEADER, WHATSNEW and there are number of developer related types like CLASSHEADER, CLASSMETHOD, CLASSPROPERTY etc. In this case we'll create an informational topic, so choose TOPIC.

  • Starting Topic
    You can choose the topic that this topic is relative to. By default this will be the currently selected topic, but you may change this to any topic in the drop down list which contains all topics of the help file (currently only one) or by using the Topic Selection Tool which provides a tree list and search functionality to select a single topic.

  • Insertion Level
    Next you need to decide how this topic should be created relative to the topic you just selected. In this case we want the System Requirements topic to sit underneath the Root topic, so we choose Insert Topic as child of the current topic. You can also create topics at the same level as the current topic or on the root level.

Click next and you'll be prompted for a title for this new topic.

Click on Next and Finish to create the new topic. The content view should now show the new topic below your index topic:

Notice the dot next to the new topic. This means that the topic body currently has no content in it. It's meant as a reminder that you have work to do on this topic. The dot also shows when a topic is marked for follow-up.

Editing your new Topic

The new topic pops up in Edit mode automatically so you're ready to start entering text into the topic immediately. Remember you can always switch between Edit and HTML view by pressing Alt-V or by clicking on the Text or Preview icons on the toolbar.

Clicking on the Preview Icon switches back into HTML view inside of the IDE. The Internet Explorer Icon fires up a separate Internet Explorer Window so you can edit and view your text simultaneously (just press CTRL-S to save your changes and refresh the view).

To create topic text simply type your text, using mostly plain text along with some basic Markdown syntax for headers, lists links and a block quote in this case:

Most common markup operations can be accomplished through the format toolbar which provides options for Bold, Italic, color options, formatted code and HTML/XML, as well justification and lists. You can also easily link other topics or external links, or embedding code blocks using dialogs that let you pick items.

Once the text has been entered you can now preview the topic immediately either using the external preview editor if it's open or by pressing Ctrl-tab to preview in the main window:

Note: The rendered topic is fully formatted and includes text - like the header and footer - that we didn't type in. This content is generated by the active layout template which is customizable.

You can also preview this topic while the editor is active by using the live previewer, which can be accessed via the Explorer icon in the toolbar, or by toggling Alt-v.

The preview is automatically updated and syncs the preview position to the active text in the editor as you type.

Note: The preview has an update delay of around one second. The preview updates after you stop typing for a second or more. While you are heads down typing the preview does not refresh.

Templates

Help Builder output generation works off a set of HTML templates, that have a base layout into which your topic content is rendered. Templates make it easy for you to focus just on your content and not have to worry about complex layout formatting.

Each topic type (Topic,Header,ClassHeader,ClassMethod etc) in Help Builder is driven by a matching HTML Topic template that is responsible for generating the HTML content for the topic. These templates are HTML with embedded field expressions that map the data you type into the Help Builder topic form.

In addition there's a layout page that drives the overall layout of the page that defines things like the header and footer and the overall page panelling for the Web page layout.

Both topic and layout templates are merged with the values typed into each of the topics to produce the final HTML output that is then displayed in the Previewer.

So for example, the TOPIC type has a matching topic.wcs template associated with it, which is an HTML file that contains expressions that render your user entered text into the template. The layout master template is called _Layout.wcs and it holds most of the main layout - the header, footer and also the sidebar shown when you preview the entire help project in a Web browser.

This template mechanism is entirely based on Web technologies - HTML5, CSS3 and JavaScript - and can be customized using these technologies. We provide several default themes that you can customize, or you can completely create your own theme.

Templates are very powerful, for simplifying your work process, while still allowing full control over the output formatting of the HTML as the templates are fully customizable.


Next: Creating a new topic tree

See also

Step By Step Guide

© West Wind Techologies, 2018 • Updated: 04/09/18
Comment or report problem with topic