Web Applications - Custom Help Windows

To purchase this Feature Pack, please click here.

 

Watch Video - Part 1

Watch Video - Part 2

Watch Video - Part 3

Watch Video - Part 4

Watch Video - Part 5

Watch Video - Part 6

 

The Custom Help Windows Feature Pack allows you to create help windows for the Grid components in your Application.

 

Here are some of the things you can do with the Custom Help Windows Feature Pack:

The custom help messages are read from a database table (either a .dbf or SQL table). This means you can dynamically edit the help contents after the application has been published by edited the records in the Help Table. For example, you could easily create a Grid component to display the records in the Help Table. Multiple Grids can share the same Help Table, so help topics that are common to multiple Grids only need to be defined once.

When you display a Help Topic you can automatically display help in the appropriate language, based on the current 'active language'.

When you define a Help Topic you can use special commands (directives) in the help text to dynamically generate parts of the help text. This would allow (for example), different help to be displayed depending on whether the logged on user was an administrator, or a manager.

 

Turning on Help in the Grid, Search and Detail View Toolbars

To turn on the Help Window for the Grid, Search and Detail View toolbars, check the Help window property. The location of this property in the builder is shown in the three screenshots below.

Grid Part

 

Search Part

 

Detail View Part

 

Here is how the Grid toolbar appears when the Help window has been turned on:

 

Defining a Help Source

Before you can define any Help Topics, you must define the Help Source. This is the table that contains the help text. It can be either a .dbf table, or a SQL table.

You can use any table you want, or you can click the 'Create Help Table' hyperlink and Alpha Five will create the help table for you (either a .dbf table or SQL table - depending on the setting of the Table Type property at the time you click the hyperlink).

If you want to use a table that you created, you will need to specify which field in your table is the 'Id' field (this must be a character field with a width of at least 60 characters) and which field is the 'Help text' field (this must be a long text, or memo field).

To bring up this dialog, go to Grid Properties, Miscellaneous, Help Table Definition.

NOTE: When you are defining the Help Id for any Help Topic (see image in next section), you can also click a button to get to this dialog.

Defining the Help ID for a Help Topic

Once you have defined the Help Source for all of the Help in your Grid, you can specify the Help Id for a topic. The Help Id is the 'key' into the Help table.

After you have specified the Help Id, you can edit the Help Text for this Id by clicking the 'Edit Help Text for this Help Id' button.

You can also browse existing Help Ids and their corresponding Help Text by clicking on the 'Browse Existing Help Topics' button.

 

Editing Help Text

When you click the 'Edit Help Text for this Help Id' button in the Help Id dialog an editor opens where you can enter the help text. The help text is HTML. It can include any HTML markup that you want, including links to other pages, embedded videos, etc. You cannot include a <head> section. If you link to another page, it is recommended that your open the target page in a new browser window by using the target="_blank" attribute in your link. For example:

<a href="someotherpage.a5w" target="_blank">Link to another topic</a>

 

When you are editing the Help Text html, you can click the 'HTML Editor' to switch the built-in HTML editor in Alpha Five.

Your help text can include special directives. These directives are used to set the size of the window that displays the help, the window title, the language of the help text, etc. See the section below on 'Help Text Directives'.

Multiple Languages

If you have defined a multi-language application, you will want your help text to be displayed in the appropriate language. See the section below on 'Help Text Directives' for information on how to define multiple versions of your help text for different languages.

 

Field Level Help

You can define help for individual fields in your Grid. To define help for a field, check the Has help property in the 'Display settings' section of the Property Grid.

When you turn on help, you can then specify the Help Id for the help topic and you can set the Show help icon property. The choices for this property are None, LeftOfControl or RightOfControl.

If the property is set to 'None' then the help will be displayed when the user presses the F1 key while the field has focus.

 

 

 

Here is how a field appears when the help icon is turned on:

 

If the field help is configured to display to the left or right of the control, then a new property, 'Help icon behavior' is exposed. The options are 'Show help on click' and 'Show help on mouse over'.

If you set the option to 'Show help on mouse over', it is strongly recommended that you set the Field Help Window Style property to 'dropdown' or 'dropdown-resizeable'. With the style set to 'dropdown', the help window open up directly under the field, rather than in the center of the screen.

Field Help Window Style

To set the Field Help Window Style, go to the Grid Properties pane and set the 'Field help window style' property.

 

 

Field Help Icon

You can set the icon that is used for field level help by clicking the smart field on the 'Customize icons' property in the Grid Properties pane.

New Action Javascript Actions

If you have the Custom Help Windows Feature Pack installed, there is a new action in Action Javascript called 'Open a Help Window'.

This action allows you to open a help window in response to any Javascript event. As with the other Help features, you simply specify the Help Id of the topic you want to display.

 

Help Text Directives

When you create the HTML help for a help topic, you can include the following directives in the text:

{LanguageStart:language name}
This directive allows you to define help text for multiple languages. For example if the active language for your application is French, then the Help Text that is between these directives will be shown:

{LanguageStart:French}
French help text goes here
{LanguageEnd}

You can include as many language directives in the help text as you want. For example, you might include a directive for French, German and Spanish help.
If the active language is not set, the help text that is OUTSIDE any {LanguageStart}/{LanguageEnd} directives will be shown.
For more information on setting the active language, see 'Setting the Active Language' below.

 

{WindowTitle:title}
Allows you to customize the title of the window in which the help text is shown. You can set the window title outside any {LanguageStart} directives, or inside a {LanguageStart} directive. This allows you to set a different window title depending on what the active language is. Example:
{WindowTitle:Help for the Customer Address Field}
If the title start with an = sign, it is assumed to be an expression. Example:
{WindowTitle:=session.var1}


{WindowSize:width,height}
Allows you to override the default window size and set a custom window size. Use CSS syntax for the size. Specify width, then height.

Example:
{WindowSize:6in,3in}


{ConditionStart:condition Id:logical expression}
Allows you to conditionally include text. The text is included only if the logical expression is true. Conditions can be nested (i.e. you can have sub-conditions within a conditional section). The condition Id is an arbitrary text string to identify the condition. The same Id must be used in the closing {ConditionEnd} directive.

Example:

{ConditionStart:abc:session.variable1="alpha"}
Here is some text that will only be included if session.variable1 is equal to 'alpha'
{ConditionEnd:abc}

{ExecuteFunction:function name}
Allows you to call an Xbasic Function that was defined in the component. The text returned by this function is included in the Help text.

Example:
{ExecuteFunction:myXbasicFunction}
 

The Xbasic Function must have this prototype:
function myXbasicFunction as c (e as p)
end function

The 'e' object that is passed into the function contains several objects. You can put a debug(1) statement into the function, and then run the component in Working Preview mode to examine the contents of 'e' in the debugger.

 

Setting the Active Language

If you don't specify an active language, the <Default> language is assumed. To set the active language, you set the 'ActiveLanguage' property for your component at run-time. You can set this property in the 'Override Settings' section in the .A5W page that loads the Grid, or in the Grid component's OnGridInitialize event.

For example, to set the ActiveLanguage in the OnGridInitialize event:

e.tmpl.ActiveLanguage = "French"

A second way to set the active language is by using the special protected session variable, session.__protected__activeLanguage. For example:

session.__protected__activeLanguage = "French"

 

If you set both the session.__protected__activeLanguage and the 'ActiveLanguage' property in Override Settings or OnGridInitialize, the session.__protected__activeLanguage property is honored.