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:


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