A template is a npm package including many code snippets for generating the output files. Template is fully customizable, you can customize the default template shipped with the product to suit your own needs in your web applications.

Customizing templates requires necessary knowledge in the related web technologies, HTML, CSS and JavaScript, and understanding on how template works. Please read the follows carefully before customizing the template.

The template engine is Node.js and the scripting language is JavaScript, to customize template you need to have basic knowledge of JavaScript.

Folders

Please make yourself familiar with the following terms:

For previous versions, all files were installed under the ProgramFiles folder. Since v2022, updatable files are installed in the PHPMaker folder (under the AppData folder) for write permission reasons. The template and extensions are installed under the node_modules folder under the AppData folder. (The non-updatable files are still installed under ProgramFiles folder.)

If you need to access the AppData folder, you can either access it manually or by using the AppData variable name.

In File Explorer, you can view the windows "AppData" folder manually by going into your Users folder, e.g. C:\Users\<user> where <user> is your Windows user name. The "AppData" folder is hidden by default, go to the "View" tab at the top and check the "Hidden items" checkbox, you should be able to see the "AppData" folder in your Users folder. Alternatively, you can access the AppData folder directly using the AppData system variable, just type "%APPDATA%" (without double quotes) into File Explorer's address bar to go to the folder (e.g. C:\Users\<user>\AppData\Roaming ). You should find the PHPMaker folder (e.g. C:\Users\<user>\AppData\Roaming\PHPMaker<version>) under that folder.

Template

To generate output files, the code generator locates the Template (see Generate Settings) you specified in the project (by default they are under your node_modules folder), then uses the files in the template to generate output files.

If you want to customize a template, you can modify the files inside the template folder (e.g. C:\Users\<user>\AppData\Roaming\PHPMaker<version>\node_modules\@phpmaker\php<version>). If you don't want to corrupt the original template, you can copy the template folder (for example, to the extensions folder) and customize the copied folder, then change the Template setting to the copied folder as the template of your project.

Control File

The core of the template is a control file named control.xml. It is an XML file containing information about files to be generated. During generation the code generator will parse the control.xml and generate the output files one by one. If you want to add an output file, you need to add a <control> tag in the control file.

General Layout

To change the general layout, modify the file layout.php in the template.

Subfolders

Subfolders are defined in control.xml, if you want to add and copy additional subfolders, you need to add a <control> tag in the control.xml.

Language Files

All the phrases in the template are separated into a single XML language file for easy translation to other languages and sharing. If you want to translate a template, this should be the only file you need to translate.

Language files are placed in the subfolder "languages" under the PHPMaker folder and they are used by all templates.

See Multi-Language Project for more information on making a language file.

UTF-8 File Encoding

The template and output files are in utf-8 encoding by default. If you need to add language phrases to template, it is recommended you use the language file. If you have to put special characters directly in the template, you must always use utf-8 and save the file in utf-8 encoding.

Template Tags and Object Properties

The code generator processes the Template Tags in the template, assembles the output files using the code snippets from template and generate code according to Object Properties. Object properties are project settings, they will be outputted to a cache folder as a .json file (e.g. C:\Users\<user>\AppData\Roaming\PHPMaker<version>\temp\<template>\cache\<project>.json) before each generation.

User Code

Advanced users can customize some dynamically generated code by User Code, you can add events to do something before and/or after generation, change project settings and add your own global functions in User Code. See Using User Code for details.

Extensions

An extension allows you to change the template to support additional feature(s) implemented in the extension.

Like template, each extension is also a npm package installed under the node_modules folder. You can open any extension folder and see how it is implemented. See Extensions for details.

If you have private extensions for your own use only, you can put them under the user extensions folder (e.g. C:\Users\<user>\AppData\Roaming\PHPMaker<version>\extensions). Files in this folder will NOT be changed when you update the public template and extensions under the node_modules folder.

Custom View Tag

Custom View Tag is same as extension except that it is used to display a field in the List and View pages with your own code. A Custom View Tag has the same structure as extension and you can create it in exactly the same way.

Custom View Tag is also a npm package installed under the node_modules folder.

Read Field Setup on how to select Custom View Tag for a field.

Custom Edit Tag

Custom Edit Tag is same as extensions except that it is used to display the Edit Tag of a field (e.g. in Add/Edit pages) with your own code. A Custom Edit Tag has the same structure as extension and you can create it in exactly the same way.

Custom Edit Tag is also a npm package installed under the node_modules folder.

Read Field Setup on how to select Custom Edit Tag for a field.

Also See

Control File
Template Tags
Object Properties
Using User Code
Extensions
Third-party Tools
Tools