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 the extension module. The try block in this code segment attempts to import the helper function from the extension module. If the function is not available in the local copy of the extension 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 by args[[1]], where args is the argument that is passed to the Run 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 the Run function by calling the helper function when the HELP subcommand is specified. In R, you can check for the HELP subcommand as follows:
    "HELP" %in% attr(args,"names")
  • The helper function is included with SPSS Statistics and is named spsspkg.helper. The if block that follows the helper function attempts to assign the name helper to this spsspkg.helper function. If the spsspkg.helper function is not available, the version of the helper function that is included with the implementation code is used.
Notes:
  • 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

Help for an extension command should contain the following content:
  • 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.