Rhapsody allows you to define your own custom properties (either through a PRP file or through the Features view). These are very useful particularly if you create your own profiles or helpers. But how do you let your users know what those properties are for ?
Rhapsody provides a context sensitive help panel at the bottom of the Features window (on the properties tab) and most of the out of the box properties have help descriptions. But did you know that you can add your own for your custom properties ?
Writing the Help File
The first thing to note is that the property help file is an xml file and it must have the same name as the Subject you are describing. (for example if your profile has a new Subject MyHelper then your help file will be MyHelper.xml). If your property file introduces several subjects then you will need to supply several property help files.
The easiest way to write one is to copy one of the existing files from Rhapsody/Doc/PropertyHelp - you will see how the sections in the XML map to the Subject, Mertaclass and Property values.
Loading the Help File
The help file is loaded using another property: Model.Profile.AdditionalPropHelpLocation but the location of the file is critical. I've already mentioned that the name of the file must match the profile name but here are the additional options and constraints:
First, in the property above you supply a path. That path may be:
- Hard Coded (e.g. c:/xxx)
- Relative to a variable (e.g. $OMROOT/xxxx)
- Relative to the Profile (the sbsx file)
Second, when Rhapsody looks for the help file it takes your path and adds /PropertyHelp/<lang> (e.g. /PropertyHelp/EN for english) so make sure you put your files in those sub folders.
If a Profile called Profile1.sbsx was in Rhapsody\UserShare\Profiles\MyProfile and the english version of the Profile1.xml property help file was in Rhapsody/UserShare/Profiles/MyProfile/Doc/PropertyHelp/EN
Then you could set the Model.Profile.AdditionalPropHelpLocation property to:
or you could set it to simply:
Which would be a relative path to the sbsx file. In both cases when Rhapsody goes looking for the help file, it adds /PropertyHelp/<lang> to the path.