An extension allows you to "extend" the template to support additional features such as implementing third party tools.

Using Extensions

Click Tools->Extensions to enable or disable these extensions. Before enabling the extension, make sure you read the notes about the extension first. If the extension has advanced settings (NOT every extension has), you'll see the Advanced tab after selecting the extension. Click the Advanced tab to configure settings for the extension.

In the Advanced tab, you may see Project, Tables, and Fields tabs, depending on extensions. Note that NOT every extension has all 3 tabs, some extensions may have project level settings only, some extensions may have table or field level settings also, e.g.

Making Extensions

It is simple to make your own extensions. Each extension is a npm package. Each package MUST have the following files in the root-level directory of the package:

1. package.json

A package is a directory that is described by a package.json file. For more information on creating a package.json file, see Creating a package.json file.

The package.json of an extension MUST contain (but not limited to) the following fields:

• name - Package name, and must be lowercase and one word, and may contain hyphens and underscores. The name can be scoped or unscoped, see Package name guidelines.
• version - Version number in the form x.x.x and follow the semantic versioning guidelines.
• phpmaker - Type of the package. Possible values are: "extension", "custom view tag" or "custom edit tag". Note This is a custom field required by PHPMaker, if not found, the package will be ignored.

e.g. package.json

2. XML description file

The package must also include an XML description file so the extension can be shown in the user interface (see Using Extensions above) for setup. The XML file has the following structure: Note The root node must be named as "ew-extension".

3. index.js

This is the main script of your extension, you can get the project level properties here and prepare for subsequent code generation, e.g.

For Custom View Tag and Custom Edit Tag, your main script must export at least the following method(s):

• CustomViewTemplate - Required. For Custom View Tag only. Method to output View Tag of the field.
• CustomViewTemplateExport - Optional. For Custom View Tag only. Method to output code (PHP only) to setup properties (e.g. ExportHrefValue property of the field object) before export. Only required if you want to output different values for export.
• CustomEditTemplate - Required. For Custom Edit Tag only. Method to output Edit Tag of the field.

e.g. index.js for Custom View Tag

4. README file

To help others using your code in their projects, you should include a README file in your extension. The content of the file is shown in the Notes tab (see above) when the extension is selected in the Extensions form.

In your extension root directory, create a file called README.md, add useful information about your extension in the file. The file extension .md indicates a Markdown file. For more information about Markdown, see Markdown. Also see About package README files for more information about README file.

4. Language files

Each extension may contain its own language files. The language file contains phrases for the extension. The phrases will be merged to the main languages during runtime. The file name should be in the format ``..xml``, e.g. *myExtension.en-US.xml*. If you support [Multi-Language](multilang.html), you should provide multiple language files, one for each language ID.

Your language files must have a parent element named by the extension name, e.g. if your extension name is "myExtension", then your language file should be like:

To retrieve the phrase by PHP you can use Language()->phrase("myExtension.foo").

To retrieve the phrase by JavaScript you can use, e.g. ``ew.language.phrases.myExtension.foo``.

6. Your files

Your code for the extension. Note Your files must use template tags.

Append code to existing file
To append code to a sub-template in the main template, just add a file with the same name.

Clear code in existing file and replace by yours
To clear generated code of the original sub-template first and then replace with your own, add a file with the same name and add the following as the first line in your file before adding your own code:

Replace code in existing file
To replace part of generated code of the original sub-template with your own, add a file with the same name and modify args.code, e.g.

where /<regular expression>/ is your regular expression to match the original code to be replaced.

Add or copy your own files
To generate additional files, make sure you add a <control> tag to the XML file (see above) for each file (or folder) you want to add or copy, see Control File for details.

In your files, you can get the extension properties (defined by <attribute> tags in the XML description file, see above) as follows:

Publishing Extensions

If your extensions are for your own use only, you can simply put your extensions under the extensions folder, e.g. C:\Users\<user>\AppData\Roaming\PHPMaker<version>\extensions.

If you want to share your extensions with other users, you can publish your extensions. Since an extension is a npm package, you can publish to any npm registry. See:

• Creating and publishing unscoped public packages
• Creating and publishing scoped public packages
  

To install an extension, open command prompt or PowerShell, go to the PHPMaker folder, e.g. C:\Users\<user>\AppData\Roaming\PHPMaker<version> (NO space between "PHPMaker" and "<version>"), and enter:

npm install [<@scope>/]<name>

where [<@scope>] is the optional scope of your package and <name> is the package name. See npm install for details.

Extensions (and Custom View/Edit Tags) shipped with PHPMaker

Additional Extensions (and Custom View Tags) for Registered Users Only

Also See

Control File
Template Tags
Object Properties
Third-party Tools