How to: Add new functions to the Plugins Generator
This document is a work in progress; it aims to describe all aspects of adding new functions to the Plugins Generator. This facility makes it easier to generate custom code in all supported languages.
First Function
Paste the following code into a file named alert.hpf, copy it to the "C:\Program Files\Chami\HTML-Kit Plugins Generator\Plugins" directory and restart the Plugins Generator. A new function named "Alert" will appear in the functions drop-down list for actions, which can be used as any other built-in function.
--- cut here ---
#name "Alert"
#id ALERT
#code hks-act-1
Alert("{{PARAM1_STR}}", "Alert Demo");
#end
--- cut here ---
Commands
Following is a list of commands supported in *.hpf files (HTML-Kit Plugins Generator Function definition files). Commands start at the beginning of the line with a "#" character and may contain other space separated parameters. Parameters containing spaces must be quoted (ie, "my parameter") and quotes inside quoted parameters must be escpaed (ie, \").
- #name "func-name" : name of the function (may contain spaces)
- #id "func-id" : function identification (must be unique and may not contain spaces)
- #paramcount "number of parameters" : number of parameters used by the function
- #parampromptN "parameter prompt label" : label for the Nth parameter
- #options ( /xes | /xou | /xep | /xse | /xnf | /xof | /xic | /xsrs | /oef )+ : enable one or more options. /x?? = code generation functions, /oef = enable code formatting.
- #code "code-block-label" : code block ending with "#end"
- #var "variable-block-label" : variable block ending with "#end"
Code Block Labels
Code blocks (#code ... #end) must have a label to indicate the language, the code position and the block id. For example, the label "hks-act-1" indicates that the code is written in the hkScript ("hks") language and should be used to handle plugin actions. The number at the end is usually 1 but can be a higher number if there are multiple code blocks of the same type. Following is a list of code block label positions:
- act : action code for plugin drop-down menu item
- header : plugin header code
- footer : plugin footer code
- top : code at the very top of the plugin file (after comments)
- bottom : code at the very bottom of the plugin file
- post-include : code below include/uses/import statements
- run-header : header code inside the hkp_Main() function
- run-footer-pre : pre-footer code inside the hkp_Main() function
- run-footer : footer code inside the hkp_Main() function
- reg-header : header code inside the hkp_Register() function
- reg-footer : footer code inside the hkp_Register() function
Variable Block Labels
Variable blocks (#var ... #end) are similar to code blocks, except they are used to define variables. For example, variables that should be declared inside the hkp_Register() function can be listed inside a #var hks-reg-1 and #end block. Following is a list of variable block label positions:
- reg : list variables inside the hkp_Register() function
- run : list variables inside the hkp_Main() function
Language Codes
All code and variable block labels must start with a language code so that the same functionality can be described in multiple languages if necessary.
- bas : Visual Basic
- c : C/C++
- cs : C#
- delphi : Delphi
- hks : hkScript
- java : Java
- js : JavaScript
- php : PHP
- pl : Perl
- py : Python
- rb : Ruby
- vbs : VBScript
Misc. Options
Code and variable blocks may use one or more of the following parameters to limit the number of times the given code is generated per plugin or per button.
- /op : generate the code once per plugin
- /ob : generate the code once per button
For example, the following code block can be used to define a variable named "n" inside the hkp_Register() function only once:
--- cut here --- #var hks-reg-1 /op var n = 0; #end --- cut here ---
Special Fields
Following fields can be used anywhere in the code to substitute their values.
- {{PARAM1_STR}} : first input field for the action as an escaped and quoted string
- {{PARAM1_STR_NQ}} : same as an escaped but unquoted string
- {{PARAM1_INT}} : same as an integer
- {{PARAM1_RAW}} : same unescaped and unquoted
- {{PARAM2_STR}} : second input field for the action as an escaped and quoted string
- {{PARAM2_STR_NQ}} : same as an escaped but unquoted string
- {{PARAM2_INT}} : same as an integer
- {{PARAM2_RAW}} : same unescaped and unquoted
- {{TAB}} : tab
- {{HKPGEN_VER}} : HTML-Kit Plugins Generator version
- {{HKPAPI_VER}} : HTML-Kit Plugins API version
- {{UID}} : an unique number
- {{BID}} : current button id number
- {{AID}} : current action id number
- {{FID}} : function id (temporary number unique to the function file)
- {{NODEINDEX}} : node id (internal number used to identify the current plugin definition node)
- {{FNAME}} : function name
- {{FCODE}} : function code
- {{FVER}} : function version
- {{FPREFIX}} : function/variable prefix
