|
Association of Shareware Professionals
The World's #1 Trade Organization for Independent Software Developers and Vendors
|
PAD Overview ->
Specification Details ->
PAD Extensions Specification
PAD Extensions
For situations, where the company and product information in a PAD file is not
sufficient, the PAD concept introduces a process to extend the default
dataset by custom fields.
PAD Extensions support is part of the PAD Specification.
A PAD Extension is a set of additional data fields that will be added to PAD
files within a separate XML node. A PAD Extension is defined within a single
HTML file including a form representation of the extension. Anyone may define a
PAD Extension, but registration with the ASP is required to avoid naming
conflicts. If you plan to create a PAD Extension, see below for the
Specification for PAD Extension Creation.
PAD generation tools need to support PAD Extensions by implementing plug-in
capabilities to display an input form for each extension, validate the input,
and add the data to the resulting PAD file. If you plan to implement PAD
Extension support within your PAD generation tool, see below for the
Specification for PAD Extension Integration into PAD
Generation Tools.
The following specification is very generic, see below for some
Examples.
For a list of PAD Extensions see the
PAD Extensions Directory.
Specification for PAD Extension Creation
A PAD Extension is defined within the HTML document format (Note: Although
HTML is used, PAD Extensions are not subject to be displayed in web browsers).
The following rules have to be respected when creating a PAD Extension:
- A PAD Extension needs to have an exclusive name, the extension
identifier. The extension identifier has to be one word, only containing the
characters A-Z, a-z, the numbers 0-9 and the _ underscore, no blanks.
To ensure that an extension identifier is really unique,
reservation with the ASP is required. Contact
PAD Support
to reserve your identifier. This will ensure that your identifier
is not yet used by someone else, and will not be issued twice.
- The extension needs to be stored in a file named [extension identifier].htm
- The extension file must be a valid HTML 3.2 file, using the <HTML>,
<HEAD> and <BODY> tags correctly.
- The <TITLE> tag within the <HEAD> needs to contain the exact
extension identifier.
- The <BODY> needs to contain a <FORM>. The <FORM> tag
does not need to have any attributes (like ACTION). It must not contain
a submit button.
- Within the form, there needs to be a <INPUT TYPE="hidden"> tag with the
attribute NAME set to "[extension identifier]_FORM" and the VALUE set to "Y".
- Within the form, there needs to be a <INPUT TYPE="hidden"> tag with the
attribute NAME set to "[extension identifier]_DESCRIPTION" and the VALUE set to
a brief, one-line description of the extension's purpose. The description will
show up on the PAD Extensions Directory.
- Within the form, there needs to be a <INPUT TYPE="hidden"> tag with the
attribute NAME set to "[extension identifier]_VERSION" and the VALUE set to
the version of the extension. The version should be incremented on changes
to the extension.
- Within the form, there needs to be a <INPUT TYPE="hidden"> tag with the
attribute NAME set to "[extension identifier]_URL" and the VALUE set to
the URL where the extension file can be downloaded. PAD generation tools will
be able to automatically download the most current version of the extension
from this location. PAD consumers will be able to download the extension, a
PAD file has been generated with, from this location. Optionally, you can ask
the ASP to host your PAD extension file in their PAD extensions directory. Contact
PAD Support
for details.
- Within the form, there needs to be a <INPUT TYPE="hidden"> tag with the
attribute NAME set to "[extension identifier]_SCOPE" and the VALUE set to
either "Company" if the extension is company information specific or "Program" if
it is program information specific. If the scope is both company and program
specific, "Program" should be set.
PAD generation tools that support saving company information to a central place,
so it does not need to be reentered for each program, should save the extension
data entries with the company or program information according to this setting.
- All custom data fields can now be inserted into the form like within a
web form, by using <INPUT TYPE="text">, <INPUT TYPE="checkbox">,
<INPUT TYPE="radio">, <TEXTAREA> or <SELECT> tags.
The NAME attributes have to be unique within the extension. It is recommended to
prefix the NAMEs with the extension identifier, for example
[extension identifier]_Custom_Field. The names may only contain the characters
A-Z, a-z, 0-9 and the underscore _.
- For each custom data field, two additional <INPUT TYPE="hidden"> tags
need to be created. The first has to be named "[field name]_REGEX" and must
contain a regular expression for input validation. The second one has to be
named "[field name]_REGEX_DOCUMENTATION" and must contain a description of the
regular expression, describing which data entries are allowed. See the PAD
Specification for examples of regular expressions and corresponding descriptions.
Keep in mind that some special characters must be masked in HTML. The regular
expression "[^<]*" for example has to be masked as "[^<]*". If a
restriction of input for the custom data field is not required, these fields may
be left out.
But it is highly recommended to create regular expressions for input validation,
as this will significantly increase the quality of the data authors will enter.
Contact
PAD Support
if you need help with your regular expressions.
- The form layout should contain labels for each input field to ensure the user
knows what to enter into the fields. Meaningful descriptions or examples should
be added if the usage is not self-explanatory.
- HTML formatting should be limited to what is absolutely necessary. There
should not be any formatting affecting font face types, font sizes, font or
background colors. Images, JavaScript or other external files are not allowed.
- The extension should contain readable contact information of the extension's
author.
Specification for PAD Extension Integration into PAD Generation Tools
- PAD generation tools need to provide abilities to display the extension
forms for each installed extension. Extension installation should be possible by
simply copying the extension files to a certain directory.
- PAD generation tools that support saving company information to a central place,
so it does not need to be reentered for each program, should save the extension
data entries with the company or program information according to the
extension's SCOPE.
- On validation, the tool must use the regular expressions from the extension
to validate the extension input.
- On PAD generation, the values of all form fields must be saved to a separate
node, a first-level sub node of the <XML_DIZ_INFO> tag. The node's name
needs to be the extension identifier. All field names and values will then be
saved to sub nodes of this extension root node. All form fields have to be saved
to the appropriate nodes, except the *_REGEX and *_REGEX_DOCUMENTATION fields.
- Optionally, tools can automatically check for the latest version of an
extension using the extension URL and version from the local extension file.
- Optionally, tools may want to query the
PAD Extensions Directory for new extensions. The
directory is also available in
XML format
(which should be self-explanatory).
Examples
The extension identifier of this sample extension is "SampleExtension".
<HTML>
<HEAD>
<TITLE>SampleExtension</TITLE>
</HEAD>
<BODY>
<FORM>
<H2>Sample PAD Extension</H2>
<INPUT TYPE="hidden" NAME="SampleExtension_FORM" VALUE="Y">
<INPUT TYPE="hidden" NAME="SampleExtension_DESCRIPTION" VALUE="Sample PAD Extension">
<INPUT TYPE="hidden" NAME="SampleExtension_VERSION" VALUE="1.0">
<INPUT TYPE="hidden" NAME="SampleExtension_URL" VALUE="http://www.asp-shareware.org/pad/extensions/SampleExtension.htm">
<INPUT TYPE="hidden" NAME="SampleExtension_SCOPE" VALUE="Program">
<INPUT TYPE="checkbox" NAME="SampleExtension_Member" VALUE="Y" CHECKED>
<INPUT TYPE="hidden" NAME="SampleExtension_Member_REGEX" VALUE="^[yYnN]\Z">
<INPUT TYPE="hidden" NAME="SampleExtension_Member_REGEX_DOCUMENTATION" VALUE="Y, y, N, or n">
Are you a member of the SampleExtension network?<BR>
If yes, enter your member code:
<INPUT TYPE="edit" NAME="SampleExtension_Member_Code" VALUE="">
<INPUT TYPE="hidden" NAME="SampleExtension_Member_Code_REGEX" VALUE="^[0-9]{0,6}\Z">
<INPUT TYPE="hidden" NAME="SampleExtension_Member_Code_REGEX_DOCUMENTATION" VALUE="Numerical 0-6 digits">
<P>
PAD Extension Author:
Association of Shareware Professionals,
<A HREF="http://www.asp-shareware.org">http://www.asp-shareware.org</A>
</FORM>
</BODY>
</HTML>
In a PAD generation tool, the sample extension will look like this:
It will generate the following output within the PAD file:
<?xml version="1.0" encoding="UTF-8"?>
<XML_DIZ_INFO>
<MASTER_PAD_VERSION_INFO>
[...]
</MASTER_PAD_VERSION_INFO>
<Company_Info>
[...]
</Company_Info>
<Program_Info>
[...]
</Program_Info>
<SampleExtension>
<SampleExtension_FORM>Y</SampleExtension_FORM>
<SampleExtension_DESCRIPTION>Sample PAD Extension</SampleExtension_DESCRIPTION>
<SampleExtension_VERSION>1.0</SampleExtension_VERSION>
<SampleExtension_URL>http://www.asp-shareware.org/pad/extensions/SampleExtension.htm</SampleExtension_URL>
<SampleExtension_SCOPE>Program</SampleExtension_SCOPE>
<SampleExtension_ASP_CD>Y</SampleExtension_ASP_CD>
<SampleExtension_ASP_Code>[users entry]</SampleExtension_ASP_Code>
</SampleExtension>
</XML_DIZ_INFO>