User Tools

Site Tools


training:docs_links

This is an old revision of the document!


Help Link Specification

Table of Contents

PURPOSE DESIGN WRITER MODE (HELP) WRITER MODE (PROGRAMMING) USER MODE IMPLEMENTATION WRITER MODE USER MODE LOAD EXISTING HELP CONTEXT ID DATA Help Context IDs from MDB REMOVE CURRENTLY ASSIGNED CONTEXT IDS SETUP FOR HELP-COMPONENT TABLE SETUP FOR HELP-ID TABLE SETUP FOR HELP-LINK TABLE SETUP FOR PROGRAMMING REQUEST TABLE ENVIRONMENT SETUP – TABLE LOCATIONS FUTURE ENHANCEMENTS DEPENDENCY REQUIREMENTS

Purpose

The purpose of this project is to allow technical writers to link up application components such as forms, buttons, tabs, labels to a help file Context ID.

This functionality will also be used to streamline the assignment of simple programming requests (component- specific). These requests would include such things as cosmetic issues (layout problems after translation, form captions not matching help text, typos, etc…) and the ability to link the component to an external file (identifying icons and linking them to their replacement file).

Design

Writer Mode (help)

In writer mode a technical writer will be able to right click on an object to bring up the help context tool. This tool will look similar to the form below.

Help Context Link Component to  Component Name: SystemFive.InvoiceForm.Pagecontrol1.ItemsTab.ItemsGrid  Component Type: TDateSelectionTool [Maintenance] [New] Help Context ID 11240 [Create New] [Test] Help Caption EBT Food Stamp Balance Query [Update] Help Topic ID EBTFoodStampBalanceQuery [Update] What’s This Help ID 11240 [Test] Help Topics – Current Form List of other help topics already on this form [Use for Help Context ID] [Use for What’s This ID] Help Topics – All List of all help topics [Use for Help Context ID] [Use for What’s This ID] [Save & Close] [Cancel]

Link Component to - Component Name includes all parents. Be sure to check for the new HelpFormName property on the form. If it exists it should replace the form name in the parent list in order to identify which purpose the form is serving ( see User Mode below).

Component type is for components common to many forms (ie. lookup words, date selection tool). Component Type is a dropdown box (populated when Component Type is checked off) that contains all component types currently having help assignments.

To edit the list of component types, press the [Maintenance] button for a simple grid view of the existing component type / context ID assignments.

To add an entry to the list of component types, press the [New] button. This will create an entry in the Help-Component table, using the control type name of the current control, and assigning help context id that has been entered. If Help Context ID or Help Topic ID are blank, you can’t add this component to the Help-Component table.

Help Context ID - Text Box (numeric). This number is retrieved from the Help-ID table. If there is not already a help assignment for this component, the designer can type in this number if known, or can press the [Create New] button, which will generate a new Help Context ID.

Press the [Test] button to verify an existing Help-ID table entry for this Context ID, update the Help Caption and Help Topic ID fields, and call the help file to test it.

The Help Topic ID is required prior to creating a new Help Context ID, as it is also a unique identifier for any help record in the Help-ID table. Either identifier (Context ID or Topic ID) can be used to retrieve info from and link to the Help-ID table.

Help Caption – This will be retrieved from the help-link table, and corresponds to the caption of the form/tab being worked on. Updating this info on an existing record will update directly to the Help-ID table, which is the sole storage point for this info.

Help Topic ID – This is a unique value tied directly to the Help Context ID and can be used interchangeably as the unique identifier for help. This needs to be entered prior to creating a new Help Context ID, so that a check for duplicate Help Topic IDs can be performed and/or open this item from the Help-ID table. Updating this info on an existing record will update directly to the Help-ID table, which is the sole storage point for this info.

Help Topics – Current Form – A list of other help topics already on this form, listed by Help Topic ID. By pushing [Use for Help Context ID] or [Use for What’s This ID], the Help Context ID from this related item can then be used as the Help Context ID of the help context definition we’re currently building, or as the Context ID for its What’s This help.

Help Topics – All – Same as ‘Help Topics – Current Form’, except this will list ALL help topics defined anywhere (essentially the Help-ID table).

What’s This Help – Directs the What’s This help to a Help Context ID. Can be zero (no what’s this help), same as component help, or different Context ID. This ID can be set from the ‘Existing current form help’ or ‘All help topics’, or entered manually. Press the [Test] button to verify an existing Help-ID table entry for this Context ID, and call the help file to test it.

[Save & Close] Will save the information to the help table and close the form. [Cancel] Will discard changes and close the form.

Writer Mode (programming)

In writer mode a user will be able to right click on an object to bring up the programming request tool. This will allow specific notes/requests to be attached to a component, or prior requests to be viewed.

Programming Request Link Component to  Component Name: SystemFive.InvoiceForm.Pagecontrol1.ItemsTab.ItemsGrid  Component Type: TDateSelectionTool Request Form caption needs to be “Invoice Form” to match Help Link to File \icons\print.ico [Browse] Programming Requests – Current Form List of programming requests already on this form  Include completed [Open] Status Open / Complete Last Edited 2005/04/29

     [Save & Close]     [Cancel]

Link Component to - Component Name includes all parents. Be sure to check for the new HelpFormName property on the form. If it exists it should be part of the parent list in order to identify which purpose the form is serving ( see User Mode below).

Component type is for components common to many forms (ie. lookup words, date selection tool). Component Type is a dropdown box (populated when Component Type is checked off) that contains all component types currently having help assignments. This list of components is intended mainly for the Help Context tool and can only be modified from the Help Context form.

Request – Details of the request, including the source of the request (ie. Translation or Help project).

Link to File – If the component needs to be link to a file, you can enter or browse to it here. This could be used so a person in Request Mode

Programming Requests – Current Form - A list of other requests already on this form, listed by control + request; any requests for this specific control sorted first. You can choose whether or not to include completed requests in the list by using the ‘Include Completed’ checkbox (default no).

Prior requests can be opened for viewing/editing by pressing [Open]. Current request will not have a unique ID assigned or a record created until you press Save, so you can safely jump other requests without cluttering up the DB with partial entries. You will be warned if you have a request in process and are choosing to load a different request into the form.

Status - Drop down box of the available statuses. • New – New request • Complete – Programming request has been resolved

[Save & Close] Will save the information to the programming request table and close the form. [Cancel] Will discard changes and close the form.

User Mode

When a user presses F1, the system will search for a help entry in the help context table in the following order.

ParentListNames…ComponentName ComponentTypeName

If none found then go to the Component’s Parent and search again based on the above order.

Implementation

Writer Mode

• Compiler Directive - A compiler directive will be added to create a special “Writer” mode to allow right-clicks to bring up the Help Context Form or the Programming Request Form.

• Right-click menu - In design mode, in the wform.OnCreate or wform.OnShow event you need to recursively loop though each component on the form and add right click menu items [Help Context] and [Programming Request]. If there is already an assigned right click menu, you need to add to it, not replace it. See wwgrid for this technology.

• Selecting a component type – If a specific component type is selected, populate the Help Context ID, Help Caption, and Help Topic ID (via the Help Context ID attached to that component type in the Help-Component table)

• Existing help-link data - When the Help Context tool is selected from a component, if it already exists in the Help-Link table, place its information in the Help Context form. Look for it in the Help-Link table first by component name (with parents), then by component type.

Context ID property on component - When the Help Context tool is selected from a component, if there is already a Help Context ID in the component’s properties we know it does not have Help-Link data (the property is cleared when a Help-Link is assigned). Use the Context ID to look in the Help-ID table – if this Context ID exists, open the Help Context form with this Context ID (and caption and Link ID) in place and default to ‘Link to: Component Name’. Write this information to the Help-Link table and clear the Context ID property from the control. If the Context ID from the control’s properties is not found in the Help-ID database, simply remove that property and open the blank Help Context form (see below).

No Context ID property and no Help-Link entry - If this is a brand new help assignment, open a blank Help Context Form. Default to ‘Link to: Component Name’.

• Context ID – Manual Entry - If you manually key in a Help Context ID, press the Test button to ensure that you’ve entered a valid ID and to retrieve it. You can not create a new Context ID record by manually keying the value. Context IDs come only from the initial data load from Help and Manual, or by being generated using the Create New button.

Context ID – Create New - To create a new Help Context ID, you must first enter a Help Topic ID. Then when you press the Create New button for the Help Context ID, it will first check to ensure this Help Link ID hasn’t already been used, and will retrieve it (and its Help Context ID and Caption) if it does exist. If it does not exist, a new Context ID will be generated. Either way, all fields will be saved as a new Help-Link record once the Create process is complete.

• For programming requests, since there can potentially be more than one, open a blank programming request form, and list all existing requests for this form.

• Make sure all edit boxes are pastable.

• Use mouseover tooltip on all text fields (including dropdown lists) to display the text.

User Mode

In user mode (and writer mode), when F1 is pressed (Application.OnHelp event), search for the appropriate help. Update the What’s This help to use it’s appropriate Context ID assignment as well.

In wForm, create a new property called HelpFormName which if assigned will be used as the Form’s Name in the search for the help link. This will allow report such as the aged a/r report which have dual purposes to have different help based on the report being displayed. This property will be set at run-time by the programmer.

Load Existing Help Context ID Data

The “Help and Manual” help designer program produces text and html reports which have been parsed and loaded into a Microsoft Access table. When the help context tool goes live, there will be a one-time import of this data into our Help-ID table. From that point forward, this information will be edited and updated via the help context tool, and the technical writer will need only to use the tool-assigned Context Ids in their help files to maintain integrity. Help Context IDs from MDB Name Type Comment HelpContext Number This is the HelpContext number that is assigned to the Topic in the Help file Caption Text The Caption of the Help Topic: This is also the Keyword TopicID Text The Internal Unique Alpha ID for Help & Manual Type Text One of Chapter, Topic or Anchor LastEdited Date/Time The Date the Topic was last edited

Remove currently assigned context IDs

Any time a component is found to have a help context ID already assigned, remove this from the component’s property. Help will be fired in conjunction with the Help Context table, and for the sake of consistency and clarity we do not want any help context id’s on the components themselves (see Context ID property on component above).

Programming changes will be required to stop the assignment of context ids in code to dynamically created controls.

Setup for Help-Component Table

Name Type Comment ComponentType String[40] Unique (eg. TDateSelectionTool) HelpContextID Integer Links to Help-ID table

Index 0 : ComponentTypeID Index 1 : ComponentName

Setup for Help-ID Table

Name Type Comment HelpContextID Integer Unique HelpCaption String[80] HelpTopicID String[80] Unique

Index 0 : HelpContextID Index 1 : HelpTopicID

Setup for Help-Link Table

Name Type Comment Unique Integer Unique Key ComponentType String[40] Links to Component table FormName String[40] Form Name or HelpFormName ComponentName String[255] List of parent Names eg PageControl1.TabItems.ItemGrid HelpContextID Integer Links to Help-ID table WhatsThisID Integer No, same as ContextID, or diff ContextID

Index 0 : Unique Index 1 : FormName + ComponentName Index 2 : HelpContextID Index 3 : ComponentTypeID

Setup for Programming Request Table

Name Type Comment Unique Integer Unique Key FormName String[40] Form Name or HelpFormName ComponentName String[255] List of parent Names eg PageControl1.TabItems.ItemGrid Request Memo Completed Boolean Completed items won’t be shown on the programming request form by default LastUpdated PervasiveDate

Index 0 : Unique Index 1 : FormName + ComponentName

Environment Setup – Table Locations

Programming Requests Tool - The programming request table will be stored on the Alpha build box and is not a distributed file. This will ensure there is only one copy of it, and that multiple users of it will not overwrite each other. We need to ensure that the pervasive workgroup engine is properly configured on the alpha build box.

Help Context Tool – The help context tables (3) will be stored on the alpha, beta, and release build boxes since there are different versions of help for each. Of the three tables, only Help-Link is a distributed file to enable the new help system. Help-ID and Help-Component tables are for internal use only.

Future Enhancements

• Automation of using the programming requests – hook into bugzilla or its future alternative. Add a bug number and/or status to the form and DB. • Setting the HelpFormName has not been fully addressed. So far we’ve added the property to wForm and use it, but have not specified how it will be set. The most complete proposal involves setting it in the OnEnter event of any multi-purpose control on that form, then clearing it when the control is exited. This would allow the Form.HelpFormName property to correctly identify the help state of any given control in focus. This would require code changes for each individual component that may have multiple help files (ie. AccountFind or LookupWords). The code would be required on every form they exist on, unless an alternative way can address the control itself and apply the HelpFormName property to its parent form dynamically…

Dependency Requirements

• Creation of Three Tables (3 hours) • Import of existing Help Context IDs from MDB (2 hours) • Programming to remove code-based context id assignments (2 hours) • Writer Mode tools (8 hours) • User Mode tool (3 hours) • Setup of versions on Alpha/Beta/Release boxes (2 hours) • Adding functions to final builder and testing building process (2 hours)

Total Time 22 hours.

training/docs_links.1280520488.txt.gz · Last modified: 2010/07/30 13:08 (14 years ago) by charlene