### Application extensions (add-ons)

Precision Helper implements two interfaces for using the application extensions (add-ons). They are command-line interface and Pascal Script interface.

Application add-ons can significantly extend the functionality of the product in different areas and can be created by third parties.

The first available add-ons:

- HTML Tidy - uses the well-known tool to check, clean and reformat the topic
- New project from files - wizard for creating a new project from an existing topic files
- Edit HHC - allows editing of TOC source file in an external HTML editor
- Edit HHK - allows editing of Index source file in an external HTML editor
- Project stats - displays a brief statistical info about the current project
- Date and time - inserts an actual date and time into currently edited topic

Where are the extensions installed?

All extensions must be installed into the Extras subfolder of Precision Helper application folder.

For default installation on Windows 2000/XP it is a folder:
"C:\Documents and Settings\%UserName%\AppData\Precision\precisionhelper\Extras"
For default installation on Windows Vista (and newer) it is a folder:
"C:\Users\%UserName%\AppData\Roaming\Precision\precisionhelper\Extras"

Each extension should be also located in a different folder. Of course, a set of extensions, that share the same components (files), can be stored in the same folder.

Add-on configuration files

Each add-on is defined by the parameters specified in the configuration file. that must have a .PHE suffix (ie. MyExtension.phe).
The configuration files for Pascal Script interface are simple and contains essentially only descriptive information. On the contrary, the configuration files for command-line interface contain a complete definition of parameters and operations, that Precision Helper must process in each step (before execution, after execution, etc.).

Pascal Script interface

The following example shows a configuration file of the Pascal Script interface add-on.

      [Precision Helper Extension]
      Interface=pascalscript

      ; Default title and description of the extension
      Caption=New from files
      Hint=Create a new help project from an existing topic files

      ; Localized title and description of the extension
      Caption.cs=Nový ze souborů
      Hint.cs=Vytvořit nový projekt nápovědy z existujících souborů témat

      [IDE]
      ; Parts of the Precision Helper IDE, where the extension should be available
      ribbonHOME=1
      ribbonTOC=0
      ribbonIDX=0
      ribbonPUB=0
      ribbonTOOLS=1
      ribbonHELP=0
      TopicSource=0

The parameters in the example are more or less clear. The code for this kind of add-ons is placed in a file named RunScript.pas. If the add-on contains a GUI (visual user interface), it must be defined in a file named RunScript.dfm.

For editing and designing the add-ons with Pascal Script interface, you can use any editor, but we recommend to use our pdScript IDE product, that contains a full support for Precision Helper pascal scripting interface (see http://www.be-precision.com/products/pdscript/).

As starting examples for creating your own add-ons you can use the predefined existing extensions, that can be found in the above mentioned folder.

Command-line interface

The following example shows a configuration file of the command-line interface add-on, including the description of individual parameters.

      [Precision Helper Extension]
      ; Interface:
      ;   pascalscript - Pascal Script interface
      ;   cmdline      - Command-line interface
      ;                  An external program is executed with the specified parameters.
      ;                  (See 'Application' and 'Command-line' sections for more info)
      Interface=cmdline

      Caption=Edit HHC
      Hint=Open the table of contents source file in an external html editor

      Caption.cs=Upravit HHC
      Hint.cs=Otevřít zdrojový soubor obsahu v externím html editoru

      [Script]
      ; not implemented yet
      ExecOnLoad=0

      [Application]
      ; Application to execute. Can be an exact path, or path with an environment variables,
      ; or can contain one of the following macros:
      ; %X% - Macro that runs one of the tools predefined in Precision Helper.
      ;       (X can be: 1 - Html editor, 2 - Web browser, 4 - Image editor, 5 - File manager)
      ; %ENVIRONMENT_VARIABLE% - Any environment variable
      ; %REG:HKxx\KeyPath,ValueName|DefaultValue% - Value from registry
      ; %APPEXTRAS% - Extensions folder of Precision Helper
      ; %APPTEMPLATES% - Templates folder of Precision Helper
      ; %APPFOLDER% - Folder that contains PrecisionHelper.exe file
      ; %APPTEMP% - Temporary folder of Precision Helper (ie. ...\Precision Helper\Temp\...)
      ; %PROJECTFILE% - Current project file
      ; %PROJECTFOLDER% - Folder of the current project
      ; %APPSAMPLES% - Samples folder of Precision Helper
      %1%

      [Command-line]
      ; Command-line parameters. Can contain macros mentioned in [Application] section (except the %X%) and the following macros:
      ; %1 - filename of currently selected item in Precision Helper (topic in TOC, topic in Index, file in Include files section, etc.)
      ; %2 - Source file name of the project (HHP)
      ; %3 - Target CHM file of the project
      ; %4 - Source file name of table of content (HHC)
      ; %5 - Source file name of index of keywords (HHK)
      ; %6 - Current installation folder of this extension
      ; %7 - Current options file name of this extension
      Parameters="%4"

      ; Precision Helper waits until the executed extension will be closed.
      ; Do not use this when you work with both programs (PH and the application) side by side.
      ; Not available when using the %X% macro in [Application] section
      waitfor=0

      ; Saves the TOC before execution
      saveTOC=1
      ; Saves the IDX before execution
      saveIDX=0
      ; Saves the whole project before execution
      saveProject=0
      ; Saves the current topic before execution
      saveTopic=0

      ; When the extension is executed, Precision Helper will reload the TOC after its next activation.
      ; If 'waitfor=1' then TOC will be reloaded after closing the extension application
      reloadTOC=1
      ; Similar to reloadTOC, but applies to Index of keywords
      reloadIDX=0
      ; Similar to reloadTOC, but applies to the whole project
      reloadProject=0
      ; Similar to reloadTOC, but applies to the current topic
      reloadTopic=0
      ; Similar to reloadTOC, but reloads all the extensions (suitable for add-ons that implements Add-Ons manager features)
      reloadExtras=0

      [IDE]
      ; Parts of the Precision Helper GUI, where the extension should be available
      ribbonHOME=0
      ribbonTOC=1
      ribbonIDX=0
      ribbonPUB=0
      ribbonTOOLS=0
      ribbonHELP=0
      TopicSource=0

As you can see from the parameters description, you can actually use any external application as an add-on, because Precision Helper is not directly dependent on its execution (except possibly waiting for it to finish), nor output.

Other add-ons options

- The add-on icons must be stored in the files named "icon16.png" and "icon24.png", and they have to be located near the configuration file
- Each add-on with Pascal Script interface has a dedicated file with its own preferences (options). This file should have the same name as configuration file, but the .PHEINI suffix (see the "NewFromFolder" add-on).
- Full description of Pascal Script interface syntax (classes, methods, types, etc.) is not yet available, but the list of supported syntax is available in a coding scheme template named "Precision Helper" inside the mentioned editor of add-ons, the pdScript IDE product (more at http://www.be-precision.com/products/pdscript/).

Copyright 2008-2011 Precision software & consulting. All rights reserved.