Making your own documentation available in Asta Powerproject

You can make your own documentation available in Asta Powerproject by editing an XML file - ribbon_help.xml, which is located by default in the folder into which Asta Powerproject is installed - and entering details of the documents that you want to make available into the file. As well as being able to make specific items of documentation available - for example, a specific PDF file, Microsoft Word document or URL - you can make available all of the documents of a particular type in a specific folder. For example, if you wanted to make a number of PDF files available, you could place them all in a single folder and specify that all PDFs within the folder should be made available in Asta Powerproject. You can also apply different icons to the items of documentation that you choose to make available.

Each item of documentation that you make available appears on the Help tab of the Backstage view. You can configure ribbon_help.xml to display the documents on the Help tab of the Backstage view in groups, which can be expanded and contracted. This enables you to group sets of related documents together logically. When you click a document, it opens in whichever application is associated with that file type. For example, PDF files will typically open in Adobe Acrobat.

You cannot make your own documentation available in Asta Powerproject SaaS.

Editing ribbon_help.xml to make your own documentation available

Ribbon_help.xml is located by default in the folder into which Asta Powerproject is installed, although it is possible to specify a different location for the file - and a different file name, if required - by editing the registry.

To specify a different location and file name for ribbon_help.xml, add a string value called DynHelpRibbon to the HKEY_LOCAL_MACHINE\SOFTWARE\Asta\PowerProject TeamPlan\1.0\Misc\ registry key and enter the required location and file name into the value.

The location that you specify can be on a network drive. You may wish to specify a location on a network drive if you wish to edit a single copy of ribbon_help.xml and make it available to all of the clients in an Asta Enterprise installation. Note that if you are administering a large number of Asta Powerproject clients on a domain, you may want to edit the registry key via Group Policy.

For example, to change the location to C:\Elecosoft XML Files\ and keep the file name unchanged, create the DynHelpRibbon string value and enter the following into it:

C:\Elecosoft XML File\ribbon_help.xml

To change the location to T:\Elecosoft XML Files\ and change the file name to elecosoft_extra_docs_ribbon_mode.xml, create the DynHelpRibbon string value and enter the following into it:

T:\Elecosoft XML Files\elecosoft_extra_docs_ribbon_mode.xml

You can edit ribbon_help.xml using any XML editing application, or using a simple tool such as Notepad. It is advisable to make a copy of the original ribbon_help.xml file before editing it, so that you can return to the original file if necessary. When editing ribbon_help.xml, you can add new groups of documents and edit or delete any existing groups of documents.

Backup copies of ribbon_help.xml are made automatically whenever you launch Asta Powerproject after having edited the XML file. These backup copies are saved into your Documents library folder, with the date and time on which they were last edited included in the file name. For example, if you were to edit ribbon_help.xml on 14 November 2019 at 09:40, when you next launched Asta Powerproject a copy of this file would be made and saved with a file name such as ribbon_help 14-11-2019 11-29-14.xml (the last three numbers in the file name indicate the time at which the file was last edited). These automatic backups can be useful when you upgrade Asta Powerproject to a later version, as future versions of Asta Powerproject may include updated ribbon_help.xml files which will overwrite the original file that you may have edited. If an upgrade does overwrite your edited version of ribbon_help.xml, you can retrieve a backup copy from your Documents library folder and replace the updated version with it.

Illustration of a sample ribbon_help.xml

The following illustration shows a sample ribbon_help.xml file, as it might appear if it were opened in Notepad. The illustration is colour-coded; refer to the table beneath the illustration for an explanation of the various elements of the XML file:

Illustration of a sample ribbon_help.xml

Explanation of the elements of ribbon_help.xml

  The first line of the XML file and the opening and closing tags of its root element, taskpanel. You must not edit the first line or the opening and closing lines of the taskpanel element.
 

The imagefile element. Each helpitem element, except those with a Type of "file", refers to an icon within an image strip file. The imagefile element is optional and can be included if you want to use icons in an image strip file of your own, rather than using the icons that are provided by default.

 

If you do wish to use your own image strip file, this element must refer to a BMP file that contains a strip of icons. If the location is not specified, it is assumed that the image strip file is located in the same folder as ribbon_help.xml. Each icon in the file must be 16 x 16 pixels in size (resulting in a file with a height of 16 pixels and a width of a multiple of 16 pixels). Whichever colour is applied to the top-left pixel in the file will appear as transparent when the images are displayed.

 

The icons that are provided by default are illustrated below:

 

Default help icons

 

A group element with a ContentType of "static", containing a number of subordinate helpitem elements. Ribbon_help.xml can contain any number of "static" group elements and each "static" group element can contain any number of helpitem elements.

 

Each "static" group element relates to a group of documents on the Help tab of the Backstage view.

 

"Static" group elements have the following attributes:

  • ContentType - a text string, always set to "static", which defines this as a group on the Help tab of the Backstage view that contains a number of specific documents, rather than as a group that contains all of the documents of a particular type in a specific folder.
  • Caption - a text string that defines the title of the group as it should appear on the Help tab of the Backstage view.
  • Description - a text string that defines the text that should appear in a popup when users hover the mouse pointer over the title of the group on the Help tab of the Backstage view. This attribute is optional.
  • Expanded - a number that indicates whether the group should be displayed expanded (open) or contracted (closed) on the Help tab of the Backstage view. Set this to "0" to display the group contracted; or "1" to display it expanded.
 

A helpitem element within a group element with a ContentType of "static". Each helpitem element relates to a single document within the group.

 

helpitem elements have the following attributes:

  • Caption - a text string that defines the title of the document as it should appear on the Help tab of the Backstage view.
  • Description - a text string that defines the text that should appear in a popup when users hover the mouse pointer over the title of the document on the Help tab of the Backstage view. This attribute is optional.
  • Type - a text string that defines the type of document: set this to "file" for the helpitem element to link to a document of any type; "help" for it to link to a CHM file; "mail" for it to provide a hyperlink that creates an email to a specific email address; or "url" for it to link to a URL, either on the Internet or on an Intranet.
  • Filename - a text string, used only for helpitem elements with a Type of "file", that defines the file name of the file and (optionally) its location. If the location is not specified, it is assumed that the document is located in the same folder as ribbon_help.xml.
  • Help - a text string, used only for helpitem elements with a Type of "help", that defines the file name of the CHM file and (optionally) the location of the file and the topic within the CHM file that should appear when the CHM file is launched. If the location is not specified, it is assumed that the CHM file is located in the same folder as ribbon_help.xml.

    If you want to specify the topic that should appear when the CHM file is launched, you do this by appending two colons to the file name of the CHM file, followed by the location of the topic within the source HTML Help project and the topic's file name, as in the following example:

    Help="powerproject.chm::/HTML Topics/Other/Support.htm"

    In order to know this information, you must be aware of the structure of the source HTML Help project.
  • MailTo - a text string, used only for helpitem elements with a Type of "mail", that defines the email address to which the email that appears should be addressed.
  • Url - a text string, used only for helpitem elements with a Type of "url", that defines the URL of the webpage that should be launched.
  • IconId - a number, used for all helpitem elements except those with a Type of "file", that indicates which icon from an image strip to display to the left of the document. If the XML file does not include an imagefile element, icons from the default image strip are used; otherwise, icons from the file specified in the imagefile element are used. Set this to "0" to refer to the first icon in the file; "1" to the second; "2" to the third; and so on.

You do not specify icons for helpitem elements with a Type of "file"; the icon that appears to the left of each document is determined automatically by the type of document.
 

A group element with a ContentType of "dynamic". Ribbon_help.xml can contain any number of "dynamic" group elements.

 

Each "dynamic" group element relates to a group of documents on the Help tab of the Backstage view. The documents that are included in the group are defined by the Folder and Extension attributes: you do not specify documents individually with this type of group.

 

Each "dynamic" group element can optionally contain one or more subordinate iteminfo elements.

 

"Dynamic" group elements have the following attributes:

  • ContentType - a text string, always set to "dynamic", which defines this as a group on the Help tab of the Backstage view that contains all of the documents of a particular type in a specific folder, rather than as a group that contains a number of specific documents.
  • Caption - a text string that defines the title of the group as it should appear on the Help tab of the Backstage view.
  • Description - a text string that defines the text that should appear in a popup when users hover the mouse pointer over the title of the group on the Help tab of the Backstage view.
  • Folder - a text string that defines the location of the folder in which the documents to include in the group are located. For example, you could set this to "C:\My Documentation" or "T:\Elecosoft Documents". This attribute is optional; if you do not specify a folder, it is assumed that the documents are located in the same folder as ribbon_help.xml.
  • Extension - a text string that defines the type, or types, of document in the specified folder to include in the group. If you specify more than one type of document, you must separate the types using a semi-colon. For example, set this to "pdf" to include all PDF files; "doc;docx" to include all Microsoft® Word documents; "pdf;doc;docx" to include all PDF files and Microsoft® Word documents; and so on.
  • Expanded - a number that indicates whether the group should be displayed expanded (open) or contracted (closed) on the Help tab of the Backstage view. Set this to "0" to display the group contracted; or "1" to display it expanded.

You do not specify icons for the documents that are included in "dynamic" groups; the icon that appears to the left of each document is determined automatically by the type of document.
 

An iteminfo element within a group element with a ContentType of "dynamic". Each iteminfo element contains information relating to a single document within the group. As you do not specify which documents are contained within "dynamic" groups individually, you do not have to include any iteminfo elements, but you may wish to do so to specify the way in which one or more particular documents within a "dynamic" group are displayed.

 

iteminfo elements have the following attributes:

  • Filename - a text string that defines the file name of the file about which to specify additional information.
  • Alias - a text string that defines the title of the document as it should appear on the Help tab of the Backstage view - if you do not specify an alias, documents within "dynamic" group elements are identified on the Help tab of the Backstage view using their file name.
  • Description - a text string that defines the text that should appear in a popup when users hover the mouse pointer over the title of the document on the Help tab of the Backstage view.

How the Help tab of the Backstage view would appear with the example ribbon_help.xml file above

If the above sample ribbon_help.xml file were used, the Help tab of the Backstage view would appear as illustrated below (note that the Manuals group would initially appear contracted):

How the Help tab of the Backstage view would appear

The following sections describe how to edit ribbon_help.xml to make specific documents, or groups of documents, available in Asta Powerproject.

To make a group of specific documents available - for example, specific PDF files, Microsoft Word documents or URLs - you need to create a group element with a ContentType of "static" within ribbon_help.xml, then create a number of subordinate helpitem elements within the group element, one helpitem element for each document within the group.

"Static" group elements have the following attributes:

  • ContentType - a text string, always set to "static", which defines this as a group on the Help tab of the Backstage view that contains a number of specific documents, rather than as a group that contains all of the documents of a particular type in a specific folder.
  • Caption - a text string that defines the title of the group as it should appear on the Help tab of the Backstage view.
  • Description - a text string that defines the text that should appear in a popup when users hover the mouse pointer over the title of the group on the Help tab of the Backstage view. This attribute is optional.
  • Expanded - a number that indicates whether the group should be displayed expanded (open) or contracted (closed) on the Help tab of the Backstage view. Set this to "0" to display the group contracted; or "1" to display it expanded.

An example "static" group element (without any subordinate helpitem elements) is illustrated below:

An example "static" group element (without any subordinate helpitem elements)

See the following sections for details of how to populate the group with individual documents.

To make a specific file of any type available, you first need to create a group element with a ContentType of "static" within ribbon_help.xml (as described above), then create a subordinate helpitem element within the group element that relates to the file. If the group element to which you want to add the file already exists, you do not need to create another group element; simply add a helpfile element to the existing group element.

helpitem elements that relate to files of any type have the following attributes:

  • Caption - a text string that defines the title of the document as it should appear on the Help tab of the Backstage view.
  • Description - a text string that defines the text that should appear in a popup when users hover the mouse pointer over the title of the document on the Help tab of the Backstage view. This attribute is optional.
  • Type - a text string that defines the type of document: set this to "file".
  • Filename - a text string, used only for helpitem elements with a Type of "file", that defines the file name of the file and (optionally) its location. If the location is not specified, it is assumed that the document is located in the same folder as ribbon_help.xml.

You do not specify icons for helpitem elements with a Type of "file"; the icon that appears to the left of these documents is determined automatically by the type of document.

Two example helpitem elements that relate to specific files within a "static" group element are illustrated below. As no location is specified in the Filename attribute of the first example helpitem element, it is assumed that the file is located in the same folder as ribbon_help.xml:

Two example helpitem elements that relate to specific files within a "static" group element

To make a specific CHM (HTML Help) file available, you first need to create a group element with a ContentType of "static" within ribbon_help.xml (as described above), then create a subordinate helpitem element within the group element that relates to the CHM file. If the group element to which you want to add the CHM file already exists, you do not need to create another group element; simply add a helpfile element to the existing group element.

helpitem elements that relate to CHM files have the following attributes:

  • Caption - a text string that defines the title of the document as it should appear on the Help tab of the Backstage view.
  • Description - a text string that defines the text that should appear in a popup when users hover the mouse pointer over the title of the document on the Help tab of the Backstage view. This attribute is optional.
  • Type - a text string that defines the type of document: set this to "help".
  • Help - a text string, used only for helpitem elements with a Type of "help", that defines the file name of the CHM file and (optionally) the location of the file and the topic within the CHM file that should appear when the CHM file is launched. If the location is not specified, it is assumed that the CHM file is located in the same folder as ribbon_help.xml.

    If you want to specify the topic that should appear when the CHM file is launched, you do this by appending two colons to the file name of the CHM file, followed by the location of the topic within the source HTML Help project and the topic's file name, as in the following example:

    Help="powerproject.chm::/HTML Topics/Other/Support.htm"

    In order to know this information, you must be aware of the structure of the source HTML Help project.
  • IconId - a number, used for all helpitem elements except those with a Type of "file", that indicates which icon from an image strip to display to the left of the document. If the XML file does not include an imagefile element, icons from the default image strip are used; otherwise, icons from the file specified in the imagefile element are used. Set this to "0" to refer to the first icon in the file; "1" to the second; "2" to the third; and so on.

Two example helpitem elements that relate to specific CHM files within a "static" group element are illustrated below. As no location is specified in the Help attribute of the second example helpitem element, it is assumed that the CHM file is located in the same folder as ribbon_help.xml. Note that the second example helpitem element refers to a particular topic within the CHM file:

Two example helpitem elements that relate to specific CHM files within a "static" group element

Note that it is also possible to make CHM (HTML Help) files available using helpitem elements with a Type of "file". However, if you do this, you are unable to use the Help attribute described above to specify the topic within the CHM file that should appear when the CHM file is launched.

To create a hyperlink that creates an email to a specific email address, you first need to create a group element with a ContentType of "static" within ribbon_help.xml (as described above), then create a subordinate helpitem element within the group element that relates to the hyperlink. If the group element to which you want to add the hyperlink already exists, you do not need to create another group element; simply add a helpfile element to the existing group element.

helpitem elements that relate to email-creating hyperlinks have the following attributes:

  • Caption - a text string that defines the title of the document as it should appear on the Help tab of the Backstage view.
  • Description - a text string that defines the text that should appear in a popup when users hover the mouse pointer over the title of the document on the Help tab of the Backstage view. This attribute is optional.
  • Type - a text string that defines the type of document: set this to "mail".
  • MailTo - a text string, used only for helpitem elements with a Type of "mail", that defines the email address to which the email that appears should be addressed.
  • IconId - a number, used for all helpitem elements except those with a Type of "file", that indicates which icon from an image strip to display to the left of the document. If the XML file does not include an imagefile element, icons from the default image strip are used; otherwise, icons from the file specified in the imagefile element are used. Set this to "0" to refer to the first icon in the file; "1" to the second; "2" to the third; and so on.

An example helpitem element that relates to an email-creating hyperlink within a "static" group element is illustrated below:

An example helpitem element that relates to an email-creating hyperlink within a "static" group element

To create a link to a URL, you first need to create a group element with a ContentType of "static" within ribbon_help.xml (as described above), then create a subordinate helpitem element within the group element that relates to the hyperlink. If the group element to which you want to add the hyperlink already exists, you do not need to create another group element; simply add a helpfile element to the existing group element.

helpitem elements that relate to URL hyperlinks have the following attributes:

  • Caption - a text string that defines the title of the document as it should appear on the Help tab of the Backstage view.
  • Description - a text string that defines the text that should appear in a popup when users hover the mouse pointer over the title of the document on the Help tab of the Backstage view. This attribute is optional.
  • Type - a text string that defines the type of document: set this to "url".
  • Url - a text string, used only for helpitem elements with a Type of "url", that defines the URL of the webpage that should be launched.
  • IconId - a number, used for all helpitem elements except those with a Type of "file", that indicates which icon from an image strip to display to the left of the document. If the XML file does not include an imagefile element, icons from the default image strip are used; otherwise, icons from the file specified in the imagefile element are used. Set this to "0" to refer to the first icon in the file; "1" to the second; "2" to the third; and so on.

An example helpitem element that relates to a URL hyperlink within a "static" group element is illustrated below:

An example helpitem element that relates to a URL hyperlink within a "static" group element

To make available all of the documents of a particular type in a folder - for example, a number of PDF files - you need to create a group element with a ContentType of "dynamic" within ribbon_help.xml that specifies the folder in which the documents are located and the type - or types - of document to include in the group.

"Dynamic" group elements have the following attributes:

  • ContentType - a text string, always set to "dynamic", which defines this as a group on the Help tab of the Backstage view that contains all of the documents of a particular type in a specific folder, rather than as a group that contains a number of specific documents.
  • Caption - a text string that defines the title of the group as it should appear on the Help tab of the Backstage view.
  • Description - a text string that defines the text that should appear in a popup when users hover the mouse pointer over the title of the group on the Help tab of the Backstage view.
  • Folder - a text string that defines the location of the folder in which the documents to include in the group are located. For example, you could set this to "C:\My Documentation" or "T:\Elecosoft Documents". This attribute is optional; if you do not specify a folder, it is assumed that the documents are located in the same folder as ribbon_help.xml.
  • Extension - a text string that defines the type, or types, of document in the specified folder to include in the group. If you specify more than one type of document, you must separate the types using a semi-colon. For example, set this to "pdf" to include all PDF files; "doc;docx" to include all Microsoft® Word documents; "pdf;doc;docx" to include all PDF files and Microsoft® Word documents; and so on.
  • Expanded - a number that indicates whether the group should be displayed expanded (open) or contracted (closed) on the Help tab of the Backstage view. Set this to "0" to display the group contracted; or "1" to display it expanded.

An example "dynamic" group element is illustrated below:

An example "dynamic" group element

Although you do not specify documents individually with this type of group - the documents that are included in the group are defined by the Folder and Extension attributes of the group element itself - you may wish to specify the way in which one or more particular documents within the group are displayed. For each document that will be displayed, you can specify a title to be displayed on the Help tab of the Backstage view and text that should appear in a popup when users hover the mouse pointer over the title of the document. To do this, you need to add subordinate iteminfo elements - one for each document about which you want to specify information.

Iteminfo elements have the following attributes:

  • Filename - a text string that defines the file name of the file about which to specify additional information.
  • Alias - a text string that defines the title of the document as it should appear on the Help tab of the Backstage view - if you do not specify an alias, documents within "dynamic" group elements are identified on the Help tab of the Backstage view using their file name.
  • Description - a text string that defines the text that should appear in a popup when users hover the mouse pointer over the title of the document on the Help tab of the Backstage view.

An example "dynamic" group element with two subordinate helpitem elements is illustrated below:

An example "dynamic" group element with two subordinate helpitem elements

Related Topics:

Introduction to the Backstage view