Ajout d'une aide pour une commande d'extension

aide au format HTML

Vous pouvez créer un fichier d'aide HTML pour votre commande d'extension et l'inclure dans le bundle d'extension de la commande. Lorsque le bundle d'extension est installé, le fichier HTML est installé avec les autres fichiers du bundle. Dans le code d'implémentation, vous pouvez inclure une fonction simple qui recherche et ouvre le fichier HTML dans le navigateur par défaut. Par convention, le nom de la fonction est helper et est défini comme suit pour 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

• La fonction helper suppose que le nom du bundle d'extension (tel que spécifié dans la zone Nom de la boîte de dialogue Créer un bundle d'extension ou dans la boîte de dialogue Propriétés d'extension si vous avez créé le bundle d'extension à partir du générateur de boîtes de dialogue personnalisées pour les extensions dans la version 24 ou ultérieure) est identique au nom du fichier de code d'implémentation (sauf que le nom du bundle peut comporter des espaces dans lesquels le fichier de code comporte des traits de soulignement). L'utilisation du même nom pour le bundle d'extension et le fichier de code est la convention recommandée. Lorsque le bundle d'extension est installé, le fichier d'aide (et tout autre fichier auxiliaire) est installé dans un dossier portant le même nom que le bundle d'extension, et ce dossier se trouve directement sous le dossier où le code d'implémentation est installé. Dans cet exemple, le bundle d'extension est nommé MYORG GETURL EXCEL et le fichier de code est nommé MYORG_GETURL_EXCEL.py, de sorte que le fichier d'aide est installé dans un dossier nommé MYORG_GETURL_EXCEL, qui se trouve directement sous le dossier qui contient le fichier de code.
• La fonction helper de cet exemple suppose que le nom du fichier HTML est markdown.html. Compte tenu de la relation entre le nom du fichier de code et l'emplacement du fichier d'aide, il est simple de localiser le fichier d'aide, comme illustré dans l'exemple de code. A cet égard, la plupart des commandes d'extension installées avec SPSS Statistics utilisent la convention markdown.html pour le nom du fichier d'aide et la convention d'égalité du nom du bundle d'extension et du nom du fichier de code.
• La fonction helper est incluse avec SPSS Statisticset fait partie du module extension . Le bloc try de ce segment de code tente d'importer la fonction helper à partir du module extension . Si la fonction n'est pas disponible dans la copie locale du module extension , la version de la fonction incluse avec le code d'implémentation est utilisée.

Vous pouvez incorporer la fonction helper dans la fonction Run du code d'implémentation en appelant la fonction helper lorsque la sous-commande HELP est spécifiée, comme illustré dans l'exemple de code suivant:

    if args.has_key("HELP"):
        helper()
    else:
        processcmd(oobj, args, geturlexcel)

Pour R, la fonction helper est affichée dans le segment de code suivant:

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)
}

• Pour R, la fonction helper requiert le nom de la commande d'extension. Bien qu'il ne soit pas affiché ici, le nom est donné par args[[1]], où args est l'argument qui est transmis à la fonction Run .
• Comme avec Python, la fonction helper dans R suppose que le nom du fichier de code d'implémentation est identique au nom du bundle d'extension. Le code utilise également la convention markdown.html pour le nom du fichier d'aide.
• Comme avec Python, vous pouvez incorporer la fonction helper dans la fonction Run en appelant la fonction helper lorsque la sous-commande HELP est spécifiée. Dans R, vous pouvez rechercher la sous-commande HELP comme suit:

  "HELP" %in% attr(args,"names")

• La fonction helper est incluse avec SPSS Statistics et est nommée spsspkg.helper. Le bloc if qui suit la fonction helper tente d'affecter le nom helper à cette fonction spsspkg.helper . Si la fonction spsspkg.helper n'est pas disponible, la version de la fonction helper incluse avec le code d'implémentation est utilisée.

Aide en texte brut

Vous pouvez incorporer l'aide dans une variable de chaîne définie dans le fichier de code d'implémentation, puis afficher la chaîne lorsque la sous-commande HELP est spécifiée. Avec cette approche, la chaîne est affichée dans un élément de journal dans le visualiseur SPSS Statistics et fonctionne en mode réparti.

Pour Python, vous pouvez imbriquer le texte d'aide dans une chaîne entre guillemets triples afin de préserver le formatage. Voici un exemple de texte d'aide qui contient uniquement le graphique de syntaxe de la commande MYORG GETURL EXCEL :

helptext = """MYORG GETURL EXCEL URL = "URL specification"
[/OPTIONS ]
   [FILETYPE = {XLS**}]
               {XLSX }
   [SHEETNUMBER = {1**    }]
                  {integer}
   [READNAMES = {ON**}]
                {OFF }
[/HELP ]
"""

Voici un exemple de code ajouté à la fonction Run pour l'affichage conditionnel du texte d'aide lorsque la sous-commande HELP est spécifiée:

    if args.has_key("HELP"):
        print helptext
    else:
        processcmd(oobj, args, geturlexcel)

Pour R, vous incluez le texte d'aide dans une variable de chaîne, puis vous l'affichez de manière conditionnelle avec la fonction writeLines .

Contenu de l'aide

Toutes les commandes d'extension installées avec SPSS Statistics incluent de l'aide et peuvent être utiles comme exemples. L'aide est au format HTML et se trouve dans le fichier markdown.html. Pour une commande d'extension particulière, le fichier markdown.html se trouve dans un dossier portant le même nom que la commande et directement sous le dossier dans lequel le code d'implémentation est installé.