Authoring - Setting up folder classes and topic classes

To explain the use of folder classes and topic classes, we will redevelop the previous example project ‘Animal information’. You will have to start up a new project but first you need to define the project's folder and topic classes based on the following case.

Assume you have a group of authors who need to work on an Encyclopedia project that contains information about birds, fishes, and plants (to keep it simple, we’ll stick to three categories).

The Encyclopedia needs to be constructed according to strict rules, I.e an author may not accidentally add plant information to the 'Birds' category. Thus, the Encyclopedia project and its categories (birds, fishes, and plants) have different construction rules and next is the blue print of the content structure.

Encyclopedia -> the main project folder

 

Birds -> category 1

 

 

One bird

 

 

 

Topic that describes the bird

 

 

Another bird

 

 

 

Topic that describes the other bird

 

Plants -> category 2

 

 

One plant

 

 

 

Topic that describes the plant

 

 

Another plant

 

 

 

Topic that describes the other plant

 

Fishes -> category 3

 

 

One fish

 

 

 

Topic that describes the fish

 

 

Another fish

 

 

 

Topic that describes the other fish

You could easily create this structure under ‘Content’ just by selecting ‘New > Folder’ and ‘New > Topic’ functions. However, HelpServer’s default class ‘Folder’ is a generic class, and it is setup to contain many other kinds of folders. The same applies for the class ‘Topic’. A good long-term solution for the Encyclopedia project would be to define new classes. When you define a class you

 

indicate its position in the project structure,

 
 

you define the behavior of the class at its position in the structure.

 

Furthermore, you can reuse a class at different points in the hierarchy. Depending on its position in the structure a class can have another behavior. This approach limits the number of new classes you need to define and it is described in extending the class structure.

By default, creating and changing folder classes and topic classes is an administrator's task, but it can be delegated to the author. This is described in security.

So, by defining classes you define the blueprint of the structure of your project..Let's implement this step by step for the Encyclopedia project. Based on the project case description you need to define the following folder classes:

 

Folder class ‘Encyclopedia’ under ‘Content’ to hold the entire Encyclopedia. This is the main project folder.

 
 

Folder class ‘Birds’ under 'Encyclopedia', to hold all the ‘Bird’ folders.

 
 

Folder class ‘Bird’ under 'Birds' to hold the information about one bird.

 
 

Folder class ‘Fishes’ under 'Encyclopedia' to hold all the ‘Fish’ folders.

 
 

Folder class ‘Fish’ under 'Fishes' to hold the information about one fish.

 
 

Folder class ‘Plants’ under 'Encyclopedia' to hold all the ‘Plant’ folders.

 
 

Folder class ‘Plant’ under 'Plants' to hold the information about one plant.

 

Why do you need a new ‘Encyclopedia’ class? Why not just do a ‘New > Folder’ under ‘Content’ and name it ‘Encyclopedia’? Two reasons:

 1.

Because ‘Folder’ can hold too many other classes (‘Library’, ‘FAQ’, etc.) and we want our Encyclopedia to hold just predefined categories (‘Birds’, ‘Fishes’, and ‘Plants’) and nothing else.

 
 2.

We expect the Encyclopedia project will grow and grow and it will contain a massive amount of files. The generic ‘Folder’ has no project properties and hence you would miss the advantages of working with projects.

 

You could enter text about a bird, a fish, and a plant under the default ‘Topic’ class. Nevertheless, we choose to define new topic classes as well. The reason for this will be explained in using chunks. So, you need to define these topic classes:

 

Topic class ‘Bird topic’ under 'Bird'.

 
 

Topic class ‘Fish topic under 'Fish'’.

 
 

Topic class ‘Plant topic under 'Plant'’.

 

Next is a step-by-step description on creating these folder and topic classes. Keep in mind that you do not create the folder or the topic itself. A class is actually the blueprint for folders and topics to be created afterwards.

Creating the ‘Encyclopedia’ project folder class

Opening the Object classes window

On the Workbench window’s menu bar, select ‘Window > Object classes’.

The Object classes window

On the window that opens, click ‘New folder class’.

The folder-class description

Enter ‘Encyclopedia’ as the class description. Select the ‘Folders of this class are project folders’ option. This option should always be checked if you define the main folder class for a new project. Click ‘Next’ to continue.

The parent-class selection

Next, select the parent of your new class. Since ‘Encyclopedia’ is the main class for our project, you should make sure that ‘Content’ is selected. Click ‘Next’ to continue.

The class properties

On the next pane, accept the defaults and click ‘OK’ to finish the definition of your first new folder class.

The main pane will reappear on the ‘Object classes’ window. We continue creating the subsequent folder classes according to the same working principles.

Creating the ‘Birds’ folder class

The Object classes window

Click ‘New folder class’.

The folder-class description

You do not need to select the ‘Folders of this class are project folders’ options. You are about to create a new subclass under a class that is already a project folder class.

Just enter ‘Birds’ as description and click ‘Next’.

The parent-class selection

The previously defined folder class ‘Encyclopedia’ occurs in the list. By default it is pre-selected to act as the parent class for the next new class. This is exactly what we want: our ‘Birds’ class is immediately dependent on our ‘Encyclopedia’ class. Just click ‘Next’ to continue.

The class properties - multiple occurrences option

On the next pane scroll down and deselect the ‘Multiple occurrences’ option. This prevents authors from adding multiple ‘Birds’ categories in our Encyclopedia.

The class properties - description format

By default, a folder’s name consists of the class description and the folder description you choose when adding it. Since there will be only one ‘Birds’ folder in our Encyclopedia, the folder description doesn't really matter. So, scroll up and deselect ‘Show main description’. Click ‘OK’ and our ‘Birds’ class is defined.

Creating the ‘Bird’ folder class

Now we are going to create a class for each 'Bird' occurrence. Note the difference with the previous class 'Birds': that class is meant to hold all the bird-related content (hence the plural 'Birds').

The folder-class description

Enter ‘Bird’ as description and click ‘Next’.

The parent-class selection

‘Birds’ is preselected in the list and indeed, it is the parent of ‘Bird’. Click ‘Next’ to continue.

The class properties - description format

As you add a folder per bird you will enter the bird’s name as the description. Since we want to see this description, you should leave the ‘Show main description’ option selected. However, we are not interested in seeing the class description as well, so you deselect the option ‘Show class description’. Click ‘OK’ and the ‘Bird’ class is defined.

The 'Bird' topic class

In the previous steps you have defined part of the structure of our project. Now we are going to define the class of the objects to hold the actual content. These are called 'Topic classes'.

The Object classes window

So, click ‘New topic class’ on the start pane of the ‘Object classes’ window.

The topic-class description

Enter ‘Bird topic’ as description and click ‘Next’.

The parent-class selection

The folder class ‘Bird’ will be the one to hold our new topic class, just be careful not to select 'Birds' (plural). Click ‘Next’ to continue.

The class properties

Accept the defaults and click ‘OK’. Our new topic class is defined.

Creating the other classes

Follow the same working principles to define the classes about the ‘Fishes’ category and its dependants and about the ‘Plants’ category and its dependents. Note that when you start defining the ‘Fishes’ folder class and later on the ‘Plants’ folder class you must select the ‘Encyclopedia’ class as parent.

Re selecting the parent class

Create the class structure with care. Its easy to extend the class structure or to change the class behavior but it is not so obvious to change the hierarchic position of a class or to remove a class from the structure or to replace a class by another one once people have added content.

Authoring

 About HelpServer
 Starting up and logging on
 The basic working principles
 Using the content in help and documentation systems
 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
 Overview
 Setting up folder classes and topic classes
 Creating the project
 Changing the class behavior
 Extending the class structure
 Using chunks
 Searching for object classes
 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