Authoring - Working with aliases

Previewing content from the Workbench is a mean for the authors to check and correct their work. Your customers and users of course, do not have an authoring tool such as the Workbench. So, how can these people access the content?

In most authoring tools the content is exported into files and these files are then distributed or put on a web server. HelpServer also offers such export facilities.

However, with HelpServer people can directly access the HelpServer content objects over the Internet just by entering a URL in a web browser’s address bar. The URL contains the location of HelpServer’s web server engine and a name that points to the requested content object. We refer to that name as an ‘Alias’. It is the alias in the URL that makes direct Internet access possible.

Assigning an alias

An alias is composed of two parts:

 

The project name.

 

This name is chosen by you the moment you add a new project folder.

 

The object name.

 

This is a unique name for a content object within the project.

The alias names can be seen in the table on the right. If you for example select the main 'Content' folder in the Workbench tree you can see the alias for the 'Project: Animals information' folder which is 'ANIMALS_MAIN'. This alias is automatically assigned the moment the project folder is added and it can be used to access the entire project over the Internet.

The alias of the project

If people do not need direct access to any of the project's dependant objects, then you do not need to do anything and you can start

But assume that people need direct access to the individual books of the 'Project: Animals information' then the first step would be to assign an alias to each book. In the next example you learn how to assign an alias to the ‘Book: Birds’ folder and how this relates to a URL.

Assigning an alias

Popup the menu of ‘Book:Birds’ and select ‘Project > Assign alias’. This will popup the ‘Assign alias’ window.

Entering the object name

You only need to enter the object name. In our example we can use ‘Birds’.

An object name cannot be changed. If you want to change it you have to unassign it and then reassign a new name. Also, an alias is NOT case sensitive.

Confirming the alias

Click ‘OK’ and confirm that you want to assign the given name to the object. If the container that holds the book (here the 'Project: Animal information' folder) is selected you can see the chosen alias in the ‘Alias’ column on the right pane of the Workbench.

Alias assigned

Using the URL

Once the alias is assign you can use it in the URL to request the object over the Internet.

Copying the URL

On the Workbench you can grab an object’s URL by popping up the object’s menu (the ‘Birds’ book in our example) and selecting ‘Copy URL>ANIMALS.BIRDS’ which copies the URL to the clipboard. If the URL relates to content that is new or changed then you will be prompted to publish.

Requesting the publish

People who access the content over the Internet by means of a URL cannot be bothered by the author's perhaps unfinished work. In this example you have performed quite some changes in the project. Assume that you have verified (previewed) it and corrected it. Then publishing is the required step to activate all your work.

You can always start the publish process manually from the popup menu on each node in the Workbench. But here, the copy URL function function prompts you to publish.

Starting the publish

If the 'Publish' window is opened make sure the option 'Publish dependants' is selected. Click 'Start' and the book and its containing objects will be published one by one.

Publish done

If the process is completed you close the window. A message will popup to confirm that the URL is available on your clipboard. If you perform the copy URL next time and nothing has changed then you won't be bothered with the publish step.

URL copied

Now open your web browser and paste the copied URL in the address bar.

Pasting the URL

After the paste you can recognize the ‘animals.birds’ parameter in the address bar. This is the alias of the content object you are going to access. If you press enter the requested content will show up.

HelpServer content shown in the web browser

The scenario above is of course just for demonstrative purposes. You probably want to use the URL as a link somewhere in your own corporative web pages or perhaps you could paste it into an email to send to your users. The URL can also be used by applications to launch the web browser programmatically.

You can assign multiple aliases to a content object and by assigning an alias to a single topic you gain direct access to that topic. If for example you would assign alias ‘Falcon’ to ‘Topic: About the falcon’ and copy the URL of the ‘Topic: About the falcon’ you can directly open the page ‘About the falcon’ in the web browser.

Notes

 

If you add a new project then two aliases are automatically assigned to the main project folder.

 
 

projectname._MAIN

 

This is a fixed name for the entire project, it cannot be removed. But you can assign other names if required.

 

projectname._ALT

 

During the development and maintenance of a help or documentation project you might remove aliases. Should an application or a web sites use an alias that has been removed ‘behind its back’ then HelpServer will revert to the folder or the topic with the ‘projectname._ALT’ alias assigned to it. By default it is automatically assigned to the main project folder. But you can remove it and reassign it to for example a topic or another folder. If this alias is not available somewhere in the project then a message ‘Information not available’ will be shown.

 

The syntax and guiding lines to construct the URL can be found in Appendix A: The URL parameters .

 

Authoring

 About HelpServer
 Starting up and logging on
 The basic working principles
 Using the content in help and documentation systems
 Working with aliases
 Working with pointers
 Building a context sensitive, web based help system
 Including the HelpServer content in your website
 Working with resource IDs
 Formatting the content
 Searching and replacing text
 Reusing content with shares
 Navigating with hyperlinks
 Navigating with pointerpaths
 Using bookmarks and jumps
 Duplicating content with clones
 Using tables
 Including media files
 Navigating to web pages
 Using embedded chunks
 Including html code
 Navigating with menus
 Using snippets
 Spelling checking
 Using the view mode
 Creating an index
 Creating a FAQ
 Creating a glossary
 Team authoring
 Working with projects
 Setting up structured authoring
 Generating file based output
 Creating printed output
 Importing files and folders
 Loading files in the project gallery
 Converting legacy content
 Including legacy content in real time
 Transferring objects between installations
 Smartcontent
 Notification
 Feedback
 Translating
 Customizing the look and feel
 User accounts
 Security
 Working with templates
 Working with metadata
 Versioning
 Auditing
 Workflow management
 Annotations
 Using event exits
 Appendix A: The URL parameters
 Appendix B: The object indicators
 Appendix C: Play Javascript