Difference between revisions of "The ARK Help System"

Revision as of 16:04, 4 July 2014

As of version 1.2 - a contextual help system has been introduced to ARK.

The help system works by using the Markup system to display help relevant to the context. There are 4 contexts in which help might be displayed, these are:

• Page Level - ie to help users understand how a page works
• Record level - to help users understand the specifics of a record (context, plan, photo etc.)
• Subform Level - to provide inline help for specific subforms
• Field Level - to provide help relating to a specific field

The help is displayed using a subform (sf_help.php) which can be either placed "inline" in the page or within an overlay. By default the help buttons fire an overlay, javascript is required to show or hide the inline help panels

By default, help is OFF. You enable help using op_help at all 4 help levels.

• Page Level - in page settings (NOT IMPLEMENTED)
• Record level - in the record nav settings
• Subform Level - in the sf_conf
• Field Level - in the field conf (NOT IMPLEMENTED)

Beyond this, there is very little configuration needed to enable the help system. The most important thing is to configure an sf_conf:

Configuring the subform

A new subform conf will need to be entered in the page_settings.php file:

$conf_mcd_help =
    array(
        'view_state' => 'max',
        'edit_state' => 'view',
        'sf_nav_type' => 'nmedit',
        'sf_title' => 'help', 
        'sf_html_id' => 'help', // Must be unique
        'script' => 'php/subforms/sf_help.php',
        'op_modtype' => FALSE, //if each modtype uses same fields (see below)
        'fields' =>
            array(
        )
);

This needs to be named $conf_mcd_help, otherwise the help system will not be able to find it. The subform has one 'op' value that can be applied:

'op_textile' => TRUE

If this op is specified, then the help will be printed using the Textile tool - which means it can be used to print complex formatted HTML (along with images, etc.). For more information on Textile see this link: http://txstyle.org/

Configuring the navigation

The help is launched using an icon (anchor tag) in the title bar of the area you want help for (eg the record nav or the sf nav).

To turn the help button on in the record nav, set this up in the record nav conf.

To turn on the help button for sf_nav, set this up in the sf_conf 'sf_nav_type' configuration option. Currently the help icon will appear when sf_nav_type is set to 'full' or 'help'.

Other things to bear in mind

The help uses the Markup system to attach the help to the fields. Therefore, the contents of the help can either be edited directly from the help subform - or using the Markup Admin tools. By default the system assumes the nickname of the markup is 'help_' concatenated onto whatever the field_id is. For instance, the help for a field with id 'conf_field_description' would be 'help_conf_field_description'. It is possible to specify a different nickname, by including the option 'op_help_nname' in the field and setting a new nickname.

As the names for the nicknames of the markup are usually help_ prefixed on the name of the field - the length of the nname field in cor_tbl_markup maybe too short. If you get an Error when updating or adding help related to the size of the field in the database then run this SQL command to fix it:

ALTER TABLE `cor_tbl_markup` CHANGE `nname` `nname` VARCHAR( 255 ) CHARACTER SET utf8 COLLATE utf8_unicode_ci NOT NULL DEFAULT