Context sensitive help
Donate to this project
Development Project Status: Completed
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 | |||
Comments
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:
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:
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:
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