Context sensitive help

Donate to this project

Development Project Status: Completed

Total cost estimate (ex-Tax): 
$1510
Due date for completion of this stage: 
26/02/2013
Release: 
1.7
Current Percentage Funded: 
100.00%
Project funding: 

Public pledges can be made to this forum topic or email me directly by clicking here (link only works in the forum).
Development will not commence until fully funded.

Project description: 

This project will add support for context sensitive help to OpenVPMS.

NOTE: it won't provide the actual help documentation, just the facility to access the help.

Help will be provided by external HTML pages. When accessing help for a particular topic, OpenVPMS will check that help for the topic is available. If so, it will launch a new browser window for the topic. If not, it will pop up a message dialog stating that no help exists.

Initially, help will be supported:

  • in each workspace
  • in each dialog

Each workspace and dialog will be assigned a help topic identifier. This will be used to look up a URL or URL fragment in a help.properties file.

This help.properties file can be localised by providing a language specific version e.g. help_fr.properties.

Where a URL fragment is specified, this will be appended to a help.url property.

E.g. given the following:

help.url  = http://www.openvpms.org/documentation/1.7/ 
workspace/customer/charges = customer/charges

The workspace/customer/charges topic identifier will resolve to the URL:

http://www.openvpms.org/documentation/1.7/customer/charges

Context sensitive help will be launched by a keyboard shortcut (e.g. F1).

The following help topic identifiers will be used:

Workspace Help Topics
Topic Identifier Default URL fragment Description
workspace/customer/information customer/information Customer Information
workspace/customer/documents customer/documents Customer Documents
workspace/customer/estimates customer/estimates Customer Estimates
workspace/customer/charges customer/charges Customer Accounts
workspace/customer/payments customer/payments Customer Payments
workspace/customer/account customer/account Customer Accounts
workspace/customer/notes customer/notes Customer Notes & Alerts
workspace/patient/information patient/information Patient Information
workspace/patient/records patient/records Patient Medical Records
workspace/supplier/information supplier/information Supplier Information
workspace/supplier/documents supplier/documents Supplier Documents
workspace/supplier/orders supplier/orders Supplier Orders
workspace/supplier/deliveries supplier/deliveries Supplier Deliveries
workspace/supplier/charges supplier/charges Supplier Charges
workspace/supplier/payments supplier/payments Supplier Payments
workspace/supplier/account supplier/account Supplier Account
workspace/workflow/scheduling workflow/scheduling Scheduling
workspace/workflow/worklists workflow/worklists Work Lists
workspace/workflow/messaging workflow/messaging Messaging
workspace/workflow/investigations workflow/investigations Investigations
workspace/product/information product/information Product Information
workspace/product/stock product/stock Product Stock Management
workspace/reporting/tillbalancing reporting/tillbalancing Till Balancing
workspace/reporting/deposits reporting/deposits Deposits
workspace/reporting/debtors reporting/debtors Debtors
workspace/reporting/workinprogress reporting/workinprogress Work In Progress
workspace/reporting/reminders reporting/reminders Reminders
workspace/reporting/reports reporting/reports Reports
workspace/admininistration/organisation administration/organisation Organisation Administration
workspace/admininistration/types administration/types Types Administration
workspace/administration/templates administration/templates Document Template Administration
workspace/administration/lookups administration/lookups Lookup Administration
workspace/administration/users administration/users User Administration
workspace/administration/groups administration/groups Group Administration
workspace/administration/roles administration/roles Role Administration
workspace/administration/authorities administration/authorities Authorities Administration
workspace/administration/archetypes administration/archetypes Archetype Administration

For dialogs, the archetypes being operated on will be used to derive the topic identifier. This enables documentation for a group of similar archetypes to be directed to the same help URL.

Dialog Help Topics
Topic identifier Default URL fragment Description
party.customerperson/select customer/select Select customer browser
party.customerperson/edit customer/edit Edit customer dialog
party.customerperson/delete customer/delete Delete customer dialog
party.customerperson/merge customer/merge Merge customer dialogs
act.customerDocumentForm/new customer/documents/new New customer document
act.customerDocumentLetter/new
act.customerDocumentAttachment/new
party.patientpet/select patient/select Select patient browser
party.patientpet/edit patient/edit Edit patient dialog
party.patientpet/delete patient/delete Delete patient dialog
party.patientpet/merge patient/merge Merge patient dialog
  etc  

JIRA: https://openvpms.atlassian.net/browse/OVPMS-1294

Comments

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.

Re: Context sensitive help

Tim A: thanks for doing this.  I would appreciate a costing as soon as you think there are no more comments so that I can organise funding.

Question: what happens when one has a 'sub-window' displayed - ie you have pressed "Select" on the Customer/information screen and you have the "Select Customer" window displayed?

Or - on the Select Customer window, you press New to get the New Customer window?

[My preference is that the topic identifier would be customer/information/select and customer/information/new respectively.]

Regards, Tim G

Re: Context sensitive help

I can see that a help topic like customer/information/select is useful, in that it allows you to organise it under a customer/information page, but this operation is applicable to the customer workspace as well as when editing appointments.

I think it would be better to have topic ids based on the current operation. In your documentation you can add hyperlinks as required.

So for customer selection, creation, editing and deletion, you would have:

  • customer/select
  • customer/new
  • customer/edit
  • customer/delete

If the behaviour of a particular operation is different depending which part of the app you are in, then the above isn't going to work as well. E.g. dialogs can have Skip buttons depending on the context.

The other place where this is a little simplistic, is in workflows. Accessing context sensitive help when in a workflow will display document for the current dialog, not the workflow itself.

Re: Context sensitive help

OK - so if there is a 'sub-function' window open, the help topic invoked is still that for the base page (eg customer/accounts), and it is up to the help constructor to have their customer/accounts help with links to help on each of the sub-functions.  What this means is that one's help system needs to have a menu system which closely resembles that of OpenVPMS.

I have also realised that your invoking [url from properties]/topic/subtopic allows me to use default.php in each topic/subtopic folder so that I happily use a php based help system.

Also, because of the required sub-function navigation, we are going to end up with a complete help system that can be used by itself as documention.  Thus, I can build the help system now, knowing that provided I organise its folder structure to match OPV's topic/subtopic structure, then it will be directly usable from OPV.

Do you have any suggestions as to the tools/framework to use? Left to myself I would probably use WeBuilder & Easy Button & Menu Maker - see http://www.blumentals.net/ since these are what I use to build and maintain www.nabiac.com . However, I am cognisant of the fact that it would be better to use a framework that is such that the help system I build could be given to the OPV community.

Regards, Tim G

Re: Context sensitive help

Not quite. Each dialog would have its own help topic identifier.

So when you edit or create a new customer, the help topic identifier would be "customer/edit".

When you select a patient, the help topic identifier would be "patient/select".

I envisaged that this would by default link to pages hosted on OpenVPMS, using a url constructed from a configurable prefix containing the OpenVPMS version, and the topic identifier suffix.

E.g. http://www.openvpms.org/documentation/1.7/customer/edit

An index page could be created that puts the pages in a coherent structure; this could be displayed alongside the context help entry.

It may be desirable to record the context that a dialog was displayed from, e.g if it was in a workflow, and the workspace it was launched from.

In this case, there might be several help topics. E.g. for the select Work List dialog in the Check In workflow on the Scheduling workspace, there are at least 3 possible topics:

  • worklist/select
  • scheduling/checkin
  • workflow/scheduling

In order to present a list of these to select from, there would need to be a facility to map from topic id to help title. This could be done either in:

  • message.properties
    • worklist/select = Select Worklist
    • scheduling/checkin = Checkin Workflow
    • workflow/scheduling = Scheduling
  • parsing the html for a title

The former is simple, but violates the DRY principle. The latter could be implemented as a tool that goes through the list of help topic identifiers, resolves the corresponding html pages, and generates an index.

Re: Context sensitive help

Tim - first let me apologise for the tardy response.  I had not set up notifications of posts to this area - but I now have.

I think that we should go initially without the context sensitive URL selection. I appreciate that some screens show differently depending on context, but I am not convinced that it is necessary to invoke a different URL for each context.  Eg for Patient Select initially displays differently depending on whether or not there is a current customer.

I also forsee a help system that contains a set of pages invoked with the screen help function key, but which would contain a menu that allowed you to navigate a) to other screen help pages; and b) to other reference information (eg how the reminder system works).

Essentially the screen help would tell you about the fields and buttons on the current screen, and the menu would allow to to access the reference information.

Context information: you could provide this via a parameter added to the URL.  The person implementing the help pages could either make use of this or not.

My immediate problem is that I need to build documention for the system in Hong Kong. I started building an OpenVPMS Reference Manual in MS Word, but it struck be that screen level help would be more usable.  I would like to get started on this immediately, but I want to build something that will integrate with OPV's future screen help. Hence the discussion above has been very useful.  However, I do not want to ask for a rolls-royce solution, just something that will invoke a specific URL given the screen you have open.  I want the amount of work required on your part to be as small as possible.

Regards, Tim G 

Syndicate content