7.6 Module Context Help

For an entity type, there is a Help icon in its Entity/Query/EntityList backing bean, which can open a help page about the entity type.

The help URL of an entity type is

	/help/[locale]/[module]/[typeName].html

The locale is current user locale, module is module name, and typeName is the mapped DataType name of the entity type.

In general, a help URL is of the form:

	/help/[locale]/filePath.html

For an entity type, the file path is [module]/[typeName].

For example, entity type Employee of HR module is mapped to DataType(HR.EMP). Its help page URL for locale zh-Hant-HK is

	/help/zh-Hant-HK/HR/EMP.html

If an entity type does not have a mapped DataType, it will not have a Help page by default. To provide a help page, its EntityBackingBean must override the getHelpPathInfo(PersistenceDataBackingBean backingBean) method.

For example, ExpenseReportQueryForm of the Example HR module is not mapped to a DataType.


public class ExpenseReportQueryFormBean extends ReportQueryFormBean<ExpenseReportQueryForm> {

	@Override
	public HelpPathInfo getHelpPathInfo(PersistenceDataBackingBean<ExpenseReportQueryForm> backingBean) {
		return new HelpPathInfo(HrModule.MODULE_NAME, "expenseReport");
	}
}

The help URL will be /help/[locale]/HR/expenseReport.html.

Help File Mapping

A help URL is mapped to an entry in module JAR. Locale fallback is supported.

Suppose current user locale is zh-Hant-HK, then the URL /help/zh-Hant-HK/filePath.xhtml is mapped in the following order in module jar:

/help/zh-Hant-HK/filePath.html
/help/zh-Hant/filePath.html
/help/zh/filePath.htmlr
/help/filePath.html

The first HTML file found is used as help content for the URL.

Module Help Directory Structure

Under the help directory, one subdirectory for each locale supported. For example, to support locale en, zh and zh-Hant, the directory structure would be:


moduleRootDir
	src/main/resources/
		help/
			zh/
			zh-Hant/

Locale en is the default locale, and its help files are put directly under help/ directory. For each help file, add one for each locale and default. For example, EMP.html,


moduleRootDir
	src/main/resources/
		help/
			contents.xml
			EMP.html
			zh/EMP.html
			zh-Hant/EMP.html

Help file directory can contain subdirectories, for example, put expenseReport.html under the "report" subdirectory:


help/report/expenseReport.html
help/zh/report/expenseReport.html
help/zh-Hant/report/expenseReport.html


public class ExpenseReportQueryFormBean extends ReportQueryFormBean<ExpenseReportQueryForm> {

	@Override
	public HelpPathInfo getHelpPathInfo(PersistenceDataBackingBean<ExpenseReportQueryForm> backingBean) {
		return new HelpPathInfo(HrModule.MODULE_NAME, "report/expenseReport");
	}
}

Help file "help/locale/filePath.html" is mapped to "help/locale/module/filePath.html". That is, module name is inserted after locale and before file path. For example, HR module help files for EMP.html are mapped to the following entry paths in the module HR jar for locale en, zh and zh-Hant.


help/HR/EMP.html
help/zh/HR/EMP.html
help/zh-Hant/HR/EMP.html

Module Help Contents

Each module can have a help contents XML(contents.xml) that will be translated into a tree structure menu. The contents XML for a module is directly under the help directory as shown in the example above.

For example, HR module help contents.xml:


<item name="HR" pathInfo="index">
	<item entityType="EMP" />
	<item entityType="EC" />
	<item name="ExpenseReport" pathInfo="expenseReport" />
</item>

A menu node will be created for each item, and child menu nodes will be created for its child items recursively. For the items with entityType, DataType names are resolved to entity type display names from module implementation.


<menuNode name="HR" link="/help/HR/index.html">
	<menuNode name="Employees" link="/help/HR/EMP.html" />
	<menuNode name="ExpenseClaims" link="/help/HR/EC.html" />
	<menuNode name="ExpenseReport" link="/help/HR/expenseReport.html" />
</menuNode>

Note that the pathInfo in the contents.xml does not have suffixes. The suffix .html will be appended for help URLs.

Relative URL

A help Html file can contain resources with relative URLs. For example, hyperlinks, images, css. Relative URLs will be resolved normally.


<a href="../foo/index.html">About Foo</a>
<img src="images/picture.gif"/>
<link type="text/css" rel="stylesheet" href="theme/foo.css" />

Disable Module Help

By default module help is enabled. To disable the context help of a Module, set the module parameter help.enabled to false in system-config.xml. For example,


<system-config>

  <module name="HR">
     <class>com.cmobilecom.af.example.hr.HrModule</class>
     <param name="help.enabled" value="false"/>
  </module>
 
</system-config>

← Entity Form Support→ Menu BeanFrames / No Frames