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/[module]/[typeName].html

In general, a help URL is of the form:
	/help/filePath.html
For an entity type, the file path is [module]/[typeName].

For example, Employee of ExampleHR module is mapping to DataType(ExampleHR, EMP). Its help page URL is /help/ExampleHR/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 ExampleHR module does 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/ExampleHR/expenseReport.html.

Help File Mapping

A help URL is mapped to a physical file under [CMOBILECOM.HOME]/help, or an entry in JAR. Locale fallback is supported.

Suppose current user locale is en_US, then the URL /help/filePath.xhtml is mapped in the following order:

  1. [CMOBILECOM.HOME]/help/en_US/filePath.html
  2. /help/en_US/filePath.html in jar
  3. [CMOBILECOM.HOME]/help/en/filePath.html
  4. /help/en/filePath.html in jar
  5. [CMOBILECOM.HOME]/help/filePath.html
  6. /help/filePath.html in jar
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_US and zh_CN, the directory structure would be:

help/
help/en_US/
help/zh_CN/
For each help file, add one for each locale and default. For example, EMP.html,

help/contents.xml
help/EMP.html
help/images/picture.gif
help/en_US/EMP.html
help/zh_CN/EMP.html
There is no module name under the help directory. Module name should be added in the path when building module help jar. see examples ant build file: build-module.xml. For ExampleHR module, the help entry names in jar would be:

help/ExampleHR/EMP.html
help/en_US/ExampleHR/EMP.html
help/zh_CN/ExampleHR/EMP.html
Help file structure can be hierarchical using subdirectory, for example, put expenseReport under report subdirectory:

help/report/expenseReport.html
help/en_US/report/expenseReport.html
help/zh_CN/report/expenseReport.html

public class ExpenseReportQueryFormBean extends ReportQueryFormBean<ExpenseReportQueryForm> {

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

Contents

Each module can have a help contents XML that will be translated into an ajaxed tree structure menu. The contents XML for a module is /help/[module]/contents.xml in a jar, or [CMOBILECOM.HOME]/help/[module]/contents.xml.

For example, ExampleHR module help contents.xml:


<item name="ExampleHR" 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, their default names are read from module implementation.

<menuNode name="ExampleHR" link="/help/ExampleHR/index.html">
	<menuNode name="Employees" link="/help/ExampleHR/EMP.html" />
	<menuNode name="ExpenseClaims" link="/help/ExampleHR/EC.html" />	
	<menuNode name="ExpenseReport" link="/help/ExampleHR/expenseReport.html" />
</menuNode>
Note that the pathInfo in the contents.xml does not have suffix. The suffix .html will be appended for help URLs, and .html will be appended for physical help files.

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="ExampleHR">
     <class>com.cmobilecom.af.example.hr.HrModule</class>
     <param name="help.enabled" value="false"/>
  </module>
 
</system-config>