Adding help for an extension 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.

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

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.