The ARK Help System

From ARK
Revision as of 16:56, 4 July 2014 by Guy (talk | contribs)

Jump to: navigation, search

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 at all 4 help levels as follows.

Page Level

In the page settings (NOT IMPLEMENTED)

Item level

Turn on op_help in the record nav, so that would be $conf_entry_nav for the data entry pages. This will enable the help button in the record nav and set up the help to work properly.

This will then try to find markup with a nickname for that page view and that type of item:

  • detfrm_cxt
  • regist_cxt
  • etc.

This then includes the relevant markup.

Subform Level

Default behaviour in subforms is to list the help for each field in the subform. To overide this and just use a single arbitrary piece of markup, use:

  • op_help_nname => 'markupnickname',

Place this on the sf_conf and specifiy the nickname of the markup you wish to use.

To turn the help button on and off in the sfNav set the sf_nav_type to one of the options that include help.

Field Level

In the field settings (NOT IMPLEMENTED)

For all levels

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

$conf_mcd_help =
        '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' =>

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:

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 at the subform level 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