Adding help for an extension command
Providing help for an extension command is optional. However, if you plan to share the command with other users then you probably want to include help for it. Two approaches for including and displaying help for an extension command are presented. The help that is discussed here is independent of any help that you provide for a custom dialog that is associated with the extension command.
Both approaches use the convention of displaying the extension command help (and doing nothing
else) when the submitted syntax contains the HELP
subcommand. This convention is
used by all extension commands that are installed with SPSS® Statistics. To
implement this convention, the XML specification of the extension command syntax must contain the
HELP
subcommand.
The modified XML, that includes a HELP
subcommand, for the example
MYORG GETURL EXCEL
command is as follows:
<Command xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://www-01.ibm.com/software/analytics/spss/xml/extension-1.0.xsd"
Name="MYORG GETURL EXCEL" Language="Python">
<Subcommand Name="" IsArbitrary="False" Occurrence="Optional">
<Parameter Name="URL" ParameterType="TokenList"/>
</Subcommand>
<Subcommand Name="OPTIONS" Occurrence="Optional">
<Parameter Name="FILETYPE" ParameterType="Keyword"/>
<Parameter Name="SHEETNUMBER" ParameterType="Integer"/>
<Parameter Name="READNAMES" ParameterType="Keyword"/>
</Subcommand>
<Subcommand Name="HELP" Occurrence="Optional"/>
</Command>
HTML help
You can create an HTML help file for your extension command and include it with the extension
bundle for the command. When the extension bundle is installed, the HTML file is installed along
with the other files in the bundle. In the implementation code, you can include a simple function
that finds and opens the HTML file in the default browser. By convention, the name of the function
is helper
and is defined as follows for Python:
def helper():
import webbrowser, os.path
path = os.path.splitext(__file__)[0]
helpspec = "file://" + path + os.path.sep + "markdown.html"
browser = webbrowser.get()
if not browser.open_new(helpspec):
print("Help file not found:" + helpspec)
try:
from extension import helper
except:
pass
- The
helper
function assumes that the name of the extension bundle (as specified in the Name field on the Create Extension Bundle dialog, or Extension Properties dialog if you created the extension bundle from the Custom Dialog Builder for Extensions in version 24 or higher) is the same as the name of the implementation code file (except that the bundle name might have spaces where the code file has underscores). Using the same name for the extension bundle and the code file is the recommended convention. When the extension bundle is installed, the help file (and any other auxiliary files) is installed in a folder with the same name as the extension bundle, and that folder is directly under the folder where the implementation code is installed. In this example, the extension bundle is named MYORG GETURL EXCEL and the code file is named MYORG_GETURL_EXCEL.py, so the help file is installed in a folder that is named MYORG_GETURL_EXCEL, which is directly under the folder that contains the code file. - The
helper
function in this example assumes that the name of the HTML file is markdown.html. Given the relationship between the name of the code file and the location of the help file, it is simple to locate the help file, as shown in the example code. In that regard, most extension commands that are installed with SPSS Statistics use the convention of markdown.html for the name of the help file and the convention of the equality of the name of the extension bundle and the name of the code file. - The
helper
function is included with SPSS Statistics, and is part of theextension
module. Thetry
block in this code segment attempts to import thehelper
function from theextension
module. If the function is not available in the local copy of theextension
module, then the version of the function that is included with the implementation code is used.
You can incorporate the helper
function into the Run
function
of the implementation code by calling the helper
function when the
HELP
subcommand is specified, as shown in the following code
sample:
if args.has_key("HELP"):
helper()
else:
processcmd(oobj, args, geturlexcel)
For R, the helper
function is shown in the following code segment:
helper = function(cmdname) {
fn = gsub(" ", "_", cmdname, fixed=TRUE)
thefile = Find(file.exists, file.path(.libPaths(), fn, "markdown.html"))
if (is.null(thefile)) {
print("Help file not found")
} else {
browseURL(paste("file://", thefile, sep=""))
}
}
if (exists("spsspkg.helper")) {
assign("helper", spsspkg.helper)
}
- For R, the
helper
function requires the name of the extension command. Although not shown here, the name is given byargs[[1]]
, where args is the argument that is passed to theRun
function. - As with Python, the
helper
function in R assumes that the name of the implementation code file is the same as the name of the extension bundle. The code also uses the convention of markdown.html for the name of the help file. - As with Python, you can incorporate the
helper
function into theRun
function by calling thehelper
function when theHELP
subcommand is specified. In R, you can check for theHELP
subcommand as follows:"HELP" %in% attr(args,"names")
- The
helper
function is included with SPSS Statistics and is namedspsspkg.helper
. Theif
block that follows thehelper
function attempts to assign the namehelper
to thisspsspkg.helper
function. If thespsspkg.helper
function is not available, the version of thehelper
function that is included with the implementation code is used.
- The help is displayed by pressing the F1 key in a Syntax Editor window when the cursor is
positioned within the associated extension command. The help is also displayed if the submitted
syntax contains the
HELP
subcommand. - If you have a style sheet for your HTML file, you can include it in the extension bundle with the HTML file. When the extension bundle is installed, the style sheet is installed under the same folder as the HTML file. All extension commands that are installed with SPSS Statistics have HTML help and an associated style sheet that you might want to use. The style sheet is also available from the IBM® SPSS Predictive Analytics Community (Docs>SPSS Statistics>Programmability>Extensions, Tools and Utilities for SPSS Statistics>Utilities). The name of the style sheet file is extsyntax.css.
- The
helper
function cannot be used in distributed mode, and raises an error message if it is used in distributed mode.
Plain text help
You can embed the help in a string variable that is defined in the implementation
code file and then display the string when the HELP
subcommand is
specified. With this approach, the string is displayed in a Log item in the SPSS Statistics Viewer, and works in distributed mode.
For Python, you can embed the help text in a triple-quoted string to preserve
formatting. An example of help text that just contains the syntax chart for the
MYORG GETURL EXCEL
command is as follows:
helptext = """MYORG GETURL EXCEL URL = "URL specification"
[/OPTIONS ]
[FILETYPE = {XLS**}]
{XLSX }
[SHEETNUMBER = {1** }]
{integer}
[READNAMES = {ON**}]
{OFF }
[/HELP ]
"""
An example of code that is added to the Run
function to
conditionally display the help text when the HELP
subcommand is
specified is as follows:
if args.has_key("HELP"):
print helptext
else:
processcmd(oobj, args, geturlexcel)
For R, you include the help text in a string variable and then conditionally display
it with the writeLines
function.
Help contents
- A brief description of the extension command.
- A syntax chart that specifies the command name, subcommands, keywords, keyword values, and default values of keywords.
- A simple example of the syntax.
- Descriptions for each of the subcommands, keywords, and keyword values.
All of the extension commands that are installed with SPSS Statistics include help and might be useful as examples. The help is in HTML format and is contained in the file markdown.html. For a particular extension command, the file markdown.html is in a folder with the same name as the command and directly under the folder where the implementation code is installed.