Vous êtes sur la page 1sur 347

PHPMaker 12 Help

PHPMaker 12 Help

Table of Contents
1. PHPMaker 12 ............................................................................................................................ 3
1.1 What's New in PHPMaker 12 .............................................................................................. 3
1.2 System Requirements ....................................................................................................... 14
1.3 Installation and Uninstallation .......................................................................................... 15
1.4 License and Ordering Information .................................................................................... 16
1.5 Technical Support ............................................................................................................. 16
1.6 Disclaimer of Warranty ..................................................................................................... 17
1.7 Third-party Tools ............................................................................................................... 17
1.8 Introduction to PHP and MySQL ....................................................................................... 19
1.9 Quick Start......................................................................................................................... 28
1.10 Project Setup................................................................................................................... 31
1.10.1 Database Setup ........................................................................................................ 31
1.10.2 PHP Settings ............................................................................................................. 38
1.10.3 HTML Settings .......................................................................................................... 48
1.10.4 Security Settings....................................................................................................... 52
1.10.5 Generate Settings .................................................................................................... 63
1.10.6 Table Setup .............................................................................................................. 66
1.10.7 Field Setup ............................................................................................................... 80
1.10.8 Lookup Table .......................................................................................................... 111
1.10.9 Server Events and Client Scripts ............................................................................ 120
1.10.10 Custom Templates ............................................................................................... 163
1.10.11 Using Custom View .............................................................................................. 171
1.10.12 Using Report ........................................................................................................ 176
1.10.13 Custom Files ......................................................................................................... 181
1.10.14 Custom Fields ....................................................................................................... 186
1.10.15 Linked Tables ....................................................................................................... 188
1.10.16 Multi-Language Project ........................................................................................ 193
1.11 Application Root ........................................................................................................... 198
1.12 Project File .................................................................................................................... 201
1.13 Tools .............................................................................................................................. 202
1.14 Customizing Template .................................................................................................. 223
1.14.1 Control File ............................................................................................................. 227

PHPMaker 12 Help
1.14.2 System Functions ................................................................................................... 231
1.14.3 Template Object Properties ................................................................................... 246
1.14.4 Using User Code ..................................................................................................... 268
1.14.5 Template Tags ........................................................................................................ 271
1.15 Tutorials ........................................................................................................................ 273
1.15.1 Connecting Remote MySQL using PHPMaker Connection Script .......................... 274
1.15.2 Master/Detail ......................................................................................................... 276
1.15.3 File Upload to Database ......................................................................................... 286
1.15.4 File Upload to Folder.............................................................................................. 291
1.15.5 Dynamic Selection List ........................................................................................... 296
1.15.6 Field Aggregation ................................................................................................... 299
1.15.7 User Registration System ....................................................................................... 301
1.15.8 Inline Add, Inline Copy, Inline Edit, Grid-Add and Grid-Edit .................................. 307
1.15.9 Advanced Security - User ID Security ..................................................................... 311
1.15.10 Advanced Security - Static User Level Security .................................................... 316
1.15.11 Advanced Security - Dynamic User Level Security ............................................... 323
1.15.12 Custom View ........................................................................................................ 331
1.15.13 Report .................................................................................................................. 337
1.15.14 Integrating with PHP Report Maker Project ........................................................ 343

PHPMaker 12 Help

1. PHPMaker 12

PHPMaker is a powerful automation tool that can generate a full set of PHP quickly from
MySQL, PostgreSQL, Microsoft Access, Microsoft SQL Server and Oracle databases.
Using PHPMaker, you can instantly create web sites that allow users to view, edit, search,
add and delete records on the web. PHPMaker is designed for high flexibility, numerous
options enable you to generate PHP applications that best suits your needs. The generated
codes are clean, straightforward and easy-to-customize. The PHP scripts can be run on
Windows servers (MySQL/PostgreSQL/Access/MSSQL/Oracle) or Linux/Unix servers
(MySQL/PostgreSQL/Oracle). PHPMaker can save you tons of time and is suitable for both
beginners and experienced develpers alike.

Also See:
What's New in PHPMaker 12(See 1.1)
License and ordering(See 1.4)

1.1 What's New in PHPMaker 12


PHPMaker 12 is a major upgrade from 11.x. It is loaded with a bunch of new features,
including many frequently requested ones. PHPMaker is probably the most powerful and
flexible product of its kind, and yet still easy-to-use as always.

Linked Tables from Multiple Databases


Now you can add Linked Tables from other databases of different database type

PHPMaker 12 Help

Custom Fields
Add custom fields to a table or view with SQL expression.

PHPMaker 12 Help

Optional Tabular Form for Desktop Mode


Option to use Bootstrap table instead of Bootstrap horizontal form for
Add/Edit/Search/Update/Register pages (Desktop mode only)

Tabular form

PHPMaker 12 Help

Horizontal form

Dropdown Selection Lists


Show the options in dropdown panel (supports SELECT, RADIO and CHECKBOX) with minwidth and max-height settings.

Multi-column Radio button list

Multi-column Checkbox list

PHPMaker 12 Help

Selection list (select-one) / Single


column radio button list

Selection list (select-multiple) /


Single column checkbox list

Option Template for Dropdown Selection Lists


Show options in HTML with JsRender template.

PHPMaker 12 Help

Improved AutoSuggest
Support Option Template, min-width and max-height settings.

Session Keep Alive and Session Timeout


Keeps session alive by Ajax or show session timeout countdown to remind users.

PHPMaker 12 Help

Anonymous User Level


Anonymous User becomes a built-in dynamic User Levels so administrators can setup
permissions at runtime.

New Actions to Manage User Profile (for Administrators)


Administrator can now easily do the following tasks in the List page of the User table.

Password Generator and Password Strength Meter

PHPMaker 12 Help
Improved Multi-Page
Options: (To be set up by Client Script)

Enable submit button for the last page only


Hide disabled submit button
Hide inactive pages
Set inactive tabs as disabled (for tabs and pills only)
Hide tabs (for tabs and pills only)
Show pager (Prev/Next buttons) at top and/or bottom
Pager template (HTML template of the Prev/Next buttons)

Simplified Client Side Events and "fields" jQuery Plugin


Add client side events easily and manipulate/validate the fields quickly with PHPMaker's
"fields" jQuery plugin.

Multi-Update of Field Settings

10

PHPMaker 12 Help
Set multiple properties of multiple fields at one time.

Import/Export of Theme Settings

Import/Export Feature of Multi-Language Property Editor

Dynamic Selection Lists in Master/Detail-Add/Edit

11

PHPMaker 12 Help

Local Storage of Search Criteria


Saves search criteria in browser local storage.

Cancel Button for Add/Edit/Delete/Update Pages


Cancel button with confirmation dialog if form data has been modified.

12

PHPMaker 12 Help

New Language Selection Buttons


Use button group with tooltip.

More Server Events

Language_Load - For customizing the language phrases, fired after the language
file is loaded.
AuditTrail_Inserting - For customizing the data to be logged, fired before inserting
the audit trail log.

More Advanced Settings

Format project file - Add indentation to XML nodes in the project file
Allow login by session variables - For use with User_CustomValidate server event
Session timeout period (minutes) - Specifies the session time-out period if the user
does not refresh or request a page
Session keep alive interval (seconds) - Specifies the interval to send Ajax request to
the server for keeping the session alive
Session time out countdown period (seconds) - Specifies the countdown period
before session ends
Use ADOdb driver for MySQL - Use the full ADOdb driver for MySQL instead of the
lite version (ewmysql.php)
Encrypt file path - Encrypt the file path of uploaded files in URL

13

PHPMaker 12 Help

Reduce image size only (image resize) - Specifies if enlarging image is preferred
(Migrated from previous Image Resize extension)
Always keep aspect ratio (image resize) - Specifies if aspect ratio should be kept
(Migrated from previous Image Resize extension)
Check password strength - Specifies if the strength of inputted password for
password fields should be checked
Minimum password strength - Specifies the minimum acceptable password strength
Generate password - Specifies if a random password generation button should be
added to password field
Password length - The length of the password to be generated
Add plain text version in HTML email - Specifies if text version of email content is
required
Use tabular form for desktop - Use Boostrap table instead of Bootstrap horizontal
form for Add/Edit/Search/Update/Register pages (Desktop mode only)

More

Use mysqli extension by default


Image Resize functionality (does not require Image Resize extension anymore)
Multi-Language support for email template
Lookup always by ajax ("Use Ajax" setting removed)
Improved Custom Actions
DetailPages property for showing and hiding detail table tabs by server event
Password change by user (for md5 password) as password recovery
Support Custom Attributes as PHP array
SelectLimit() support for MSSQL >= 2005
Global array for passing server side values to client side
"addoption" and "newoption" client side event for lookup fields (supports both lookup
fields with lookup table or user values)
JavaScript alerts replaced by Modal dialog
jQuery, JsRender, jQuery File Upload updated
tinyMCE and CKEditor extensions (for registered users only) updated with latest
versions
Multi-Language support for reCAPTCHA, JsCalendar, tinyMCE and CKEditor
QRCode/BarCode Custom View Tags combined (Flash Files Custom View Tag
removed)
A new built-in "plain" theme
UTF-8 output files if project charset is utf-8
PHPMailer updated
Setting PHPMailer properties in Email_Sending server event
mobile_detect.php updated and mobile-detect.js adopted
Bootstrap 3.3.5
Many other minor improvements

1.2 System Requirements


PHPMaker

Windows Vista/2008/2012/7/8

PHPMaker requires the following system files. If you do not have latest version of these files,
you may experience ActiveX errors. To update your system, go the Microsoft download
pages listed below.

Service Pack 6 for Visual Basic 6.0: Run-Time Redistribution Pack (vbrun60sp6.exe)

14

PHPMaker 12 Help

MSXML Parser 3.0


IIS Express (only required if you want to use IIS Express as testing web server)

If you use Microsoft Access, SQL Server or Oracle, PHPMaker requires the following database
drivers to connect to the database:

Microsoft Data Access Components (MDAC) 2.8 (for Microsoft Access, SQL Server
and Oracle)
Microsoft Jet 4.0 Service Pack 8 (SP8) (for Microsoft Access <= 2003)
2007 Office System Driver: Data Connectivity Components (for Microsoft Access
2007)
Microsoft Access Database Engine 2010 Redistributable (for Microsoft Access 2010)
Microsoft SQL Server 2012 Native Client (X86 Package) (for Microsoft SQL Server
2005/2008/2012)
Oracle Client (for Oracle)

Server

Linux/Unix (MySQL/PostgreSQL/Oracle) or Windows


(MySQL/PostgreSQL/Access/MSSQL/Oracle) web server
PHP >= 5.3

Browser

IE 9+, Chrome/Firefox/Safari/Opera (current stable version and the


version that preceded it).

1.3 Installation and Uninstallation


Before you install PHPMaker, you must log in Windows as an user with
administrative privileges.
Important

PHPMaker 12 can co-exist with previous version of PHPMaker. You do NOT need to uninstall
previous version of PHPMaker if you don't want to.
Double-click on the downloaded installer to start the installation process. Follow the prompts
and change the settings whenever necessary.
To uninstall PHPMaker, go to [Control Panel]. Click [Add/Remove Programs] and select
[PHPMaker 12].

Note for Windows Vista/2008/2012/7/8 users:


In Windows Vista/2008/2012/7/8, User Account Control (UAC) is enabled by default,
members of the administrators group do NOT have full administrator privileges.
When you install (by double-clicking the installer or right-clicking the installer and choose
Run as administrator), an User Account Control prompt may be displayed and ask you
if you allow the program to make changes to your computer, click Yes to let the installer run
elevated.
If you still cannot install successfully, log in Windows as the built-in administrator
account to install. The built-in administrator account is disabled by default, you may need
to enable the built-in administrator account first:

15

PHPMaker 12 Help
1. Login as administrator. Open a command prompt (under All Programs ->
Accessories) in administrator mode by right-clicking and choosing Run as
administrator,
2. Type the command: net user administrator /active:yes. You should see:
"The command completed successfully."
3. Log out. You'll now see the Administrator account show up on the login screen.
Log in as the built-in administrator and install again. After successful installation, if you want
to disable the built-in administrator account. Logout and re-login as your regular user
account, and then open an administrator mode command prompt as above. Type the
command: net user administrator /active:no. The administrator account will now
be disabled, and should not show up on the login screen anymore.

1.4 License and Ordering Information


PHPMaker is not a free software. You are permitted to use this program for a period of 30
days. Continued use after that will require payment of the registration fee.
Benefits for registered users

Free upgrades of all minor versions for 12 months


Free email support for 6 months
Email notifications of upgrades
Access to registered user site
Additional extensions (if any)

After receiving your license key, register by clicking [Help]->[Register].


To register the program in Windows Vista/2008/2012/7/8 (or later), you need
administrative privileges and you may need to start the program by right clicking the
program file (.exe file) in the installed folder or its shortcut on the desktop and choose Run
as administrator. For more info on User Account Control (UAC), read:
http://support.microsoft.com/kb/922708
Note

Registration can be done as follows:


Credit Card Payment
http://www.hkvstore.com/phpmaker/purchase.asp
Mail order or Wire Transfer
Hong Kong Dollars Cheque or Money Order (List price), OR
International Bank Cheque or International Money Order or Wire Transfer or other payment
method (List price plus 25%)
Please contact sales@hkvstore.com for information about our bank account.

1.5 Technical Support


Registered users are entitled to 6 months free email support. Send your technical support
request to php.support@hkvstore.com.
Your email message should include the following information:

16

PHPMaker 12 Help
1. Is the problem reproducible? If so, provide the steps to reproduce it?
2. What version of Windows is your PC running?
3. What version of PHPMaker are you running? (Click [Help] and then [About...] to
check)
4. What database and what version are you using?
5. What OS is the server running? Windows or Linux? What version of PHP is running?
(Note that PHP 4 is not supported.)
6. If any error message was displayed, please include the full text of error message. If
not, describe the problem in detail.
7. Your project file (.pmp file) and your database (.sql file) with enough data for
reproducing the problem.
8. Your license information. Emails without license information will be ignored.
While we are happy to support your usage of our software, please note that technical
support does NOT entail customization of templates, extensions or generated code, writing
server events or client scripts (JavaScripts) or custom template, integrating third-party
code, setting up web server, or any other issues not directly related to the workings of the
software. Request for debugging or modifying code not generated from the original template
will be ignored.
Note

1.6 Disclaimer of Warranty


PHPMaker is supplied "AS IS". The authors disclaim all warranties, expressed or implied,
including, without limitation, the warranties of merchantability and of fitness for any
purpose. The authors assume no liability for damages, direct or consequential, which may
result from the use of PHPMaker.
Please note this program is Shareware. It is not Freeware. You are permitted to try the
program for a maximum of 30 days. Continued use will require payment of the registration
fee. Please refer to the License and Ordering(See 1.4) Section for details.

1.7 Third-party Tools


All the following tools are not developed by the author of PHPMaker and are not part of
PHPMaker, NO TECHNICAL SUPPORT WILL BE PROVIDED.
Note

PHPMaker uses the following third-party tools in template/extensions:


CKeditor
Website: http://ckeditor.com
CKEditor is distributed under the MPL Open Source license. If IE, requires IE >= 9.
JSCalandar
Website: http://www.dynarch.com/projects/calendar/old
This program is available under the terms of the GNU Lesser General Public License version
2.1 or above.
PHPMailer
Website: http://phpmailer.sourceforge.net
This program is available under the terms of the GNU Lesser General Public License version
2.1 or above.
DOMPDF
Website: http://code.google.com/p/dompdf
DOMPDF is available under the terms of the LGPL License.
Requires MBString and DOM extensions.

17

PHPMaker 12 Help
This extension is EXPERIMENTAL only. There are some known issues of DOMPDF,
please read the developer website for more information. Known issues includes (but now
limited to):
Warning

not particularly tolerant to poorly-formed HTML input


large files can take a while to render
use a lot of memory

jQuery
Website: http://jquery.com/
jQuery is released under MIT License.
JsRender
Website: https://github.com/BorisMoore/jsrender
JsRender is released under MIT License.
Bootstrap
Website: http://getbootstrap.com/
Bootstrap is licensed under Apache License v2.0.
Barcode and QRCode
Website: http://www.phpclasses.org/package/2441-PHP-Generate-barcode-graphs-usingdifferent-standards.html
The class is distributed for free without warranty.
PHP Thumb
Website: https://github.com/masterexploder/PHPThumb
PHP Thumb is distributed under the MIT License.
Supports GIF, JPEG and PNG images only. Requires PHP GD2 extension.
pGenerator and pStrength
Website: https://github.com/M1Sh0u/pGenerator and
https://github.com/M1Sh0u/pStrength/blob/master/pStrength.jquery.js
Both are released under the MIT License.

Additional extensions: (for registered users only)


Additional extensions are provided for registered users as examples of customzing and
extending template only, NO TECHNICAL SUPPORT WILL BE PROVIDED. Registered users
will be provided information to download the extensions. These tools will NOT automatically
work with PHPMaker without the extensions.
Note

Horizontal Menu
Replaces the graphical extension for previous versions. Uses Bootstrap Navbar as horizontal
menu.
FCKeditor File Manager (for CKEditor)
FCKeditor is the previous version of CKEditor and has been discontinued after version
2. FCKeditor extension had been dropped by PHPMaker. This extension only applies
the free File Manager from FCKeditor to CKEditor (so the commerical product CKFinder is not
required), based on http://www.mixedwaves.com/2010/02/integrating-fckeditorfilemanager-in-ckeditor/.
FCKeditor Website: http://sourceforge.net/projects/fckeditor/
FCKeditor is distributed under the LGPL Open Source license.

18

PHPMaker 12 Help
TinyMCE
Website: http://tinymce.moxiecode.com
TinyMCE is distributed under the LGPL Open Source license. If IE, requires IE >= 9.
Time Picker
Website: http://jonthornton.github.io/jquery-timepicker/
Timepicker Plugin for jQuery is made available under the open source MIT License.
PHPExcel
Website: http://phpexcel.codeplex.com
This program is available under the terms of the GNU Lesser General Public License version
2.1 or above. Requires PHP version 5.2.0 or higher, PHP extension php_zip enabled (for
Excel2007 format), PHP extension php_xml enabled and PHP extension php_gd2 enabled (if
not compiled in).
PHPWord
Website: http://phpword.codeplex.com
This program is available under the terms of the GNU Lesser General Public License version
2.1 or above. Requires PHP version 5.2.0 or higher, PHP extension php_zip enabled, PHP
extension php_xml enabled and PHP extension php_gd2 enabled (if not compiled in).
Detail Preview
Allow previewing detail records in an expanded row of the main table in List page, and/or in
a popup overlay by Bootstrap Popover.
Scrollable Table
Scrolling table example. Enable X/Y scrolling of the main table in the List page. If IE,
requires IE >= 9.
CAPTCHA
Generates CAPTCHA image. Requires PHP GD extension with GD2.
Also support reCAPTCHA (https://developers.google.com/recaptcha/). reCAPTCHA is
OPTIONAL. If you choose to use reCAPTCHA, note that reCAPTCHA is a Web service,
meaning that the CAPTCHA images are served directly from reCAPTCHA's servers to the end
users, the end users need to be online. To use the service, you must register at the
reCAPTCHA Web site and obtain public and private keys.

1.8 Introduction to PHP and MySQL


What is PHP?
PHP is a widely-used general-purpose server-side scripting language that can be embedded
into HTML. You can think of it as a "plug-in" for your Web server that will allow it to do more
than just send plain Web pages when browsers request them. With PHP installed, your Web
server will be able to read a new kind of file (called a PHP script) that can do things like
retrieve up-to-the-minute information from a database and insert it into a Web page before
sending it to the browser that requested it. PHP is completely free to download and use. If
you are new to PHP and want to get some idea of how it works, try the introductory tutorial.
PHP Home Page
Manual
Download

What is MySQL?

19

PHPMaker 12 Help
MySQL is a relational database management system, or RDBMS. It has become the world's
most popular open source database because of its consistent fast performance, high
reliability and ease of use. PHP has MySQL extension which makes it really easy to access
data in MySQL.
MySQL Home Page
Manual
Download

Useful MySQL Database Administration Tools


phpMyAdmin (freeware)

Installing PHP and MySQL on Windows


Both PHP and MySQL support various platforms, including Windows. It is recommended
that you install MySQL and PHP on your computer so you can easily develop and
test your PHP locally before uploading to your production server.
If you use Internet Information Services (IIS), you can install PHP on your Windows system
PHP for Windows installer which installs PHP for IIS, it configures the web server as well.
Alternatively, you can use Microsoft Web Platform Installer, see http://php.iis.net/.
If you do not have IIS, you can use other Web server such as Apache. If you have difficulties
installing PHP and MySQL, you might as well try EasyPHP which is an "out of the box"
Apache, MySQL, and PHP installation for Windows.
For PHP 5, MySQL is not enabled by default, so the php_mysql.dll (or php_mysqli.dll) DLL
must be enabled in php.ini. Also, PHP needs access to the MySQL client library. A file named
libmysql.dll is included in the Windows PHP distribution and in order for PHP to talk to MySQL
this file needs to be available to the Windows systems PATH.
The next step is to set up a valid configuration file for PHP, the php.ini. PHP searches for
php.ini in the locations described in The configuration file.
If you're using NTFS on Windows, make sure that the user running the web server has
read permissions to your php.ini (e.g. make it readable by Everyone).
Note

Some Important Settings in php.ini for Using PHP on Windows


extension_dir - In what directory PHP should look for dynamically loadable extensions. It
should be set to the folder where your extensions are installed, e.g.
extension_dir="C:\Program Files (x86)\PHP\ext"
session.save_path - This is the path where session data files are stored. Make sure this
setting points to an existing folder on your machine, e.g.
session.save_path="C:\Windows\Temp"
If you're using NTFS on Windows, make sure that the user running the web server has
write permissions to this folder (e.g. make it readable and writable by Everyone). See the
section Configuring Permissions below.
Note

upload_tmp_dir - If you want to use file upload, make sure this setting points to an existing
folder on your machine, e.g. upload_tmp_dir="C:\Windows\Temp"

20

PHPMaker 12 Help
If you're using NTFS on Windows, make sure that the user running the web server has
write permissions to this folder (e.g. make it readable and writable by Everyone). See the
section Configuring Permissions below.
Note

php_com_dotnet.dll - If you use MS Access or MS SQL Server (on Windows server), the COM
extension is required. As of PHP 5.3.15 / 5.4.5, the COM extension
requires php_com_dotnet.dll to be enabled inside of php.ini, i.e.
extension=php_com_dotnet.dll
Also make sure you have installed the php_com_dotnet.dll in the extension folder
(extension_dir) specified in php.ini.
Note

Internet Information Services (IIS)


IIS 7.x or later is included with Windows Vista/2008/2012/7/8/10 and is installed via
Programs->Turn on or off Windows features in the Control Panel. Read:
http://www.iis.net/learn/install/installing-iis-7/installing-iis-on-windows-vista-and-windows7

Creating Virtual Directories in IIS 7 (Windows Vista or Later)

The IIS manager user interface consists of three panes.

The left hand side pane is Connections, the middle pane is Workspace and the right hand
side pane is Actions.
The Connections pane lists application pools and websites. The workspace pane consists of
two tabs at the bottom namely Features View and Content View. The Features View
allows you to work with the settings of the selected item from Connections pane whereas
the Content View displays all the child nodes (content) of the selected item.

21

PHPMaker 12 Help
Application pool is a group of IIS applications that are isolated from other application
pools. Each application pool runs in its own worker process. Any problem with that process
affects the applications residing in it and not the rest of the applications. You can configure
application pools individually.
In order to create a new application pool, select "Application Pools" under Connections pane.
Then click on "Add application pool" from Actions pane. This will open a dialog as shown
below:

Specify a name for the new pool to be created. Select .NET framework version that all the
applications from the pool will use. Also select pipeline mode. There are two pipeline modes
viz. integrated and classic. The integrated mode uses the integrated request processing
model whereas the classic mode uses the older request processing model. Click OK to create
the application pool.
Your new application pool will now be displayed in the Workspace pane. To configure the
application pool click on the "Advanced Settings" option under Actions pane. The following
figure shows many of the configurable properties of an application pool.

22

PHPMaker 12 Help

If you use 64-bit Windows, set Enable 32-Bit Applications to True. (See Running on 64bit Windows Operating System below.)
To create a new web site, select Web Sites node under Connections pane and then click on
"Add Web Site" under Actions pane. This opens a dialog as shown below:

23

PHPMaker 12 Help

Here, you can specify properties of the new web site including its application pool and
physical location.
Creating an IIS application or a Virtual Directory is quick and simple. Just right click on
the web site and choose either "Add Application" or "Add Virtual Directory" to open
respective dialogs (see below).

24

PHPMaker 12 Help

An existing Virtual directory can be marked as an IIS application by right clicking on it and
selecting "Convert to Application".
If you use IE, you may encounter the following error messages when you run PHP pages
with IIS 7:
An error occurred on the server when processing the URL. Please contact the system
administrator.
Go to Internet Options -> Advanced, disable Show friendly HTTP error messages.

25

PHPMaker 12 Help

Configuring Permissions
An important aspect of working with file upload to a folder on the Web server is to correctly
configure permissions.
When a Web application uses a file, the application must have Read permission to the file so
the application can access the data. Additionally, the application must have Write permission
to the folder that contains the file. Write permission is required because the file may be
created at run time.
If you use Linux/Unix, CHMOD your upload folder to "777" by using your FTP software.
To use an Access database in an PHP Web application, you must configure the folder that
contains the Access database to have both Read and Write permissions for the IIS user
account.
The default anonymous IIS user depends on IIS version. In IIS 5, it is
IUSR_<MachineName>. In IIS 6 and IIS 7 it can be NETWORKSERVICE or IUSR. In IIS 7.5
it depends on Application Pool, read Application Pool Identities for detail.
To set permissions in the folder (if you're using NTFS on Windows),

26

PHPMaker 12 Help
1. In Windows Explorer, move to the root folder for the Web site. e.g.
C:\Inetpub\wwwroot\ExampleSite.
2. If the folder does not already exist, create one.
3. Right-click the folder, click Properties, and then click the Security tab.

4. Under Group or user names, look for or add the user.


5. Verify that the account has Read and Write permissions for the folder.
Similarly, set permissions in the folder where the audit trail log file reside.

Running on 64-bit Windows Operating System

Windows Server 2008 or Windows 7 64-bit (IIS 7.x)


On 64-bit Windows 2008/7, IIS 7.x can run both 32-bit and 64-bit worker processes
simultaneously. To run 32-bit Web applications in IIS 7.x on 64-bit Windows all it needs is to
assign the 32-bit applications to a separate application pool in IIS and turn on the Enable
32-Bit Applications switch for that application pool. To do this, open IIS Manager, open
Application Pool, select the application pool, and then click Advanced Settings. In
Enable 32-Bit Applications, select True.

27

PHPMaker 12 Help

1.9 Quick Start


PHPMaker connects to your database, extracts tables and fields information, and generates
PHP scripts instantly based on these information. For each table, it will generate a list page,
add/copy page, view page, edit page, delete page and search page all linked up properly.
To generate scripts, you just need to follow the tabs and setup the options, that is:
[Database] > [PHP] > [HTML] > [Security] > [Generate]
However, if you are a first time user, we recommend you to generate a basic PHP application
and get to know how PHPMaker and PHP works first.
If you have not used PHP before, it is recommended that you read Introduction to PHP
and MySQL(See 1.8) first.
Note

To generate your first PHP project, you can skip the options and use default settings first. In
other words, you skip the intermediate steps and go directly to the [Generate] tab after
connecting to your data source, that is:
[Database] > [Generate]
You can generate the web site quickly by the following steps:
1. Start up PHPMaker. There are two connection methods to connect to your MySQL server DIRECT or URL. As explained in Introduction to PHP and MySQL(See 1.8), it is recommended
that you have a local MySQL server during development. You usually connect to MySQL by
the DIRECT method, the URL method is only used when you want to conenct to a remote
MySQL server which does not allow direct connection. (See Tutorial - Connecting Remote
MySQL using PHPMaker Connection Script(See 1.15.1).)
2. In this example, we use direct connection. Enter connection details for the MySQL Server
.

28

PHPMaker 12 Help

3. Click the [Connect] button to load the database information. Tables and fields
information will be loaded and displayed on the left hand side.

4. Click the [Generate] tab and select the follows:


Template file - The zipped file that contains the template of the generated pages. Just use
the default template is shipped with PHPMaker.
Application root folder - The root folder of your PHP application. (See Application
Root(See 1.11))
Destination folder - The folder that the generated scripts will reside. This can be same as
the application root folder or a subfolder under the application root folder. In this case, we
use the same folder for simplicity.

29

PHPMaker 12 Help

To run PHP you need to setup a website or virtual directory (See Introduction to PHP and
MySQL (See 1.8)). If you are not familiar with web server, you can install IIS Express which
can be downloaded from Microsoft website. Then select [IIS Express] and [Browse after
generation] in PHPMaker.
5. Click the [Generate] button, the generation process will begin. After the web site is
generated successfully, a completion message will be displayed. The web site should then be
ready to run. If [Browse after generation] is enabled, PHPMaker will open your browser,
and - voila! - you'll see PHP displaying the data in your first PHP website.

30

PHPMaker 12 Help
After understanding how it works, you can then take advantages of various other options
provided by PHPMaker and setup your project more precisely. See Project Setup(See 1.10)
for full details.

1.10 Project Setup


To make use of the various features of PHPMaker and create scripts that best suit your Web
sites, read the following information and get to know the options PHPMaker provide. It is
assumed that you have basic knowledges of HTML and PHP and the technical terms are used
without further explanation. To generate a Web site, please perform the following steps:
1.
2.
3.
4.
5.

Database(See 1.10.1)
PHP(See 1.10.2)
HTML(See 1.10.3)
Security(See 1.10.4)
Generate(See 1.10.5)

To further control the functionality of the generated scripts, you can setup different options
for each table/field:

Table Setup(See 1.10.6)


Field Setup(See 1.10.7)

You can also setup additional database objects for your project in PHPMaker:

Custom View(See 1.10.11)


Report(See 1.10.12)
Custom File(See 1.10.13)
Linked Table(See 1.10.15)

1.10.1 Database Setup


If you are not at the [Database] tab yet, clicking the
icon in the toolbar to go to
[Database] tab. PHPMaker can connect to MySQL, PostgresSQL, Microsoft Access, Microsoft
SQL Server and Oracle.
1. MySQL
Select MySQL as database type.

31

PHPMaker 12 Help

There are 2 connection methods you can choose:


Direct Connection (default)
1. Enter your database host/server name (or IP address), username, password and
port number (default is 3306 for MySQL),
2. Select your database,
3. Select the SQL Identifier Quote Character, default is backquote (`) for MySQL,
4. Click the [Connect] button to load the database information.
The server name or IP should be valid on your production Web server also. Otherwise
you'll need to modify the generated connection info in ewcfg*.php before you upload it to
your production server. For example, if you have a testing MySQL Server installed on the
same computer, you can use "localhost" as server name when you connect to it with
PHPMaker. The generated scripts will then try to connect to a MySQL Server on the same
computer as the production Web server, if this is not the case, the connection will fail.
URL Connection (for remote database)
Note

(Also see Tutorial - Connecting Remote MySQL using PHPMaker Connection Script(See
1.15.1))
While the direct connection method is quick and easy, some remote MySQL server may not
allow direct connection. PHPMaker provides an alternative simple way to connect remote
servers:
1. Upload the PHP connection script provided by PHPMaker to your site. Note that:
a.
b.

The script is named "phpmaker.php" and can be found under your installed
folder, usually C:\PHPMaker,
Always use the script shipped with your version of PHPMaker.
PHPMaker may not work with script shipped with previous versions.

2. If it is the first time that you use this script, you may want to test the script with
your browser:

32

PHPMaker 12 Help
a.

Browse to this script with your browser,

b.

Enter the connection info,

c.

Click "Get Database List" and then "View Schema", you should be able to
view the schema of your database in XML properly. Now go back to
PHPMaker.

3. Enter the SAME connection information, select URL for connection method, enter the
URL of the script (e.g. http://servername/path/phpmaker.php), you can test the URL
by clicking the [Test] button,

4. Click the [Connect] button to load the database information. PHPMaker will connect
to the database server through the PHP script over HTTP.

33

PHPMaker 12 Help

2. PostgreSQL
Select PostgreSQL as database type.

There are 2 connection methods you can choose:


Direct Connection (default)
1. Enter your database host/server name (or IP address), username, password and
port number (default is 5432 for PostgreSQL),
2. Select your database,
3. Select the SQL Identifier Quote Character, default is double quote (") for
PostgreSQL,
4. Click the [Connect] button to load the database information.
The server name or IP should be valid on your production Web server also. Otherwise
you'll need to modify the generated connection info in ewcfg*.php before you upload it to
your production server. For example, if you have a testing PostgreSQL Server installed on
the same computer, you can use "localhost" as server name when you connect to it with
PHPMaker. The generated scripts will then try to connect to a PostgreSQL Server on the
same computer as the production Web server, if this is not the case, the connection will fail.
URL Connection (for remote database)
Note

Similar to above for MySQL.

3. Microsoft Access (Windows only)


If you use Microsoft Access database, you need to have OLEDB drivers installed on both
the PC running PHPMaker and on the web server. See System Requirements(See 1.2).
(ODBC connection is not supported.)
Note

34

PHPMaker 12 Help

Select Microsoft Access as database type,

Click the

Select the Microsoft Access database file by clicking the


button,
Specify the database path where the database file will reside under the your
application root,
Connect button to load the database information.

Notes

1. Database path is relative to application root. Use slashes "/" as path delimiter, no
leading slash. e.g. If the application root of your website is
C:\Inetpub\wwwroot\demo and you enter "data/" in this textbox, the folder for the
database will be C:\Inetpub\wwwroot\demo\data. If you are not sure which folder is
application root, please read Creating Virtual Directories in IIS(See 1.8).
2. PHP COM extension is required on the web server. As of PHP 5.3.15 / 5.4.5, the COM
extension requires php_com_dotnet.dll to be enabled inside of php.ini in order to use
these functions. Previous versions of PHP enabled this extension by default. Read
http://php.net/manual/en/book.com.php.

4. Microsoft SQL Server (Windows only)


Notes

1. If you use SQL Server 2000/2005/2008/2012 and have installed SQL Server 2012
Native Client on your computer, then Microsoft SQL Server and Microsoft SQL
Server 2005/2008/2012 database type will be available for selection. You can use
this database type for connection to SQL Server 2000, 2005, 2008 or 2012. You can
download SQL Server 2012 Native Client from the Microsoft website. See System
Requirements(See 1.2). The native client must also be installed on the web server.
(ODBC connection is not supported.)
2. PHPMaker connects to the SQL Server by TCP/IP (NOT Windows authentication),
make sure TCP/IP protocols is enabled for your SQL server, you can use SQL Server
Configuration Manager to check and configure.
3. If the SQL Server is a remote server (not on the same machine as PHPMaker), make
sure your SQL Server allows remote connection, you can use SQL Server
Management Studio to check and configure.

35

PHPMaker 12 Help
4. If you have firewall enabled on the server, make sure it allows inbound
traffic on port 1433 for TCP/IP. If the SQL Server uses another port number, make
sure you have set up the firewall rules accordingly.

Select Microsoft SQL Server (or Microsoft SQL Server 2005/2008/2012 if you
use SQL Server 2005/2008/2012 or later) as database type,
Enter the name or IP of the SQL server,
Enter the User ID and Password,
Select the database you want or just enter the name of your database,
Click the

Connect button to load the database information.

Notes

1. If Microsoft SQL Server 2005/2008/2012, make sure the server name includes
the instance name, e.g. localhost/SQLEXPRESS.
2. The server name or IP should be valid on your production Web server also.
Otherwise you'll need to modify the generated connection string in ewcfg*.php
before you upload it to your production server. For example, if you have a testing
SQL Server installed on the same computer, you can use "(local)" as server name
when you connect to it with PHPMaker. The generated scripts will then try to connect
to a SQL Server on the same computer as the production Web server, if this is not
the case on the server, the connection will fail. It is common that SQL Server is
installed on a different server in production environment.
3. PHP COM extension is required on the web server. As of PHP 5.3.15 / 5.4.5, the COM
extension requires php_com_dotnet.dll to be enabled inside of php.ini in order to use
these functions. Previous versions of PHP enabled this extension by default. Read
http://php.net/manual/en/book.com.php.

5. Oracle

36

PHPMaker 12 Help
If you have installed Oracle client on your computer, this database type will be available
for selection. You can download Oracle client from the Oracle website. Make sure the path of
your Oracle client (e.g. oci.dll) is among the Path variable under Windows Environment
Variables -> System variable.
Note

Select Oracle as database type,


Enter the Oracle Service name,
Enter the User ID and Password,
Select the Schema you want or just enter the Schema name,
Click the

Connect button to load the database information.

The service name should be valid on your production Web server also. Otherwise you'll
need to modify the generated connection info in ewcfg*.php before you upload it to your
production server. The service name must be set to the appropriate Net8 name which is
known to the naming method in use. For example, for Local Naming, it is the alias in the
tnsnames.ora file; for Oracle Names, it is the Net8 Service Name.
Note

Load from PMP Project File


If you previously saved your project file (.pmp file), you can load it back by clicking the
open button on the tool bar (or select "Project", "Open" from the menu bar). At completion,
the tables and fields information will be loaded and displayed on the left pane.

37

PHPMaker 12 Help

The database pane is dockable. If you prefer to display the database pane on the right hand
side, simply drag it to the right side.
Dynamic Table Loading
By default all tables in the database are loaded. It is convenient but loading and
sychronization could be slow if your database contains a large number of tables or fields. If
this option is enabled, a table will only be loaded when you select it in the database pane. If
you just use a few tables out of a large database, this feature enables you to work much
faster than before. To enable this feature, simply check [Load tables dynamically]
BEFORE pressing the [Connect] button.

1.10.2 PHP Settings


General Options

38

PHPMaker 12 Help

Add shell call

(For Unix-based server only) If you put the PHP parser binary
somewhere outside of the web tree of files, for example, in
/usr/local/bin, you will have to put a line similar to: #!/usr/local/bin/php
as the first line of any file containing PHP tags. (You will also need to
make the file executable.)

Set locale

Set locale information. PHPMaker uses localeconv() which returns data


based upon the current locale as set by setlocale().
Different systems have different naming schemes for locales.
If you do not know the correct locale string on your server or you want
to override system locale and use your own locale settings, click the [...]
button and enter your locale settings.

39

PHPMaker 12 Help

Refer to localeconv() for the definition of the settings.


If you use Multi-Language (see below), DO NOT use this setting
unless all languages share the same locale settings. Each language has
its own locale settings and you should specify locale settings for each
language in the respective language file. (See Customizing
Template(See 1.14))
Note

Default Date
Format

The default date format for the scripts. Possible values are:
yyyy/mm/dd, mm/dd/yyyy, dd/mm/yyyy,
yyyy-mm-dd, mm-dd-yyyy, dd-mm-yyyy,
yyyy.mm.dd, mm.dd.yyyy, dd.mm.yyyy
with or without time (hh:mm:ss). The selected date format also
determines the date separator ("/" or "-" or ".").

No Cache

Whether caching is required on browser

Multi-Language

Enable multi-language project. If enabled, a combobox will appear on


the top of the generated scripts for user to select language. See
Tools(See 1.13) for selecting languages for the multi-language project.
Important

1. Multi-Language project must use utf-8 encoding. The charset of


the project must be "utf-8".
2. The data in your database must be stored in unicode, otherwise
your data will not be displayed properly.
3. If you have customized the template and put unicode characters
in the template directly instead of using language files, enable
the Advanced Setting UTF-8 output files (see Customizing

40

PHPMaker 12 Help
Template(See 1.14) and Tools(See 1.13)).
Default Language Default language of the project. It must be compatible with Charset
(see HTML Settings(See 1.10.3)). Default is English.
There is always one default language for a project. Only the English
language file (english.xml) is shipped with PHPMaker. If your project is
single language but you use another language, create a language file for
your language (see Customizing Template(See 1.14)), put it in the
"languages" subfolder under the installation folder and then select your
default language using this combobox.
If you enable Multi-Language, you must select one of the selected
languages as the default language.

File Upload

Upload folder - The global folder where the uploaded files resides. If
you do not enter a specific folder for a file upload field in the Edit Tag
panel of the Field Setup(See 1.10.7) page, all the uploaded files will be
put in this folder.
Always specify an upload folder if you allow file upload.
This folder is used as the root folder of temporary folders for file upload
fields during Add/Edit. It is also used as the root folder of the user files
folder of CKEditor.
Important

Notes

1. Unlike the field specific upload folder setting (which is a PHP


expression), this field specific setting must be a constant
string (without double quotes). If you want dynamic upload
folders for different fields, specify upload folder for each field
(see Field Setup(See 1.10.7)).
2. Make sure that the Web server user have read/write
access to the folder.
3. The path is relative to application root. Use slashes "/" as
path delimiter, no leading slash. e.g. If the application root of
your website is C:\Inetpub\wwwroot\demo and you enter
"uploads/" in this textbox, the folder for the uploaded files will
be C:\Inetpub\wwwroot\demo\uploads. If you are not sure
which folder is application root, please read Application Root(See
1.11).
Max File Size - Maximum file upload size in bytes. If <= 0, there is no

41

PHPMaker 12 Help
checking on file size.
File upload also depends on your PHP, web server and database
configuration:
Notes

1. PHP - Check your php.ini, related configurations are


file_uploads, upload_max_filesize, upload_tmp_dir,
post_max_size, max_input_time, memory_limit, and
max_execution_time directives in php.ini.
2. Apache - If you use Apache web server, check
LimitRequestBody directive.
3. MySQL - Check the max_allowed_packet setting in your MySQL
configuration.
Allowed file types - The allowed file extensions of the uploaded files.
Separate the file extensions (without ".") by comma without space, e.g.
gif,png,png. If blank, all file types are allowed.
Delete file on update/delete - Option to delete the uploaded file when
the field value is replaced, removed or if the record is deleted.
If Delete file on update/delete is enabled, the uploaded file will
be deleted. If the deleted record is a copied record, deleting the
uploaded files will affect the original record. To prevent such possible
problem, enable Advanced Setting Create upload file on copy (see
Advanced Settings(See 1.13)) to duplicate the uploaded file when
copying a record.
Note

Audit Trail

You can choose to log activities in a log file or in a database table.


Log file folder - The folder where the audit trail log file resides.
Notes

1. Make sure that the Web server user have read/write


access to the folder.
2. The path is relative to application root. Use slashes "/" as
path delimiter, no leading slash. e.g. If the application root of
your website is C:\Inetpub\wwwroot\demo and you enter
"uploads/" in this textbox, the folder for the log file will be
C:\Inetpub\wwwroot\demo\uploads. If you are not sure which
folder is application root, please read Application Root(See
1.11).
Use database table - Log the activities in the specified table instead of
log file. The table must have the following fields: (actual data types

42

PHPMaker 12 Help
depend on database type)

DateTime (DateTime)
Script (VarChar)
User (VarChar)
Action (VarChar)
Table (VarChar)
Field (VarChar)
KeyValue (Long VarChar)
OldValue (Long VarChar)
NewValue (Long VarChar)

You can create the database yourselves and select the table in the
combobox, then click the [...] button to select the fields in your table.
Alternatively, if you have not created the table yet, you can click
[Create Table] and let PHPMaker creates the table and setup the
settings for you.
Track login/logout activities - If security feature is enabled,
login/logout activities will also be logged.
Validation

Server-side - Enable server-side form validation.


Client-side (JavaScript) - Enable client-side form validation.
If the available validation format in the Edit Tag panel (see Field
Setup(See 1.10.7)) does not fulfil your requirements, you can use your
own server-side and/or client-side validation code using Server Event
and Client Scripts(See 1.10.9).
Note

List/View Page Options (Global)


The following list/view page options are global for all tables. If you want different settings
for a particular table, you can use table-specific options available in the Table Setup(See
1.10.6) page.

43

PHPMaker 12 Help

Records per page

Number of records to be displayed on the list page


of all tables. If blank or 0, default setting of 20 will
be used.

Selectable page sizes

Number of records to be selected by user. Comma


separated values, e.g. 10,20,50,ALL.
"ALL" (without quotes) is supported, other
values must be integers.
Note

Paging section style

"NumericPages" or "NextPrev"

Sort type

None, Single column or Multiple column. If


Multiple column is selected, the generated list
page supports multi-column sorting by Ctrlclicking the table header.

44

PHPMaker 12 Help
Multiple column

Show multiple records per row. Default is 0. This


feature will only take effect if the value is > 0.
Possible values: 1, 2, 3, 4, 6, 12

Paging section at top

Show the paging section at top (also applies to


View page)

Paging section at bottom

Show the paging section at bottom (also applies


to View page)

Paging section in View page

Show paging section in View page also

Paging section in Edit page

Show paging section in Edit page also

Multiple delete

Show checkboxes in the list page for selecting


multiple records to delete

Inline delete

Delete records directly without showing delete


confirm page

Links on left side

Show the links in record row on the left instead of


right

Use buttons as links

Show the links in record row as a button group


instead of individual icons or links.

Use button dropdown for links

Show the links in record row as a button with


dropdown menu instead of individual icons or
links.

Use button dropdown in paging


section

Show the links in paging section as buttons with


dropdown menu instead of individual links.

Use modal dialog for Advanced


Search

Show the Advanced Search page in a modal dialog

Export

Enable export in List page - allow export in List


pages
Enable export in View page - allow export in
View pages also
Use button dropdown - show the export links as
a button with dropdown menu. Default is showing
the export links as a row of icons.
Print/CSV/HTML/Excel/Word/XML/PDF/Em
ail - Records can be exported to Print (printerfriendly), CSV, HTML, Excel, Word, XML, PDF
format or sent as HTML email content.
The fields in printer friendly version are same
as in List/View page, while the fields in other
format are determined by the Export setting of the
field in Field Setup(See 1.10.7) page.
Note

Note that the fields in printer friendly version are


same as in List/View page, while the fields in
other format are determined by the Export setting

45

PHPMaker 12 Help
of the field in Field Setup(See 1.10.7) page.
Export type - Determines which records to
export. The follows are supported:

All Pages - Records in all pages are


exported
Current Page - All records in current
page are exported
Selected Record - If selected, a
checkbox will be displayed in each row for
selection. Only selected records in the
current page are exported. (Selecting
records in different pages is not allowed.)
To select records primary key is required,
Current Page export type will be used for
tables without primary key.

Notes

1. Binary data (BLOB fields) cannot be


exported.
2. Export to HTML/CSV/XML/PDF are not
applicable to reports.
3. Images cannot be exported to
Word/Excel/CSV/XML.
4. Export-to-XML requires PHP DOM (part of
PHP 5 core).
5. Export-to-Word/Excel works by exporting
data in HTML format for Word/Excel to
convert/import, the exported file is not
native .doc/.xls format. (Registered user
can use the PHPExcel extension which
output native Excel file format.)
Notes (Export to PDF)

1. The extension is an experimental


extension only. There are known issues,
see Third-party Tools(See 1.7) and read
the note in the extension setup page (see
Tools -> Extensions(See 1.13)) for more
information before use. Only enable it if
necessary.
2. The extension performs best if you are
using non-unicode alphanumerical
characters (e.g. iso-8859-1) only. If you
use unicode, configure advanced settings
for the extension, read the note in the
extension setup page (see Tools ->
Extensions(See 1.13)) for more
information.
3. By default export is only enabled in View
page. If you want to enable it in the List
page also (the number of records to be
exported is not large), you can set the
advanced settings of the extension (see
Tools -> Extensions(See 1.13)).
4. The extension supports images (jpg, gif
and png only), but a temporary folder is
required during export, the extension uses
the Upload folder (see File Upload

46

PHPMaker 12 Help
above) because write permission for the
folder should be already setup properly. If
you do not use file upload to folder, but
you use export to PDF with images, then
make sure you still specify an upload
folder and set up the write permission.

Email Settings
PHPMaker supports many features that can send emails. If you use these features, you'll
need to specify a SMTP server.
From v9, PHPMailer (see Third-party Tools(See 1.7)) is always used as the email
component. Make sure you generate and upload the subfolder named "phpmailer<version>"
to your website.
Note

SMTP server

The host name or IP of the SMTP server.


Some servers do not support "localhost" as SMTP server, in
such case you need to specify a valid SMTP server in the
network.
Note

SMTP server port

Port number of SMTP server. Default is 25.

SMTP server username

User name for SMTP server authentication. If your SMTP server


does not require authentication, leave it blank.

SMTP server password

Password for SMTP server authentication. If your SMTP server


does not require authentication, leave it blank.

Sender (Email address)

Email address of the sender of all emails

Recipient (Email address)Email address of the recipient(s) for notification emails when a
record is added/edited/deleted (if enabled, see Table Setup(See
1.10.6)). If there are multiple recipients, separate them by
comma.

47

PHPMaker 12 Help
Protocol used by the SMTP server. Possible values are: SSL or
TLS.

Security

Leave this setting empty if your SMTP server does not use
such protocols.
Note

1.10.3 HTML Settings


General

Title

Title displayed on all pages.


If you use Multi-Language (see PHP Settings(See 1.10.2)), use MultiLanguage Property Editor, see Tools(See 1.13) for details.
Note

Charset

Charset setting used in the META tag of the site and for exporting data.
If you use Multi-Language (see PHP Settings(See 1.10.2)), this setting
must be utf-8.
Note

Font

Default font. If not specified, Bootstrap (see below) @font-family-sans-serif will


be used, default is: "Helvetica Neue", Helvetica, Arial, sans-serif.

Size

Default font size (pixel). Unit must be in pixel for working with Bootstrap (see
below). Default is 14.

Site icon

Icon of the site. For browsers to show your URL with an icon. Must be an .ico
file.

Site header Logo image in the header


logo
Note This setting is enabled in registered version only. Registered version
allows no logo.
Site footer Footer text (e.g. copyright statement)
text
Notes

48

PHPMaker 12 Help
1. If you use Multi-Language (see PHP Settings(See 1.10.2)), use MultiLanguage Property Editor, see Tools(See 1.13) for details.
2. This setting is enabled in registered version only.

Theme
Provides over a dozen of themes for you to setup the look and feel of your project quickly.

You can change the various properties of the selected theme to suit your style. The property
name are self-explanatory.
Themes are intergrated with Bootstrap, you can customize Bootstrap properties directly in
the Theme tab, scroll down to find the Bootstrap variables which start with "@".
To export custom theme settings, click the [Export theme] button to export the theme to an
external xml file. To import custom theme settings from earlier saved xml files, click the
[Import theme] button.

49

PHPMaker 12 Help

There are some settings related to Bootstrap but they are not Bootstrap "@xxx" variables:
Mobile Menu - Inverted

Modify the look of the mobile menu by adding CSS class


".navbar-inverse". Default is FALSE.
Mobile menu uses Bootstrap Navbar which support
"inverted" style, see Inverted Navbar.

Theme (Bootstrap) - Use


Bootstrap Theme

Load the optional Bootstrap theme for a visually


enhanced experience. See Bootstrap Theme. Default is
TRUE.

Notes

1. Changing a setting in the user interface does not change the corresponding setting
in the theme definitions, it only changes the setting for the project. The theme
definition files (in XML format) are installed in the subfolder "themes" under the
installation folder. You can easily add your own themes by duplicating one of the
theme definition file (except the theme.xml which is for defining the settings and
data type in a theme), rename it and modify the settings in the file, just make sure
you give your theme an unique theme name.
2. Bootstrap is a sleek, intuitive, and powerful front-end framework for faster and
easier web development, to get started, checkout http://getbootstrap.com.
3. After changing theme properties, make sure you re-generate *.css files.

50

PHPMaker 12 Help
Styles

Edit styles

A separate CSS stylesheet will be generated for each project. Click the
[Edit styles] button to open CSS editor.
Notes

1. All projects use CSS stylesheet.


2. If you have TopStyle Pro (v1.5+) or TopStyle Lite (v1.5-3.1)
installed on your PC, PHPMaker will use it automatically.
Notes

When you edit the CSS styles in the editor, note the follows:

1. DO NOT MODIFY the system styles section, it is generated by the


system, your modifications will be overwritten. If you want to
change the stylesheet template, modify the ew.css in the "themes"
subfolder under the installed directory. Only modify the ew.css if
you have the necessary knowledges in CSS.
2. DO NOT REMOVE THE FOLLOWING COMMENTS:

BEGIN_USER_STYLES
END_USER_STYLES
You MUST write your styles between these two comment
lines, styles outside this user styles section will be
discarded.
3. If you want to override the system styles, you can copy the styles
to the User Styles Section, or you can use a separate user
stylesheet.
User StylesheetSpecify an external user stylesheet (will be copied across during
generation)
You can see the effect of new settings immediately in the preview window at the bottom of
the HTML tab.

51

PHPMaker 12 Help

Other than choosing color from the palettes, the color picker can also pick color directly from
screen using the "eyedropper".

1.10.4 Security Settings

Field Description:
Administrator Login (HardCoded)

Administrator user id and password

Login Name

Login Name for administrator

Password

Password for administrator

Use Existing Table

Link to existing table for login name and password


validation

52

PHPMaker 12 Help
Table

Existing table in database containing login name and


password information

Login Name Field

Login Name field in table used for authentication

Password Field

Password field in table used for authentication

Login Options

Login options in the login page:


Auto-login - Auto login until the user logout explicitly

When you enable the auto-login feature, a few cookies


will be placed on the user's computer to identify the
user, meaning that the user do not have to type
username and password every time he/she visit the site.
For this reason, you should advise your users not to use
this feature on a public or shared computer, as any other
user of the computer will be able to access the account.

Remember username - Save the user's user name in


cookie

Always ask - Do not save user name and password,


always ask for them in the login page

Advanced Security
Advanced Security feature allows you to setup User ID, assign User Levels to users and
create a complete user registration system. To setup, click the [Advanced] button.
PHPMaker supports two types of security - User ID and User Level. User ID Security
secures data at record level. User Level Security secures data at table level. They
complements each other and they can work independently or together. Users get their User
ID and User Level after login. Before login, an user's identity is unknown and the user is an
Anonymous User.

53

PHPMaker 12 Help

User ID
User ID Security secures data at record level. Protected tables must have an User ID field
for identifying which user a record belongs to. The User ID field names can be different in
tables though. When User ID security is enabled, users can only access their own data.

Steps to setup User ID security for different tables/views:


1. Click on User ID in the left pane.
2. Select the [User ID field] from your user table, this field is usually the primary key
of the User Table. (Note: if this field is not set, the feature is disabled)
3. (Optional) Select the [Parent User ID field] from your user table. Parent User ID
field stores the parent User ID that the user belongs to, parent user can modify the
child user's records. Parent User ID is hierarchical, parent users can access the
records owned by the child users of their child users. (Note: if this field is not set,
the Parent User feature is disabled.)
4. In the [User ID Field] column, select the User ID Field for the tables/views that
requires User ID security.
5. (Optional) Enable [Allow View All] if you allow all logged in users (not including
Anonymous User) to list/search/view (but not add/copy/edit/delete) all records in
the table.

User Level
User Level Security secures data at table level. Each user level is granted with specific
permissions to tables in the database.
There are 2 types of User Level security:
1. Static User Levels - the User Levels and the permissions are defined in this form and
the User Levels are not to be changed after script generation.

54

PHPMaker 12 Help

Steps to setup static User Level security for different tables/views:


1. Click on User Levels in the left pane,
2. Select an integer field in your user table as the [User Level field], (Note: if this
field is not set, the feature is disabled)
3. Define your user levels, click
user level.

icon the add an user level and

icon to delete an

2. Dynamic User Levels - the User Levels and the permissions are defined in 2 tables in
the database, the User Levels can still be changed with the generated scripts.

Steps to setup dynamic User Level security for different tables/views:


1. Click on User Levels in the left pane,

55

PHPMaker 12 Help
2. Select an integer field in your user table as the [User Level field],(note: if this
field is not set, the feature is disabled)
3. Switch to the [Dynamic User Levels] tab, check [Enable Dynamic User Levels],
4. Select your User Level Table and User Level Permission Table and the required
fields.
The User Level Table and User Level Permission Table must have the following fields,
note the data types, User Level ID and the Permission fields must be of integer type, the
field names can be different though:

If you want PHPMaker to create these 2 tables in your database, click the [Create tables]
button, the following form will display for you to change the table/field names if necessary.
You can change the table/field names and then click OK to continue.

If you have projects created by previous versions of PHPMaker you may want to use
dynamic User Levels and migrate the previously defined static User Levels in the project to
the database. After selecting or creating the User Level and User Level Permission
tables/fields, just click the [Migrate] button to let PHPMaker do that for you.

56

PHPMaker 12 Help
After setting the user levels, PHPMaker will populate the user levels to the User Level field's
Edit Tag (also see Field Setup(See 1.10.7)) so administrators can assign user levels using
the generated pages.
Important Notes on Anonymous Users

1. From v12, the permissions for anonymous users are integrated in the User Level
security settings. See built-in user levels for anonymous users below.
There are three built-in user levels:
Anonymous - Anonymous user level is a built-in user level for the anonymous user (i.e.
users that have not logged in). The User Level ID of the anonymous user is -2.
Administrator - Administrator user level is a built-in user level that has all permissions plus
the privileges to modify User IDs and User Levels. Its permissions are same as that of the
hard-coded Administrator. The User Level ID of Administrator is -1.
Default - Default user level is built-in user level with user level = 0. Since User Level field is
an integer field, if you set a default value of 0 for this field, this user level will become the
default user level for the user after registration and before the Administrator assigning
another higher user level.
Important Notes on User Levels

1. Even you enable all permissions for an user defined User Level, the User Level will
NOT become same as this Administrator User Level. User defined User Levels will
not have the permissions to manage users.
2. From v9, the permissions for List/Search/View are separate in newly created
projects. However, for backward compatibility, the permissions for List/View/Search
in converted projects (created by previous versions) are the same unless you have
enabled Separate permssions for List/View/Search in Advanced Settings(See
1.13).
3. You may need to use the hard-coded Administrator Login to log on and assign
dynamic user levels to users initially.
4. It is possible to use single login and common Dynamic User Levels for multiple
projects provided that ALL projects use the same project name and same Advanced
Security tables (i.e. User Table, User Level Table and User Level Permission Table).
If all projects uses the same database and same Advanced Security tables, then the
latter condition is automatically fulfilled. However, if the projects use different
databases, you need to use Database_Connecting(See 1.10.9) server event to
change the connection info so the user can get the Dynamic User Levels from the
common Advanced Security tables correctly during login. For the projects not using
the database with the common Advanced Security tables, you still need to create
dummy Advanced Security tables (with same table/field names as the common
Advanced Security tables) in the project database so you can setup Advanced
Security.

User Login Options


User Login Options allows you to create a complete user registration system for your Web
site, with options to let user register, change password and recover password.

57

PHPMaker 12 Help

Login
Track failed attempts

If enabled, number of failed login attempts


(invalid password) will be tracked. If exceeded,
the user will be locked out and the password
must be reset.

Maximum failed attempts

The maximum number of failed login attempts

Failed attempts windows (minutes)

The time window, in minutes, during which


failed password attempts are tracked.

58

PHPMaker 12 Help
Disallow concurrent login

If enabled, only one session is allowed for each


user (except the hard-coded Administrator). If
one user has already logged in, other users
trying to login with the same username (and
password) will be rejected.
Users are distinguished by Session ID as
recognized by the web server. If you login
again with your PC in another window of the
same browser or in just another tab of your
browser, you can still login. If you login again
with another browser or another PC, the
Session ID will be different and the login will be
rejected.
Note

Maximum concurrent user session countFor use with Disallow concurrent login. By
default only one session is allowed fror each
user. But you may want to give more than one
chance to user so they will not be rejected after
unexpected incidents such as a system crash.
Please be reminded that this option
somewhat compromise the Disallow
concurrent login feature. Use this option
discreetly and always use the smallest possible
value.
Note

Login status timeout (minutes)

The number of idle minutes after which the


login status will be considered as logged out
and login will be allowed again.
If a logged-in user does not explicitly log out
(for example, close the browser directly), the
user session is not closed and the user's login
status will remain as "logged in". Attempts to
login again will fail. This timeout setting
ensures login will be allowed again after a
period of idle time.

CAPTCHA (requires extension)

Optionally requires user to type letters or digits


from a distorted image that appears on the
screen..
Requires CAPTCHA extension, click Tools > Extensions from the main menu to enable.
Also see Third-party Tools(See 1.7).
Note

Password
MD5 password

Use MD5 password


Notes

1. If you enable MD5 password, make


sure that the passwords in your user
table are stored as MD5 hash (32-

59

PHPMaker 12 Help
character hexadecimal number) of the
clear text password. If you also use
case-insensitive password, convert the
clear text passwords to lower case first
before calculating MD5 hash.
Otherwise, existing users will not be
able to login. MD5 hash is irreversible,
password will be reset during password
recovery. Note that the reset password
is also in the format of 16-character
hexadecimal number, it is NOT the MD5
hash of the old password.
2. PHPMaker will try to detect salted
password created by other application.
(PHPMaker itself does NOT create salted
password.) If salted, the password
must be stored in
'<hashedstring>:<salt>' format, and
the hashed string must be the md5
hash of the concatenated string of the
clear text password and the salt. Other
salt algorithm is not supported, you can
however customize the function
ew_EncryptPassword() in the template
to suit your applcation.
Case-sensitive password

Use case-sensitive password

Enable password expiry

If enabled, user password will expire after a


period of time (except the hard-coded
Administrator password)

Password expiry time (days)

For use with Enable password expiry, user


password will expire after the specified number
of days

User Registration Page


Enabled

Generate user registration page and add a link


in login page.

Fields

Select fields (from the user table) to show in


the registration page. Click the [...] button the
select the fields.

Confirm before submit

Optionally send email confirmation after


registration

Send registration email

Optionally send email confirmation after


registration

Requires activation

Optionally requires user click an activation link


in the email sent after registration to activate
the user account.
Send email must be enabled for sending
the email with activation link.
Note

Auto login after registration/activation Optionally auto-login the user after registration
or activation.

60

PHPMaker 12 Help
Requires activation is enabled, the user
is not activated yet after registration, auto login
will be applied when the user clicks the
activation link in the email.
Note

CAPTCHA (requires extension)

Optionally requires user to type letters or digits


from a distorted image that appears on the
screen..
Requires CAPTCHA extension, click Tools > Extensions from the main menu to enable.
Also see Third-party Tools(See 1.7).
Note

Change Password Page


Enabled

Generate change password page

Send email

Optional email confirmation after changing


password

CAPTCHA (requires extension)

Optionally requires user to type letters or digits


from a distorted image that appears on the
screen.
Requires CAPTCHA extension, click Tools > Extensions from the main menu to enable.
Also see Third-party Tools(See 1.7).
Note

Password Recovery Page


Enabled

Generate password recovery page (forgot


password page) and add a link in login page.
User name and password will be sent to the
user's email address.

CAPTCHA (requires extension)

Optionally requires user to type letters or digits


from a distorted image that appears on the
screen.
Requires CAPTCHA extension, click Tools > Extensions from the main menu to enable.
Also see Third-party Tools(See 1.7).
Note

User Table Fields


Email address field

Email address field in user table used for


sending email

Activated field

Email activated field in user table used for


storing the status of user. A boolean field is
recommended, although an integer field or a
string field will also work.
Notes

1. To enable user account activation, the


Requires activation and Send email
options under User Registration Page
must be checked. The user needs to

61

PHPMaker 12 Help
click an activation link in the email sent
after registration to activate the user
account.
2. If enabled, make sure the activated
field for existing users in your user
table is updated with your activation
values (e.g. True/False, 1/0, Y/N) or
the existing users cannot login because
they are not recognized as activated.
You can enable Multi-Update feature for
the user table so administrators can
activate or deactivate existing users
easily.
Profile field

A memo field for persisting all the additional


user information. This field is required if the
following options are used:

Track failed attempts


Disallow concurrent login
Enable password expiry

User Table List Page Options


Reset concurrent user session count

If enabled, a new option is generated in the


User Table list page for the administrator to
reset the concurrent user session count for an
user to 0

Reset login failed attempts

If enabled, a new option is generated in the


User Table list page for the administrator to
reset the login failed attempts for an user to 0

Reset login failed attempts

If enabled, a new option is generated in the


User Table list page for the administrator to
reset the login failed attempts for an user to 0

Set password expired

If enabled, a new option is generated in the


User Table list page for the administrator to set
the password of an user as expired

Resend registration email

If enabled, a new option is generated in the


User Table list page for the administrator to
resend the registration email to an user

Email Template
The email sending function and the email contents can be customized in the template. The
following special tags are used in the email templates:

<!--$From--> is sender email address


<!--$To--> is user email address
<!--$Password--> is user password
<!--FieldName--> (without the $ symbol) is the field value. For example, <!-LastName--> is the field value of the field "LastName".

62

PHPMaker 12 Help
You can also dynamically change the email by code using Email_Sending event before the
email is sent. (See Server Events and Client Scripts)(See 1.10.9)

Email Templates for Multi-Language projects

1. To set up email templates for Multi-Language projects, read the topic Tutorial Multi-Language Project Setup(See 1.10.16)

Also See:
Tutorial
Tutorial
Tutorial
Tutorial
Tutorial

User ID Security(See 1.15.9)


Static User Level Security(See 1.15.10)
Dynamic User Level Security(See 1.15.11)
User Registration System(See 1.15.7)
Multi-Language Project Setup(See 1.10.16)

1.10.5 Generate Settings

Template file
Application root folder

Template archive (zip file)


The root folder of the PHP application. (See Application Root (See

63

PHPMaker 12 Help
1.11) for more info on application root)
Destination folder

The destination folder where the PHP scripts are to be generated.


The folder is usually same as the application root folder or a
subfolder under the application root folder.

Output filename

None - no prefix/infix/suffix is added


Prefix - a prefix is added to all output file names
Infix - an infix (between table name and page ID) is added to all
table-specifc file names
Suffix - a suffix is added to all output file names

Prefix/Infix/Suffix

The string to be concatenated to output file names when the


Prefix or Infix or Suffix option is specified

Lowercase

Specify whether output file names are in lowercase

Extension

Extension name of the generated scripts, default is "php".

Default page

File name of the start page, default is "index.php".


This is just the file name of a website's default page usually
named index.php. This is NOT the start page (see below) of the
generated site.
Note

Start page

Specify the first page that the default page (usually "index.php")
should redirect users to.
If this setting is left blank, user will be redirected to the List page
of the default table (see Table Setup(See 1.10.6)) or the first
table that the user have permission to access.
If this setting is not blank, the default page will simply redirect
user to the page you specify, e.g. a page not generated by the
current project or a custom file. If you start the site by the typical
index.php, leave this setting blank, do NOT enter index.php or
there will be a indefinite loop.

Testing web server

Specify the web server that you want to use to test the generated
site. For use with Browse after generation (see below). You
can choose IIS Express or Other. Requires IIS Express installed
on the same machine as PHPMaker.
IIS Express is a simpler and self-contained version of IIS that is
optimized for developers. IIS Express is free, does not require
administrative privileges to run. It can be downloaded from
microsoft.com.
If you choose Other web server (e.g. you use IIS or Apache),
you need to specify Testing root URL (see below) also.

Browse after generationSpecify whether to open a browser to test the generated site
after script generation.
Testing root URL

Specify the URL of your testing site that maps to the Application
root folder (see above). For use with Browse after
generation. If you use IIS Express, this setting is NOT

64

PHPMaker 12 Help
required.
For example, if you have set up a website like:
Application root folder:
C:\Users\Administrator\Documents\mycompany.com
Destination folder:
C:\Users\Administrator\Documents\mycompany.com\project1
and you have setup your testing website's document root at the
application root folder, so that you browse the main site by:
http://localhost/
and browse the PHPMaker generated site by:
http://localhost/project1/
Then the Testing root URL should be:
http://localhost/
(NOT http://localhost/project1/, which points to the Destination
folder).
PHPMaker will calculate the relative path and add "project1/" to
the Testing root URL when opening the browser.

After setting above, click the [Generate] button to generate scripts. PHPMaker allows you
select scripts to generate, just select the files you want to generate in the [Output] column.
If you want include PHPMaker scripts into your custom PHP scripts, you may not want to
generate header and footer in those pages. Then you can enable [No header/footer] for
those pages. Note that header/footer means the header row containing the site header
logo and the footer row containing the site footer text.
After selection, click the [Generate] button to generate scripts.
If it is your first generation for the project or you have changed some project level
settings, you must select [Other files] to generate the non table-specific pages.
Note

If you modify settings for a table and want to re-generate script for that table only, you can
click [Unselect All], then select the files you want to re-generate and click the [Generate]
button to generate again. If you are not sure which files to re-generate, click [Select All]
and re-generate all files.
You can also right-click the column header of [Output] or [No header/footer] to quickly
select all or unselect all items in the column.

65

PHPMaker 12 Help

If you need to abort script generation in the middle of the process, just click the [Cancel]
button under the progress bar that displayed during generation.

Also See:
Customizing Template(See 1.14)
Project File (See 1.12)

1.10.6 Table Setup


For simplicity, we use "table" in the following description to refer to any of database
object in the project. A database object can be either a table, a view, a Custom View, a
report or a Linked Table.
Note

After loading the database, the tables will be shown in the database pane on the left pane.
To access ALL setting for a table (including Multi-page, Table-specific Options and
Master/Detail), click the table node of any table in the database pane and then
click the [Table] tab to go to the Table Setup page. This is the setup page for a single
table.

66

PHPMaker 12 Help

You can also click on the [Tables] or [Views] or [Custom Views] or [Reports] or
[Linked Tables] node in the database pane to go to the Tables Setup page which is a grid
showing the most frequently used settings for all tables. If you need to set these settings for
multiple tables, this page allow you to view and set them quickly. Note that this page does
not include Multi-page, Table-specific Options and Master/Detail.

Notes

1. For all checkbox or combobox columns, if you want to apply the setting to ALL tables
or views, you can choose your setting at the [Tables] or [Views] or [Custom
Views] or [Reports] or [Linked Tables] row.

67

PHPMaker 12 Help
2. View/Edit/Search functionality works at field level and can be setup for each field in
the Field Level Setup page. Please refer to the Field Setup(See 1.10.7) for details. If
all fields are not selected for View/Edit/Search, the function will not be generated.
If you prefer to view the tables in alphabetical order, click [Tools]->[Sort Tables
Alphabetically] (see Tools(See 1.13)).
You can still change the display order of the menu item by drag-and-drop. Select a table by
clicking the first column - [Table/View Name] column, then drag and drop to where you
want. Note that a table cannot be moved out of its parent node.
Note that changing the display order of table in this Table Setup page does not change the
display order of the tables in the menu. To change the display order of the menu item, click
[Tools]->[Menu Editor] (see Tools(See 1.13)).
Important

1. It is assumed that all tables have primary key. (Composite key is supported) If there
is no primary key specified, View/Add/Copy/Delete/Edit/Update settings have no
effect and will be reset to disabled when the [Generate] button is pressed. Only the
List page can be generated. If you add back a primary key later, you'll need to come
back to this page and re-enable them. Since reports are read-only,
View/Add/Copy/Delete/Edit/Update settings are not applicable to reports.
2. Views or Custom Views involving more than one table are usually NOT updatable.
Although you can force PHPMaker to enable the Add/Copy/Delete/Edit/Update pages
by specifying a primary key, the generated pages will not work if these views or
Custom Views cannot be updated like regular tables.

The available table level settings are as follows:


General
Generate

Select/unselect a particular table for generation

Caption

To change the caption of a table, click on [Caption] box to make the


necessary change.
If you use Multi-Language (see PHP Settings(See 1.10.2)), use
Multi-Language Property Editor, see Tools(See 1.13) for details.
Note

Filter

Specify a filter (WHERE clause) for the table. Click the [...] button in
[Filter] column, the Filter Editor will popup. Enter your filter, you can
drag the field names from the left pane to the editor, the SQL identifier
quote characters will also be added for you automatically.

68

PHPMaker 12 Help

The filter must be a valid PHP expression and it will be concatenated


to the SQL. If it is a string, it should be double quoted.
Note

Sort

Specify the sort fields (ORDER BY clause) for the table. Click the [...]
button in [Sort] column, the following dialog box will popup. You can
choose up to 6 fields, in either ascending or descending order.

69

PHPMaker 12 Help

Output folder

For use with Custom File only. The output folder is relative to
application root(See 1.11).

Include custom
files

For use with Custom File and for PHP file only. Include common files
such as header and footer so the custom file will have the same layout .

Default

Set a Table as the Default Table. The Default table is the first table the
user see when visiting your site. Select the table you want in the
[Default] column.

List
Inline Add

Enable/disable Inline Add function for the table. Inline Add allows
users to add a record within the List page. Default is disabled.

Inline Copy

Enable/disable Inline Copy function for the table. Inline Copy


allows users to copy a record within the List page. Default is
disabled.

Inline Edit

Enable/disable Inline Edit function for the table. Inline Edit allows
users to edit a record within the List page. Default is disabled.

Grid Add

Enable/disable Grid-Add function for table. Allows users to add


multiple records to the table. Default is disabled.

Grid Edit

Enable/disable Grid-Edit function for table. Grid-Edit allows users


to edit multiple records within the List page. Default is disabled.

Detail Add

Enable/disable Master/Detail-Add function for table (as detail

70

PHPMaker 12 Help
table). Allows users to add multiple records to the detail table in
the Add page of the master table. Default is disabled.
Detail Edit

Enable/disable Master/Detail-Edit function for table (as detail


table). Allows users to edit multiple records of the detail table in
the Edit page of the master table. Default is disabled.

Detail View

Enable/disable Master/Detail-View function for table (as detail


table). Allows users to view multiple detail records in the View
page of the master table. Default is disabled.

Multiple Detail Tables

Enable/disable multiple Detail Add/Edit/View.


By default each pair of Master/Detail tables are handled
separately, meaning that in a page, there are one master table
(the current table) and one of its detail tables only. If this option
is enabled, all detail tables will be displayed together in the same
page. Enabling this option will hide separate Master/Detail table
pairs.

Requires Search CriteriaSpecifies if the List page requires search criteria. Default is
disabled.
Notes

1. If enabled, the List page always requires search criteria.


When the page is initially loaded, no records will be
displayed until searching is done. (Remember to enable
Quick Search, including Extended Quick Search, or
Advanced Search or both. See below.)
2. If a record is added but the new record does not meet the
search criteria (or there is no search criteria yet), the
record will not appear in the List page. So this option is
best for tables which are for browsing only.
Detail Record Count

Specifies if the number of detail records for the master record


should be displayed. Default is disabled.
Note

1. Applicable to master tables with master/detail


relationships defined in PHPMaker only, see below.
2. If the detail table is a report, this feature is NOT
applicable, there will be NO detail record counts for the
detail report.
3. The counts are retrieved by using a subquery for each
detail table. The more detail tables, the more
performance penalty. You should enable this feature
discreetly.
Sequence number

Add a column to show the sequence number (record index) of the


record in the recordset.

View
ViewIf enabled, a View page for the table will be generated (for displaying a record).
Default is enabled.

71

PHPMaker 12 Help
The table must have primary key or this setting will be unchecked during
generation.
Note

Add
Add

If enabled, an Add page for the table will be generated (for adding/copying a
record). Default is enabled.
The table must have primary key or this setting will be unchecked during
generation.
Note

Copy

If enabled, Add page will be generated and "Copy" links will be generated for
record(s) in List/View page (for copying). Default is enabled. (If this setting is
enabled, the "Add" setting is also enabled by default as copying requires the Add
page.)
The table must have primary key or this setting will be unchecked during
generation.
Note

CAPTCHAEnable/disable CAPTCHA function for the Add page. Default is disabled. (CAPTCHA
requires that the user type the letters or digits of a distorted image before
submitting a form to prevent automated software from posting spam to your web
application.)
Notes

1. Requires CAPTCHA extension, click Tools -> Extensions from the main
menu to enable. Also see Third-party Tools(See 1.7).
2. Not applicable to Inline/Grid-Add/Copy.
Confirm Enable/disable confirmation function for the Add page. Default is disabled. If
enabled, there will be a confirmation step in the Add page, users will be able
check their input before actually inserting the record.
Note

Not applicable to Inline/Grid-Add/Copy.

Edit
Edit

If enabled, an Edit page for the table will be generated (for updating a
record). Default is enabled.
The table must have primary key or this setting will be unchecked
during generation.
Note

CAPTCHA

Enable/disable CAPTCHA function for the Edit page. Default is disabled.


(CAPTCHA requires that the user type the letters or digits of a distorted
image before submitting a form to prevent automated software from
posting spam to your web application.)
Notes

1. Requires CAPTCHA extension, click Tools -> Extensions from the


main menu to enable. Also see Third-party Tools(See 1.7).
2. Not applicable to Inline/Grid-Edit.

72

PHPMaker 12 Help
Confirm

Enable/disable confirmation function for the Edit page. Default is disabled.


If enabled, there will be a confirmation step in the Edit page, users will be
able check their input before actually updating the record.
Note

Not applicable to Inline/Grid-Edit.

Check ConflictsCheck if the record is changed by other user before updating the record.
Notes

1. Since processing of current data for later comparison is required,


using this feature will increase the time required to load the page.
For better performance only the first hundreds of bytes of the BLOB
fields are processed by default, but there are chances that change
of BLOB data is not detected (if the first nth bytes are not
changed). You can increase the number of bytes in Advanced
Setting(See 1.13), if you want to process all bytes, enter 0.
2. You can use the Row_UpdateConflict server event (see Server
Events and Client Scripts(See 1.10.9)) to resolve the conflicts
according to your business logic by code.
3. Not applicable to Inline/Grid-Edit.

Delete
DeleteIf enabled, a Delete page for the table will be generated (for deleting record or
multiple records). Default is enabled.
The table must have primary key or this setting will be unchecked during
generation.
Note

Multi-Update
Multi-UpdateIf enabled, a Multi-Update page for the table will be generated (for updating
multiple records). Default is disabled. With this feature you can select multiple
records in the List page and update all records at the same time. You can
select fields (see Field Setup(See 1.10.7) page) to be included in the MultiUpdate page.
The table must have primary key or this setting will be unchecked during
generation.
Note

Confirm

Enable/disable confirmation function for the Multi-Update page. Default is


disabled. If enabled, there will be a confirmation step in the Multi-Update
page, users will be able check their input before actually updating the selected
records.

Search
Quick

If enabled, Quick Search panel (including Extended Quick Search) will


be generated with the List page. Default is enabled.
Quick Search searches text fields and optionally numeric fields only.
These fields are selectable in Field Setup(See 1.10.7) page. You may
want to hide the Quick Search form for tables that do not have
searchable fields.

73

PHPMaker 12 Help
Default value

Default value for Quick Search.


If no user input for Quick Search, this default value will be used. After
users entering their search criteria, the default value will not be used.

Default search typeDefault search type for Quick Search. Possible values are:

Any words
All words
Exact match

Extended

If enabled, Extended Quick Search inputs will be generated in the List


page. Default is enabled.

Fields per Row

For use with Extended Quick Search. Specifies the number of fields per
row in the Quick Search panel. Default is 0 (unspecifed), which means
one field per row.

Advanced

If enabled, an Advanced Search Page will be generated and linked to


the List page. Default is disabled.

Highlight

If this setting is checked, the search criteria in the search result (List
page) will be highlighted. Default is disabled.

Audit Trail
To use this feature, you must also specify the [Audit Trail folder] or database table and
field under [PHP]->[General Options] tab. See PHP Settings(See 1.10.2) for details.
Audit TrailIf audit trail for a table is enabled, when an user add(copy)/edit/delete a record
or login/logout, the related information will be logged in a log file or into the
specified database table.
By default all add(copy)/edit/delete info will be logged, if you want to select
what to log, or want to log search/view activities also, use the Audit Trail
Extension, also see [Tools]->[Extensions(See 1.13)].
Note

Email Notification
To use this feature, you must also specify the [Email Settings] under [PHP]->[Email
Settings] tab. See PHP Setup(See 1.10.2) for details.
On Add

If enabled, when an user add a record, an email will be send to pre-set recipient
email address(es). Default is disabled.

On Edit

If enabled, when an user edit a record, an email will be send to pre-set recipient
email address(es). Default is disabled.

On DeleteIf enabled, when an user delete a record, an email will be send to pre-set
recipient email address(es). Default is disabled.

Other than above Tables Setup page, you can also click on a particular table node (under
[Tables] or [Views] or [Custom Views] or [Reports] or [Linked Tables] node) in the

74

PHPMaker 12 Help
database pane to go to the Table Setup page for that table. The Table Setup page includes
the following tabs: Table, Fields(See 1.10.7), and Server Events/Client Scripts(See 1.10.9).
Click on the Table tab you'll see settings for the selected table only. The right side includes
two panel - the [Table-specific Options] panel and the [Master/Detail] panel (see
below), the left side contains settings same as above (but for the selected table only) plus
the following additional settings:

Multi-page
Normally each field is displayed as a table row in the View/Add/Edit page, this Multi-Page
features allow you to display divide the fields into pages and display only one page at a
time. To enable, at least one field with page number larger than 1 must be set up in Field
Setup(See 1.10.7) page. This feature is presented as tabs.
Multi-Page type

Specifies how to display the pages. Possible values are:

Page Labels

Tabs - use Bootstrap basic tabs (default)


Pills - use Bootstrap basic pills
Accordion - use Bootstrap Collapse

Specifies the page captions of each page in the Multi-Page. Click the [...]
button and enter the page captions and click [OK] to save.

75

PHPMaker 12 Help

If page captions are not specified, "Page n" will be used by default. To
add a page, go to Field Setup(See 1.10.7) page, specify the page
number for the fields in the page first.
If you use Multi-Language (see PHP Settings(See 1.10.2)), use
Multi-Language Property Editor, see Tools(See 1.13) for details.
Note

Add page

Specifies if Multi-Page is enabled for Add page.

Edit page

Specifies if Multi-Page is enabled for Edit page.

View page

Specifies if Multi-Page is enabled for View page.

Search page

Specifies if Multi-Page is enabled for Advanced Search page.

Registration pageSpecifies if Multi-Page is enabled for registration page. This setting is


only available for the user table specified in Security Settings(See
1.10.4).

Return Pages
After Add

Specifies the return URL after a new record is added.


The URL must be a valid PHP expression. If it is a string, it should be
double quoted.
Note

Example 1
If you want to redirect user to a custom page, enter: (with quotes)

"MyPage.php"
Example 2
If you want to pass field values, enter: (with quotes)

"MyPage.php?xxx=" . urlencode($this-><Field>->CurrentValue)
e.g.

"MyPage.php?ID=" . urlencode($this->ID->CurrentValue)

76

PHPMaker 12 Help
Example 3
If you have just added a master record and want to go to Grid-Add page of the
detail table, enter: (with quotes)

"<DetailTable>list.php?a=gridadd&showmaster=<Table>&fk_<Key
Field>=" . urlencode($this-><Field>->CurrentValue)
e.g.

"OrderDetailslist.php?a=gridadd&showmaster=Orders&fk_OrderI
D=" . urlencode($this->OrderID->CurrentValue)
Example 4
If you have just added a master record and want to go to Add page of the
detail table, enter: (with quotes)

"<DetailTable>add.php?showmaster=<Table>&fk_<KeyField>=" .
urlencode($this-><Field>->CurrentValue)
e.g.

"OrderDetailsadd.php?showmaster=Orders&fk_OrderID=" .
urlencode($this->OrderID->CurrentValue)
After Edit

Specifies the return URL after a record is edited.


The URL must be a valid PHP expression. If it is a string, it should be
double quoted.
Note

After
Register

Specifies the return URL after an user is registered. This setting is only
available for the user table specified in Security Settings(See 1.10.4).
The URL must be a valid PHP expression. If it is a string, it should be
double quoted.
Note

Table-specific Options
These options are same as the list page options as described in PHP Settings(See 1.10.2)
except that the options are table-specific, meaning that you can have different list page
options for different tables. To use table-specific options, select a table in the grid, uncheck
[Use global settings] in the [Table-specific Options] panel, the panel will be enabled for
you to setup.

77

PHPMaker 12 Help

Master/Detail
When you set up a master/detail relationship, you link two tables so that all the records of
one table (the detail table) always correspond to the single current record in the other table
(the master table). Each table can have multiple master tables and details tables.
You can establish master/detail (one-to-many) relationship between two tables as follows
1. Select a table in the table grid,
2. Then in [Master/Detail] panel at the bottom right corner of the page, click
[Modify...] to bring up the visual master/detail relationship editor.
3. Click [Add table] to add the master and detail table to the diagram.
4. Create a relationship between them by dragging from the master field (key field
in master table) to the detail field (foreign key field in the detail table). If
there are more linked field, repeat the step until all the relationships are setup.

78

PHPMaker 12 Help

If you want to remove a relationship, select the link in the diagram and click [Delete]. After
setup, click [OK] to confirm.
The diagram only shows master/detail relationships of the selected table. Although you
can setup relationships for other tables in the diagram and view them in the
[Master/Detail] panel immediately after clicking [OK], the relationships for other tables
will not be loaded again if you go to other table and then come back to this table. Instead,
the relationships will only be displayed when you change to the related tables.
Note

In most cases, master and detail tables are joined by one field, you have one link between
the master/detail table and you have one row in the Master/Detail panel only.

Referential IntegritySpecifies that user may not add/update a record in the detail table
unless the foreign key points to a valid record in the master table.
Cascade Delete

Specifies that if a record in the master table is deleted, all


corresponding records in the detail table will be deleted.
If you have used ON DELETE CASCADE for the table in the
database, no need to enable this setting.
Note

79

PHPMaker 12 Help
Cascade Update

Specifies that if the primary key for a record in the master table
changes, all corresponding records in the detail table will be updated.
If you have used ON UPDATE CASCADE for the table in the
database, no need to enable this setting.
Note

Also See:
Tutorial - Master/Detail(See 1.15.2)

1.10.7 Field Setup


After loading the database, the database objects (tables, views, custom views, reports and
linked tables) will be shown in the left pane (the database pane). Click on any table to go to
the Field Setup Page for that table at any time.
For simplicity, we use "table" in the following description to refer to any of database
object in the project. A database object can be either a table, a view, a Custom View, a
report or a Linked Table.
Note

PHPMaker support most commonly used data types. If PHPMaker finds any unsupported
fields in a table, an [Unsupported Fields] tab will appear. You can click on the tab to view
the list of fields that are not supported.
The Field Setup pages consists of two section. The upper section is a grid showing available
options of all fields. The lower section contain two panels, the [Edit tag] panel and the
[View tag] panel for the selected field.

80

PHPMaker 12 Help

The grid consists of the following sections:

General
List Page
View Page
Edit Page
Add Page
Multi-Update Page
Advanced Search Page

General

Properties
Field Name

Field Name (read only)

Data Type

Data Type (read only)

Size

Maximum field length (read only)

Expression

The expression for custom field (Custom Fields only). See also Custom
Fields(See 1.10.14)

Caption

Field caption to be displayed

Primary Key

Primary Key of the table. Composite key is supported.


Important

1. You should use the same primary key as declared in the


database, do not change it unless you are absolutely sure that
the selected field(s) values are unique. Otherwise a record
cannot be located properly and unexpected results may occur.
2. Primary key is uneditable in the edit page.
Page No.

Page number of the field. For use with Multi-Page. By default all the
fields are in page 1 and Multi-Page is disabled.
Multi-Page is supported for Add/Edit/View/Search pages, you can
optionally enable it for each page. Page labels are also supported. See
Table Setup(See 1.10.6).
If Multi-Page is enabled and the page number is 0, the field will
appear in all pages.
Note

You can multi-select the fields by ctrl-click or shift-click the Field

81

PHPMaker 12 Help
Name column and then right click to set the page number for the
selected fields simultaneously.
Auto-Update ValueA dynamic value to update the field function automatically in Add/Edit
pages.
The dropdown list for this setting is preloaded with a few functions for
your selection. For example, you may want to record the last modified
date of a record, then you can select "ew_CurrentDate". Do not select a
function that return values of unmatching data type, for example, you
should not select a function that return a non-numeric string for a
numeric field.
Notes

1. This setting will make the field hidden automatically and it


overrides the default value in Add page and custom value for
Hidden Edit tag in Edit page. (see section below)
2. You can add your own PHP functions, the function must accept
no argument and return a value. You can add your function
names (comma separated) for the Advanced Settings AutoUpdate values (See Tools - Advanced Settings(See 1.13)),
e.g. You can enter: (no quotes)

MyAutoValueFunction1,MyAutoValueFunction2
Then put your functions under server side Global Code section,
see Server Events and Client Scripts(See 1.10.9).
Change Field Display Order by Drag-and-Drop
You can change the field order defined in the database by simple drag-and-drop. Simply ctrlclick or shift-click the Field Name column to select multiple fields, then drag it to where you
want. PHPMaker will generate scripts and display records according to this order.

Change Multiple Field Properties


Some field properties allow mulit-update. You can ctrl-click or shift-click the Field Name
column to select multiple fields, then right click and select Set field properties... to update
them at the same time.

82

PHPMaker 12 Help

List Page

Properties
List

Show field in list page


The setting is also used for Inline/Grid-Add/Edit and Master/DetailAdd/Edit/View.
Note

Export

Include the field when export

Aggregate

Enable Field Aggregation. Aggregated values will be shown at Page Footer.


Not applicable in multi-column view. Aggregate options include:
- TOTAL (sum of all field values in current page)
- COUNT (count of records in current page)

83

PHPMaker 12 Help
- AVERAGE (average field value in current page)
Width

Specify CSS width property for field column width . e.g. If you enter: (no
quotes)

200px
the output will be:

style="width: 200px"
If your table is too wide, browsers will try to best fit the content into
screen and the specified width may be overridden.
Note

Wrap

Enable/Disable text-wrap for field value


If you enable text-wrap but the field value has no line-breaking points
(e.g. spaces or punctuation), the text still cannot be wrapped.
Note

Quick SearchInclude this field when performing Quick(Basic) Search in the List page.
Only text fields and numeric fields are supported in Quick Search. By
default only text fields are enabled.
Note

Ext. Search

Use this field in Extended Quick Search


Extended Quick Search is enhancement of Quick Search. If a field is checked
for Ext. Search, a form element for the field will be shown in the Quick(Basic)
Search form and the user input criteria for this field will be included when
performing Quick(Basic) Search.
Extended Quick Search will use the same search operators specified under the
"Advanced Search Page" section (see below).
Extended Quick Search only works with field selected to show in the List
page or the search criteria cannot be highlighted (if enabled, see Table
Setup(See 1.10.6)) and may confuse some users.
Note

View Page

Properties
View

Show field in view page

View Tag

HTML tag to display the field. Used in List/View pages.

84

PHPMaker 12 Help
You can either click the [View Tag] column and select a View Tag from the drop down box
or click the icon on the View Tag panel toolbar to select. After selecting the View Tag, you
can further setup its properties in the View tag panel.

View Tag
There are two types of View Tag, Formatted Text and Image.
Formatted Text - View Tag to display the field value as formatted text using <div> tag
with optional hyperlink. Properties:

DIV Tag attributes


Style

Align - Left/Center/Right/Justify. Align the data.


Italic - Display as Italic
Bold - Display as Bold

Custom Attributes Other custom attributes for the <div> or <span> tag. For example, you
can enter as string, e.g. (string with single/double quotes)

"onmouseover='my_js_function();'
onmouseout='my_js_function2();'"
or preferably as an array (array for PHP < 5.4), e.g.

array("onmouseover" => "my_js_function();",


"onmouseout" => "my_js_function2();")

85

PHPMaker 12 Help
or (array for PHP >= 5.4), e.g.

["onmouseover" => "my_js_function();", "onmouseout" =>


"my_js_function2();"]
Notes

1. The setting must be a valid PHP expression. If it is string, it


should be single/double quoted.
2. If you use your own JavaScript functions for the client events.
You can put your JavaScript functions in the Global Code for
client scripts (see Server Events and Client Scripts(See 1.10.9))
so it is available for use in the generated scripts.
3. Sometimes the generated code already uses some attributes
(e.g. onchange event, class attribute, style attribute), if you add
the same attribute/event using the string format, there will be
more than one event/attributes of the same name and it will be
ignored by browsers. But if you add the same attribute using
the array format, the attributes will be concatenated together.
Therefore, the array format is recommended over the
string format.
Format
None

No formatting

Currency

Display as formatted currency

Date/Time

Display as formatted date


For simplicity the Date/Time named format indicates the date
format with "/" as the date separator regardless of the Default date
format setting, but the actual date separator used in the generated
scripts is determined by the Default date format setting (see PHP
Settings(See 1.10.2)).
Note

Number

Display as formatted number

Percent

Display as formatted percentage

String

Format the field value with specified PHP string function or custom
function

Replace CR+LF by Display the fields with CR+LF replaced by <BR>


<BR>
Note This setting only applied to memo fields.
Max Length (List
page)

Truncate the field value at specified max. length and append "..." to the
end.
This setting only applied to memo fields in list page and must be
larger than 0 to take effect.
Note

Hyperlink
HREF field

Display the field as hyperlink with the href attribute set to the value of
this field. It can be the field itself.

Original field
value

Use original field value of the Href field in the hyperlink instead of
display field value.

86

PHPMaker 12 Help
If the HREF field has lookup table or user values, by default the display
value will be used. If this option is enabled, the original field value will
be used instead.
Target

Target attribute of the hyperlink. Possible values are: _top, _parent,


_self, or _blank. You can also enter your own.

Prefix

Prefix added before the HREF field value. You can select one of the
follows:
-

None (no prefix, relative path of URL)


http:// (prefix http:// added, absolute path of URL)
mailto: (prefix mailto: added, email link)
ftp:// (prefix ftp:// added, ftp link)
file:// (prefix file:// added, file link)
news:// (prefix news:// added, newsgroup link)

You can also enter your own partial URL (preceding the HREF field
value)
This setting is a string to be quoted by double quotes, if you want
to use PHP variable, wrap it in "{" and "}". Since "{" can not be
escaped, this syntax will only be recognized when the "$" immediately
follows the "{". Read PHP Strings for more information on parsing
variable in string.
Note

For example, you can enter: (no quotes)

mypage.php?id=
The value of the HREF field will be appended to the end of the your
prefix in the outputted HTML.
If you want pass a field value, you can enter: (no quotes)

mypage.php?myfield={$this->UrlEncode($this->MyField>CurrentValue)}&id=
If you need to pass parameters which should not be URL-encoded, for
example, if you use ew_Encrypt() to encrypt your parameter, you can
enter: (no quotes)

mypage.php?myfield={$this->Raw(ew_Encrypt($this>MyField->CurrentValue))}&id=
Suffix

Suffix added after the HREF field value. You can use this setting to
append additional URL parameters.
For example, you can enter: (no quotes)

&field2={$this->UrlEncode($this->Field2>CurrentValue)}
If the suffix is URL parameter(s), you should use "&" at the
beginning of the string.
Note

Custom Attributes Custom attributes for the <A> tag.


For example, you can enter a string, e.g. (string with single/double

87

PHPMaker 12 Help
quotes)

"rel='xxx'"
or preferably as array, e.g. (array for PHP < 5.4)

array("rel" => "xxx")


or, e.g. (array for PHP >= 5.4)

["rel" => "xxx"]


Notes

1. The setting must be a valid PHP expression. If it is string, it


should be single/double quoted.
2. If you use your own JavaScript functions for the client events.
You can put your JavaScript functions in the Global Code for
client scripts (see Server Events and Client Scripts(See 1.10.9))
so it is available for use in the generated scripts.
3. Sometimes the generated code already uses some attributes
(e.g. onchange event, class attribute, style attribute), if you add
the same attribute/event using the string format, there will be
more than one event/attributes of the same name and it will be
ignored by browsers. But if you add the same attribute using
the array format, the attributes will be concatenated together.
Therefore, the array format is recommended over the
string format.
Tooltip
Tooltip field

Display the field as tooltip

Tooltip width

The width of the tooltip in pixels. Default is 0 (auto).


By default the width is not specified and the width will depend on the
field value. However, when the tooltip field is a long text field, the width
can take up the browser width, which may be unwanted. Then you can
specify a value to limit the width.

Custom View Tag


Custom View Tag Display the field value in List/View page by custom code.
Custom View Tag overrides ALL above View Tag
settings.
Important

There are some ready-to-use Custom View Tag for you to choose:

Google Maps
Barcode and QR code
YouTube videos

If your data stores information for above, just click the down arrow
button to open the setup form, enable one of them, read the notes at
the bottom panel carefully, then click the Settings tab to setup, and
click OK to save your settings.
Notes

1. Only one of above Custom View Tag can be selected at a time.

88

PHPMaker 12 Help
All records will use the same Custom View Tag. For instance,
you can NOT use Barcode for a record and use Google Maps
for next record.
2. The above Custom View Tags are provided as examples only.
The third party tools used are not developed by the author of
PHPMaker and are not part of PHPMaker, NO TECHNICAL
SUPPORT WILL BE PROVIDED.
You can also create your Custom View Tag, they are implemented in
exactly the same way as template extensions (see Customizing
Template(See 1.14)). Custom View Tags must be placed under the
subfolder "customviewtags" of the installation folder. Each Custom View
Tag must have a XML description file so it can be loaded for selection.
You can open an XML file in the "customviewtags" subfolder to see the
content, which is self-explanatory. Unzip the zip file to see how it is
implemented.
If you want absolute freedom, click the [...] button to enter your own
code to display the your data in your own PHP, HTML and JavaScript.
If you choose to enter your own code, you are completely on
your own to display the field value. Intermediate knowledge in PHP,
HTML and JavaScript is required.
Important

Custom View Tag is HTML, if you want to embed PHP code, use <?php
and ?>, if you want to use JavaScript, use <script

type="text/javascript"> and </script>.


Note

DO NOT use $this in your PHP code. There is no $this in the

context, you can use CurrentPage() to get the current page object.
To reuse the original code, you can generate scripts without Custom
View Tag first, then customize the field in View page as needed. When
done, copy and paste your customized code to PHPMaker user interface
as your Custom View Tag.
The original code will also be generated in a hidden DIV with
id="orig_<table>_<field>", you can also reuse it by JavaScript.
Example 1
Output the field value conditionally:

<?php
if (CurrentPage()->MyField->CurrentValue == "xxx") {
// Assume string field
echo "something";
} else {
echo "something else";
}
?>
Example 2
Output a custom link:

<a href="mypage.php?id=<?php echo


urlencode(CurrentPage()->MyField->CurrentValue) ?>">My
Link</a>

89

PHPMaker 12 Help
Example 3
Reuse the original code by JavaScript. Replace some code in the original
code by regular expression:

<div id="my_unique_id"></div>
<script type="text/javascript">
$("#my_unique_id").html($("#orig_MyTable_MyField").htm
l().replace("xxx", "yyy").concat("zzz")); // Replace
part of the old code by new code, and append something
at the end
</script>
Notes

1. Always use a DIV with unique ID to output your code. DO NOT


use document.write().
2. After outputting the code as innerHTML of the output DIV. You
can also further manipulate the content of the DIV by
JavaScript. Alternatively, you can manipulate the content of the
hidden DIV containing the original code by JavaScript and then
copy the innerHTML to the output DIV.

Image - View Tag to display as Image using <img> tag. The field should be a BLOB field or
a field storing the path of an image.
Only image files can use the Image View Tag. Other files such as PDF cannot be
displayed as image. If the field contains mixed file types, do not use Image View Tag.
Note

IMG Tag attributes


Width

Specify the width of the image in pixels

90

PHPMaker 12 Help
Height

Specify the height of the image in pixels

Alt

Specify the alt attribute of the image tag


If you use Multi-Language (see PHP Settings(See 1.10.2)), use
Multi-Language Property Editor, see Tools(See 1.13) for details.
Note

Custom attributesOther custom attributes for the <div> or <span> tag. For example, you
can enter: (string with single/double quotes)

"onmouseover='my_js_function();'
onmouseout='my_js_function2();'"
or (array for PHP < 5.4)

array("onmouseover" => "my_js_function();",


"onmouseout" => "my_js_function2();")
or (array for PHP >= 5.4)

["onmouseover" => "my_js_function();", "onmouseout" =>


"my_js_function2();"]
Notes

1. The setting must be a valid PHP expression. If it is string, it


should be single/double quoted.
2. If you use your own JavaScript functions for the client events.
You can put your JavaScript functions in the Global Code for
client scripts (see Server Events and Client Scripts(See 1.10.9))
so it is available for use in the generated scripts.
3. Sometimes the generated code already uses some attributes
(e.g. onchange event, class attribute, style attribute), if you add
the same attribute/event using the string format, there will be
more than one event/attributes of the same name and it will be
ignored by browsers. But if you add the same attribute using the
array format, the attributes will be concatenated together.
Therefore, the array format is recommended over the
string format.
Resize image

Resize the image to above width and/or height on displaying the image.
This feature requires PHP GD extension and supports GIF, JPEG and
PNG images only.
Note

Hyperlink, Tooltip and Custom View Tag (same as above)

Edit Page

Properties

91

PHPMaker 12 Help
Edit

Show field in edit page


The setting is for Edit page only, NOT for Inline/Grid-Add/Edit and
Master/Detail-Add Edit in the List page. See the List setting above.
Note

Title to be placed in title attribute of Edit Tag. (see section below) The title will
also appear as popup tooltip of the Edit Tag.

Title

If you use Multi-Language (see PHP Settings(See 1.10.2)), use MultiLanguage Property Editor, see Tools(See 1.13) for details.
Note

Read OnlyMake the field read only in edit page


This setting replaces the Edit Tag by a INPUT type=hidden tag and show the
field by its View Tag (see above). If you want to set the Edit Tag's readonly
attribute (supported by INPUT type=text, INPUT type=password, TEXTAREA),
use Row_Rendered server event. If you want to set the Edit Tag's disabled
attribute, you can set $this-><field>->Disabled property. (See Server
Note

Events and Client Script(See 1.10.9).)


Edit Tag

Form element for the field. Use in Add/Copy/Edit/Search pages. (See below for
details)

You can either click the [Edit Tag] column and select a Edit Tag from the drop down box or
click the icon on the [Edit Tag] panel toolbar to select. After selecting the Edit Tag, you can
further setup its properties in the Edit Tag panel:

Edit Tags
Edit Tags are HTML forms elements for the field in Add/Copy/Edit/Search pages. All HTML
form elements are supported:
Text

<input type="text"> tag


Display the field as a textbox.

92

PHPMaker 12 Help

Size

Size attribute of the textbox

Maxlength

Maximum input length of the textbox


Other custom attributes for the tag. For example, you
can enter: (with quotes)

"onmouseover='my_js_function();'"
or (array for PHP < 5.4)

array("onmouseover" =>
"my_js_function();")
or (array for PHP >= 5.4)

["onmouseover" => "my_js_function();"]


Notes

Custom attributes

1. The setting must be a valid PHP expression. If


it is string, it should be single/double quoted.
2. If you use your own JavaScript functions for
the client events. You can put your JavaScript
functions in the Global Code for client scripts
(see Server Events and Client Scripts(See
1.10.9)) so it is available for use in the
generated scripts.
3. Sometimes the generated code already uses
some attributes (e.g. onchange event, class
attribute, style attribute), if you add the same
attribute/event using the string format, there
will be more than one event/attributes of the
same name and it will be ignored by browsers.
But if you add the same attribute using the
array format, the attributes will be
concatenated together. Therefore, the array
format is recommended over the string

93

PHPMaker 12 Help
format.
Client side events

See section below

Validation

See section below


For use with Auto-Suggest and/or Auto-Fill (see
below) with Lookup Table(See 1.10.8).

Use lookup table

Auto-Suggest is Text Edit Tag with a Lookup


Table(See 1.10.8). When user types in the textbox, a
dynamic dropdown list populated with data from the
lookup table matching the user input will appear for
user to select. If the data already exists, the user can
easily select without typing the full text. If not, the
user can still input as usual. Check [Use lookup
table] to enable Auto-Suggest and then enter the
lookup table info in the [Lookup Table] panel next to
the [Edit Tag] panel. See Lookup Table(See 1.10.8)
for more details.
For use with Auto-Suggest and/or Auto-Fill (see
below) with Lookup Table(See 1.10.8). This setting
must be enabled if you want to use Auto-Fill with
Auto-Suggest.
When this setting is enabled, the user must select one
of the auto-suggested options, the textbox will become
similar to a combobox ("select-one"). This setting is
usually enabled if the field is a lookup field, i.e. the
field stores Link Field values (e.g. primary key) of the
Lookup Table(See 1.10.8).

Force selection

If this setting is disabled, the form will submit the user


input (not the Link Field value) if no suggestion is
selected, so make sure user input is acceptable. For
example, if the Link field is same as the Display
field #1, then disabling this setting should be fine and
the field will save one of the suggestion (if selected) or
what the user inputs.
If Allow sort/search (see Lookup Table(See 1.10.8))
is enabled, usually the user wants to search the
display value rather than the Link field value, so this
setting is disabled automatically in the search forms,
which will submit the selected suggestion's display
value or the user input, and the script will search the
display value of the field.

Dropdown min-width (px)

Minimum width for dropdown. For use with AutoSuggest only.

Dropdown max-height (px)

Maximum height for dropdown. For use with AutoSuggest only.

Option Template

Optional JsRender template for options. For use with


Auto-Suggest only. See Lookup Table(See 1.10.8) for

94

PHPMaker 12 Help
details.
Passw <input type="password"> tag
ord
Display the field as a masked textbox.

Size

Size attribute of the textbox

MaxLength

Maximum input length of the textbox

Custom attributes

Same as above (see Text Edit Tag)

Client side events

See section below

Validation

See section below

Radio <input type="radio"> tag


Display the field as a radio button list.

95

PHPMaker 12 Help

Custom attributes Same as above (see Text Edit Tag)


Client side events See section below
Validation

See section below

Use lookup table

Use an existing lookup table instead of user input value/label


pairs for the radio buttons. To enable this feature, check this
option and enter the lookup table info in the [Lookup Table]
panel next to the [Edit Tag] panel. See Lookup Table(See
1.10.8) for details. If you don't use lookup table, you can enter
the options manually in the [User Value] panel next to the
[Edit Tag] panel.

Repeat columns

Specifies the no. of radio boxes per row


Show the options in dropdown panel with min-width and maxheight settings, e.g.

Use dropdown

Note that if Repeat columns is 1 (single column), the options


will be displayed same as dropdown selection list (Select Edit
Tag with Use dropdown enabled, see below), radio buttons will
be hidden, e.g.

96

PHPMaker 12 Help

Dropdown minwidth (px)

Minimum width for dropdown

Dropdown maxheight (px)

Maximum height for dropdown

Option Template

Optional JsRender template for options. See Lookup Table(See


1.10.8) for details.

Check <input type="checkbox"> tag


box
Display the field as a checkbox list.

For MySQL, PHPMaker considers enum('Y','N') and enum('1','0') as boolean


fields. For Oracle, fields with two and only two User Values (see below) and the
Note

97

PHPMaker 12 Help
labels and values are "Y" and "N" (or "1" and "0") will be considered as boolean
fields. PHPMaker will display a boolean field by a checkbox automatically.
Custom attributes Same as above (see Text Edit Tag)
Client side events See section below
Validation

See section below

Use lookup table

Use an existing lookup table instead of user input value/label


pairs for the checkboxes. To enable this feature, check this
option and enter the lookup table info in the [Lookup Table]
panel next to the [Edit Tag] panel. See Lookup Table(See
1.10.8) for details. If you don't use lookup table, you can enter
the options manually in the [User Value] panel next to the
[Edit Tag] panel.

Repeat columns

Specifies the no. of checkboxes per row


Show the options in dropdown panel with min-width and maxheight settings, e.g.

Use dropdown

Note that if Repeat columns is 1 (single column), the options


will be displayed same as dropdown multilpe selection list
(Select Edit Tag with Multiple and Use dropdown enabled,
see below), e.g.

98

PHPMaker 12 Help

Dropdown minwidth (px)

Minimum width for dropdown

Dropdown maxheight (px)

Maximum height for dropdown

Option Template

Optional JsRender template for options. See Lookup Table(See


1.10.8) for details.

The submitted values of the multi-selected checkboxes is a commaseparated string. Therefore you must use a string field for checkbox list.
Note

Select <select> tag


Display the field as a combobox ("select-one") or a listbox ("select-multiple").

99

PHPMaker 12 Help

Size

No. of options to show. If more that 1, the selection


list is shown as a listbox, otherwise it is shown as a
combobox.

Multiple

Check to enable multiple selection (listbox)

Custom attributes

Same as above (see Text Edit Tag)

Client side events

See section below

Validation

See section below

Use lookup table

Use an existing lookup table instead of user input


value/label pairs for the checkboxes. To enable this
feature, check this option and enter the lookup table
info in the [Lookup Table] panel next to the [Edit
Tag] panel. See Lookup Table(See 1.10.8) for details.
If you don't use lookup table, you can enter the
options manually in the [User Value] panel next to
the [Edit Tag] panel.

Repeat columns

Specifies the no. of checkboxes per row


Show the options in dropdown panel with min-width
and max-height settings, e.g.

Use dropdown

select-one (Multiple disabled)

100

PHPMaker 12 Help

select-mulitple (Multiple enabled)


If Use dropdown is used, the HTML element is
NOT <select> anymore. The dropdown panel uses
radio buttons (if Multiple disabled) or checkboxes (if
Multiple enabled) to support Option Template (see
below). If you need to write JavaScript for the HTML
elements, make sure you write code for correct HTML
elements. Inspect HTML source in your browser to
view the HTML elements.
Note

Dropdown min-width (px) Minimum width for dropdown


Dropdown max-height
(px)

Maximum height for dropdown


Optional JsRender template for options. See Lookup
Table(See 1.10.8) for details.

Option Template

If Use dropdown is not used, the HTML element


is native <select> element, which usually does NOT
support HTML tags in options (depending on
browsers), though HTML entities are supported.
Note

TextAr <textarea> tag


ea
Display the field as a textarea.

101

PHPMaker 12 Help

File

Cols

No. of columns of the textarea

Rows

No. of rows of the textarea

Custom
attributes

Same as above (see Text Edit Tag)

Client side
events

See section below

Validation

See section below

Use DHTML
Editor

Replace the textarea with a DHTML editor for editing the data as
HTML. See Third-party Tools(See 1.7) for more info on DHTML
Editors.

<input type="file"> tag


Display the field as a file upload control. For BLOB fields or string fields only.
File upload supports displaying thumbnails of uploaded image. The feature
requires PHP GD extension and supports GIF, JPEG and PNG images only.
Note

102

PHPMaker 12 Help

Size

Size of the input tag (NOT file size)

Custom attributes

Same as above (see Text Edit Tag)

Client side events

See section below

Validation

See section below

If the field is of BLOB (binary) data type, file is uploaded to the database.
You can also store the information of the uploaded file in the following fields: (for
BLOB field only)
File type field - Recommended. Useful when you want to response to user browser
the exact content type of the data.
File name field - Optional. Useful if you want to use the original filename.
Do not specify file name field if you want IE to open the file automatically. (IE
may fail to open non-image files retrieved from database properly.) Use file name
field if you want IE to popup a File Download dialog for user to save the file with
the filename specified in the file name field.
Note

File size field - Optional. Stores the uploaded file size.


Image width field - Optional. For use with images only. Stores the width of the

103

PHPMaker 12 Help
uploaded image.
Image height field - Optional. For use with images only. Stores the height of the
uploaded image.
If the field of string type, file is uploaded to a subfolder relative to the
application root.
Multiple - Allow multiple upload. Field value will be comma separated file names.
NOT application to BLOB field.
Upload folder - Folder where the uploaded file will reside. If you do not enter a
specific folder, all the uploaded files will be put in the global upload folder specified in
the PHP tab (see PHP Settings(See 1.10.2)).
Notes

1. Unlike the global upload folder setting (which is a constant and must be a
string without double quotes, see PHP Settings(See 1.10.2)), this field
setting must be a valid PHP expression. If it is a string, it must be single
or double quoted.
2. Make sure that the Web server user have read/write access to the folder.
3. The path is relative to application root. Use slashes "/" as path
delimiter, no leading slash. e.g. If the application root of your website is
C:\Inetpub\wwwroot\demo and you enter "uploads/folder1/" (with double
quotes) in this textbox, the folder for the uploaded files will be
C:\Inetpub\wwwroot\demo\uploads\folder1. If you are not sure which folder
is application root, please read Creating Virtual Directories in IIS(See 1.8).
4. The path can be dynamic. For example, if the upload path varies with some
field value, you can refer to other fields by $this->MyField->DbValue.
However, you must be very careful when using dynamic folder, make sure
the setting is valid as a folder name, i.e. it does not contain some characters
which can not be used in a file path on your server. The setting will be
evaluated to obtain the upload folder before the file is displayed and before
the uploaded file is saved, so your setting should be consistent, do not use
random number or current date/time to name the folder. Alternatively, you
can also use Row_Rendered, Row_Inserting and Row_Updating server
events(See 1.10.9) to set the field object's UploadPath property.
5. If Multiple is enabled, all upload files use the same upload folder.
Resize image - Optionally resize the image to resize width and/or height.
Resize width - Width of the resized image
Resize height - Height of the resized image
Resizing requires PHP GD extension and supports GIF, JPEG and PNG images
only.
Note

Allowed file types - Comma separated file extensions (e.g. jpg,png,gif) without
spaces and quotes. If not specified, the global setting (see PHP Settings(See 1.10.2)
-> General Options -> File Upload) will be used.
Max file size (bytes) - The maximum allowed file size in bytes. (Requires browsers
supporting the File API.) If not specified, the global setting (see PHP Settings(See
1.10.2) -> General Options -> File Upload) will be used.
Max number of files - The maximum number of files that are allowed to be
uploaded if Multiple (see above) is enabled. It must be larger than 1. (If you just
allow one file, disable Multiple.) If not specified, unlimited file uploads are allowed.

104

PHPMaker 12 Help
Since file names are stored as comma separated value in the field, the max number
of files is also limited by the field size defined in the database.
Hidde <input type="hidden"> tag
n
Hide the field with a hidden form element.

This is different from de-selecting the field in the [Edit] column. If a field is deselected, no code will be generated for the field in the Edit page and the field will not
be updated. With a hidden form element the field is not seen but it may still get
updated.
Note

Custom value - by default the 'value' attribute contains the field value, custom
value is used to update the field with another value when a record is updated using
the Edit page.
Notes

1. Custom value is used in Edit page only. It cannot be used with Read-only
fields, User ID fields and Detail fields(Foreign key fields)
2. In Add page, if a default value is specified (see section below), hidden form
element will also be used but the 'value' attribute will contain the default
value. If default value is not specified, the field will be displayed as a normal
textbox.
3. Other preferable ways of updating a hidden field is to use Auto-Update
Value (see above) or to use Row_Inserting and/or Row_Updating server
events(See 1.10.9).
Custom attributes - same as above (see Text Edit Tag)

Using User Values for Edit Tag (Radio/Checkbox/Select)


For Radio/Checkbox/Select Edit Tags, the default option values are user input values,
you can enter as many value/label pairs as you want in the [User Values] panel next to the
[Edit Tag] panel.

105

PHPMaker 12 Help

For boolean fields, if you use Radio Edit Tag with User Values, the first value/label
should be for True and the second for False.
Note

Using Lookup Table for Edit Tag (Text/Radio/Checkbox/Select)


In real world applications, the option values usually come from a (lookup) table in the
database. PHPMaker make it very simple to use lookup values for key field values, simple
click [Use Table], the [Lookup Table] panel will replace the [User Values] panel, see
Lookup Table(See 1.10.8) for details.

Dynamic Selection Lists


PHPMaker supports Dynamic Selection Lists in which child lookup fields' selection list options
change dynamically based on option selected in the parent selection list. To setup child
lookup fields, click the [Child lookup fields...] button and the following setup form will be
displayed:

Read Tutorial - Dynamic Selection List(See 1.15.5) for more information.

Client side events (for Add/Copy/Edit/Search)

106

PHPMaker 12 Help
You can manipulate fields on the client side quickly with PHPMaker's "fields" jQuery plugin
(see Server Events and Client Scripts(See 1.10.9)).
Example 1
Set field values based on current field value

{ // keys = event types, values = handler functions


"change": function(e) {
if (this.value == "xxx") {
$(this).fields("FieldA").value("yyy"); // Set
FieldA
//$(this).fields("FieldA").visible(false); //
show, false to hide
//$(this).fields("FieldA").readonly(true); //
readonly, false as normal (for Text and TextArea only)
//$(this).fields("FieldA").disabled(true); //
disabled, false as normal
} else {
$(this).fields("FieldB").value("zzz"); // Set
FieldB
}
}
}

value to
true to
true as
true as
value to

Example 2
Client side calculation based on user input

{ // keys = event types, values = handler functions


"change keyup": function(e) {
var $row = $(this).fields(); // Get an object of all fields,
each property is a jQuery object of the input element(s) of a field
var st = $row["UnitPrice"].toNumber() *
$row["Quantity"].toNumber() * (1 - $row["Discount"].toNumber()); //
Convert to number and calculate
$row["SubTotal"].value(st); // Set result to a field
}
}
All client side events are generated in the script userevt<version>.js, after changing
client side events, remember to re-generate the .js file.
Note

Validation (for Add/Copy/Edit/Search)


The data input for each field can be validated using client-side JavaScript.
Validate

Supported validation formats are:

Integer
Float
Range
Date(yyyy/mm/dd) - also allows yy/mm/dd and date
with time
Date(mm/dd/yyyy) - also allows mm/dd/yy and date
with time
Date(dd/mm/yyyy) - also allows dd/mm/yy and date
with time
Time(hh:mm:ss)
Email

107

PHPMaker 12 Help

Credit card
GUID
US phone number
US zip code
US social security number
Regular Expression

Notes

1. For simplicity the validation format indicates the date


format with "/" as date separator, but the actual date
separator used in the scripts is determined by the
Default date format setting (see PHP Settings(See
1.10.2)).
2. If Regular Expression, client side and server side
arguments must be entered, depend on if you have
enabled client-side and server-side validation (see PHP
Settings(See 1.10.2)), see Arguments (Client-side)
and Arguments (Server-side) below.
3. You can add your own functions for validation. The
function must accept at least one argument (the value)
and return true (valid value) or false (invalid value). If
your functions requires additional arguments, see
Arguments (Client-side) and Arguments (Serverside) below. You can add your function names (comma
separated) in the Advanced Setting
CustomValidationFunctions. (See Tools(See 1.13).)
Note that since it is both JavaScript and PHP function
name, it must be a string that corresponds to a valid
identifier for both sides. For example, you can enter
"myValidateFunction1,myValidateFunction2" (no quotes).
If you have enabled Client-side (JavaScript) validation
(see PHP Settings(See 1.10.2)), you need to provide
your JavaScript function. If you have enabled Serverside validation (see PHP Settings(See 1.10.2)), you
need to provide your PHP function. You can put your
functions in the Global Code section under Server
Events and Client scripts respectively (see Server
Events and Client Scripts(See 1.10.9)) so they are
available for use in the generated scripts.
Arguments (Client-side) Arguments for the JavaScript functions for validation. For
Regular Expression and custom validation functions only.
This is JavaScript arguments, it should be comma separated
(if more than one) JavaScript expressions. e.g. If it is a string, it
must be single or double quoted.
Note

If the Validate setting (see above) is Regular Expression, this


setting must be a valid JavaScript regular expression pattern
along with flags that identify how to apply the pattern (delimit
the pattern by "/" characters, not single or double quotes), e.g.

/foobar/i
See Creating a Regular Expression for more information about
the pattern and flags.
Arguments (Server-side)Arguments for the PHP functions for validation. For Regular
Expression and custom validation functions only.

108

PHPMaker 12 Help
This is PHP arguments, it should be comma separated (if
more than one) PHP expressions. e.g. If it is a string, it must be
single or double quoted.
Note

If Regular Expression, arguments must be the the pattern to


search for, as a single or double quoted string, e.g.

'/foobar/i'
See PHP function preg_match for more information about the
pattern.
Use date/time picker

Check this option to use a JavaScript date/time picker instead of


manual input.
Notes

1. Popup calendar is only available for validation formats


DateTime (yyyy/mm/dd), DateTime
(mm/dd/yyyy) or DateTime (dd/mm/yyyy), you
must select one of these validation formats first.
2. Time picker is only available for Time validation format,
you must select the Time format first.
3. The popup calendar and time picker are not developed
by the author of PHPMaker and no technical support will
be provided. (See Third-party Tools(See 1.7).)
Required

Check this checkbox if the field is mandatory.


Notes

1. If the field is defined as NOT NULL in your database, the


field is required even this option is not enabled.
2. By default required fields will be denoted by an asterisk
beside the field caption. You can change the asterisk to
other or remove it in the language file.
Error message

Enter the error message to popup if error occurs.


If you use Multi-Language (see PHP Settings(See
1.10.2)), use Multi-Language Property Editor, see Tools(See
1.13) for details.
Note

Check duplicate

Specify whether to check duplicate values for the field before


editing or inserting a record.
If the field is an unique indexed field, PHPMaker will generate
server side codes to check duplicate values automatically even
this option is not selected. This option is useful when you want
to check a non unique indexed fields for duplicated values.

Add Page

109

PHPMaker 12 Help

Properties
Add

Show field in add page


The setting is for Add page only, NOT for Inline/Grid-Add/Edit and
Master/Detail-Add Edit in the List page. See the List setting above.
Note

Default ValueDefault value for field (for adding new record only) .
The value must be a valid PHP expression. (If it is a string, must be single or
double quoted.)

Multi-Update Page

Properties
Multi-UpdateShow field in Multi-Update page
If a field is selected, it will be included in the (See 1.10.7)Multi-Update page.
In the generated (See 1.10.7)Multi-Update page, there is a checkbox for each
field, the field will only be updated if the checkbox is checked so users can
update only the checked fields without affecting values of the other unchecked
fields.

Advanced Search Page

Properties
Search

Show field in Advanced Search page (Note: NOT related to Quick Search)

110

PHPMaker 12 Help
Search Opr 1

Search operator #1 for the field. Used in Advanced Search or Extended


Quick Search.

Default Value

Default value for Search Opr 1.


The value must be a valid PHP expression. (If it is a string, must be single
or double quoted.)

Search Opr 2

Search operator #2 for the field. Used in Advanced Search or Extended


Quick Search.
Notes

1. This second search operators will be useful when you need 2


criteria for the field when searching. You can also select AND/OR to
relate the 2 criteria during runtime.
2. If you want to use "BETWEEN" search operator, select "BETWEEN"
as the first search operator. Since "BETWEEN" requires 2 search
criteria, when it is used, the second search operator will be ignored.
Default Value 2Default value for Search Opr 2 .
The value must be a valid PHP expression. (If it is a string, must be single
or double quoted.)

Also See:
Custom Fields(See 1.10.14)

1.10.8 Lookup Table

Lookup Table
Lookup Table is used for lookup field with Text (Auto-Suggest), Radio, Checkbox and
Select Edit Tags. To enable, check User lookup table under Edit Tag panel after selecting
one of the Edit Tags.

111

PHPMaker 12 Help

From v12, Lookup Table always use Ajax and the "Use Ajax" option in previous versions
has been removed.
Note

Table name

Required. The lookup table to be linked to.

Link field

Required. The field to be used as the value of an option. Note that this is
the actual value to be submitted by the form This field is usually the key
field of the lookup table.

Display field #1

Required. The field in lookup table to be used as the label of an option.

Display field #2

Optional. The 2nd field in lookup table to be included in the label.

Display field #3

Optional. The 3rd field in lookup table to be included in the label.

Display field #4

Optional. The 4th field in lookup table to be included in the label.

Order By

Optional. Specify a field in the lookup table for sorting the options.

Asc/Desc

Optional. Sorting order. For use with Order By.

Distinct

Optional. Specify adding DISTINCT option to the SELECT statement for


the lookup table.

Filter

Optional. Specify the WHERE clause of the SELECT statement for the
lookup table. The input should be a valid PHP expression. If it is a string,
it should be quoted.
If your lookup table has a special field (e.g. named "ALookupTableField")
for filtering the records by a field (e.g. named "AField") in the current

112

PHPMaker 12 Help
record (of the current table), you can enter:

(strval(CurrentPage()->AField->CurrentValue) <> "") ?


"`ALookupTableField` = " . CurrentPage()->AField>CurrentValue : ""
Notes:
1. Make sure your expression returns a valid string. If some
variables in the expression has empty values, the expression will
return an incomplete WHERE clause leading to no records
returned from the lookup table. So you should always check if
the variables has non empty values first. If empty, return an
empty string (i.e. no filter) as in above example.
2. If the field in the WHERE clause is of string type, remember to
single-quote it. For example, if ALookupTableField in above
example is of VARCHAR type, you need to quote the value by
single quotes, e.g.
a. if the value is fixed,

"`ALookupTableField` = 'SomeValue'"
b. if the value needs to be escaped,

(strval(CurrentPage()->AField->CurrentValue) <>
"") ? "`ALookupTableField` = " .
ew_QuotedValue(CurrentPage()->AField>CurrentValue, EW_DATATYPE_STRING) : ""
3. This setting is used in all pages. If you want to used in some
pages only, you should add your conditions, e.g. if you just want
to use your filter in the Edit page,

(CurrentPageID() == "edit") ?
"`ALookupTableField` = 'SomeValue'" : ""
4. This setting is an one-liner. If your logic is complex and cannot
be implemented in one line, you can write a function and enter a
function call, e.g.

MyLookupFilterFunction()
You can also pass some variables to your function as arguments,
e.g.

MyLookupFilterFunction(CurrentPage()->AField>CurrentValue)
Your function should return a valid WHERE clause, e.g.

function MyLookupFilterFunction($value) {
if (strval($value) <> "") {
return "`ALookupTableField` = " . $value;
// assume ALookupTableField is integer field
} else {
return "";
}
}

113

PHPMaker 12 Help
You can place your function in Global Code section under
Server Events/Client Scripts. (See Server Events and Client
Scripts(See 1.10.9).)
Parent field #1

Optional. For use with dynamic selection lists. Specify the parent field
(in the current table) for the current selection list.
When the parent selection list is changed, the available options in
current selection list will be changed accordingly. Each field can have up
to 4 parent fields.
Parent field is solely used with Filter field for dynamic selection
lists only. Each Parent field MUST have a corresponding Filter field.
The Parent field alone does NOT do any filtering.
Note

Filter field #1

Optional. For use with dynamic selection lists. Specify the filter field (in
the lookup table) for filtering.
When the parent selection list changes, only options (records from the
lookup table) with Filter field value matching the selected value(s) of
its corresponding Parent field will be shown.
Filter field is solely used with Parent field for dynamic selection
lists only. Each Filter field MUST have a corresponding Parent field.
The Filter field alone does NOT do any filtering.
Note

Parent/Filter #2 Optional. For use with dynamic selection lists. The 2nd pair of parent
field and filter field.
If setup, the filtering of lookup table records will be based on 2 fields.
For example, if you have set up Parent/Filter field #1 and
Parent/Filter field #2, and both Parent field #1 and Parent field
#2 have selected value, the records will be filtered by:

(Filter field #1 value = Parent field #1 selected


value) AND (Filter field #2 value = Parent field #2
selected value)
By default, if either parent field is not selected, above filter will lead
to no results, the field will not have any options.
Note

Parent/Filter #3 Optional. For use with dynamic selection lists. The 3rd pair of parent
field and filter field. If setup, the filtering of lookup table records will be
based on 3 fields.
Parent/Filter #4 Optional. For use with dynamic selection lists. The 4th pair of parent
field and filter field. If setup, the filtering of lookup table records will be
based on 4 fields.
Allow add

Optional. If enabled, the user will be allowed to add an option to the


selection list.
Notes

1. Review your lookup table design before using this option. The
option works best if you there is only one display field and the
link field (primary key) is an autoincrement field. In that case
the user only need to fill in a textbox and the option is added.
But if the link field (primary key) is not an auto-increment field,

114

PHPMaker 12 Help
the user will need to enter the link field value which the user
may not know.
2. The user will be asked to enter the link field and the display
field(s) only. If the lookup table has other NOT NULL fields other
than the link field and display field(s), the new option cannot be
added. However, you can define default values for these fields in
the database (not in PHPMaker).
3. This feature is implemented using Ajax.
4. Adding fields other than the link field, display fields and filter
field is allowed. Click the [...] button and select additional fields
in the lookup table. However, please note that this feature is
designed for adding a lookup value on-the-fly only, it is NOT
supposed to replace the full-featured Add page of the lookup
table. Although file upload and JavaScript features such as
popup calendar and DHTML editor are also allowed (v9+), there
may be chances that they do not work properly in the popup
form. You should choose as few fields as possible. Also, note
that the add option form for each lookup table is shared among
all fields (possibly in different tables) using the same lookup
table. If you change the fields to be added to the lookup table,
the shared add option form will affect other fields as well.
Auto fill

Optional. If enabled, the script fills the target fields for you
automatically.
For example, when you select a product number (which is a lookup field
using the product table as its lookup table), it will fill product price
textbox for you.
Before using Auto-Fill, review your database design, you should
consider database normalization, in many cases you do NOT need to and
you should NOT copy the field values from one table to another. You can
view the other field values by creating a query/view joining the current
table with the lookup table using the parent field as linked field.
Note

The required conditions are:


1. The field has Lookup Table and Link field,
2. The field is setup as Radio or Select with Multiple disabled (i.e.
"select-one" only),
3. Auto fill is enabled,
4. Source Fields and Target Fields are set up.
If properly set up, when the user changes the selected value of the field,
the scripts will try to use other field values (specified by [Source
Field]) of the selected record (from the lookup table) to fill the target
fields of the current table (specified by [Target Field]) automatically.
Click the [...] button and select the source fields and target fields:
Remember that the actual field values of the Source Field and
Target Field as stored in the database will be used. The data types of
the Source Field and the Target Field must match. If the Source Field
has Lookup Table, its actual field value (NOT its Display Field value) is
used. Similarly, if the Target Field has Lookup Table, you should fill it
with a Source Field value that matches its actual field value (NOT its
Display Field value).
Note

115

PHPMaker 12 Help

In this example, when you select a product from combobox, the script
know the product ID from the option value, so it can use the ID to
locate the product from the same lookup table (your product table) and
retrieve other field values such as the product unit price and fill the
target fields.
Do NOT setup fields to autofill each other. For example, if you set
up field A to autofill field B (A -> B) and B -> A, it will be an infinite
loop. Similarly, if you setup A -> B and B -> C and C -> A, it will not
work either.
Note

Allow sort/search Enable sorting and searching of the looked-up values. For use with
Select (select-one) or Radio or Text Edit Tag only.
Since display values are field values in the lookup table (not in the main
table), they are retrieved dynamically by code during execution of the
script and normally the field cannot be sorted or searched by the display
values. PHPMaker makes it possible by adding a subquery to the SQL to
create a virtual field in the main table.
Limitations

1. No multiple selection. Select Edit Tag with Multiple enabled


and Checkbox Edit Tag are not supported.
2. No lookup table filter or table filter. If the lookup table has
filter, the subquery becomes too complex and the SQL will not
be supported by the database. The table filter and lookup table
filter will be ignored.
3. May not work with all databases. With subqueries the SQL
become more complex than usual, especially for Custom View,
the SQL may not be supported by your database. (This is
another reason why you should always use database query/view
whenever possible, see Using Custom View(See 1.10.11).)
4. Enable as few fields as possible. Since the SQL become more
complex, there is performance penalty, so do not blindly enable
this feature for all lookup fields.
Text input for
search

Enable text input for the field in the search forms. For use with Select
(select-one) or Radio or Text Edit Tag with Allow sort/search
enabled.
If Edit Tag is not Text (i.e. Select or Radio) and you have enabled
Allow sort/search, you may want to search with a textbox instead of
combobox or radio buttons. If so, enable this setting. Note that if Edit
Tag is Text and you have enabled Allow sort/search, the input is

116

PHPMaker 12 Help
textbox, this setting is enabled automatically even you have not checked
this setting to enable it explicitly.
NOT compatible with Dynamic Selection Lists. When this option is
enabled, the form element value (and the submitted value) is always
the text input (not the Link field value) for searching to work.
Therefore, if the field is a parent field in Dynamic Selection Lists (see
below), the child fields may not work in the search forms.
Note

Option Template
By default, the options are displayed as comma separated values of the display field values.
If you just want to change the display value separator from comma to other string, you can
use server events such as Page_Load (see Server Events and Client Scripts(See 1.10.9)) to
set the field object's DisplayValueSeparator property, e.g. if the field name is "MyField",

$this->MyField->DisplayValueSeparator = "-"; // Use hyphen as separator


$this->MyField->DisplayValueSeparator = array(",", "|", "-"); // Array
of separators (max. 3) for display field #2 to #4
However, if you want to display the link field and the display fields in your own HTML, you
can use Option Template, just write your HTML code in [Option template] under [Edit
Tag] panel, e.g. if you have settings like:

and you enter Option Template like:

<span class="text-info">{{:df1}}</span> <small class="textmuted">({{:df2}})</small>


Then the options for the field will be displayed in your HTML format like:

117

PHPMaker 12 Help
Option Template supports the following tags:

{{:lf}}

Link field value

{{:df1}}

Display field #1 value

{{:df2}}

Display field #2 value

{{:df3}}

Display field #3 value

{{:df4}}

Display field #4 value

Option template is in the format of JsRender template, refer to JsRender API for more
details.
Note

If the options needs to show some additional data from the lookup table, you can get the
additional data as Display fields so you can use them in Option Template. If you use Text
Edit tag (see Field Setup(See 1.10.7)), sometimes you may not need the additional data in
the input textbox, then again you can set the DisplayValueSeparator property by server
event. If the separator for a display field is not specified, the display field value will not be
placed in the input textbox You must always put the additional data in the last (n) display
field(s). There are 3 possible settings:

$this->MyField->DisplayValueSeparator = array(); // Display field #2 to


#4 hidden
$this->MyField->DisplayValueSeparator = array(", "); // Display field
#3 to #4 hidden
$this->MyField->DisplayValueSeparator = array(",", "|"); // Display
field #4 hidden

Ajax by Server Events and Client Scripts


Sometimes you may want to access the lookup table by Ajax yourself. For example, after
the user entering a value for a field, you may want to auto-fill another field in your own way,
then you can use Server Events and Client Scripts(See 1.10.9) to do it (in such cases do not
enable the built-in Auto-Fill in the Lookup Table panel). Say, if you want to fill the product
price when you select a product number (using products table as lookup table) when
inserting a new record, you can auto-fill the product price in orderdetails table either
asynchronously or synchronously with your code.
Example 1: Auto-Fill synchronously
Write Page_Load server event for Add Page: (PHP)

ew_SetClientVar("MyCustomSql", ew_Encrypt("SELECT UnitPrice FROM


products WHERE ProductID = {query_value}")); // Pass a server side
variable (encrypted SQL) to client side
Note that the WHERE clause of your SQL must contain the tag {query_value} which will
be replaced by the input value.
The variable will be passed to client side as property of the ewVar object so you can get it
back by ewVar.MyCustomSql or ewVar["MyCustomSql"].

118

PHPMaker 12 Help
Write a Startup Script for Add Page to attach onchange event: (JavaScript)

$("#x_ProductID").change(function() {
var result = ew_Ajax(ewVar.MyCustomSql, $(this).val()); // Send
the encrypted SQL and client side input value to server side by Ajax
for execution and get the result
$("#x_UnitPrice").val(result); // Set the result (manipulate it
first if necessary) to the target field
});
Note

The function ew_Ajax() reuses the generated script for lookup tables (ewlookup*.php)

so there is no need to write server side handler. For synchronous requests, if the result is a
recordset, it is in the format of array of object. If the result is a row, it is in the format of
object. If the result is a single value, it is in the format of string, remember to convert it to
the proper data type before manipulation. The function also supports asynchronous request,
just pass a callback function as the third argument, but the result from the server side is not
processed and therefore is always in the format of array of object. See the source code of
ew_Ajax() in the generated ewp*.js for details.

Example 2: Auto-Fill asynchronously


Write a Startup Script for Add Page to attach onchange event: (JavaScript)

$("#x_ProductID").change(function() {
$.post(ew_CurrentPage(), { "myajax": 1, "token": EW_TOKEN,
"value": $(this).val() }, function(result) { // Post back your custom
data (with the synchronizer token)
$("#x_UnitPrice").val(result); // Set the result (manipulate
it first if necessary) to the target field
});
});
Write a server side handler, check your custom data "myajax" in Page_Load server event
for Add Page and return the required value. In this example, only a single value is required
so ew_ExecuteScalar() (see Server Events and Client Scripts(See 1.10.9)) is used, e.g.
(PHP)

if (@$_POST["myajax"] == 1 && @$_POST["value"] != "") { // Check if it


is your custom Ajax and if the query value is present
$val = ew_ExecuteScalar("SELECT UnitPrice FROM products WHERE
ProductID = " . $_POST["value"]); // Get the desired value (assume
ProductID is integer so no need to quote the value)
echo $val; // Return the value (manipulate it first if necessary)
$this->Page_Terminate(); // Terminate the page
}
If you want to return a whole row (as JavaScript object) so you can fill multiple fields, you
may want to use ew_ExecuteRow() (see Server Events and Client Scripts(See 1.10.9)) and
json-encode the row before returning it so that you do not need to convert before using it in
your callback function on the client side, e.g.

$val = json_encode(ew_ExecuteRow("SELECT * FROM products WHERE


ProductID = " . $_POST["value"]));

119

PHPMaker 12 Help

1.10.9 Server Events and Client Scripts


You can implement your own business logic by writing your own server events and client
scipts. Your code is stored in the project so you can migrate your project to other templates
or future versions easily. This feature reduces the need of template customization and create
maximum possibilities for you to customize and create more advanced features for your
projects.
After loading the database, the database objects (tables, views, custom views and reports)
will be shown in the left pane (the database pane). Click on any table to go to the Field
Setup Page and then select the Code tab (which contains Server Events, Client Scripts
and Custom Templates).

Note: For simplicity, we use "table" in the following description to refer to any of database
object in the project. A database object can be either a table, a view, a custom view or a
report.

The treeview shows the available server events and client scripts that you can add to your
project:
Server Events Server-side PHP procedures
Global

The events are applicable to all PHP pages

Table-SpecificThe set of events are table-specific, the events are applicable to the selected
table only
Other

The events are applicable to some common pages in the project only

120

PHPMaker 12 Help
Client Scripts Client-side JavaScript
Global

The JavaScript are included in all pages with header and footer

Table-SpecificThe JavaScript are table-specific, they are included to pages for the selected
table only
Other

The JavaScript are included in some common pages in the project only

To add your custom scripts to the server events or client scripts, select an item in the
treeview, then enter your code in the editor.
The editor supports Find and Replace. Press Ctrl-F to open the Find dialog and press Ctrl-H
to open the Replace dialog.
You can click the [Clear] button to discard the existing code and reset template code for the
server event or client script.

Code Repository
PHPMaker provides a Code Repository for easy reuse of your code across projects and
sharing with other users. Click the [Code Repository] button to open it, categorized
reusable code will be displayed:

You can add the code to the editor by clicking the [Add to Editor] button. The reusable
code is stored in XML files which reside in s subfolder name "code" under the installation
folder. The format of the XML files is simple, there are 3 parts:
1. description - description of the reusable code
2. code - code to be inserted to editor
3. globalcode - common code to be inserted to Global Code (see below), this code will
only be inserted once into the project. For example , if your code is used several

121

PHPMaker 12 Help
times in your project and your code calls a helper function, it is unnecessary to
include the helper function several times. In this case you put your helper function in
the globalcode section, then the function will only be included one time.
There are a few example files in the "code" folder, you can copy and modify for your own
code and then save them under the "code" folder for reuse.

Server Events
In general, server events are fired in the following order:

Page_Loading (Global function)


Page_Load (Page class method)
Page_Rendering (Global function)
Page_Render
Page_DataRendering
RecordSet_* / Grid_* / Row_* (Page class method)
Page_DataRendered
Page_Unload (Page class method)
Page_Unloaded (Global function)

Notes

1. From v9, the page class inherit from the table class, so you can use $this in the
page class methods to access table class members. For backward compatibility, the
table object is kept and it is an alias of the page object, so you can also use $this
in the table class methods to access page class members.
2. The Page_Unload and Page_Unloaded are server side events to be fired every
time the page is accessed and before the HTML is outputted to the browser on the
client side. They are NOT events to be fired before you leave the page and reload
the page or go to another page. For example, if you submit a form in the page,
usually it submits to the page itself, you are actually reloading the page, all server
events will be fired again. For another example, if you click a hyperlink which links to
another page, the page on the server side is not even accessed again and no server
events for the page will be fired.
3. If a server event is a global function, there is NO $this in the function context. If
you want to refer to the current page object, you can use the global function
CurrentPage().
4. In the following table, the <fieldname> in code, e.g. in $this-><fieldname>><property> or x_<fieldname>, represents the field variable name. In general, if
the field name is alphanumeric, field variable name is same as the field name.
Otherwise, spaces are replaced by underscores, and other non alphanumeric
characters are replaced by their hexadecimal string representation of their unicode
value. If the variable is a reserved word or starts with a digit, it will be prepended
with an underscore. However, note that if the field name is quoted, e.g. as a key in
$rs['<fieldname>'], <fieldname> is the actual field name as in the database,
not the field variable name.
5. Server events are functions or class methods, if you need to use global variables in
the events, note the PHP variable scope, you must use the global keyword or
$GLOBALS.
Available server events are:
Global -> All Pages
Page_Head

The code you entered in this event will be placed in the header.php
before closing the <head> section. You can use this event to can add

122

PHPMaker 12 Help
your code in head section. Note: This is a global function.
Example
PHPMaker does NOT use jQuery UI, but you can include it yourself
(using CDN):

ew_AddStylesheet("http://code.jquery.com/ui/1.10.3/the
mes/smoothness/jquery-ui.css"); // Add CSS stylesheet
ew_AddClientScript("http://code.jquery.com/ui/1.10.3/j
query-ui.js"); // Add JavaScript
Then you can use the widgets using Startup Script (see below).
Database_Connecti This event will be called by all PHP pages before connecting to the
ng
database. Note: This is a global function.
If MySQL/PostgreSQL, the argument is an array with the following
keys: host, port, user, pass, db. If Access/MSSQL, the argument is
the connection string for ADO. You can use this event to change the
connection string (e.g. changing connection info with server, or even
connect to other databases).
Example 1

// MySQL/PostgreSQL
function Database_Connecting(&$info) {
//var_dump($info);
// assume the scripts are generated with
connection info for local PC
if (ew_CurrentUserIP() <> "127.0.0.1") { // not
connecting to local PC
// connect to the production database
$info["host"] = "localhost";
$info["user"] = "xxx";
$info["pass"] = "yyy";
$info["db"] = "production_db";
}
}
Example 2
It is possible to use single login and common Dynamic User Levels for
multiple projects provided that ALL projects use the same project
name and same Advanced Security tables (i.e. User Table, User Level
Table and User Level Permission Table). If all projects uses the same
database and same Advanced Security tables, then the latter condition
is auto fulfilled. However, if the projects use different databases, you
can use this event to change the connection info so the user can get
the Dynamic User Levels from the common Advanced Security tables
correctly during login, e.g.

// MySQL/PostgreSQL
function Database_Connecting(&$info) {
//var_dump($info);
if (preg_match('/login|userpriv/',
CurrentPageID()) { // login.php or userpriv.php

123

PHPMaker 12 Help
// connect to the common database with the
common Advanced Security tables
$info["host"] = "localhost";
$info["user"] = "xxx";
$info["pass"] = "yyy";
$info["db"] = "common_db";
}
}
Database_Connect This event will be fired by all PHP pages after connecting to the
ed
database. Note: This is a global function.
The argument is the connection object, you can use it to execute your
own statements.
Example
Call a stored procedure after connection.

function Database_Connected(&$conn) {
$conn->Execute("CALL MyStoredProcedure");
}
Language_Load

This event will be fired when the language file is loaded. You can use it
to change the language phrases if necessary. Note: This event is a
language class member.
Example

function Language_Load() {
$this->setPhrase("MyID", "MyValue"); // Refer to
language file for the actual phrase id
$this->setPhraseClass("MyID", "glyphicon
glyphicon-xxx ewIcon"); // Refer to
http://getbootstrap.com/components/#glyphicons for
icon name
}
Page_Loading

This event will be called by all PHP pages at the beginning of the page.
If the pages involves database connection, it will be called after
connecting to the database and before the Page_Load event. Note:
This is a global function, NOT page class member.

Page_Rendering

This event will be called by all PHP pages before outputting HTML for
the page. Note: This is a global function, NOT page class
member.

Page_Unloaded

This event will be called by all PHP pages at the end of the page. If the
pages involves database connection, it will be called before closing
database connection and after the Page_Unload event. Note: This is
a global function, NOT page class member.

Global Code

Code to be included in all PHP pages. This may contain your constants,
variables and functions.

User_CustomValidaFor use with security. (See Security Settings(See 1.10.4)) This event
is fired before default user validation. You can use this event to

124

PHPMaker 12 Help
te

validate the user yourself. The arguments are the user name and
password the user entered. Return TRUE if the username and
password pass your custom validation. Note: This event is a
security class member.
From v9, default validation will continue after this event is fired. If
you return TRUE, the user will always pass the default validation and
get the User ID and User Level, if any. If you return FALSE, the default
validation proceeds as normal. If you use Advanced Security, you still
need the user table to store user information such as User ID and User
Level, although the password field value can be empty or any value if
you return TRUE.
Note

Example 1
Login user by Windows user name.

function User_CustomValidate(&$usr, &$pwd) {


// e.g. Simple Windows authentication
if (ew_ServerVar("LOGON_USER") <> "") {
$usr = ew_ServerVar("LOGON_USER");
return TRUE;
}
}
Example 2
Login user by LDAP. (The following example code can be found in
Code Repository.)

function User_CustomValidate(&$usr, &$pwd) {


// e.g. LDAP authentication example for
User_CustomValidate server event
if (!function_exists("ldap_connect"))
die("LDAP extension not installed.");
$ldapconn = ldap_connect("ldap.example.com", 389)
or die("Could not connect to LDAP server."); // Note:
Replace the host name and port
if ($ldapconn && ldap_bind($ldapconn, $usr, $pwd))
{
$this->setCurrentUserName($usr); // Set the
current user name
return TRUE;
}
}
User_Validated

For use with security. (See Security Settings(See 1.10.4)) This event
is fired after successful user login. The user info is passed to the event
as an array (see note), you can get more info of the user and use it as
you need. Note: This event is a security class member.
Notes

1. This event is not fired for the hard-coded administrator.


2. The argument $rs is an array, you can get a field value by
$rs['<fieldname>'].
Example 1

125

PHPMaker 12 Help
Add current user's country to session variable

function User_Validated(&$rs) {
$_SESSION["UserCountry"] = $rs['Country'];
}
Example 2
Check if an user password has expired by custom code with Enable
password expiry (see Security Settings(See 1.10.4)) enabled

function User_Validated(&$rs) {
if ($rs["PasswordExpired"] == "Y") { // Assume the
user table has a field named "PasswordExpired" storing
if the password has expired
$this->SetPasswordExpired($rs["Username"]); //
// Assume the user name field is named "Username"
return FALSE; // Return FALSE to invalidate
the user
}
}
UserLevel_Loaded For use with User Level security. (See Security Settings(See 1.10.4))
This event is fired after successful user login and after the User Level
settings are loaded. It is possible to do actions such as changing or
adding User Level permissions. Note: This event is a security class
member.
Example
Change the permissions of an User Level for a table

// Note: This event is a Security class member, so you


can refer to other members of the Security class
directly
function UserLevel_Loaded() {
$this->DeleteUserPermission("Sales", "orders",
EW_ALLOW_ADD);
$this->AddUserPermission("Sales", "orders",
EW_ALLOW_EDIT);
}
MenuItem_Adding This event is fired for custom menu items before it is added to the
menu. The menu item info is passed to the event as an instance of the
cMenuItem object (see below). Return FALSE if you don't want to show
the menu item. If you return TRUE, the menu item will be added to the
menu, but it does not mean that it will be always displayed. A menu
item will be displayed only if its Allowed property is TRUE. When the
menu item is passed to this event, the Allowed property is set based
on the User Level Security of the project, you can however change it
by setting $Item->Allowed as TRUE or FALSE as needed. Note: This
is a global function.
Example
Only show a menu item after the user has logged in

function MenuItem_Adding(&$Item) {
//var_dump($Item);
// Return False if menu item not allowed

126

PHPMaker 12 Help
if ($Item->Text == "Download")
return Security()->IsLoggedIn();
return TRUE;
}
Menu_Rendering

This event is fired before the menu is rendered. You can manipulate
the menu items in this event. The argument is the menu object. (See
Menu Object below.) Note: This is a global function.
Example 1
Add an additional menu item to the menu for logged in users only.

function Menu_Rendering(&$Menu) {
if ($Menu->IsRoot) { // Root menu
$Menu->AddMenuItem(10000, "MyName",
"MyMenuText", "MyPage.php", -1, "", IsLoggedIn());
$Menu->MoveItem("Logout", $Menu->Count() - 1);
// Move to last
}
}
Example 2
Remove all the default menu items and use your own menu items.

function Menu_Rendering(&$Menu) {
if ($Menu->IsRoot) { // Root menu
$Menu->Clear(); // Clear all menu items
$Menu->AddMenuItem(1, "MyName1",
"MyMenuText1", "MyPage1.php");
$Menu->AddMenuItem(2, "MyName2",
"MyMenuText2", "MyPage2.php");
}
}
TablePermission_L For use with User Level security. (See Security Settings(See 1.10.4))
This event is fired before the user permission for the table of the
oading
current page is loaded. It is possible to do actions such as changing or
adding more User Level permissions to the current user. Note: This
event is a security class member.
This is an event fired for the current table only. If you
change the permissions of the other tables in this event, there will be
no effect. Use the UserLevel_Loaded event if you need to change
permissions of other tables.
Note

Example
Grant another User Level to the user and let the user have permissions
of more than one User Level for the current table.

// Note: This event is a Security class member, so you


can refer to other members of the Security class
directly
function TablePermission_Loading() {
if (CurrentUserName() == "nancy")

127

PHPMaker 12 Help
$this->AddUserLevel("Manager");
}
TablePermission_L For use with User Level security. (See Security Settings(See 1.10.4))
This event is fired after the user permission for the table of the current
oaded
page is loaded. It is possible to to change the permission by using the
setCanXXX methods of the Security class. Note: This event is a
security class member.
This is an event fired for the current table only. If you
change the permissions of the other tables in this event, there will be
no effect. Use the UserLevel_Loaded event if you need to change
permissions of other tables.
Note

Example
Grant more permissions to the user and let the user have more
permissions than his/her User Level allows for the current table.

// Note: This event is a Security class member, so you


can refer to other members of the Security class
directly
function TablePermission_Loaded() {
if (CurrentUserName() == "nancy" &&
CurrentTable()->TableName = "orders")
$this->setCanEdit(TRUE);
}
UserID_Loading

For use with User ID security. (See Security Settings(See 1.10.4)) This
event is fired after successful user login and before loading the User ID
and its child User IDs of the current user. These User IDs determine
which records the current user can access. It is possible to do actions
such as changing the User ID of the current user so the user can
access records that he/she can access by its original User ID. Note:
This event is a security class member.
Example
Change the user's User ID to his parent user's user ID and let the user
access more records (accessible by the parent user).

// Note: This event is a Security class member, so you


can refer to other members of the Security class
directly
function UserID_Loading() {
if (CurrentParentUserID() <> "")
$this->CurrentUserID = CurrentParentUserID();
}
UserID_Loaded

For use with User ID security. (See Security Settings(See 1.10.4)) This
event is fired after loading the User ID and its child User IDs of the
current user. These User IDs determine which records the current user
can access. It is possible to do actions such as adding or deleting the
loaded User IDs for the current user so the user can access more or
less records that he/she can access by its originally loaded User IDs.
Note: This event is a security class member.
Example

128

PHPMaker 12 Help
Add more User IDs to the user and let the user access more records

// Note: This event is a Security class member, so you


can refer to other members of the Security class
directly
function UserID_Loaded() {
if (CurrentUserName() == "nancy")
$this->AddUserID($this>GetUserIDByUserName("janet"));
}
User_PasswordExp This event will be called if the user password is already expired. User
information is passed to the event as argument, you can get user
ired
information by $rs["<fieldname>"] where <fieldname> is a field name
of the user table. Note: This event is a security class member.
AuditTrail_Insertin This event will be called before an audit trail record is written. The
audit trail information is passed to the event as argument, you can get
g
the information by $rsnew["<fieldname>"] where <fieldname> is the
audit trail field name. Return False to cancel the insert. Note: This is
a global function.
Table-Specific -> Common (Note: These events are members of the page class)
Recordset_Selectin This event will be called before selecting records. The argument of the
event is the filter (part of the WHERE clause of the SQL) for selecting
g
records, you can customize the filter to change the records to be
selected.
Example
Add your own filter. Note that the $filter may have value, if you want
to add some additional filter, append your filter to it, not replace it.

function Recordset_Selecting(&$filter) {
ew_AddFilter($filter, "Field1 = 1234"); // Add
your own filter expression
}
Recordset_Selecte This event will be called after selecting records. Note: The argument is
d
the recordset object (not array).
Recordset_SearchV This event will be called after the Form_CustomValidate event and
the search criteria is assigned to the table/field objects. You can
alidated
modify the search criteria in this event.
This event is a member of the table class. There is no arguments for
this event. To change the Quick Search criteria, change the
BasicSearchKeyword and BasicSearchType property of the table
object. To change the Advanced Search criteria, change the
AdvancedSearch property (which is an object of the
cAdvancedSearch class) of the field object.
Example

function Recordset_SearchValidated() {
$this->MyField1->AdvancedSearch->SearchValue =
"your search criteria"; // Search value
}

129

PHPMaker 12 Help
Recordset_Searchi This event will be called before the search criteria is saved for the
session. The argument of the event is the part of WHERE clause built
ng
from the Quick/Extended/Advanced search criteria. You can modify the
WHERE clause in this event.
Example
Search a MySQL DATE field for a selected date or within 3 days after
the selected date.

function Recordset_Searching(&$filter) {
//die($filter); // Uncomment to view the filter
first
$filter = preg_replace('/`MyDateField` = (\'\d{4}\d{2}-\d{2}\')/', '`MyDateField` >= $1 AND
`MyDateField` < DATE_ADD($1, INTERVAL 3 DAY)',
$filter); // Replace part of the filter with your
modified filter
}
Row_Deleting

This event will be called before deleting a record. The argument of the
event is the record to be deleted as an array.

Row_Deleted

This event will be called after deleting a record. The argument of the
event is the record deleted as an array.
Example
Delete detail records from the detail table after the master record is
deleted.

function Row_Deleted(&$rs) {
// Assume ForeignKeyField is of integer type
ew_Execute("DELETE FROM DetailTable WHERE
ForeignKeyField=" . $rs["PrimaryKeyField"]);
}
Row_Inserting

This event will be called before inserting a record. The arguments of


the event are the arrays of the old (if copying record) and new record
to be inserted. You can change the values in the $rsnew.
Example
Make sure a field value is valid.

function Row_Inserting(&$rsold, &$rsnew) {


if ($rsnew["Percentage"] > 100)
$rsnew["Percentage"] = 100;
// To cancel, set return value to False
return TRUE;
}
Row_Inserted

This event will be called after inserting a record. The arguments of the
event are the arrays of the old (if copying record) and new record just
inserted.
Example
Get the ID (autoincrement field) of the just inserted record

function Row_Inserted(&$rsold, &$rsnew) {

130

PHPMaker 12 Help
$this->setSuccessMessage("Record Inserted. The ID
of the new record is " . $rsnew["ID"]);
}
Row_Rendering

This event will be called before rendering (applying the View/Edit Tag
settings) a record.

Row_Rendered

This event will be called after rendering a record.


This is an extremely useful event for conditional formatting, you can
do a lot of things with this event, such as changing font color, font
styles, row background color, cell background color, etc. by changing
the table or field class properties in the event according to field values.
The table class has a RowAttrs property which is an associative
array of HTML attributes for the table row. The field class has
CellAttrs, ViewAttrs and EditAttrs for the table cell, View Tag and
Edit Tag of the field respectively. The keys of these arrays must be
valid HTML attributes for the HTML tag, always use lowercase for the
keys. The attribute values will be outputted as double quoted
attributes, so if you have double quotes in your values, try to use
single quotes if possible, or use "&quot;".
Note

To view the properties of the field class for development or debugging,


you can use the PHP's var_dump function in the server event, e.g.

var_dump($this->RowAttrs);
var_dump($this->Trademark);
var_dump($this->Trademark->CellAttrs);
var_dump($this->Trademark->EditAttrs);
var_dump($this->Trademark->ViewAttrs);
Example
Click "Cars" node on the database panel, select [Server
Events/Client Scripts], and click [Table Specific] - > [Common] > [Row_Rendered] server event. The default Row_Rendered event
code is shown. Change as follow:

function Row_Rendered() {
// Change the row color in List page by Bootstrap
classes
if ($this->Trademark->ViewValue == "BMW") // List
page only
$this->RowAttrs["class"] = "info";
// Change the table cell color
if ($this->PageID == "list" || $this->PageID ==
"view") { // List/View page only
if ($this->Cyl->CurrentValue == 4) {
$this->Cyl->CellAttrs["style"] =
"background-color: #ffcccc";
} elseif ($this->Cyl->CurrentValue == 6) {
$this->Cyl->CellAttrs["style"] =
"background-color: #ffcc99";
} elseif ($this->Cyl->CurrentValue == 8) {
$this->Cyl->CellAttrs["style"] =
"background-color: #ffccff";
}
}

131

PHPMaker 12 Help
// Change text style by Bootstrap classes
if ($this->Category->CurrentValue == "SPORTS")
$this->Category->ViewAttrs["class"] = "bgwarning text-warning";
}
Row_Selecting

This event will be called before selecting a record. The argument of the
event is the filter (part of the WHERE clause of the SQL) for selecting
the record, you can customize the filter to change the record to be
selected.

Row_Selected

This event will be called after selecting a record. The argument is the
record selected as an array.

Row_UpdateConflicThis event will be called if conflicts is found before updating a record (if
Check Conflicts is enabled, see Table Setup(See 1.10.6)). The
t
arguments of the event are the old record (as array) and new record
(as array) to be updated.
You can use this event to resolve the conflicts according to your own
criteria. If you want to ignore conflicts or you have resolved the
conflicts in the event (by setting new values to the argument rsnew)
and want to continue update, return FALSE. Otherwise, return TRUE.
By default the event returns TRUE.
Row_Updating

This event will be called before updating a record. The arguments of


the event are the arrays of the old and new record to be updated.
Example
Make sure a field value is not changed

function Row_Updating(&$rsold, &$rsnew) {


if ($rsnew["Qty"] < $rsold["Qty"]) {
// To cancel, set return value to False
$this->CancelMessage = "The new quantity must
be larger than the old quantity.";
return FALSE;
}
return TRUE;
}
Row_Updated

This event will be called after updating a record. The arguments of the
event are the arrays of the old and new record updated.
Example
After updating a field in detail table, update a field in the master table.

function Row_Updated($rsold, &$rsnew) {


//var_dump(rsold, rsnew); die(); // Print the old
and new record and end the script
$rs = array();
$rs["FieldInMasterTable"] =
$rsnew["FieldInDetailTable"]; // Set field values
(new cMasterTable())->Update($rs,
"PrimaryKeyFieldInMasterTable = " .
$rsold["ForeignKeyFieldInDetailTable"]); // Note:
Table class is named as c<TableName>. Assume
PrimaryKeyFieldInMasterTable is integer.

132

PHPMaker 12 Help
}
Grid_Inserting

For use with Grid-Add for a table and Master/Detail-Add for a detail
table, this event will be called before inserting records. This event has
no arguments.
You can use this event to check all records to be inserted. If you want
to cancel insert, return FALSE. Otherwise, return TRUE. By default the
event returns TRUE.
If you only need to check individual record, there is no need to
use this event, simply use Row_Inserting (see above) which will be
called for each row in the grid.
Note

Example
Check all records before inserting. Note that this event is called before
Row_Inserting, the field values are not loaded yet, but you can load
them yourself.

function Grid_Inserting() {
$rsnew = $this->GetGridFormValues(); // Get the
form values of the new records as an array of array
//var_dump($rsnew); die(); // Print the records
and end the script
$sum = 0;
foreach ($rsnew as $row) // Loop through the new
records
$sum += intval($row["Percentage"]);
if ($sum < 100) {
// To cancel, set return value to False
$this->setFailureMessage("The total of
percentages must be 100.");
return FALSE;
}
return TRUE;
}
Data returned from GetGridFormValues() is read only, do NOT
try to change the values. To change the values, use Row_Inserting
(see above) which will be called for each row in the grid.
Note

Grid_Inserted

For use with Grid-Add for a table and Master/Detail-Add for a detail
table, this event will be called after inserting all records. The argument
of the event ($rsnew) is array of records inserted (retrieved from
database).
For example, you can use this event to update a field in the master
table (similar to the example for Row_Updated above) after
Master/Detail-Add.

Grid_Updating

For use with Grid-Edit for a table and Master/Detail-Edit for a detail
table, this event will be called before updating records. The argument
of the event ($rsold) is array of records to be updated (retrieved from
database).
You can use this event to check all records to be updated. If you want
to cancel update, return FALSE. Otherwise, return TRUE. By default the
event returns TRUE.

133

PHPMaker 12 Help
If you only need to check individual record, there is no need to
use this event, simply use Row_Updating (see above) which will be
called for each row in the grid.
Note

Example
Check all records before updating. Note that this event is called before
Row_Updating, the field values are not loaded yet, but you can load
them yourself.

function Grid_Updating($rsold) {
$rsnew = $this->GetGridFormValues(); // Get the
form values of the new records as an array of array
//var_dump($rsnew); die(); // Print the records
and end the script
$oldtotal = 0;
foreach ($rsold as $row) // Loop through the old
records
$oldtotal += intval($row["Subtotal"]);
$newtotal = 0;
foreach ($rsnew as $row) // Loop through the new
records
$newtotal += intval($row["Subtotal"]);
if ($newtotal < $oldtotal) {
// To cancel, set return value to False
$this->setFailureMessage("The new total must
be larger than the old total.");
return FALSE;
}
return TRUE;
}
Note

Data returned from GetGridFormValues() is read only, do NOT

try to change the values. To change the values, use Row_Updating


(see above) which will be called for each row in the grid.
Grid_Updated

For use with Grid-Edit for a table and Master/Detail-Edit for a detail
table, this event will be called after updating all records. The argument
of the event ($rsold and $rsnew) are array of records before and
after update (retrieved from database).
For example, you can use this event to update a field in the master
table (similar to the example for Row_Updated above) after
Master/Detail-Edit.

Email_Sending

This event is fired before the email notification is sent. You can
customize the email content using this event. Email_Sending event has
the following parameters:
Email - the email object instance which contain all the information
about the email to be sent. It is an instance of the cEmail class (see
below).
Args - an array which contains additional information.
If Add, the new record in the format of array can be access by
$Args["rsnew"]. If Copy, the old record in the format of array can be
access by $Args["rsold"]. If Edit/Update, the old data of the records in
the format of array can be access by $Args["rsold"], the new data of

134

PHPMaker 12 Help
the records in the format of array can be access by $Args["rsnew"]. If
Register, the new record in the format of array can be access by
$Args["rs"]. You can get a field value by, e.g.

$rsnew = $Args["rsnew"];
$MyValue = $rsnew["MyField"];
or

$MyValue = $Args["rsnew"]["MyField"];
Return FALSE in the event if you want to cancel the email sending.
If Grid-Add/Edit or Update page, there are more than one records, the
arguments are array of array.
Example
Assume there is an email field in the record, and you want to change
the recipient to the value of that field.

function Email_Sending(&$Email, &$Args) {


//var_dump($Email);
//var_dump($Args);
//exit();
if (CurrentPageID() == "add") { // If Add page
$Email->Recipient =
$Args["rsnew"]["MyEmailField"]; // Change recipient to
a field value in the new record
$Email->Subject = "My New Subject"; // Change
subject
$Email->Content .= "\nAdded by " .
CurrentUserName(); // Append additional content
}
return TRUE;
}
Lookup_Selecting

This event is fired before building the SQL for selecting records from
the lookup table. You can use this event to change the filters.
In the event, the SQL and filter for the lookup can be viewed by:

var_dump($this->LookupFilters);
The property LookupFilters is an array, the key values are:

SQL (SELECT clause and FROM clause only)

Datebase ID

Filter template for filter field <n> (where n = 1 to 4), by default


f<n> it is in the format of "FilterField<n> = {filter_value}" where
"{filter_value}" is to be replaced by selected value(s) submitted
from client side by Ajax.

t<n>

The data type of the filter field. Do not change unless you
change the filter field in f<n>.

fn<n>The function used to concatenate the filter, by default it is


empty and the default function "ew_AddFilter" is used to

135

PHPMaker 12 Help
concatenate the filters by "AND".
Example 1
Add additional filter to the lookup table filter

function Lookup_Selecting($fld, &$filter) {


//var_dump($this->LookupFilters); // Uncomment to
view the SQL and the filters
if ($fld->FldName == "MyLookupField")
ew_AddFilter($filter, "MyField = 'xxx'"); //
Assume the field is of string type
}
Example 2
Change the default filter of a filter field from "`MyFilterField` IN
({filter_value})" to "`MyFilterField` > ({filter_value})"

function Lookup_Selecting($fld, &$filter) {


//var_dump($this->LookupFilters); // Uncomment to
view the SQL and the filters
if ($fld->FldName == "MyLookupField")
$fld->LookupFilters["f1"] = str_replace("IN",
">", $fld->LookupFilters["f1"]);
}
UserID_Filtering

For use with User ID security. (See Security Settings(See 1.10.4)) This
event is fired before adding the User ID filter to the WHERE clause of
the table. It is possible to modify, replace or add filter so the user can
access more or less records that he/she can access by its originally
loaded User IDs.
Example
Assume you have 2 User ID fields in the current table and in the user
table, and you want to filter by both User ID fields.

function UserID_Filtering(&$filter) {
ew_AddFilter($filter, "MyUserIDField2 = " .
CurrentUserInfo("MyUserIDField2InUserTable")); //
Assume the field is of integer type
}
Table-Specific -> Add/Copy page
Page_Load

This event will be called after connecting to the database.

Page_Render

This event will be called before outputting HTML for the page. You can
use this event to make some last minute changes to the page before it
is outputted.

Page_Unload

This event will be called before closing database connection.

Page_DataRenderi This event will be called after the header.php is included. You can use
ng
this event to add content at the top of page content.
Page_DataRendere This event will be called before the footer.php is included. You can use
d
this event to add content at the bottom of page content.
Page_Redirecting

This event will be called before redirecting to other page. The

136

PHPMaker 12 Help
argument is the URL to be redirected to.
By default after inserting a record user is redirected back to the List
page. You can change that by using Return Page (see Table Setup(See
1.10.6)). However, If you want to change by code, you can also use
this event.
Message_Showing This event is fired before the message stored in the session variable is
shown.
The first argument $msg is the message to be shown, the second
argument $type is the type of the message, possible values of type
are: "" (empty string), "success", "failure", and "warning".
Example
Replace an error message by custom message

function Message_Showing(&$msg, $type) {


if ($type == 'success') {
//$msg = "your success message";
} elseif ($type == 'failure') {
if (strpos($msg, "some standard message") !==
FALSE)) // The original message contains some keywords
you want to replace
$msg = "My custom message";
} elseif ($type == 'warning') {
//$msg = "your warning message";
} else {
//$msg = "your message";
}
}
Form_CustomValid This event is fired after the normal form validation. You can use this
event to do your own custom validation. In general, the form data can
ate
be accessed by $this-><Field>->FormValue (e.g. $this->HP>FormValue). Alternatively, you can get all the form values in an array
first, e.g.

$rs = $this->GetFieldValues("FormValue");
An argument $CustomError is passed to the event, you can add your
error message and return FALSE if the form values do not pass your
validation.
Example
Make sure an integer field value meet a certain requirement

function Form_CustomValidate(&$CustomError) {
$rs = $this->GetFieldValues("FormValue"); // Get
the form values as array
if (intval($rs["Qty"]) % 10 <> 0) {
// Return error message in $CustomError
$CustomError = "Order quantity must be
multiples of 10.";
return FALSE;
}
return TRUE;
}

137

PHPMaker 12 Help
If you use this server event, make sure you have enabled serverside validation, see Validation in PHP Settings(See 1.10.2).
Note

Table-Specific -> Delete Page


Page_Load

This event will be called after connecting to the database.

Page_Render

This event will be called before outputting HTML for the page. You can
use this event to make some last minute changes to the page before it
is outputted.

Page_Unload

This event will be called before closing database connection.

Page_DataRenderi This event will be called after the header.php is included. You can use
ng
this event to add content at the top of page content.
Page_DataRendere This event will be called before the footer.php is included. You can use
d
this event to add content at the bottom of page content.
Message_Showing This event is fired before the message stored in the session variable is
shown. You can use this event to change the message which is passed
to the event as argument.
Page_Redirecting

This event will be called before redirecting to other page. Event


argument is the URL to be redirected to.
By default after deleting record(s) user is redirected back to the List
page. You can change that using this event.

Table-Specific -> Edit Page


Page_Load

This event will be called after connecting to the database.

Page_Render

This event will be called before outputting HTML for the page. You can
use this event to make some last minute changes to the page before it
is outputted.

Page_Unload

This event will be called before closing database connection.

Page_DataRenderi This event will be called after the header.php is included. You can use
ng
this event to add content at the top of page content.
Page_DataRendere This event will be called before the footer.php is included. You can use
d
this event to add content at the bottom of page content.
Message_Showing This event is fired before the message stored in the session variable is
shown. You can use this event to change the message which is passed
to the event as argument.
Page_Redirecting

This event will be called before redirecting to other page. Event


argument is the URL to be redirected to.
By default after updating a record user is redirected back to the List
page. You can change that by using Return Page (see Table Setup(See
1.10.6)). However, If you want to change by code, you can use this
event.

Table-Specific -> List Page

138

PHPMaker 12 Help
Page_Load

This event will be called after connecting to the database.


The export links are stored as a cListOptions object (also see
ListOptions_Load and ListOptions_Rendered event below), you
can manipulate the links in the same way. The defaut names of the
options are:
Note

print
html
excel
word
xml
csv
pdf
email

Note that the names are in lowercase and are case-sensitive.


Example 1
Hide the export to PDF link in List page:

function Page_Load() {
$item = @$this->ExportOptions->Items["pdf"];
if ($item)
$item->Visible = FALSE;
}
Example 2
Add a custom link at the end of the export links

function Page_Load() {
$item = &$this->ExportOptions->Add("MyName");
$item->Body = "<a href='MyURL'>My Link</a>";
}
Example 3
Add a custom action to submit selected records by HTTP POST

function Page_Load() {
$this->CustomActions["star"] = "Add Star"; //
Where "star" is the id and "Add Star" is the caption
of the custom action
}
Adding a custom action by its name and caption is a actually a short
form of

$this->CustomActions["star"] = new cListAction("star",


"Add Star");
and is supported for backward compatibility only. Use the cListAction
class so you have more options for the custom action. The constructor
of cListAction class is

function __construct($Action, $Caption, $Allow = TRUE,


$SubmitType = EW_ACTION_POSTBACK, $SelectType =
EW_ACTION_MULTIPLE, $ConfirmMsg = "", $Icon =

139

PHPMaker 12 Help
"glyphicon glyphicon-star ewIcon")
$SubmitType is either EW_ACTION_POSTBACK (submit by HTTP
POST) or EW_ACTION_AJAX (submit by Ajax).
$SelectType is either EW_ACTION_MULTIPLE (submit the selected
records) or EW_ACTION_SINGLE (submit the current record only).
To process the action, you also need to write a handler with
Row_CustomAction server event (see below).
Note

Example 4
Add a custom action to submit selected records by Ajax

function Page_Load() {
$this->CustomActions["star"] = new
cListAction("star", "Add Star", IsLoggedIn(),
EW_ACTION_AJAX, EW_ACTION_MULTIPLE, "Add Star to
selected records?");
}
To process the action, you also need to write a handler with
Row_CustomAction server event (see below).
Note

Example 5
When Custom Templates (see Custom Templates(See 1.10.10)) is
used, they will be used for export to Word/Excel/PDF/Email (not
including PHPExcel and PHPWord) by default. You can however disable
it. The corresponding (boolean) page properties are:
ExportExcelCustom, ExportWordCustom, ExportPdfCustom and

ExportEmailCustom.
function Page_Load() {
$this->ExportExcelCustom = FALSE; // Disable using
Custom Templates for export to Excel
}
Page_Render

This event will be called before outputting HTML for the page. You can
use this event to make some last minute changes to the page before it
is outputted.

Page_Unload

This event will be called before closing database connection.

Page_DataRenderi This event will be called after the header.php is included. You can use
ng
this event to add content before the main table.
Example
Hide a field from the main table

function Page_DataRendering() {
$this->MyField->Visible = FALSE; // Hide a field
named "MyField"
}
Page_DataRendere This event will be called before the footer.php is included. You can use
d
this event to add content after the main table.

140

PHPMaker 12 Help
Page_Redirecting

This event will be called before redirecting to other page. Event


argument is the URL to be redirected to.

Message_Showing This event is fired before the message stored in the session variable is
shown. You can use this event to change the message which is passed
to the event as argument.
Form_CustomValid This event is fired after the normal form validation. You can use this
event to do your own custom validation. See description of
ate
Form_CustomValidate for Add/Copy page above.
ListOptions_Load

This event will be called before the main table is rendered. Use this
event to modify the non data columns of the main table (i.e. the links
and the checkbox for each record). You can modify these columns or
add your own columns using this event. You can get a column by
name using $this->ListOptions->Item["name"].
The following predefined names are reserved, do not use them for
your own columns. These names are case-sensitive and are in
lowercase except for the detail table names.
Note

checkbox
view
copy
delete
edit
detail_<DetailTable> - Detail table column
details - the Multiple Master/Detail column
preview - column for preview row of the Detail Preview
extension (for registered users) only
sequence - column for sequence number
button - column for button group or button dropdown

Example 1
Add a new column.

function ListOptions_Load() {
$item = &$this->ListOptions->Add("new");
$item->Header = "MyCaption"; // Set the column
header (for List page)
$item->OnLeft = TRUE; // Link on left
$item->MoveTo(0); // Move the column to the
specified index
}
If you have enabled Use buttons as links and/or Use button
dropdown for links (see PHP Settings(See 1.10.2)), note that the
feature will hide the list options and try to move hyperlinks to the
button group or button dropdown. If your Body property (see below)
is not hyperlink(s), it cannot be shown in the button group or button
dropdown, you should remove your list option from the button group
or button dropdown by adding, e.g.
Note

$item->ShowInButtonGroup = FALSE;
and/or

141

PHPMaker 12 Help
$item->ShowInDropDown = FALSE;
Example 2
Hide the "view" column.

function ListOptions_Load() {
$this->ListOptions->Items["view"]->Visible =
FALSE;
}
Example 3
Hide a detail table named "MyDetailTable" in Preview Row or Overlay
(requires Detail Preview extension(See 1.7) which is for registered
users only)

function ListOptions_Load() {
$this->DetailPages->Items["MyDetailTable"]>Visible = FALSE;
}
ListOptions_Rende This event will be called before a record is rendered. Use this event to
modify content of the non data columns for the record. To access field
red
object of the current row, you can use $this-><Field>-

><Property> (e.g. $this->HP->CurrentValue).


Do NOT try to show/hide a column dynamically by setting the
Visible property of the list option in this event. If the column is visible
in one row but invisible in another, the table will be malformed. If you
want to hide the content dynamically, you can set the Body property
as empty string.
Note

Example 1
Set the content of the new column dynamically based on a field value.

function ListOptions_Rendered() {
if ($this->MyField->CurrentValue == "xxx") {
$this->ListOptions->Items["new"]->Body =
"yyy";
} else {
$this->ListOptions->Items["new"]->Clear(); //
Set Body = ""
}
}
Example 2
Add a link to perform a custom action for the row by Ajax.

function ListOptions_Rendered() {
$this->ListOptions->Items["new"]->Body = "<a
href=\"#\" onclick=\"return ew_SubmitAction(event,
{action: 'star', method: 'ajax', msg: 'Add star?',
key: " . $this->KeyToJson() . "});\">Add Star</a>";
}
To process the action, you also need to write a handler with
Row_CustomAction server event (see below).
Note

142

PHPMaker 12 Help
Row_CustomAction If you have used Page_Load server event (see above) to add your
custom action to the List page, the page will show the checkbox
column for users to select records (similar to Multi-Update and MulitDelete). When user clicks the custom action link or button, the page
will post back to itself and this event will be fired (after Page_Load
and before Page_Render) for each selected row to process the
custom action.
Return TRUE to proceed to next record or return FALSE to abort
custom action.
Example
Update the status of the selected records, assuming the table has a
field named "Starred" for storing the status.

function Row_CustomAction($action, $row) {


if ($action == "star") { // Check action name
$rsnew = array("Starred" => "Y"); // Array of
field(s) to be updated, you can use ["Starred" => "Y",
...] if PHP >= 5.4
$result = $this->Update($rsnew); // Note: The
Update() method updates the current record only
if (!$result) { // Failure
$this->setFailureMessage("Failed to
update record, ID = " . $row["ID"]);
return FALSE; // Abort and rollback
} elseif ($this->SelectedIndex == $this>SelectedCount) { // Last row
$this->setSuccessMessage("All selected
records updated.");
}
return TRUE; // Success
}
}
If you cancel the action by returning FALSE in the event, you can
use the setFailureMessage() method to set your message. However,
note that if the event returns FALSE, subsequent rows will not be
processed and the database changes for previous rows will be rolled
back (if your database supports transaction). So if you just want to
cancel action for a row without affecting other rows, the event should
still return TRUE and use setSuccessMessage() method to set your
message.
Note

Page_Exporting

This event will be called before the page is exported. You can use this
event to add your additional code to the beginning of file to be
exported. Return FALSE to skip default export and use Row_Export
event (see below). Return TRUE to use default export and skip
Row_Export event. Check $this->Export for the export type (e.g.
"excel", "word"). The content of the export document is $this-

>ExportDoc->Text.
If Custom Templates is used (see Custom Templates(See
1.10.10)), this event may be overridden. You can disable using
Custom Templates for report, see example for Page_Load above.
Note

Example

143

PHPMaker 12 Help
Add a title to the export document and use custom export if export to
Excel

function Page_Exporting() {
if ($this->Export == "excel") {
$this->ExportDoc->Text = "<p>My Title</p>"; //
Add a title
return FALSE; // Return FALSE to skip default
export and use Row_Export event
}
return TRUE; // Return TRUE to use default export
and skip Row_Export event
}
Row_Export

If you return FALSE in Page_Exporting event (see above), this event


will be called when a row is exported for you to export in your own
code.
The argument ($rs) is an array of the record to be exported. The
values in $rs are unformatted database values. If you want to export
formatted values, use $this->MyField->ViewValue.
Notes

1. If you return TRUE in Page_Exporting event (see above),


default export will be used and this event will NOT be called.
2. If Custom Templates is used (see Custom Templates(See
1.10.10)), this event may be overridden. You can disable using
Custom Templates for report, see example for Page_Load
above.
Example
Export a record with custom code if export to Excel

function Row_Export($rs) {
if ($this->Export == "excel")
$this->ExportDoc->Text .= "<div>" . $this>MyField->ViewValue . "</div>"; // Build HTML with
field value: $rs["MyField"] or $this->MyField>ViewValue
}
Page_Exported

This event will be called after the page is exported. You can use this
event to add your additional code to the end of the file to be exported.
If Custom Templates is used (see Custom Templates(See
1.10.10)), this event may be overridden. You can disable using
Custom Templates for report, see example for Page_Load above.
Note

Example
Add a footer to the export document if export to Excel

function Page_Exported() {
if ($this->Export == "excel")
$this->ExportDoc->Text .= "my footer"; // Add
a footer
//die($this->ExportDoc->Text); // View the whole
export document for debugging
}

144

PHPMaker 12 Help
Table-Specific -> Multi-Update Page
Page_Load

This event will be called after connecting to the database.

Page_Render

This event will be called before outputting HTML for the page. You can
use this event to make some last minute changes to the page before it
is outputted.

Page_Unload

This event will be called before closing database connection.

Page_DataRenderi This event will be called after the header.php is included. You can use
ng
this event to add content at the top of page content.
Page_DataRendere This event will be called before the footer.php is included. You can use
d
this event to add content at the bottom of page content.
Page_Redirecting

This event will be called before redirecting to other page. Event


argument is the URL to be redirected to.
By default after updating records user is redirected back to the List
page. You can change that by using this event.

Message_Showing This event is fired before the message stored in the session variable is
shown. You can use this event to change the message which is passed
to the event as argument.
Form_CustomValid This event is fired after the normal form validation. You can use this
event to do your own custom validation. See description of
ate
Form_CustomValidate for Add/Copy page above.
Table-Specific -> Report Page
Page_Load

This event will be called after connecting to the database.

Page_Render

This event will be called before outputting HTML for the page. You can
use this event to make some last minute changes to the page before it
is outputted.

Page_Unload

This event will be called before closing database connection.

Page_DataRenderi This event will be called after the header.php is included. You can use
ng
this event to add content at the top of page content.
Page_DataRendere This event will be called before the footer.php is included. You can use
d
this event to add content at the bottom of page content.
Page_Redirecting

This event will be called before redirecting to other page. Event


argument is the URL to be redirected to.

Message_Showing This event is fired before the message stored in the session variable is
shown. You can use this event to change the message which is passed
to the event as argument.
Table-Specific -> Search Page
Page_Load

This event will be called after connecting to the database.

Page_Render

This event will be called before outputting HTML for the page. You can
use this event to make some last minute changes to the page before it

145

PHPMaker 12 Help
is outputted.
Page_Unload

This event will be called before closing database connection.

Page_DataRenderi This event will be called after the header.php is included. You can use
ng
this event to add content at the top of page content.
Page_DataRendere This event will be called before the footer.php is included. You can use
d
this event to add content at the bottom of page content.
Page_Redirecting

This event will be called before redirecting to other page. Event


argument is the URL to be redirected to.
By default user is redirected to the List page after the search criteria is
processed. You can change that by using this event.

Message_Showing This event is fired before the message stored in the session variable is
shown. You can use this event to change the message which is passed
to the event as argument.
Form_CustomValid This event is fired after the normal form validation. You can use this
event to do your own custom validation. See description of
ate
Form_CustomValidate for Add/Copy page above.
Table-Specific -> View Page
Page_Load

This event will be called after connecting to the database.

Page_Render

This event will be called before outputting HTML for the page. You can
use this event to make some last minute changes to the page before it
is outputted.

Page_Unload

This event will be called before closing database connection.

Page_DataRenderi This event will be called after the header.php is included. You can use
ng
this event to add content at the top of page content.
Page_DataRendere This event will be called before the footer.php is included. You can use
d
this event to add content at the bottom of page content.
Page_Redirecting

This event will be called before redirecting to other page. Event


argument is the URL to be redirected to.

Message_Showing This event is fired before the message stored in the session variable is
shown. You can use this event to change the message which is passed
to the event as argument.
Page_Exporting

This event will be called before the page is exported. You can use this
event to add your additional code to the beginning of file to be
exported. Return FALSE to skip default export and use Row_Export
event (see below). Return TRUE to use default export and skip
Row_Export event. Check $this->Export for the export type (e.g.
"excel", "word"). The content of the export document is $this-

>ExportDoc->Text.
If Custom Templates is used (see Custom Templates(See
1.10.10)), this event may be overridden. You can disable using
Custom Templates for report, see example for Page_Load above.
Note

146

PHPMaker 12 Help
Row_Export

If you return FALSE in Page_Exporting event (see above), this event


will be called when a row is exported for you to export in your own
code. The argument ($rs) is an array of the record to be exported.
The values are unformatted database values. If you want to export
formatted values, use $this->MyField->ViewValue.
If Custom Templates is used (see Custom Templates(See
1.10.10)), this event may be overridden. You can disable using
Custom Templates for report, see example for Page_Load above.
Note

Page_Exported

This event will be called after the page is exported. You can use this
event to add your additional code to the end of the file to be exported.
If Custom Templates is used (see Custom Templates(See
1.10.10)), this event may be overridden. You can disable using
Custom Templates for report, see example for Page_Load above.
Note

Table-Specific -> Preview Page


Page_Load

This event will be called after connecting to the database.

Page_Render

This event will be called before outputting HTML for the page. You can
use this event to make some last minute changes to the page before it
is outputted.

Page_Unload

This event will be called before closing database connection.

Page_DataRenderi This event will be called before the page content is outputted. You can
ng
use this event to add content at the top of page content.
Page_DataRendere This event will be called after the page content is outputted. You can
d
use this event to add content at the bottom of page content.
Page_Redirecting

This event will be called before redirecting to other page. Event


argument is the URL to be redirected to.

Message_Showing This event is fired before the message stored in the session variable is
shown. You can use this event to change the message which is passed
to the event as argument.
Other -> Default Page
Page_Load

This event will be called at the beginning of the page.

Page_Unload

This event will be called at the end of the page.

Page_Redirecting

This event will be called before redirecting to other page. Event


argument is the URL to be redirected to.
By default user is redirected to the default page (e.g. index.php) after
successful login. You can change that by using this event.

Other -> Login Page


Page_Load

This event will be called at the beginning of the page.

Page_Render

This event will be called before outputting HTML for the page. You can
use this event to make some last minute changes to the page before it

147

PHPMaker 12 Help
is outputted.
Page_Unload

This event will be called at the end of the page.

Page_DataRenderi This event will be called after the header.php is included. You can use
ng
this event to add content at the top of page content.
Page_DataRendere This event will be called before the footer.php is included. You can use
d
this event to add content at the bottom of page content.
Page_Redirecting

This event will be called before redirecting to other page. Event


argument is the URL to be redirected to.
By default user is redirected to the default page (e.g. index.php) after
successful login. You can change that by using this event.

Message_Showing This event is fired before the message stored in the session variable is
shown. You can use this event to change the message which is passed
to the event as argument.
User_LoggingIn

This event will be called before validating the username and password.

User_LoggedIn

This event will be called after the user login.

Form_CustomValid This event is fired after the normal form validation. You can use this
event to do your own custom validation. Inspect the HTML source of
ate
the page in your browser to view the form element names.
An argument $CustomError is passed to the event, you can add your
error message and return FALSE if the form values do not pass your
validation.
User_LoginError

This event will be called if the user fail to login.

Other -> Logout Page


Page_Load

This event will be called at the beginning of the page.

Page_Unload

This event will be called at the end of the page.

Page_Redirecting

This event will be called before redirecting to other page. Event


argument is the URL to be redirected to.
By default user is redirected to the default page (e.g. index.php) after
successful login. You can change that by using this event.

User_LoggingOut

This event will be called before user logout.

User_LoggedOut

This event will be called after user logout.

Other -> Registration Page


Page_Load

This event will be called at the beginning of the page.

Page_Render

This event will be called before outputting HTML for the page. You can
use this event to make some last minute changes to the page before it
is outputted.

Page_Unload

This event will be called at the end of the page.

148

PHPMaker 12 Help
Page_DataRenderi This event will be called after the header.php is included. You can use
ng
this event to add content at the top of page content.
Page_DataRendere This event will be called before the footer.php is included. You can use
d
this event to add content at the bottom of page content.
Page_Redirecting

This event will be called before redirecting to other page. Event


argument is the URL to be redirected to.
By default user is redirected to the default page (e.g. index.php) after
successful login. You can change that by using this event.

Email_Sending

This event is fired before the email notification is sent. You can
customize the email content using this event. Email_Sending event has
the following parameters:
Email - the email object instance which contain all the information
about the email to be sent. It is an instance of the cEmail class (see
below).
Args - an array which contains additional information. For registration
page, the new record in the data type of a recordset can be accessed
by $Args["rs"].
Return FALSE in the event if you want to cancel the email sending.

Message_Showing This event is fired before the message stored in the session variable is
shown. You can use this event to change the message which is passed
to the event as argument.
Form_CustomValid This event is fired after the normal form validation. You can use this
event to do your own custom validation. See description of
ate
Form_CustomValidate for Add/Copy page above.
User_Registered

This event is fired after successful registration of a new user.


Argument is a recordset of the new record in the user table.

User_Activated

This event is fired after activating a new user (if user activation is
required, see Security Settings(See 1.10.4)). Argument is a recordset
of the new record in the user table.

Other -> Change Password Page


Page_Load

This event will be called at the beginning of the page.

Page_Render

This event will be called before outputting HTML for the page. You can
use this event to make some last minute changes to the page before it
is outputted.

Page_Unload

This event will be called at the end of the page.

Page_DataRenderi This event will be called after the header.php is included. You can use
ng
this event to add content at the top of page content.
Page_DataRendere This event will be called before the footer.php is included. You can use
d
this event to add content at the bottom of page content.
Page_Redirecting

This event will be called before redirecting to other page. Event

149

PHPMaker 12 Help
argument is the URL to be redirected to.
By default user is redirected to the default page (e.g. index.php) after
successful login. You can change that by using this event.
Email_Sending

This event is fired before the email notification is sent. You can
customize the email content using this event. Email_Sending event has
the following parameters:
Email - the email object instance which contain all the information
about the email to be sent. It is an instance of the cEmail class (see
below).
Args - an array containing additional information. For Change
Password page, the old data of the records in the data type of
recordset can be accessed by $Args["rsold"], the new data of the
records in the data type of recordset can be accessed by
$Args["rsnew"].
Return FALSE in the event if you want to cancel the email sending.

Message_Showing This event is fired before the message stored in the session variable is
shown. You can use this event to change the message which is passed
to the event as argument.
Form_CustomValid This event is fired after the normal form validation. You can use this
event to do your own custom validation. Inspect the HTML source of
ate
the page in your browser to view the form element names.
An argument $CustomError is passed to the event, you can add your
error message and return FALSE if the form values do not pass your
validation.
Other -> Password Recovery Page
Page_Load

This event will be called at the beginning of the page.

Page_Render

This event will be called before outputting HTML for the page. You can
use this event to make some last minute changes to the page before it
is outputted.

Page_Unload

This event will be called at the end of the page.

Page_DataRenderi This event will be called after the header.php is included. You can use
ng
this event to add content at the top of page content.
Page_DataRendere This event will be called before the footer.php is included. You can use
d
this event to add content at the bottom of page content.
Page_Redirecting

This event will be called before redirecting to other page. Event


argument is the URL to be redirected to.
By default user is redirected to the login page after successful login.
You can change that by using this event.

Email_Sending

This event is fired before the email notification is sent. You can
customize the email content using this event. Email_Sending event has
the following parameters:

150

PHPMaker 12 Help
Email - the email object instance which contain all the information
about the email to be sent. It is an instance of the cEmail class (see
below).
Args - an array containing additional information. For Password
Recovery Page, the old data of the records in the data type of
recordset can be accessed by $Args["rs"].
Return FALSE in the event if you want to cancel the email sending.
Message_Showing This event is fired before the message stored in the session variable is
shown. You can use this event to change the message which is passed
to the event as argument.
Form_CustomValid This event is fired after the normal form validation. You can use this
event to do your own custom validation. Inspect the HTML source of
ate
the page in your browser to view the form element names.
An argument $CustomError is passed to the event, you can add your
error message and return FALSE if the form values do not pass your
validation.
User_RecoverPass This event is fired after the password is recovered. Argument is a
word
recordset of the user's record in the user table.

Client Scripts
In general, each page has two blocks of JavaScript:
Client Script - the first block of JavaScript to be included at the beginning of the page, you
can put your JavaScript variables and functions there. The View Tag (for display) and Edit
Tag (for input) of the fields supports Custom Attributes (See Field Setup(See 1.10.7)) so you
can add your own attributes to work with your own JavaScript included here.
Startup Script - the second block of JavaScript to be included at the end of the page, you
can put code here to "start up" your JavaScript.
In the following table, the <fieldname> in code represents the field variable name. In
general, if the field name is alphanumeric, field variable name is same as the field name.
Otherwise, spaces are replaced by underscores, and other non alphanumeric characters are
replaced by their hexadecimal string representation of their unicode value. If the variable is
a reserved word or starts with a digit, it will be prepended with an underscore. If in doubt,
always inspect HTML source in your browser to check the actual id, name, and
other attributes of the elements.
Note

Global -> Pages with header/footer


Client Script

The script will be placed in the header and therefore included in all
pages with header.
This event is NOT related to the No header/footer setting in
the Generate form (see Generate Settings(See 1.10.5)). Even if No
header/footer is enabled, this event will also be fired.
Note

Startup Script

The script will be placed in the footer and therefore included in all
pages with footer. This is a very useful event which is fired for all

151

PHPMaker 12 Help
pages with footer, you can almost do everything by changing the
document DOM of those pages.
This event is NOT related to the No header/footer setting in
the Generate form (see Generate Settings(See 1.10.5)). Even if No
header/footer is enabled, this event will also be fired.
Note

Example
Use jQuery to replace the logo

$("#ewHeaderRow").html('<img src="path/mylogo.png"
alt="xxx">');
Global Code

JavaScript code to be included in all pages with header. This may


contain your global constants, variables and functions.

Table-Specific -> Add/Copy page


Client Script

The script will be placed after the header. This may contain your
JavaScript variables and functions for the page. You can also use
this event to subscribe JavaScript events.
Example 1
Set Multi-Page (see Table Setup)(See 1.10.6) properties

CurrentForm.MultiPage.Set({
//LastPageSubmit: true, // Enable submit button
for the last page only
//HideDisabledButton: true, // Hide disabled
submit button
//HideInactivePages: true, // Hide inactive
pages
//HideTabs: true, // Hide all tabs
//ShowPagerBottom: true, // Show pager at
bottom
//PagerTemplate: '<nav><ul class="pager"><li
class="previous ewPrev"><a href="#"><span
class="icon-prev"></span> {Prev}</a></li><li
class="next ewNext"><a href="#">{Next} <span
class="icon-next"></span></a></li></ul></nav>' //
Pager template
LockTabs: true,// Set inactive tabs as disabled
ShowPagerTop: true // Show pager at top
});
Note: The argument of the Set() method is a JavaScript object, if
you modify above example, make sure that the syntax is correct
and that the last property value does not have a trailing comma.
Example 2
Subscribe the jQuery ajaxSend event before an Ajax request is sent
(e.g. "updateoption", "autosuggest", "autofill")

$(document).ajaxSend(function(event, jqxhr,
settings) {
var data = settings.data;
//console.log(data); // Uncomment to view data
in browser console

152

PHPMaker 12 Help
if (ew_Get("ajax", data) == "updateoption" &&
ew_Get("name", data) == "x_MyField") // Ajax
selection list
settings.data = data.replace("xxx", "yyy");
// Replace data with custom data
});
Example 3
Subscribe the "updatedone" event for Dynamic Selection Lists(See
1.15.5). The event fires after options of a child field is updated.

$(document).on("updatedone", function(e, args) {


//console.log(args); // Uncomment to view the
arguments in browser console
alert($(args.target).data("field") + " has been
updated.");
});
Example 4
Subscribe the "create.editor" event for the field named "MyField" to
change configuration of the DHTML editors. The event fires before
the DHTML editor is created.

$(document).on("create.editor", function(e, args) {


//console.log(args); // Uncomment to view the
arguments in browser console
if (args.name == "x_MyField")
args.settings.height = "300px"; // Refer to
DHTML editor doc for details about the settings
});
Example 5
Subscribe the "rendertemplate" event for Custom Templates(See
1.10.10). The event fires before a Custom Template is rendered.

$(document).on("rendertemplate", function(e, args)


{
//console.log(args); // Uncomment to view the
arguments in browser console
args.enabled = false; // Disable the Custom
Template
ew_ShowTemplates(args.template.substr(4)); //
Show the templates with the specified class name
});
Startup Script

The script will be placed before the footer. This is a very useful
event which you can almost do everything by changing the
document DOM.
PHPMaker provides a jQuery plugin .fields() for you to easily
get/set the form values in client side events such as Startup Script
and Form_CustomValidate (see below)

$row = $(this).fields(); // return an object of all


fields, each property is a jQuery object of the
input element(s) of a field
$field = $row["<fieldname>"]; // get jQuery object
of the input element(s) of a field
You can also get the jQuery object for a field directly,

153

PHPMaker 12 Help
$field = $(this).fields("<fieldname>"); // return
jQuery object of the input element(s) of a field
The jQuery object of the field is the jQuery object of the input
element of the field. (Note that if Edit Tag of the field is CHECKBOX
or RADIO, the jQuery object may contain more than one elements.)
For example, if the page is an Edit page and the field is named
"Field1" and it is a textbox, $(this).fields("Field1") is
equivalent to $("#x_Field1"). The advantages of using

.fields() plugin is that the returned jQuery object has the


following additional methods:
.value() get field value, .value(value) set the field
value.
.value([value])

This method is NOT the same as jQuery's


.val() method. This method takes other features
(e.g. DHTML editor, AutoSuggest) into
consideration.
Note

.visible() get the visibility of the field,


.visible(value) set the visibility of the field. The
value should be a boolean value.
Note

.visible([value])

1. This method shows/hides the row of the


field (i.e. the <tr> or the <div>), NOT
just the input element(s) of the field itself
in Add/Edit page.
2. The setter is NOT the same as jQuery's
.toggle() method.

Get/Set the readonly attribute of the input


element. The value should be a Boolean value.
.readonly(value)
Note For <input type="text"> and <textarea>
only.
Get/Set the disabled attribute of the input
element. The value should be a Boolean value.
.disabled(value)

A disabled control's value is NOT submitted


with the form. Use this carefully in Add/Edit page
or the field may be updated with an empty value.
Note

Get the jQuery object of the row (<tr> or <div>)


of the field.
Notes

.row()
1. If Add/Edit page, the row is the <tr> or
the <div> of the field.
2. If Grid page, the row is the <tr> of the
record.
.toNumber()

Get the input value as a JavaScript Number (by

154

PHPMaker 12 Help
default the input value is string).
.toDate()

Get the input value as a moment object (by


default the input value is string).

.toJsDate()

Get the input value as a JavaScript Date object


(by default the input value is string).

Example 1
Add onchange event to the field named "Field1" in Add/Edit page
to change other fields by jQuery plugin .fields()

$("input[name='x_Field1']").change(function() { //
Assume Field1 is a text input
if (this.value == "xxx") {
$(this).fields("FieldA").value("yyy"); //
Set value to FieldA
} else {
$(this).fields("FieldB").value("zzz"); //
Set value to FieldB
}
});
Example 2
Add onclick event to the field named "Field2" which uses
CHECKBOX as Edit Tag.

$("input[name='x_Field2[]']").click(function() { //
Field2 has multiple inputs (checkboxes) so they
should be selected by name
if (this.checked) { // If checked
// Do something
} else { // Not checked
// Do something else
}
});
Example 3
Add onchange event to the field named "Field1" in Grid-Add/Edit
page to change other fields by jQuery plugin .fields()

$("input[data-field='x_Field3']").change(function()
{ // Field1 has multiple inputs in Grid-Add/Edit so
they should be selected by data-field attribute
if (this.value == "xxx") {
$(this).fields("FieldA").value("yyy"); //
Set value to FieldA in the same row
} else {
$(this).fields("FieldB").value("zzz"); //
Set value to FieldB in the same row
}
});
Example 4

155

PHPMaker 12 Help
Toggle visibility of a page in Multi-Page (see Table Setup)(See
1.10.6)

$(function() {
CurrentForm.MultiPage.TogglePage(2, false); //
Hide the 2nd page
});
Form_CustomValidateThis event is fired after the normal form validation. You can use this
event to do your own custom validation. Note: This function is a
member of the JavaScript page class.
Return false if the form values do not pass your validation.
If you use this client side event, make sure you have enabled
client-side validation, see Validation in PHP Settings(See 1.10.2).
Note

The HTML form object can be accessed by the parameter fobj. You
can also use the jQuery plugin .fields() in this event.
Example 1
Make sure an integer field value meet a certain requirement

function(fobj) { // DO NOT CHANGE THIS LINE!


var $qty = $(this).fields("Qty"); // Get a
field as jQuery object by field name
if ($qty.toNumber() % 10 != 0) // Assume Qty is
a textbox
return this.OnError($qty, "Order quantity
must be multiples of 10."); // Return false if
invalid
return true; // Return true if valid
}
Example 2
Compare 2 date fields

function(fobj) { // DO NOT CHANGE THIS LINE!


var $row = $(this).fields(); // Get all fields
if ($row["Start"].toJsDate() >
$row["End"].toJsDate()) // Assume Start and End are
textboxes
return this.OnError($row["End"], "The End
Date must be later than the Start Date."); //
Return false if invalid
return true; // Return true if valid
}
Example 3
Manipulation of date fields

function(fobj) { // DO NOT CHANGE THIS LINE!


var $start = $(this).fields("Start"), $end =
$(this).fields("End"); // Get fields as jQuery
objects by field names
if ($start.toDate().add(7,
"days").isAfter($end.toDate())) // Assume Start and
End are textboxes
return this.OnError($end, "The End Date

156

PHPMaker 12 Help
must be at least 7 days after the Start Date."); //
Return false if invalid
return true; // Return true if valid
}
Table-Specific -> Delete Page
Client Script

The script will be placed after the header.

Startup Script

The script will be placed before the footer.

Table-Specific -> Edit Page


Client Script

The script will be placed after the header.

Startup Script

The script will be placed before the footer.

Form_CustomValidateThis event is fired after the normal form validation. You can use this
event to do your own custom validation. The form object can be
accessed by the parameter fobj. Return false if the form values do
not pass your validation.
Table-Specific -> List Page
Client Script

The script will be placed after the header.

Startup Script

The script will be placed before the footer.

Form_CustomValidateThis event is fired after the normal form validation. You can use this
event to do your own custom validation. Return false if the form
values do not pass your validation.
The form object can be accessed by the parameter fobj.
Note that the form element names are different in InlineAdd/Copy/Edit or Grid-Add/Edit mode of List page. They are named
as "x0_<fieldname>" in Inline-Add/Copy, as "x1_<fieldname>" in
Inline-Edit mode, and as "x1_<fieldname>", "x2_<fieldname>",
etc. in Grid-Add/Edit since there are multiple rows. Inspect the
elements in your browser to check the actual form element names.
Form_CustomValidate is fired for EVERY row in the grid. You
can also use the jQuery plugin .fields() (see above) to
manipulate the fields, but remember that the plugin return field(s)
of the CURRENT row only. If you need to access fields in other rows,
either use fobj.elements or jQuery with CSS selectors.
Note

Table-Specific -> Multi-Update Page


Client Script

The script will be placed after the header.

Startup Script

The script will be placed before the footer.

Form_CustomValidateThis event is fired after the normal form validation. You can use this
event to do your own custom validation. The form object can be
accessed by the parameter fobj. Return false if the form values do
not pass your validation.
Table-Specific -> Report Page

157

PHPMaker 12 Help
Client Script

The script will be placed after the header.

Startup Script

The script will be placed before the footer.

Table-Specific -> Search Page


Client Script

The script will be placed after the header.

Startup Script

The script will be placed before the footer.

Form_CustomValidateThis event is fired after the normal form validation. You can use this
event to do your own custom validation. The form object can be
accessed by the parameter fobj. Return false if the form values do
not pass your validation.
Table-Specific -> View Page
Client Script

The script will be placed after the header.

Startup Script

The script will be placed before the footer.

Other -> Login Page


Client Script

The script will be placed after the header.

Startup Script

The script will be placed before the footer.

Form_CustomValidateThis event is fired after the normal form validation. You can use this
event to do your own custom validation. The form object can be
accessed by the parameter fobj. Return false if the form values do
not pass your validation.
Other -> Registration Page
Client Script

The script will be placed after the header.

Startup Script

The script will be placed before the footer.

Form_CustomValidateThis event is fired after the normal form validation. You can use this
event to do your own custom validation. The form object can be
accessed by the parameter fobj. Return false if the form values do
not pass your validation.
Other -> Change Password Page
Client Script

The script will be placed after the header.

Startup Script

The script will be placed before the footer.

Form_CustomValidateThis event is fired after the normal form validation. You can use this
event to do your own custom validation. The form object can be
accessed by the parameter fobj. Return false if the form values do
not pass your validation.
Other -> Password Recovery Page
Client Script

The script will be placed after the header.

Startup Script

The script will be placed before the footer.

158

PHPMaker 12 Help
Form_CustomValidateThis event is fired after the normal form validation. You can use this
event to do your own custom validation. The form object can be
accessed by the parameter fobj. Return false if the form values do
not pass your validation.

It is recommended that you develop your server event and client scripts in the
generated script so you can edit and test it immediately. When you finish your custom
script, copy it to PHPMaker custom script editor and save it.
Note

Objects in PHPMaker Generated Code


The following objects are available in the generated code and you can use them in the
Server Events to add more power to the code. The most important objects are:
Page Object
The Page object is generated for most pages. You can access the object properties using the
-> notation (e.g. CurrentPage()->PageID). The page class inherits from the table class
generated for each table. The methods and properties of the page class varies with page, for
the complete list of methods and properties, please refer to the generated page class in the
generated scripts and the class "c<Table>" (e.g. cCars) in the generated file
"<Table>info.php".
Field Object
A <Field> object is generated for each field in a table. For example, the "Trademark" object
is generated for the "Trademark" field in the "Cars" table. You can access the object
properties using the -> notation (e.g. CurrentPage()->Trademark->CurrentValue).
For the complete list of methods and properties, please refer to the class "cField" in the
generated file "phpfn*.php".
Security Object
The Security object is used to store the current Advanced Security settings. Please refer to
the class "cAdvancedSecurity" in the generated file "phpfn*.php" for the complete list of
methods and properties.
Email Object
The Email object contains the required information of the email to be sent, the instance of
the object will be passed to the Email_Sending events as argument and let you modify the
email. Please refer to the class "cEmail" in the generated file "phpfn*.php" for the complete
list of methods and properties.
Menu Object
The Menu object contains all information of a menu, the instance of the menu will be passed
to the Menu_Rendering events as argument and let you work with the menu. Please refer to
the class "cMenu" in the generated file "ewshared*.php" for the complete list of methods
and properties.
MenuItem Object
The MenuItem object contains all information of the menu item, the instance of the menu
item will be passed to the MenuItem_Adding events as argument and let you work with the
menu item. Please refer to the class "cMenuItem" in the generated file "ewshared*.php" for
the complete list of methods and properties.
ListOpions Object
The ListOptions object contains all information of the non data columns in the main table of

159

PHPMaker 12 Help
the List page. Please refer to the class "cListOptions" in the generated file "phpfn*.php" for
the complete list of methods and properties.
ExportOpions Object
The ExportOptions object contains all information of the export links in the List page. It is
also an instance of the class "cListOptions". Please refer to the class "cListOptions" in the
generated file "phpfn*.php" for the complete list of methods and properties.
Language Object
The language Object lets you retrieve a phrase of the active language during runtime. The
phrase can be retrieved in the generated scripts using methods such as Phrase, TablePhrase
and FieldPhrase. Please refer to the class "cLanguage" in the generated file "ewshared*.php"
for the complete list of methods and properties.
Breadcrumb Object
The Breadcrumb object contains all information of the breadcrumb at the top of page. Please
refer to the class "cBreadcrumb" in the generated file "phpfn*.php" for the complete list of
methods and properties.
There are other objects in the generated code, please refer to the source code of the file
"phpfn*.php" and "ewshared*.php" in template or generated scripts.

Some Global Functions


The following are some useful global function available in the generated code for you to get
information easier in server events:
Notes

1. In the following table, the argument $dbname or $tablename or $fieldname is


the database/table/field variable name. It is case-sensitive. In general, if the name
is alphanumeric, the variable name is same as the name. Otherwise, spaces are
replaced by underscores, and other non alphanumeric characters are replaced by
their hexadecimal string representation of their unicode value. If the variable is a
reserved word, it will be prepended with an underscore. If you use databases with
the same name, check the database variable name in the Add Linked Table form,
see Linked Tables(See 1.10.9).
2. If MS Access, the $dbname is the file name of the database without the extension.
If Oracle, the $dbname is the schema name.
3. Argument in square brackets means that the argument is optional.
4. If $dbname is not specified, the database of the project is assumed. If $dbname is
specified, the specified database of Linked Tables is used.
Function

Description

Example

Conn([$dbname])

Get the global


connection
object.

$rs = Conn()>Execute("SELECT ...");


// execute a SELECT
statement and get
recordset object

If $dbname is
not specified, it
returns the
$rs = Conn("MyDbName")connection object >Execute("SELECT ...");
for the database // execute a SELECT
of the project. If statement and get
$dbname is
recordset object
specified, it

160

PHPMaker 12 Help
returns the
connection object
for the specified
database of a
Linked Table.

Security()

Get the global


security object

Language()

Language()Get the global


language object >setPhrase("AddLink",

if (Security()>CanEdit()) { // check
if current user has Edit
permission for the
current table (for use
with User Level Security
...your code...
}

"xxx"); // change the


wording for the "Add"
link
CurrentUserName()

Get current user $username =


CurrentUserName();
name.

CurrentUserID()

$userid =
For used with
User ID Security CurrentUserID();
(see Security
Settings(See
1.10.4)). Get
current User ID.

CurrentUserLevel()

$levelid =
For used with
CurrentUserLevel();
User Level
Security (see
Security
Settings(See
1.10.4)). Get
current user's
User Level ID
(integer). (Note:
NOT current
user's permission
as integer.)

CurrentUserInfo($fieldname)

$email =
For used with
Advanced
CurrentUserInfo("email")
Security (see
;
Security
Settings(See
1.10.4)). Get
current user's
info from the
user table. The
argument is the
field name in the

161

PHPMaker 12 Help
user table.

CurrentPageID()

Get current page if (CurrentPageID() ==


"add") {
ID. A page ID
...your code...
identifies the
}
page type, it can
be "list", "view",
"add", "edit",
"delete",
"search", etc.

CurrentPage()

Get current page $rowindex =


CurrentPage()->RowCnt;
object.

CurrentLanguageID()

Get current
language ID.

Page([$tablename])

Get page object $value =


of another table Page("MyMasterTable")in the page, e.g. >MyField->CurrentValue;
the page object
of the master
table or detail
table. If
$tablename is
not specified, it
returns

$langid =
CurrentLanguageID();

CurrentPage()
.

IsLoggedIn()

if (IsLoggedIn()) {
For used with
Advanced
...your code...
Security (see
}
Security
Settings(See
1.10.4)). Get the
login status of
the current user.

IsAdmin()

if (IsAdmin()) {
For used with
Advanced
...your code...
Security (see
}
Security
Settings(See
1.10.4)). Check
if the current
user is an
administrator.

ew_Execute($sql [,$dbname])

Execute UPDATE, ew_Execute("UPDATE


INSERT, or
MyTable SET...
DELETE
WHERE...");
statements.

ew_ExecuteRow($sql [,$dbname])

Set $row =
Executes the
ew_ExecuteRow("SELECT *
query, and
returns the first

162

PHPMaker 12 Help
FROM MyTable WHERE...");
row as a
dictionaru object.
ew_ExecuteScalar($sql
[,$dbname])

Executes the
query, and
returns the first
column of the
first row.

DbHelper([$dbname])

$db = DbHelper();
Get database
helper object of a
databse (also see
Custom Files(See
1.10.13)).

$value =
ew_ExecuteScalar("SELECT
MyField FROM MyTable
WHERE...");

There are many other useful functions in the generated code, please refer to the source code
of the file "phpfn*.php" and "ewshared*.php" in template or generated scripts.

1.10.10 Custom Templates

Custom Templates
By default fields are presented in tabular form, e.g. one field per row in
Add/Edit/Search/View page, or one record per row in List/Delete page. Custom Templates
enable you to re-arrange the fields in your own way.
Do not confuse Custom Template (which is a table level setting within a project) with
customizing the whole template zip file. If you want to customize the general layout of the
generated site or customize something for all tables and all projects, you should customize
the template zip file, see Customizing Template(See 1.14).
Note

How it Works
If a Custom Template is provided, PHPMaker splits the original code in many small client side
templates. A client side template is HTML code enclosed by <script type="text/html"> and
</script>. Since browsers do not know how to execute "text/html" scripts, they simply
ignore it. So it is possible to re-assemble HTML from the small client side templates by
JavaScript based on your provided Custom Template. In other words, it is simply rearrangement of existing HTML parts in browser.
During script generation, PHPMaker converts your Custom Template to a client side template
and outputs JavaScript to render the template. The client side template is rendered by
JsRender (see Third-Party Tools(See 1.7)) which is a third-party JavaScript template engine
optimized for high-performance pure string-based rendering. The generated scripts only use
its "template composition" feature to render HTML from other external templates, your
Custom Template can however make use of its other features if you need to. (Note that
JsRender is still in beta, if you use its features directly, be aware that there may be some
breaking changes in the future.)

163

PHPMaker 12 Help
What it Can Do (and Cannot Do)
Custom Templates let you customize the layout of the fields originally placed in the main
HTML table of the page, they cannot customize HTML outside those regions. The
customizable regions are highlighted as follows:

164

PHPMaker 12 Help

Custom Template Tags


To let you create your Custom Templates easily, PHPMaker supports the following Custom
Template Tags. Since JsRender supports tags enclosed by {{ and }} (double curly
brackets), in order to let you use them in your Custom Templates, PHPMaker Custom
Template Tags uses {{{ and }}} (triple curly brackets) to differentiate. Note that Custom
Template Tags will be converted to JsRender tags during script generation, they can only be
used in PHPMaker user interface, they cannot be used elsewhere such as template (zip file)
or generated scripts.
In the following table, field represents the field variable name. In general, if the field
name is alphanumeric, field variable name is same as the field name. Otherwise, spaces are
replaced by underscores, and other non alphanumeric characters are replaced by their
hexadecimal string representation of their unicode value. If the variable is a reserved word
or starts with a digit, it will be prepended with an underscore.

{{{field}}}

Field with or without caption and other values,


depending on where it is used:

List/Delete page
CustomTemplateHeader - field caption
(supports sorting)
CustomTemplateBody - field value only
CustomTemplateFooter - field aggregate value

165

PHPMaker 12 Help

Search page/Extended Search panel - field


caption + search operator + search value (+
search condition + search operator 2 + search
value 2)
Other pages - field caption + field value

{{{caption field}}}

Field caption

{{{header field}}}

Field header (caption with sort links)

{{{value field}}}}

Field value (or input) without caption.

{{{value2 field}}}}

Search value 2. For use with Search page or Extended


Search panel only.

{{{operator field}}}}

Search operator. For use with Search page or Extended


Search panel only.

{{{operator2 field}}}}

Search operator 2. For use with Search page or


Extended Search panel only.

{{{condition field}}}}

Search condition. For use with Search page or Extended


Search panel only.

{{{cell_attrs field}}}}

Cell attributes for the field in the current row (originally


for the <td> tag of the field). For use in List/Delete
page only.

{{{list_options}}} or
{{{list_options n}}}

List options with <td> tags. Each list option is enclosed


by "<td>" and "</td>". For use in List page only.
n is the "rowspan" attribute of the <td> tag and it is
optional. If not specified, default is 1.

{{{list_options_2}}}

List options with <span> tags. Each list option is


enclosed by "<span>" and "</span>". For use in
CustomTemplateBody (List Page) only.

{{{list_option xxx}}}

List options with name xxx. For use in


CustomTemplateBody (List Page) only. Possible
values of xxx are same as those used in server
events(See 1.10.9), i.e.

copy
delete
edit
checkbox
preview - for use with Preview extension (for
registered users) only, or
detail_<DetailTable> - NOT for use with
Preview extension (for registered users)

{{{page_n}}}...{{{/page_n}}}Multi-Page template tag for page n. The content inside


the tags is the Custom Template for page n.
For use with Multi-Page (see Table Setup(See
1.10.6)(See 1.10.7)) only. No need to use this tag if
Note

166

PHPMaker 12 Help
single page.

{{{row_attrs}}}

Current row attributes (originally for the <tr> tag of


the record) . For use in List/Delete page only.

{{{row_cnt}}}

Current row index (1-based). For use in List/Delete


page only.

{{{confirm_password}}}

Text input (with caption) for password confirmation. For


use in Registration Page only.

{{{value confirm_password}}}Text input (without caption) for password confirmation.


For use in Registration Page only.

How to Use
To enter your Custom Template for a table, follow the following steps:
1. Select the table in the database pane,
2. Select the Code tab (which contains Server Events, Client Scripts and Custom
Templates),
3. Scroll down the treeview or collapse the Server Events and Client Scripts node,
select a template node under Custom Templates,
4. Enter your Custom Template in the editor.
You can enter the first character of a field name and then press Ctrl + Space to
open the completion list of the editor and select a {{{field}}} tag.
Note

Then just generate and run your scripts in your browser as usual.

167

PHPMaker 12 Help
Examples
Example 1 - Custom Template in Add/Edit/Search/View page or Extended Search in List
page

{{{Trademark}}}&nbsp;{{{Model}}}<br>
{{{HP}}}&nbsp;{{{Liter}}}
If you want to have more control on the layout, use DIV and SPAN with CSS styles, e.g.

<div class="ewRow"><span class="ewCell">{{{Trademark}}}</span><span


class="ewCell">{{{Model}}}</span></div>
<div class="ewRow"><span class="ewCell">{{{HP}}}</span><span
class="ewCell">{{{Liter}}}</span></div>
or use a HTML table, e.g.

<table class="ewTable">
<tbody>
<tr><td>{{{Trademark}}}</td><td>{{{Model}}}</td></tr>
<tr><td>{{{HP}}}</td><td>{{{Liter}}}</td></tr>
</tbody>
</table>
Example 2 - Custom Template in Add/Edit/Search/View page (Multi-Page)

{{{page_1}}}
<div class="ewRow"><span class="ewCell">{{{Trademark}}}</span><span
class="ewCell">{{{Model}}}</span></div>
<div class="ewRow"><span class="ewCell">{{{HP}}}</span><span
class="ewCell">{{{Liter}}}</span></div>
{{{/page_1}}}
{{{page_2}}}
<div class="ewRow">{{{Description}}}</div>
{{{/page_2}}}
{{{page_3}}}
<div class="ewRow">{{{Picture}}}</div>
{{{/page_3}}}

Example 3 - Card view in List page using {{{list_options_2}}}


CustomTemplateHeader

<table class="ewTable">
<tbody>
CustomTemplateBody

<tr{{{row_attrs}}}>
<td>
<div class="ewRow">
<span class="ewCell"><b>{{{caption
Trademark}}}:</b>&nbsp;{{{Trademark}}}</span>

168

PHPMaker 12 Help
<span class="ewCell"><b>{{{caption
Model}}}:</b>&nbsp;{{{Model}}}</span>
</div>
<div class="ewRow">
<span class="ewCell"><b>{{{caption
HP}}}:</b>&nbsp;{{{HP}}}</span>
<span class="ewCell"><b>{{{caption
Liter}}}:</b>&nbsp;{{{Liter}}}</span>
</div>
<div class="ewRow">{{{list_options_2}}}</div>
</td>
</tr>
CustomTemplateFooter

</tbody>
</table>

Example 4 - Show each record in 2 rows in List page using {{{list_options n}}}
where n is the rowspan. Note: Do not confuse {{{list_options 2}}} with

{{{list_options_2}}}.
CustomTemplateHeader

<table cellspacing="0" class="ewTable ewTableSeparate">


<thead>
<tr class="ewTableHeader">
{{{list_options
2}}}<td>{{{Trademark}}}</td><td>{{{Model}}}</td>
</tr>
<tr class="ewTableHeader">
<td>{{{HP}}}</td><td>{{{Liter}}}</td>
</tr>
</thead>
<tbody>
CustomTemplateBody

<tr{{{row_attrs}}}>
{{{list_options 2}}}<td>{{{Trademark}}}</td><td>{{{Model}}}</td>
</tr>
<tr{{{row_attrs}}}>
<td>{{{HP}}}</td><td>{{{Liter}}}</td>
</tr>
CustomTemplateFooter

</tbody>
</table>

Important

1. Remember that Custom Template is rearrangement of existing some HTML


fragments in the page, all other code is still the same, the fields in the Custom
Template should be the same as the original script. The available fields are
same as the orignal script, if you try to include other fields in the table or from other

169

PHPMaker 12 Help
table by Custom Template, it will NOT work without writing your own code. In
Add/Copy/Edit page, if a field is missing, no field value is submitted but the
generated scripts contain code for the field, unwanted results may occur, for
example, if a field is missing in the Edit page, the field value in the table will be
cleared after editing. If Multi-Page (see Table Setup(See 1.10.6)) is enabled for the
page, the Custom Templates should include templates for all pages using
{{{page_n}}} and {{{/page_n}}}, and each field should be placed in the same
page as in the original script.
2. Custom Template is HTML, if you want to embed PHP code, you need to use <?php
and ?> to enclose your code, if you want to use JavaScript, you need to use
<script type="text/javascript"> and </script>.
3. DO NOT use $this in your PHP code. There is no $this in the context, you can
however use CurrentPage() to get the current page object.
4. Avoid using JavaScript in the template. If you need to use JavaScript, try to put your
JavaScripts in Client Scripts and Startup Scripts of the page (see Server Events and
Client Scripts(See 1.10.9)). If you have to use JavaScript in the template, DO NOT
using document.write() because the script will be extracted from the template
and be executed at the end of the template, you can however use a DIV with unique
id and write to its innerHTML.
5. In List page, CustomTemplateBody is the template for a record. Your Custom
Template needs NOT to be a HTML table, but if it is (see the example above), then
CustomTemplateHeader and CustomTemplateFooter must at least contains
<table><tbody> and </tbody></table> respectively, and you need to provide
the <tr> and <td> tags in these templates. If the table uses Aggregate values
(see Field Setup(See 1.10.7)), you should also include <tfoot> in your
CustomTemplateFooter. If you want to use the PreviewRow extension (for
registered users only), your Custom Template must be a HTML table because the
extensions works by inserting a preview row in the table, and in
CustomTemplateBody each <tr> row must contain the attribute datarowindex="{{{row_cnt}}}" or {{{row_attrs}}} as the extension needs the
row index for inserting a row below it. The row index attribute is also required for
alternating/selected/highlighted row colors. Basic sample code of
CustomTemplateHeader/Body/Footer can be found in Code Repository (below
the editor).
6. Before the Custom Template is applied, the jQuery event "rendertemplate" will be
fired, you can use Client Script of the page (see Server Events and Client
Scripts(See 1.10.9)) to subscribe this event and pass custom data to the Custom
Template or even disable it.
7. Custom Template does NOT support the following:
o Export to CSV/HTML/PHPExcel/PHPWord/XML (the data is exported in
original tabular format)
o Add Blank Row in Grid-Add/Edit
o Detail grid in Master/Detail-Add/Edit/View
8. Custom Template supports Printer-Friendly/Export to Excel/Word/Email. Note
that Export to Excel/Word works by letting Word/Excel to import the exported
HTML, so make sure your Custom Template is simple enough for Word/Excel to
import. As for Export to Email, the exported HTML will be rendered by email
clients. Different email clients render HTML email content differently, the result may
vary with email client. In general, keep your Custom Template simple and stupid for
export. You can even use PHP's if/elseif/else to output different Custom
Template according to the value of CurrentPage()->Export. Also, Custom
Template will override Page_Loading, Row_Export and Page_Exported server
events, you can however use Page_Load server event to disable using Custom
Template for export, see Server Events and Client Scripts(See 1.10.9).

170

PHPMaker 12 Help

1.10.11 Using Custom View


WARNING! Custom View expects simple SELECT statements only, they are NOT designed
to and cannot replace views provided by the database. PHPMaker supports creating database
view, you should always use database views whenever available. Views provided by
database allow you to use them more like regular tables. If you use MySQL 5, you should
ALWAYS use MySQL view.
A Custom View is basically a stored SELECT statement. Custom View allows you to
save your SELECT statements in a project as a virtual table. If your database, for example,
MySQL 4, does not support views, you'll find this feature useful.

Converting Custom View to Database View


Custom View expects a simple SELECT statement only. If you create a Custom View with a
SELECT statement with some complex clauses, or with an UNION statement instead of a
single SELECT statement, the sorting or searching may fail. In such cases you should change
the Custom View to database view. PHPMaker allows converting your Custom View to
database view provided that the database user have CREATE VIEW privilege.
After loading the database in PHPMaker, the database objects (tables, views, custom views
and reports) will be shown in the left pane (the database pane). To convert a Custom View
to database view, right click the Custom View in the database pane and select [Convert
Custom View to View]. Alternatively, you can select the Custom View first, then click
[Edit] in the main menu and then select [Convert Custom View to View]. After creating
the view, the existing Custom View and field settings will be moved to the new view. If your
project is connected to a development database, export the new views and recreate them on
your production database during deployment.
If under some circumstances you cannot change Custom View to database view (e.g. you
are still using MySQL 4.1) and you must use Custom View, you can try use a derived table
(supported since MySQL 4.1) in the format of SELECT * FROM (<Original SQL>) AS t as the
SQL of the Custom View. (Note for MySQL 4.1 users only: If you upgrade to MySQL 5 later,
you should convert your Custom Views to MySQL views. If you use the derived table
approach before, edit the Custom View, remove the derived table and use the original SQL
first, MySQL 5 still does not support subquery in the FROM clause when creating view.)

Creating Custom View


To create a custom view, right click the database pane and select [Add Custom View].
Alternatively, you can click [Edit] in the main menu and then select [Add Custom View].
The Custom View Setup window will show up:

171

PHPMaker 12 Help

PHPMaker will give the new Custom View a temporary name, CustomView<n>, where n is
an integer. If you want to change the name, enter a new name in the [Custom View
name] edit box in the main toolbar.
It is recommended that the built-in visual query builder be used to build your SQL. The
query builder interface is intuitive and fully supports drag-n-drop, in most cases you don't
need to type the table or field names.
On the left hand side, the available tables are displayed in the table pane. On the right hand
side, there are three tabs: [Builder], [SQL] and [Result]. (The [Result] tab will only be
visible after you execute the SQL.)

Builder
To build your SQL, drag your tables from the table pane on the left to the builder area and
check the required fields.
To create a link between two objects (i.e. join them) you should select the field by which
you want to link an object with another and drag it to the corresponding field of another
object. After you finish dragging, a line will appear between the linked fields. The join type
created by default is INNER JOIN, i.e. only matching records of both tables will be included
in resulting dataset. To define other types of joins you should right click the link and select
the Edit... item from the drop down menu or simply double-click it to open the Link
Properties dialog. This dialog allows you to define join type and other link properties.
The easiest way to add a field to the list of query output fields is to check the checkbox at
the left of field name in the Query Building Area. To include all the fields of an object you
should click the checkbox at the left of the asterisk item of an object.
Note

You should select your fields explicitly, not using the * symbol.

172

PHPMaker 12 Help
Another way is to select a field name from the drop-down list of the Expression column in
the Columns Pane. And the most common way is to write any valid expression to the
Expression column in the Columns Pane.
To remove a field from the list of query output fields you should uncheck the checkbox at
the left of field name in the Query Building Area or you may remove it by unchecking the
Output column checkbox. Such operations as removing lines from the Columns Pane or reordering output fields are available by right clicking on the left-most gray column via the
drop-down menu.
To define sorting of output query fields you should use the Sort Type and Sort Order
columns of the Columns Pane.
The Sort Type column allows you to specify how the fields will be sorted - in Ascending or
Descending order.
The Sort Order column allows you to setup the order in which fields will be sorted, if there
are more than one field to sort specified.
To cancel sorting by some field you should clear the Sort Type column for this field.
To define criteria for the expression listed in the Columns Pane you must use the Criteria
column.
Here you should write the criteria omitting the expression itself. For get the following criteria
in your query

WHERE (field >= 10) AND (field <= 20)


you should write

>= 10 AND <= 20


in the Criteria column.
You may specify several criteria for one expression using the Or... columns. These criteria
will be concatenated in the query with the OR operator.
To setup grouping by some of the fields and/or to define aggregate functions on grouped
rows you may use the Group by column.
You may select one of the following values for this column from the drop-down list:

"Expression" and "Where": These values are used when no grouping is specified.
The "Expression" value is set when this expression is used as output expression in
the SELECT clause and nothing else. The "Where" value is set automatically when
you define a criteria to this expression that results in including this expression to the
WHERE clause. Normally you shouldn't care about value of the Group By column
when you don't want to define grouping.

"Group by" and "Having": These values are similar to the previous two, but used
when you want to define grouping in your query. In this case you should set the
"Group by" value for all columns you want to group by. Specifying criteria for the
grouped columns will include these criteria in the HAVING clause. If you want to
include an expression ONLY in the HAVING clause you should set the "Having" value
in the Group By column for this expression.

Aggregate functions (Count, Sum, etc): By selecting one of these values you will
create an aggregate expression for the value indicated in the Expression column.

173

PHPMaker 12 Help

SQL
You can always click the [SQL] tab to check the SQL generated by the query builder, the
SQL editor is also syntax-highlighted to enhance the readability of the SQL.

The SQL tab is actually an SQL editor, you can type your SQL directly without using the
query builder here, or paste your SQL from elsewhere, or open a saved SQL script (*.sql)
from file.
Notes

1. If the SQL is not generated by the built-in query builder, there are chances that
query builder cannot parse the SQL and display it visually in the [Builder] tab.
However, this does not necessarily mean that the SQL is invalid, you can verify its
validity by executing it (see below) and check if it returns the data you want in the
[Result] tab. And you can create the Custom View directly by click the OK button
without switching to the [Builder] tab.
2. If you type your SQL directly, always use aliases (use "AS") for fields whenever
applicable. Otherwise, the alias will be assigned by the database and you will not be
able to refer to the field with a known and meaningful name.

Result
When you have finished your SQL, you can test the SQL by any one of the following ways:
(for "DIRECT" connection only)

Clicking the
[Execute] button in the toolbar
Pressing [F9] on your keyboard
Clicking [Query] in the menu and then [Execute]

174

PHPMaker 12 Help

The [Result] tab will become visible and display the result data. If the data is correct, the
Custom View setup is almost done.
Note: Executing the SQL is for testing the SQL only. The data displayed in the [Result] tab
will not show the memo fields and blob fields, they may be represented by "(MEMO)" and
"(BLOB)" only. This is not related to the data that will be displayed by the generated scripts.
Since a Custom View is based on an existing table, there is an option that the fields in the
Custom View use the same Field Setup(See 1.10.7) (Edit Tags, View Tags, etc.) as the
source table. If you want to copy field settings, check the checkbox [Copy field settings
from source table (when applicable)]; if not, uncheck it. Then you can press [OK] to
finish.
Note: "when applicable" means that if enabled, field settings will be copied from the
source table when a new Custom View is created, or when a new field is found after editing
a Custom View, and the field can be found from existing tables. (This is also why building a
SQL with the built-in query builder and not using * symbol are recommended, these ensure
that the SQL can be parsed and therefore the source table and source field can be found.)
When a Custom View is added, PHPMaker will load it and display it in the database pane and
Table Setup page under the [Custom Views] node. To view the SELECT statement of the
Custom View, right click the Custom View in database pane and select [Object
Properties]. Alternatively, you can select the Custom View first, then click [Project] in the
main menu and then select [Object Properties].
To edit a custom view, right click the Custom View in the database pane and select [Edit
Custom View]. Alternatively, you can select the Custom View first, then click [Edit] in the
main menu and then select [Edit Custom View].
When a Custom View is added or edited, PHPMaker will check the SQL. If the SQL is invalid,
the icon of the Custom View will have a cross on it like
, you can view the error in the
[Object Properties] window and then edit the Custom View to correct the SQL.

Important

175

PHPMaker 12 Help
1. After a Custom View is created, it works independently from the table(s) it based on.
Changing the structure of the source table(s) does not change the Custom View. If
you delete a field in the source table that is used by a Custom View, the Custom
View will fail. You should edit the Custom View to update the SELECT statement.
Also, a Custom View has its own field settings, changing field settings in the source
table does not change the field settings in related Custom Views.
2. During searching, sorting and grouping, PHPMaker generated codes need to change
the WHERE and/or ORDER BY clause of SQL for the list page dynamically. For
Custom Views, since there might be fields with aliases, it is necessary to use the
actual expressions of the aliases in order to ensure the result SQL works. For
example, if you have a field, "UnitPrice*12 AS TotalPrice" in your SQL, you cannot
sort using "ORDER BY TotalPrice", you need to use "ORDER BY UnitPrice*12".
Therefore, if your Custom View contain fields with aliases, it is important that the
SQL can be parsed correctly by PHPMaker. To make sure that, here are the recaps:
a. It is recommended that the built-in visual query builder be used to build
your SQL.
b. You should select your fields explicitly, not using the * symbol.
c. If you type your SQL directly, always use aliases (use "AS") for fields
whenever applicable.

1.10.12 Using Report


Report in PHPMaker can be used with any databases, the generated report page is a pure
PHP script, no server-side components is required.
A report is created from one existing Table, View or Custom View(See 1.10.11). If you need
to display data from more than one table or view, join them first using a view your database
(preferably) or using a Custom View(See 1.10.11) in PHPMaker.
After loading the database, the database objects (tables, views, custom views and reports)
will be shown in the left pane (the database pane). To create a report, right click the
database pane and select [Add Report]. Alternatively, you can click [Edit] in the main
menu and then select [Add Report].
The Report Setup window will show up:

176

PHPMaker 12 Help

The Report Setup window has 4 tabs. Go through these tabs one by one to setup your
report.

General
PHPMaker will give the new Report a temporary name, Report<n>, where n is an integer. If
you want to change the name, enter a new name in the [Report name] edit box. Then you
can select a table, or a view, or a Custom View form the [Table or View] combobox.
The field in the table will be displayed in the [Available fields] listbox, select fields you
want to display by moving them to the [Selected fields] listbox. It is recommended that
you select only the fields you required or the report page may be too wide to view without
scrolling.
This settings in this tab are mandatory.

Grouping Levels

177

PHPMaker 12 Help

You can optionally add up to 6 grouping levels in either ascending or descending order and
choose to show summary for each level. Select the grouping field for each level in the
comboboxes and click the button next to the comboboxes to choose the sorting order. To
enable summary, check [Show Summary] next to the grouping fields. When any of the
[Show Summary] fields is selected, the [Summary Values] tab will appear for you to
setup the summary values later. (See below)

Sort Order

178

PHPMaker 12 Help

You can optionally sort records by up to 6 fields, in either ascending or descending order.
Select the sorting fields in the comboboxes. Press the button to change the sort order.

Summary Values

179

PHPMaker 12 Help

If any of the [Show Summary] checkboxes is selected in the [Grouping Levels] tab, this
tab will become visible. You can optionally select aggregate values for each selected numeric
field. Available summary values are [Sum], [Avg], [Min] and [Max]. These summary
values will be shown at the end of the grouping levels with [Show Summary] enabled.
In this tab, you can also choose to show [Detail and Summary] or [Summary only] for
your report. If [Detail and Summary] is selected, records belonged to each grouping level
will be displayed under the grouping level title, then followed by the summary. [Detail and
Summary] is the default.
Finally, you can choose to [Show grand summary] for all records at the end of the report.
This options is enabled by default.

Press [OK] to finish setup. When a report is created, the field settings will be copied from
the source table. But from then on, the Report has its own field settings and is much like
other table in PHPMaker.
To edit a Report, right click the Report in the database pane and select [Edit Report].
Alternatively, you can select the Report first, then click [Edit] in the main menu and then
select [Edit Report]. Note that the source table of a report cannot be changed.

Important

1. After a report is created, a report works independently from the source table it
based on. Changing the structure of the source table does not change the report. If
you delete a field in the source table that is used by a report, the report will fail.
Similarly, if the report is based on a Custom View and you change the SELECT

180

PHPMaker 12 Help
statement of the Custom View, the report may fail if a field in the report is missing.
However, in the latter case, when a Custom View is edited, PHPMaker will check the
validity of the SQL. If the SQL fails, both the Custom View and reports that based on
the Custom View will be displayed with a cross in the icon, like
and
. Also, a
Report has its own field settings, changing field settings in the source table does not
change the field settings in related Reports.
2. Report does not support exporting to CSV, XML or PDF. You should export from the
source table.
3. Report does not include BLOB fields or fields that use file upload.
4. Report is not updatable or searchable, but it supports User ID and User Level. (See
Security(See 1.10.4))

Also See:
Custom View(See 1.10.11)
Security(See 1.10.4)

1.10.13 Custom Files

Custom Files
Custom Files enables you to add your own files to the project. Basically, a custom file is a
blank page with the layout of the project for you to add your own content so it will have a
consistent look and feel like other generated files.

How to Use
To create a Custom File, simply right click the database pane or click Edit in the main menu,
then select Add File, the following form will show:

The properties are as follows:

181

PHPMaker 12 Help
File name with extension.
Notes

File Name

1. Do not include path, you can enter Output


Folder later (see below).
2. Do not use characters not allowed as a file
name on your machine or on your server.
Alphanumerical characters only is
recommended.
3. If file name on your server is case-sensitive,
make sure you enter the file name in correct
lettercase. If you have selected Lowercase
in Generate tab (see Generate Settings(See
1.10.5)), the file name will be converted to
lowercase during generation.
4. The file name cannot be same as any table
(including view, Custom View and report)
name.

Caption

The caption of the page. This is similar to table


caption for a table and will be shown up in the menu
and in the Breadcrumbs of the page.

Includes common files

For .php file only. Specify whether to include the


common files (mainly header, menu and footer) in
the file so it will be consistent with other generated
scripts and able to use PHPMaker classes and
functions.
The output folder of the page. This must be relative
to application root of the project (see Generate
Settings(See 1.10.5)).
For example, if you have set up a website like:
Application root folder:
C:\Users\Administrator\Documents\mycompany.co
m

Output folder (relative to


application root)

Destination folder:
C:\Users\Administrator\Documents\mycompany.co
m\project1
and you want to generate your Custom File in the
destination folder, you should enter "project1/" (no
quotes).
Do NOT use parent path ".." or the file will be
generated outside the application root leading to
some unexpected results.
Note

After entering above properties, click OK button to save. The Custom File will show up in the
database pane under the Custom Files node:

182

PHPMaker 12 Help

To edit the Custom File properties, right click the Custom File in the database pane and
select Edit File.
To delete a Custom File, right click the Custom File in the database pane and select Delete
File.
To enter content for the file, select the Custom File in the database pane , then select the
Code tab (which contains Server Events, Client Scripts and Custom Templates) in the
right pane.
Scroll down the treeview or collapse the Server Events and Client Scripts node, select the
Custom Templates -> Table-Specific -> Custom File -> Content node, then you can
enter or paste your content in the editor:

183

PHPMaker 12 Help

Then just save your project generate and run your scripts in your browser as usual.

Although it is convenient to save your own files in the project, you should avoid
saving all the contents in the project or the project will become so large that the
performance of the UI will be affected. If the file content is large, you can put the content in
an external file and then include it in the Custom File. If the number of files is large, put the
minimum number of files in the project by Custom Files only, you can generate a blank
Custom File and duplicate it as containers for other files, then just add menu items to the
project by the Menu Editor for those external files.
Important

Examples
Example 1 - Include an external file instead of saving the page content in the project.

<?php include_once "MyPage.php"; // Includes an external file ?>

Example 2 - Add a Bootstrap Panel in the page to show some news.

<div class="panel panel-default">


<div class="panel-heading">Latest news</div>
<div class="panel-body">
<p>PHPMaker 12.0 is released</p>
</div>
</div>
The result:

184

PHPMaker 12 Help

Example 3 - Add multiple Bootstrap Panels in the page as a dashboard page. Use database
helper to execute SQLs and display data as HTML table.
To use the database helper, click Tools -> Advanced Settings (see Tools(See 1.13))
and enable Generate database helper and make sure you generate the file named
ewdbhelper<version>.php. The database helper is generated in the destination folder of the
project. If Includes common files is enabled, it is auto-loaded so there is no need to
explicitly include the script.
Note

<?php
$db =& DbHelper(); // Create instance of the database helper class
by DbHelper() or by name c<database>_db where <database> is database
name of the project
?>
<div class="panel panel-default">
<div class="panel-heading">Out of stock products</div>
<?php
$sql = "SELECT DISTINCT " .
"`categories`.`CategoryName` AS `CategoryName`," .
"`products`.`ProductName` AS `ProductName`," .
"`products`.`QuantityPerUnit` AS `QuantityPerUnit`" .
" FROM `categories` JOIN `products` ON (`categories`.`CategoryID`
= `products`.`CategoryID`)" .
" WHERE " .
"`products`.`UnitsInStock` <= 0";
echo $db->ExecuteHtml($sql, array("fieldcaption" => TRUE, "tablename"
=> array("products", "categories"))); // Execute a SQL and show as
HTML table
?>
</div>
<div class="panel panel-default">
<div class="panel-heading">Discontinued products</div>
<?php
$sql = "SELECT DISTINCT " .
"`categories`.`CategoryName` AS `CategoryName`," .
"`products`.`ProductName` AS `ProductName`," .
"`products`.`QuantityPerUnit` AS `QuantityPerUnit`," .
"`products`.`UnitsInStock` AS `UnitsInStock`" .
" FROM `categories` JOIN `products` ON (`categories`.`CategoryID`
= `products`.`CategoryID`)" .
" WHERE " .
"`products`.`Discontinued` = '1'";
echo $db->ExecuteHtml($sql, array("fieldcaption" => TRUE,
"tablename" => array("products", "categories"))); // Execute a SQL and
show as HTML table
?>
</div>
The result:

185

PHPMaker 12 Help

Note

Other than ExecuteHtml(), there are a few other useful methods in the database

helper class, refer to the source code of the file ewdb.php in the template for details. You
can also extend the database helper class (e.g. in server side Global Code, see Server
Events and Client Scripts(See 1.10.9)) and add your own methods.

1.10.14 Custom Fields

Custom Fields
The feature enables you to add your own Custom Fields to a table or view based on valid
SQL expressions. You can treat a Custom Field as a dummy field you added to the table and
the value of the Custom Field is evaluated from the specified SQL expression. Once added,
the field can be treated as a normal field and will appear in all generated pages. You can use

186

PHPMaker 12 Help
Server Events and Client Scripts to manipulate the Custom Field to display any content you
want.
Important Notes

1. The SQL expression must be a valid SQL expression for the database based on the
fields of the table/view. Otherwise, the Custom Field cannot be created.
2. If no SQL expression is entered, the Custom Field will be a blank field and you need
to write your own Server Events and/or Client Scripts to handle the value of the
Custom Field.
3. A Custom Field is not an actual field in the database table/view so input
value will NEVER be inserted/updated to the database.

How to Use
To add a Custom Field to a table/view, simply right click on any database table/view (in the
database pane) or click Edit in the main menu, then select Add Custom Field, the following
form will show:

The properties are as follows:


Field Name

Field name of the Custom Field. Note that the field name cannot be the same as
any fields/Custom Fields in the table/view

Caption

The caption of the Custom Field.

Expression A valid SQL Expression based on existing fields.


After entering above properties, click OK button to save. The Custom Field will show up in
the Fields panel of the specific table/view.

187

PHPMaker 12 Help

To edit the Custom Field, right click the Custom Field and select Edit Custom Field.
To delete the Custom Field, right click the Custom Field and select Delete Custom Field.

Testing SQL Expression


Custom Field is just a subquery in the SELECT statement for the table, e.g.

SELECT *, (SQL Expression) AS CustomField FROM MyTable


The highlighted part is the Custom Field, it is a subquery inserted to the normal SELECT
statement for the table. That is why the expression for the Custom Field must be a valid SQL
Expression. To make sure your SQL expression is valid, you can test your expression in your
database manager first by executing:

SELECT (SQL Expression) AS CustomField FROM MyTable


e.g. SELECT (`UnitPrice`*`Quantity`*(1-`Discount`)) AS SubTotal FROM

MyTable
If it works, your SQL expression is valid, then you can enter your SQL Expression and

CustomField to create your Custom Field and use them as Expression and Field Name in
the Add Custom Field dialog said above.

1.10.15 Linked Tables


Linked Tables enables you to add tables/views from other databases to the project.
Supported databases include MySQL, PostgresSQL, Microsoft Access, Microsoft SQL Server
and Oracle. Linked Tables can be used like regular tables in the project, for example, you
can generate Add/Edit/Delete/Update scripts for the Linked Tables, you can use a Linked
Table as lookup table, user table, master or detail table.
Note

Using Linked Tables in Custom Views or Views is not supported.

Adding a Linked Table


To add new Linked Tables, simply right click the database pane or click [Edit] in the main
menu, then select [Add Linked Table], the following form will show:

188

PHPMaker 12 Help

Click the [Add Database] button in the toolbar to add a database.


The Database Connection form is same as that in the Database tab, see Database Setup(See
1.10.1) for detail.

Enter your database connection information and click the [Connect] button to load the
database information. The list of tables/views of the selected database will be displayed.

189

PHPMaker 12 Help

The database combobox will show the database name, database variable name and the
database type. The database variable name is to be used for retrieving the database
information in server side code such as server events (see Server Events and Client
Scripts(See 1.10.9)). By default it is same as the database name if the database name
contains alphanumeric characters and underscore only. Otherwise, the database variable
name will be different, with non-alphanumeric characters replaced. Besides, the database
name of a Linked Table can be same as the main database or database of other Linked
Tables. If database names are the same, an index will be appended to the database variable
name. If your project uses databases with the same name and you need to write server side
code, make sure you check the variable name here.
Note

Select the tables/views you need and click [OK]. The selected tables/views will be added to
the project as a Linked Table and will appear under the [Linked Tables] node of the database
pane. You can then manipulate the Linked Table as a regular table/view.

Deleting a Linked Table


To remove a Linked Table from the project, right click the Linked Table in the database
pane, and click Delete Linked Table. Click "Yes" to confirm deletion.

190

PHPMaker 12 Help

Note that if the database related with the Linked Table being deleted no longer has any
other Linked Tables associated, you may want to remove this database from the project as
well.
To do that, right click the database pane or click [Edit] in the main menu, then select [Add
Linked Table]

Select the database you want to remove from the dropdown selection, and click the
[Remove Database] button. Click "OK" to confirm deletion.

Synchronizing with Database of Linked Tables


If you are adding Linked Tables and you have altered the database of the Linked Tables, you
may want to synchronize the table list with the database so you can choose the new or
renamed tables. Or if you have changed some connection information of the database such
as the username or password, you may also want to update it.

191

PHPMaker 12 Help
To do that, right click the database pane or click [Edit] in the main menu, then select [Add
Linked Table], select the database and click the [Synchronize Database] button.

The connection information will be displayed again.

Change the connection information if necessary and then press the [Synchronize] button.

192

PHPMaker 12 Help
If you create a Linked Table and then rename the table in your database, the Linked
Table will fail, synchronizing with the database will NOT fix it since if a table is a renamed
table cannot be determined. You need to delete the old Linked Table and create a new one.
Note

1.10.16 Multi-Language Project

Multi-Language Project
Important

1. Multi-Language project must use utf-8 for everything. The charset of the
project must be "utf-8".
2. The data in your database must be stored in unicode, otherwise your data will
not be displayed properly.
3. If you have to customize the template and put unicode characters directly in the
template instead of using language file, always use utf-8 encoding and enable the
Advanced Setting UTF-8 output files (see Customizing Template(See 1.14) and
Tools(See 1.13)).
4. Only the English language file is provided by our products, you'll need to prepare the
language files for other languages yourself. You may also check our website and see
if there are any user submitted language files. If you want to share your language
files with others (without any conditions), you can submit your language file to us
too.

Making Language Files


Language files are placed in the subfolder "languages" under the installed folder. The files
are used for all templates.
To translate a language, duplicate the shipped english.xml and rename it. It is
recommended that the file name should contain alphanumeric characters (and underscore)
and in lowercase only.
1. Open the new XML file with any text or XML editor, you'll see the root node:

<ew-language date="2015/07/13" version="12.0.0" id="en"


name="English" desc="English" author="e.World Technology Ltd.">
You must change at least the id, name and desc attributes.
The id is an identifier for identifying the language in generated scripts, it must be
unique. It is recommended that you use the following values as the language IDs.
Language

Value Language

Value Language

Value

Arabic

ar

German (Austria)

de-AT Portuguese

pt

Bengali

bn

German
(Switzerland)

de-CH

Bulgarian

bg
Greek

el

Portuguese (Brazil)

pt-BR

Portuguese (Portugal) pt-PT

193

PHPMaker 12 Help
Catalan

ca

Hebrew

iw

Romanian

ro

Chinese
(Simplified)

zh-CN

Hindi

hi

Russian

ru

Chinese
(Traditional)

zhTW

Hungarain

hu

Serbian

sr

Indonesian

id

Slovak

sk

Croatian

hr

Italian

it

Slovenian

sl

Czech

cs

Japanese

ja

Spanish

es

Danish

da

Kannada

kn

Spanish (Latin
America)

es419

Dutch

nl

Korean

ko
Swedish

sv

English (UK)

en-GB Latvian

Tamil

ta

English (US)

en

Lithuanian

lt
Telugu

te

Estonian

et

Malay

ms
Thai

th

Filipino

fil

Malayalam

ml
Turkish

tr

Finnish

fi

Marathi

mr
Ukrainian

uk

French

fr

Norwegian

no
Urdu

ur

Persian

fa
Vietnamese

vi

French (Canadian) fr-CA


German

de

Gujarati

gu

lv

Polish

pl

The name is for displaying the language name in the user interface (which does not
support unicode), it should contain alphanumeric characters, underscore and spaces
only.
The desc is for displaying the language name in generated scripts, it can be in the
encoding of the XML file.
For example, if you want to make language file for Traditional Chinese, you may
rename the file as chinese.xml and modify the node as:

<ew-language date="2015/07/13" version="12.0.0" id="zh-TW"


name="Traditional Chinese" desc="" author="e.World
Technology Ltd.">
2. The language file contains a <locale> node. If you use Multi-Language, you must
customize the locale settings for each language. Either enter the locale string for the
language OR set use_system_locale to "0" to disable system locale and customize
the other locale settings. For example, you may want to change the decimal point as
"," and thousand separator as ".":

<locale>
<phrase id="locale" value=""/><!-- *** system locale for this
language -->

194

PHPMaker 12 Help
<phrase id="use_system_locale" value="0"/><!-- *** change to "0"
to disable system locale and use the following settings *** -->
<phrase id="decimal_point" value=","/>
<phrase id="thousands_sep" value="."/>
<phrase id="mon_decimal_point" value="."/>
<phrase id="mon_thousands_sep" value=","/>
<phrase id="currency_symbol" value="$"/>
<phrase id="positive_sign" value=""/>
<phrase id="negative_sign" value="-"/>
<phrase id="frac_digits" value="2"/>
<phrase id="p_cs_precedes" value="1"/>
<phrase id="p_sep_by_space" value="0"/>
<phrase id="n_cs_precedes" value="1"/>
<phrase id="n_sep_by_space" value="0"/>
<phrase id="p_sign_posn" value="3"/>
<phrase id="n_sign_posn" value="3"/>
<phrase id="time_zone" value="US/Pacific"/><!-- *** used for
multi-language site only *** -->
</locale>
If use_system_locale is set to "1", only the locale setting will be used. If
use_system_locale is set to "0", the locale setting will be ignored and other
settings (i.e. decimal_point, thousands_sep, etc.) will be used.
Note

3. You can edit or even add your own phrases. Just open the language file with any
text or XML editor, edit/add your <phrase> nodes. Make sure you provide an unique
id to each phrase. The id must be alphanumerical only.
The phrases are not limited to text, you can also use HTML, e.g.

<phrase id="FieldRequiredIndicator" value="&lt;span


class=&quot;ewRequired&quot;&gt;&amp;nbsp;*&lt;/span&gt;"/>
If you want to use an image instead of text for a phrase, you can use the
"imageurl", "imagewidth" and "imageheight" attributes, e.g.

<phrase id="UnmatchedValue" value="Value does not exist"


imageurl="{_images}/warn.gif" imagewidth="16" imageheight="15"/>
where {_images} is the image folder defined in control.xml, by default it is
"phpimages", you should place your own images in the generated image subfolder.
Alternatively, you can put your images in the "images" subfolder of the template.
4. Language file is an XML file, when you edit the file, make sure that you keep it wellformed. If you use HTML tags or special characters in the attributes of the
XML tags, you need to use entity references. For example, to insert the >
symbol, you need to use &lt;. Make sure your characters are supported by the
encoding of the XML file specified in the processing instruction node (the first line).
You can load the file in your browser to check if the file is well-formed, if it is, the
browsers should be able to load and display it without any errors.
DO NOT use old language files from previous versions directly or the new phrases will
be missing. You should compare the English version of the language files from old and new
version and then add the new phrases to your new language file.
Note:

Selecting Language Files for Project

195

PHPMaker 12 Help
Click [Tools] -> [Languages] to select the languages you want to use in the project. If
more than one language is selected, a combobox will appear on the top of the generated
scripts for user to select language.

Enabling Multi-Language and Selecting Default Language


If you want to use multi-language project, make sure you have enabled Multi-Language in
the [PHP]->[General] tab (see PHP Settings(See 1.10.2)).
Then, select a Default Language in the [PHP]->[General] tab (see PHP Settings(See
1.10.2)).

196

PHPMaker 12 Help

Multi-Language Property Editor


If you use single language, you do NOT need to use this editor, just enter your phrases
in the general user interface. Only use this editor if you use Multi-Language.
Note

Some text properties support Multi-Language. This editor allows you to enter your
property values for each language. Supported properties are:

Table/Field Captions
Menu Text
Site Title and Footer Text
Table Page Names
Field Edit Tag Title
Field Error Message
Field Image Tag Alt
Field User Values

To edit these properties, click [Tools] -> [Multi-Language Property Editor] to open the
editor. Alternatively, you can also click the small button next to above properties in the user
interface to open.

Select a property in the Property pane on the left to edit, then enter your properties in
unicode. For example, you can copy and paste from Word.
The editor supports import/export of the phrases (of the mutli-language properties only, not
including the phrases in the language files):

197

PHPMaker 12 Help
Click the export button to export the phrases to a XML file so you can edit the file with text
or XML editor or share the file with other project. Click thie import button to choose the XML
file that you want to import so you can quicky use edited phrases or easily reuse other
project's XML file.
Previously saved properties are displayed in bold font. Once you use this editor to save
your unicode text, the saved unicode property values will always be used prior to the original
property values (in the general user interface) . The original property value will only be used
if unicode property value of the language cannot be found. If you want to edit the property,
always go back to this editor. After editing and saving unicode properties, remember
to re-generate the languages file and upload them again.
Note

Sending Email in Multi-Language


There is a subfolder named "html" inside the template archive (e.g. phpv120.zip) containing
the following HTML email templates:

changepwd.html
forgotpwd.html
notify.html
register.html
resetpwd.html

The content of these files are in English. To make email templates in other langauges, copy
the files and rename the files and translate the content to the your languages. The files must
be renamed as <original_file_name>_<language_id>.html. For example, the file nofify.html
should be renamed as notify_zh-TW.html if the file is to be translated into traditional
Chinese.
Remember to put the translated files back into the "html" subfolder of the template archive.
If translated files not found in the "html" subfolder of the template archive and hence
translated files not copied to the generated "phphtml" subfolder, the default English version
will be used.
Note

Using Server Events


If you prefer to customize the language phrases by code, you can use the Language_Load
server event. However, note that the Language_Load event cannot change the email
templates, if you want to change the email content by server event, use Email_Sending
server event to customize the Content property of the Email object. You can use the global
function CurrentLanguageID() to get the current language ID and write your code
accordingly. See Server Events and Client Scripts(See 1.10.9) for more details.

1.11 Application Root


Note that upload folders and audit trail folder are relative to application root. This enables
the user to put the uploaded files and the audit trail log files in folder outside of the script
folder. (In older versions, the file upload folder is relative to the script, it was supposed to be
a subfolder under the script.)
Where is the application root? PHPMaker scripts looks for the application root in the following
sequence:

198

PHPMaker 12 Help

1. Root Relative Path


Root Relative Path is the path relative to destination folder. The destination folder is the
folder where the generated scripts reside.
When you generate scripts, you must specify the [Application root folder] and the
[Destination folder] correctly based on your folder structure. The relative folder structure
on your local computer must be the same as that on your production server.
For example, if you put the generated scripts in a subfolder:

In this case, the Root Relative Path is therefore the parent folder of the script, i.e. "..". The
scripts will use this relative path to find the application root.
It is recomended that you set the [Application root folder] to the root folder of your
Website where is accessed by http://www.mycompany.com/ so you can specify your upload
folder and audit trail folder straightforwardly using the Website root as a starting point. For
example, if you specify "upload/" as upload path, since it is relative to application root, the
upload folder will be accessible by http://www.mycompany.com/upload/.
On your testing server, you may work with multiple projects and test your projects one
folder level lower at http://localhost/<projectname>/ (cf. http://<projectname>/). In this
case you should set the [Application root folder] in each project as the root folder of the
project (the folder that is accessed by http://localhost/<projectname>/). After uploading to
the production server, the site may be then accessed by http://www.mycompany.com/ (cf.

199

PHPMaker 12 Help
http://localhost/<projectname>/), but as long as the relative location of the two folders
(Application Root folder and the script folder) are the same, the scripts will still work
properly.

2. Document root
If Root Relative Path is empty, the script checks the following variables:
$_SERVER["APPL_PHYSICAL_PATH"] (for Windows) or $_SERVER["DOCUMENT_ROOT"]
or $_ENV["DOCUMENT_ROOT"] (for Linux).
When you generate scripts, you still need to specify the [Application root folder] and the
[Destination folder] based on your folder structure so that the relative location of the two
folders is correct.

3. Script Path
If both Root Relative Path and Document Root are empty, the script will use the path of the
current script.

4. Custom Path
The above three approaches should handle most cases. If in some special cases they don't
return the path you want, you can modify the function ew_AppRoot() in phpfn*.php. You can
simply customize the template and specify your real server path directly. For example,
Windows:

function ew_AppRoot() {
return 'C:\Inetpub\wwwroot\MyWebRoot\'; // replace with your real
server path directly, include the trailing path delimiter
}
Linux/Unix:

function ew_AppRoot() {
return '/home/username/public_html/'; // replace with your real
server path directly, include the trailing path delimiter
}
Remember that you must also check the value of the constant EW_ROOT_RELATIVE_PATH,
make sure it correctly points to your application folder relative to the script folder. Using
above example, you specify that the application root is "C:\Inetpub\wwwroot\MyWebRoot",
if your scripts are placed in "C:\Inetpub\wwwroot\MyWebRoot\MyScripts\", then
EW_ROOT_RELATIVE_PATH should be "..".
TIP: You can call the PHP function phpinfo() (i.e. <?php phpinfo(); ?>) to view your
server information, including the server paths. Alternatively, in the generated scripts (that
includes phpfn<version>.php), you can call the PHPMaker function ew_WritePaths() (i.e.
<?php echo ew_WritePaths(); ?>) to view the path settings in your project.

200

PHPMaker 12 Help

1.12 Project File


A project file is an XML file which stores all settings of a particular project. You should save a
project file for each site you generate and back it up. You will NOT be able to create a
project file backwardly from the generated scripts later.
A project file is an XML file, like other XML document, it is human-legible. You should be able
to open a project file in any text editor and view the content. Each object (e.g. database,
table, field, etc) is represented by an XML node in the project file. The object properties are
saved as attributes of the node.
A project file is in utf-8 encoding, your text editor needs to support utf-8. Most text editors
support utf-8 nowadays. You can simply use Notepad if you do not have other text editors.
With basic understanding of XML, you can change the settings manually. However, If you
modify a project file, make sure your keep it well-formed. To check if the file is well-formed,
you can change the file extension to .xml and open it with Internet Explorer or Firefox. If the
file can be loaded and displayed properly in the browser, it is well-formed.

Auto Backup
PHPMaker supports auto-backup. When you save a project, the old version will be saved to
the subfolder <Documents folder>\<product name>\Backup folder first, you can recover
older versions of your project from the backup folder in case of corrupted projects or other
accidental losses. Note that only the latest 10 versions will be kept, older versions will be
deleted.
The Documents folder is your personal folder in which you can store your personal
files. For example, in Windows Vista (or later), the folder is C:\Users\<user
Name>\Documents.
Note

Project Name
Each project has a project name. By default the file name (without extension) of the project
file is used as project name. Before you name your project file when saving it for the first
time, a temporary name, Project<n>, where n is a number, is used. The project name is an
important property, it is used in the generated codes to identify your project.
Note

It is recommended that only alphanumerical characters is used in project name.

If you need to change the project name, use Advanced Settings(See 1.13).

Project ID
Each project has a project ID which is a GUID (globally unique identifier). The value of a
GUID is represented as a 32-character hexadecimal string, such as {095F6728-DF53-4763A372-D8F2EAC959F2}. It is used to identify the project and the scripts generated by it.
Each script generated by the project has the project ID. An XML file named <GUID>.xml is
also generated for each project in the subfolder named by the project name under the
application root(See 1.11). The XML file contains some project information and is used to
share with other projects (e.g. PHP Report Maker project) with the same project name. So

201

PHPMaker 12 Help
do not reveal the project ID to public and do not change the project ID unless absolutley
necessary. If you really need to, use Advanced Settings(See 1.13).
If you use Dynamic User Level (see Advanced Security(See 1.10.4)), the project ID is also
used in the User Level Permission table as a prefix of the table name so that the table
names from different projects will not clash.

Save As vs. Save A Copy


If you want to create a new project based on an existing project, use [Save As...] under
the [Project] menu. If [Save As...] is used, the project name and project ID are
changed in the new file. The new file is NOT the same project anymore.
If you want to create a backup copy or another version of an existing project, you should
use [Save a Copy...] to save the file with another name. If [Save a Copy...] is used, the
project name and project ID are NOT changed. The project name may not be same as
the file name anymore. However, with the same project name and project ID, scripts
generated from these project files will still work like they are generated from the same
project file.

Also See:
Template Object Properties(See 1.14.3)

1.13 Tools

Tools
Click [Tools] in the main menu bar to access the following useful tools available in
PHPMaker.
Synchronization
Extensions
Advanced Settings
Copy Table Settings
Copy Field Settings
Sort Tables Alphabetically
Languages
Multi-Language Property Editor
Delete Template Cache
Menu Editor

Synchronization
During the course of project development, it is common that you have altered your database
schema. To save the effort of doing the customization from scratch again, PHPMaker

202

PHPMaker 12 Help
provides you with the ability to synchronize your project data with the database. The
synchronization process can be invoked in the following situations:

1. When working in PHPMaker


Simply click [Tools]->[Synchronize] or click the button on the toolbar to perform the
synchronization. PHPMaker will check automatically to see if the database schema has been
altered. If there are changes, you will be prompted whether or not to proceed with the
synchronization.
2. When opening a project file
When open a project file, PHPMaker will automatically check the database to see if the
schema has been altered. You will be prompted to keep or update to the new schema.
If the database contains a large number of tables/fields, this auto-synchronization
feature may make reloading a project file slow. In that case you can disable this feature by
unchecking [Tool]->[Auto Synchronize].
Note

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 it), you'll see the [Advanced] tab after
selecting the extension. Click the [Advanced] to configure advanced settings for the
extension.

203

PHPMaker 12 Help

Advanced Settings
Advanced Settings are some advanced general settings for PHPMaker, or some rarely
changed settings for the project, or custom defined settings for use during code generation.
Click [Tools] -> [Advanced Settings] to change these settings:

General

General settings for PHPMaker (for all projects)

Auto-Update values

The comma separated PHP function names for


the Auto-Update feature (see Field
Setup(See 1.10.7))
You can add your own functions by putting
your functions in the server side Global Code
section (see Server Events and Client
Scripts(See 1.10.9)) and then add your
function name here. The function name must
follow the standard rules for naming variables
in PHP.

Custom validation functions

The comma separated function names for the


Validate feature (see Field Setup(See
1.10.7))
You can add your own PHP/JavaScript
functions for custom server/client-side
validation. The function name is used for both
PHP and JavaScript, so it must be a valid

204

PHPMaker 12 Help
function name for both languages. You can put
your server-side and client-side validation
function in the Global Code (see Server
Events and Client Scripts(See 1.10.9)) section
of server-side and client-side respectively.
Script engine timeout (milliseconds)

The Windows Script engine timeout period.


PHPMaker uses Windows Script to generate
scripts dynamically, if you have a lot of tables
or fields, the script engine may time out during
generating a file and prompt you to cancel
execution or continue. To avoid this problem,
you can increase this timeout setting. For
example, you can increase 60000 ms (one
minute) at a time.

UTF-8 output files

If enabled, the output file is in utf-8 encoding.


Otherwise, it is ASCII by default.
The template files and output files are in ASCII
encoding by default. Since the phrases are
separated into XML language files in utf-8
encoding, ASCII encoding will suit most cases
as the scripts contain code only. When you
customize a template, it is recommended you
use the language file also. If you have to put
unicode characters directly in the template
files, you must always use utf-8 and save the
file in utf-8 encoding with the byte order mark
(EF BB BF), and enable this setting to make
the code generator output files in utf-8
encoding.

IIS Express (iisexpress.exe) path

The installed path of iisexpress.exe. For use


with Browse after generation and IIS
Express as Testing web server, read
Generate Settings(See 1.10.5).
PHPMaker will try to find automatically where
iisexpress.exe is installed. If no found, enter
your path here.

IIS Express port

The port to be used by IIS Express. For use


with Browse after generation and IIS
Express as Testing web server, read
Generate Settings(See 1.10.5).
PHPMaker will try to find a free port
automatically. If you want to specific one
explicitly, enter it here.

PHP CGI (php-cgi.exe) path

The installed path of php-cgi.exe. For use with


Browse after generation and IIS Express
as Testing web server, read Generate
Settings(See 1.10.5).

205

PHPMaker 12 Help
IIS Express uses php-cgi.exe to run the testing
site, make sure you have included php-cgi.exe
when you install PHP on your PC. If not,
download the zip file from php.net and put the
php-cgi.exe in your installation folder for PHP
(usually <Program Files>\PHP).
PHPMaker will try to find automatically where
php-cgi.exe is installed. If not found, enter
your path here.
Format project file

Format and indent project file so that it is


more readable

Project

Settings for the current project only

Project name

Project name. See Project File(See 1.12) for


more info.

Project ID

Unique ID of the project. Do not change the


project ID unless absolutley necessary. See
Project File(See 1.12) for more info.

Debug

Show the SQL and runtime error for


debugging.

Compress project .css

Compress the project stylesheet (i.e.


<project>.css) and output minified .css file.

Compress project .js

Compress the project JavaScript file (i.e.


ewp<version>.js) and output minified .js file.

Generate database helper

Generate a database helper named


ewdbhelper<version>.php for including in
current or other project for simple access to
the database and retrieiving data.

Disable project CSS styles

Do not generate the the project stylesheet.


If you use this setting, there will be no
CSS styles generated for the scripts and the
HTML will be malformed, make sure you
provide your own CSS styles, for example, by
specifying your own stylesheet, read HTML
Settings(See 1.10.3).
Note

Character encoding (for Ajax/iconv)

Specify the encoding for Ajax/iconv


Some features such as Ajax require conversion
between your encoding and utf-8. If you use
non English languages, you may need to set
character encoding for these features. By
default PHPMaker will setup the encoding
automatically based on your project's Charset
setting. If that is incorrect, you can specify
yours. Make sure either iconv functions or
multibyte string functions are enabled and
your encoding is supported. See PHP manual

206

PHPMaker 12 Help
for details.
File system encoding

The encoding of the file system of the server.


When saving a file to the server, the file name
need to be converted to the file system
encoding. If your project charset/encoding is
different from the file system encoding and
you accepts non alphanumeric file names,
enter the file system encoding of the server

MySQL charset (for SET NAMES)

Specify the charset for MySQL SET NAMES


statement.
If actually charset encoding of your data is
different from the charset of your project, you
may need to specify this setting for MySQL to
convert between them. Read
http://dev.mysql.com/doc/refman/5.0/en/char
set-connection.html before using this setting.

Validate NOT NULL fields

By default PHPMaker will detect fields declared


as NOT NULL in the database (and without
default value in database or the project) and
force "Required" validation. If for some special
reason you need to disable this feature,
disable this setting.

Default time zone

Specify the default time zone of the server.


Read
http://www.php.net/manual/en/function.datedefault-timezone-set.php and
http://www.php.net/manual/en/timezones.php
for supported time zones.

Use DOM XML for Language object

Use PHP 5 DOM XML to load language file


instead of using PHP XML parser.
By default the scripts use PHP XML parser to
load the language file for faster loading. If
your PHP setup does not have PHP XML parser
installed or you want to manipulate the loaded
XML document by DOM XML, enable this
setting.

Use JavaScript popup message

Use JavaScript popup message to display


messages of the application.
By default the messages are displayed above
the main table. This options uses JavaScript to
show the message as a popup message on
page load.

Disable button on submit

Disable submit buttons when submitting the


form.
Enable this setting if you need to prevent user
submitting the form more than once (by

207

PHPMaker 12 Help
clicking the submit button) when the browser
is submitting the form.
Allow login by URL

Allow passing username and password to the


login page as URL parameters.
By default the login page accepts HTTP POST
only. If this setting is enabled, it accepts HTTP
GET also, then user can login by URL , e.g.

login.php?username=xxx&password=yyy
(where "yyy" is a plain text password)
For example, this allows user login by using
PHP cURL from your own scripts.
For security, you should pass an encrypted
password whenever possible. In fact, usually
you can retrieve an encrypted password (e.g.
a md5 hashed password) from other web
application only, if it is same as the encrypted
password for your project (e.g. MD5
password is enabled in the project, or the
project uses the same user table), then you
can pass an additional URL parameter
encrypted=1 to let the scripts know how to
compare the passwords, e.g.

login.php?username=xxx&password=xyz
&encrypted=1 (where "xyz" is an encrypted
password)
Allow login by session variables

Allow passing username and password to the


login page via session variables.
By default the login page accepts HTTP POST
only. If this setting is enabled, it accepts
session varaibles also, then user can autologin by setting some session varaibles , e.g.

$_SESSION[EW_PROJECT_NAME .
"_Username"] = "xxx"; // where
EW_PROJECT_NAME is the constant of
your project name (see above) and
"xxx" is user name
$_SESSION[EW_PROJECT_NAME .
"_Password"] = "yyy"; // where
"yyy" is a plain text password
For security, you should pass an encrypted
password whenever possible. In fact, usually
you can retrieve an encrypted password (e.g.
a md5 hashed password) from other web
application only, if it is same as the encrypted
password for your project (e.g. MD5
password is enabled in the project, or the
project uses the same user table), then you
can pass an additional session variable to let

208

PHPMaker 12 Help
the scripts know how to compare the
passwords, e.g.

$_SESSION[EW_PROJECT_NAME .
"_Username"] = "xxx"; // where
"xxx" is user name
$_SESSION[EW_PROJECT_NAME .
"_Password"] = "xyz"; // where
"xyz" is an encrypted password
$_SESSION[EW_PROJECT_NAME .
"_Encrypted"] = TRUE;
Remove XSS

Specify if sensitive keywords allowing XSS


attack should be removed.
If enabled, all user input string will be checked
against an array of sensitive keywords. If
discovered, those keywords will be broken by
inserting "" to prevent XSS attack. If this
behavior is unwanted, you can disable this
feature at your own risks. Re-generate and reupload the ewcfg*.php after changing this
setting.
If you just want to allow some sensitive
keywords, you can customize the array
EW_XSS_ARRAY in ewcfg.php of the template.
(Read Customizing Template(See 1.14).)

Check token for form post

Check synchronizer token for forms with


method="post".
Synchronizer token is used to prevent CrossSite Request Forgery (CSRF). If you add your
own HTML forms with metho="post", you
should add the token to your form by a hidden
tag, e.g.

<input type="hidden" name="token"


value="<?php echo CurrentPage()>Token ?>">
If you post your form by JavaScript, e.g. by
jQuery.post(), you should also add the token
to the data, the JavaSript variable of the token
is EW_TOKEN.
Session timeout period (minutes)

Specifies the session time-out period if the


user does not refresh or request a page.
PHP has its own settings for session timeout,
you can configure them in php.ini, read
http://php.net/manual/en/session.configuratio
n.php, but sometimes you may want to control
the session period yourself, then you can
setup BOTH this setting and the Session keep
alive interval (seconds) setting (see below)

209

PHPMaker 12 Help
to a positive value.
Session keep alive interval (seconds)

Specifies the interval to send Ajax request to


the server for keeping the session alive.
Notes

1. For this setting to work, this setting


MUST be SHORTER than the
session.gc_maxlifetime and
session.cookie_lifetime in php.ini,
otherwise the session will be expired
by PHP first. Do not set the interval
too short, making requests to the
server every 300-600 seconds (5-10
minutes) should be enough.
2. To enable this feature, this setting
must be set to a value larger than 0.
Session time out countdown period
(seconds)

Specifies the countdown period before session


ends.
When the session is about to end, a modal
dialog will show up to remind user and let the
user choose to continue the session. If the
user does not respond after the countdown
period, the session will expire.

Composite key separator

The separator between key values of a


composite key. Default is ",".
If your primary key values are of string type
and contain commas also, the commas will
affect parsing of the composite key value in
the script and lead to failure of locating a
record, you can change the separator to avoid
such problem.

Export all time limit

Set time limit (seconds) when exporting all


records

Export field caption

Export field caption instead of field names


during export.

Export original values

Export original field values instead of looked


up values (for fields setup with user values or
lookup tables) during export.

Export CSS styles

Export HTML/Excel/Word with CSS styles (e.g.


for keeping the row color in the exported file)

Format output for XML export

Use formatted XML during export.


By default DOM XML does not output
formatted XML (no line breaks and indent
between tags), enable this setting to override
it.

210

PHPMaker 12 Help
Export master record

Specify if master record should be exported


during exporting master/detail records. (Not
applicable to CSV) Default is true.

Export master record for CSV

Specify if master record should be exported


during exporting master/detail records to CSV.
Default is false.
If master record is exported, the result CSV
may not be imported into other application. If
you want to export it anyway, enable this
setting.

Export detail records in Master/DetailView

Specify if detail records in View page of master


table (in Master/Detail-View) should be
exported. Default is true.

Export detail records for CSV in


Master/Detail-View

Specify if detail records in View page of master


table (in Master/Detail-View) should be
exported for CSV. Default is false.

Show vertical master record in List Page Specify if master record in List page of detail
table should be displayed in vertical format.
Default is true.
Language files

The default language files for a project. (For


use with Multi-Language.)

Allow no paging section

Allow no paging section in List page.


If both paging section at top and that at
bottom are disabled, users will not be able to
go to the second or later pages of the
recordset. The scripts will use paging section
at bottom by default to make sure paging is
possible. If you want to allow no paging
section (e.g. you always have all records in
one page), enable this setting.

Use hierarchical User ID

For used with User ID Security. (see Security


Settings(See 1.10.4).)
If enabled, a parent user can view records of
child users and grandchild users and so on. If
disabled, a parent user can only view records
of child users.

Use subquery for master/detail

For used Master/Detail with User ID Security


(see Security Settings(See 1.10.4)) . Default is
False.
If master table is protected by User ID
Security, the detail tables "inherit" the security
even they have not the User ID field. This is
achieved by checking the master records that
the user can access with User ID Security,
then limit the detail records to those belonged
to the accessible master records. The checking

211

PHPMaker 12 Help
can be done by using subquery but not all
databases support subquery, you may want to
disable this setting in such cases. On the other
hand, if you have large number of detail
records and not using subquery makes the
SQL too long for your database, then enable
this setting if your database supports
subquery.
Initiate search panel as collapsed

Specify if the search panel should be initialized


as collapse on page load

Blob field byte count for hash value


calculation

For use with Check Conflicts (see Table


Setup(See 1.10.6)). Specify the number of
bytes for calculating the hash value . Default is
200.
Check Conflicts will increase the time
required to load the page, for better
performance only the first hundreds of bytes of
the BLOB fields are processed by default, but
there are chances that change of BLOB data is
not detected (if the first nth bytes are not
changed). You can increase the number of
bytes, if you want to process all bytes, enter
0.

Separate permissions for


List/View/Search

Specify if the permissions for List, View, and


Search are different. Default is true. Note: For
use with Dynamic User Levels (see Security
Settings(See 1.10.4)) only.
If disabled, the permssions for
List/View/Search are the same. That is, if the
List page is accessible by an user, then the
View page and Advanced Search page are also
accessible by the user.

Use ADOdb driver for MySQL

Use ADOdb driver if MySQL database is used


(by default a customized lite version
ewmysql<n>.php is used)

Oracle charset

By default the project character is also used


for connecting to Oracle. If you need to use a
different charset, specify it with this setting.

Oracle compare

For setting Oracle's NLS_COMP parameter.


Requires Oracle 10gR2 (or later). Possible
values are: BINARY, LINGUISTIC, ANSI.
For example, if you want to do case insensitive
search you can select LINGUISTIC.

Oracle sort

For setting Oracle's NLS_SORT parameter.


Requires Oracle 10gR2 (or later).
For example, if you want to do case insensitive

212

PHPMaker 12 Help
search you can enter "BINARY_CI" (no double
quotes).
Auto-Suggest maximum display entries

Specify the number of options to be displayed


during Auto-Suggest. Default is 10.

Auto-Suggest for all display fields

Specify if Auto-Suggest should consider


Display field #2 to #4.
By default Auto-Suggest only uses Display
field #1 and only finds records with Display
field #1 STARTS WITH the input characters. It
this setting is enabled, Auto-Suggest finds
records with Display field #1 to #4
CONTAINS the input characters

Auto-fill original value

For use with Auto-Fill (see Field Setup(See


1.10.7)). By default the looked-up value (if
any) will be used to fill the target field, enable
this option to use the original (database) value
instead.

Grid-Add row count

Specify the initial number of blank rows in


Grid-Add and Master/Detail-Add mode. Default
is 5.

Use View Tag number of decimal digits


for edit

To keep the original precision of a decimal


number, by default all decimal digits as
outputted by the database will be used in Edit
page. For example, if a number is 1.23456 in
database, the Edit page will also show 1.23456
even you may have specified just 2 decimal
digits in View Tag panel (see Field Setup(See
1.10.7)). If you want to show the number as
in the View page, you can enable this setting.
However, note that after saving the record,
the number will be saved as 1.23 only even
you have not edited the field value.
If you enable this setting, there may be
loss of precision after saving the record. Only
use this setting when precison is unimportant.
Note

Create upload file on copy

Specify if an uploaded file should be copied


when copying a record with file upload fields.
(For use with file upload to folder.) Default is
false.
If the option Delete file on update/delete
(see PHP settings(See 1.10.2)) is enabled, the
uploaded file will be deleted. If the deleted
record is a copied record, deleting the
uploaded files will affect the original record. To
prevent such possible problem, enable this
setting to duplicate the uploaded file when
copying a record.

213

PHPMaker 12 Help
Multiple file upload separator

Specify the file upload separator used to


separate the file names. By default, comma is
used. If you allow file names with comma, you
can enter another separator, e.g. "|".

Upload preview thumbnail width (px)

The width of the thumbnail displayed during


the upload process.

Upload preview thumbnail height (px)

The height of the thumbnail displayed during


the upload process.

Encrypt file path

Encrypt upload file path if enabled.

Thumbnail default width (px)

For use with image resize.


If a target resize width is <= 0, this default
width will be used. If this setting is also 0, the
width will be auto-adjusted to keep the aspect
ratio.

Thumbnail default height (px)

For use with image resize.


If a target height width is <= 0, this default
height will be used. If this setting is also 0, the
height will be auto-adjusted to keep the aspect
ratio.

Use Colorbox for images

Specify if colorbox should be used to displayed


full size image on clicking the thumbnail in the
List/View page. Default is true.

Reduce image size only (image resize)

Do not resize if image is smaller than the


resize dimension.

Always keep aspect ratio (image resize) Keep aspect ratio during image resize.

Search keywords in any selected fields


(Quick search)

For use with "All words"option of Quick Search,


allows searching all keywords in any fields
selected for Quick Search.
When searching "All words" with Quick Search
(see Table Setup(See 1.10.6)), by default all
keywords must be found in the same field.
This option provides an alternative searching
behavior.

Search multiple value option

Option for searching fields that store multiple


values as comma separated string.
Valid values are: (Default is 3)
1 - no multiple value, the whole comma
separated string is considered as one string
2 - all multiple values must meet the search
criteria (AND condition)
3 - either one of the multiple values must

214

PHPMaker 12 Help
meet the search criteria (OR condition)
Replace textarea by text input for search Replace textarea by textbox in Search page
and Extended Search. Default is TRUE.
Use ILIKE operator (PostgreSQL)

Use ILIKE instead of LIKE for case-insensitive


search (for PostgreSQL only).

Collation for LIKE operator (MySQL)

Use the specified COLLATION for the LIKE


operator (for MySQL only).

Collation for LIKE operator (Microsoft


SQL Server)

Use the specified COLLATION for the LIKE


operator (for Microsoft SQL Server only).

Check password strength

Check password strength for password fields.

Minimum password strength

Minimum password strength if check password


strength is enabled.

Generate password

Option to use random password generator.

Password length

Password length when generating a random


password.

Add plain text version in HTML email

Add plain text version when sending HTML


email.

Max email recipient

For use with Export (Email). (see PHP


Settings(See 1.10.2).) Default is 3.
To avoid abusing the export to email feature,
the number of email addresses in the recipient
field is limited to the specified value.

Max email sent count per session

For use with Export (Email). (see PHP


Settings(See 1.10.2).) Default is 3.
To avoid abusing the export to email feature,
the number of emails can be sent by the user
in each session is limited to the specified
value.

Use user id for audit trail

Use user id value for audit trail if User ID


Security is enabled.

Use responsive layout

Use responsive layout for mobile devices


automatically. Default is TRUE.
If disabled, there will be NO mobile
features, everything will be for desktop only.
Note

Use tabular form for desktop

By default Bootstrap horizontal form is used in


Add/Edit/Search/Update/Registration pages,
this option makes the scripts use Bootstrap
table instead.
Notes

1. The mobile mode still uses Bootstrap

215

PHPMaker 12 Help
form, NOT table.
2. The mobile detection is done on the
server side for this feature. Unlike
other pages, resizing desktop browser
will NOT change the page from
desktop mode to mobile mode.
Use dropdown for button group in
mobile

Use button dropdown instead of button group


to save more spaces for data in mobile mode.
Default is TRUE.

Use place holder for text box

Add placeholder attribute to form elements


automatically. Possible values are:

Use css-flip

None - no placeholder
Caption - use field caption (see Field
Setup)(See 1.10.7) as placeholder
attribute value (default)
Title - use field title (see Field
Setup)(See 1.10.7) as placeholder
attribute value

Use Twitter css-flip to convert the generated


<project>.css, bootstrap.css and bootstraptheme.css to RTL version (*-rtl.css) and add
dir="rtl" attribute to the BODY tag.
Notes

1. PHPMaker and Bootstrap 3 does NOT


support RTL. This setting is it is
provided for users' convenience only.
2. css-flip just flips the CSS, using it
alone cannot make everything
perfectly RTL automatically. You'll still
to adjust some CSS (and JavaScript)
yourself to make your website
completely RTL. However, this will be a
very good start point for your own
customization.
3. css-flip is not written by the author of
PHPMaker. NO TECHNICAL SUPPORT
WILL BE PROVIDED.

The settings are defined in the settings.xml located at the "src" folder. If you are an
advanced user who customize templates, you can also add your own settings to the
"Project" section. Open the settings.xml with a text or XML editor, add a <setting> node
under the "Project" section. Make sure you provide an unique id to the setting. Supported
data type is "String", "Integer" and "Boolean". If not specified, default is "String". The
setting value can be retrieved in the template during code generation (NOT during runtime
of the generated script) using the PROJ.GetV(id) method. Also read Template Tags(See
Note

1.14.5) and Template Object Properties(See 1.14.3).

216

PHPMaker 12 Help
Copy Table Settings
If you use database built-in query/view to make an alternate version of a table, you need to
set up the table and field settings again, this tool help you quickly copies table and field
settings from the source table to the view. Click [Tools] -> [Copy Table Settings] to open
the following form:

Select the [Source table] and the [Target table] (e.g. the query/view), click OK to copy
the table settings. If a field in the target table has the same name as that in the source
table, field settings will also be copied.
This feature copies setting without validation. If settings from the source table/field are
not applicable to the target table/field, errors may result. Check the settings after copying.
Note

Copy Field Settings


When you create a Custom View, PHPMaker allows you to copy field settings from the source
table. However, when database built-in query/view is used, you need to set up the field
settings again, this tool help you quickly copies field settings from the source table to the
view. Click [Tools] -> [Copy Field Settings] to open the following form:

217

PHPMaker 12 Help

Select the [Source table] and the [Target table] (e.g. the query/view), the fields of the
target table will be listed in the left column, you can then select the respective source fields
(from the specified source table) in the right column and click OK to copy the field settings.

Sort Tables Alphabetically


If you prefer to have the table list displayed in the user interface in alphabetical order, click
[Tools] -> [Sort Tables Alphabetically] to do so.
Notes

1. Re-arranging the table display order by drag-and-drop in the Table Setup page is
still supported, so the display order will NOT be re-sorted automatically after
synchronizing the project with your database even there are new tables added to the
database. Use this tool to sort again if necessary.
2. Only tables are sorted, the display order of the fields in the user interface or in the
generated scripts will NOT be affected by this tool.
3. The display order of the menu items in the generated scripts is still controlled by the
Menu Editor, using this tool will NOT affect the menu items.

Languages

218

PHPMaker 12 Help
If you want to use multi-language project, click [Tools] -> [Languages] to select the
languages you want to use in the project. See Multi-Language Project(See 1.10.16) for more
details.

Multi-Language Property Editor


Some text properties support Multi-Language. This editor allows you to enter your
property values for each language. See Multi-Language Project(See 1.10.16) for details.

Delete Template Cache


PHPMaker will reuse the pre-processed template scripts to speed up code-generation. We
refer to these pre-processed scripts as "template cache", sometimes these template cache
may become corrupted resulting from, for example, generating with a corrupted template or
badly customized template. In these cases you may want to delete bad template cache and
let PHPMaker builds the template cache again. You can do so by either clicking [Tools] ->
[Delete Template Cache] or by manually removing the folder for the template under your
Documents folder, i.e. <Documents Folder>\PHPMaker\Templates\<TemplateName>.zip\.
(Also see Customizing Template(See 1.14).)

Menu Editor

219

PHPMaker 12 Help
PHPMaker allow you to modify the menu in the generated site, to open the menu editor,
click [Tools] -> [Menu Editor] in the main menu or click the "Menu Editor" icon in the
toolbar.

Use the following toolbar buttons to manage your menu items:


Add item

Add a new menu item. You can add new


menu items and link them to your own
URLs. Just click the button to add and then
enter your URL. Note that the URL of the
List pages of the tables are uneditable,
they will be generated by PHPMaker
automatically.

Add child item

Add a child menu item to the focused


menu item. You can also easily drag-anddrop the icon of a menu item to another
menu item to create child menu items.

Delete

Delete the focused menu item

Edit item

Edit the displayed text of the focused


menu item. You can also click the text
directly to edit.

Post

Post the changes you make to the focused


menu item

Cancel

Cancel the changes you make to the

220

PHPMaker 12 Help
focused menu item
Refresh

Refresh the menu items

Move up one level

Move the focused menu item up one level

Move down one level

Move the focused menu item down one


level

Move Up

Move the menu item up

Move Down

Move the menu item down

Expand all items

Expanse all menu items so all menu items


of each level are shown

Collapse all items

Collapse all menu items so only menu


items of the first level are shown

Import items from PHP Report Maker projectImport menu items from PHP Repot Maker
project
Delete imported menu items

Delete imported menu items

Multi-Language

Show Multi-Language Property Editor for


editing unicode menu text

Chart menu items

Show/hide the menu items for charts


(imported from PHP Report Maker)

Your can show/hide the menu items by checking/unchecking the checkboxes beside the
menu item text. If a parent menu item is hidden, all the child items will also be hidden.
If you want to use special characters in the menu caption, you can use HTML entities such as
&#euro;.
If your custom menu items requires login, uncheck [Allow Anonymous User]. For other
(non custom) menu items, this setting is same as the List/Search/View permission for
Anonymous User in Advanced Security. (See Security Settings(See 1.10.4).)
After modifying, make sure you click [OK] to save the changes.
By default, the menu is vertical.

221

PHPMaker 12 Help
Registered user can use the Horizontal Menu(See 1.7) extension, click [Tools] ->
[Extensions] to enable the graphical extension, then click [Advanced] tab to set the
menu options.

Grouped menu items is supported. Grouped menu items are to be set up in the same way as
a sub menu. You can check the title menu item in the Group Title column of the Menu
Editor:

Then menu group title will be displayed like:

222

PHPMaker 12 Help

Since horizontal menu cannot display menu groups like vertical menu, group title
should not be enabled for root level menu items in horizontal menu. If enabled, they will
only be displayed as normal submenus. However, since submenu is vertical, you can use
group title for menu items in submenus.
Note

1.14 Customizing Template


A template is a zip file of code snippets needed to generate 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
and JavaScript, and understanding on how template works. Please read the follows carefully
before customizing the template.
The template engine is Windows Script and the scripting language is JavaScript, to
customize template you need to have basic knowledge of JavaScript. If you are not familiar
with the scripting language, refer to the JavaScript Fundamentals and JavaScript Reference.

Zipped Template, Unzipped Template and Template Cache


To generate output files, the code generator first unzips the template to the subfolder
\<product name>\Templates\<template name> under your Documents folder, preprocesses the scripts in the template into template cache, then use the template cache to
generate output files. If the unzipped template already exists, the code generator will skip
the unzip process and reuse the template cache so the time required for generation is
minimized.

223

PHPMaker 12 Help
If you want to customize a template, normally you customize the files in the zipped
template, but you'll need to zip it back after customization, for example, by dragging the
customized files back to the zipped template. The unzipped template under the Documents
folder provides an optional way to customize the template without re-zipping the template.
Either way, you should zip it back after all the customizations are done.
The Documents folder is your personal folder in which you can store your personal
files. For example, in Windows 7, the actual location of the Documents folder is
C:\Users\<user name>\Documents by default, where C is the drive in which Windows is
installed, and <user name> is the currently logged-on user.
Note

If you prefer to work with the unzipped template but you have not generated any files yet,
do once first. Then you can modify the unzipped files under the subfolder named "Script".
For example, if the template archive is named as "default.zip", it will be unzipped to the
folder <document folder>\<product name>\Templates\default.zip\, you can modify files
under the subfolder "Script" under it.
The customized files will not be zipped back to the template archive automatically. It
you want to transfer or share your template, you need to zip the template files back to a
template archive yourself. When you zip the template files, make sure you zip the files and
subfolders in the unzipped folder, not the unzipped folder itself. Otherwise there will be one
level different. Using above example, you should add the files and subfolders under
<document folder>\<product name>\Templates\default.zip\ to the template archive, NOT
the whole folder.
Note

When changes in the zipped template is detected, the code generator will ask you to confirm
overwriting the old unzipped version, you should answer carefully, especially if you've
implemented some customizations previously. Always back up your customized
template first!

Control File
The core of the template file is a control file named control.xml. It is an XML file containing
all the necessary instructions for the generation process. During generation the code
generator will parse the control.xml and follows the instructions to 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. If the file is to be included in other file(s), you may need to add <session> tags in
control.xml also. See Control File(See 1.14.1) for details.

Language File
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 installed folder. The files
are used for all templates.
Note

The language file contains a <locale> node, if you use Multi-Language, you must

customize the locale settings for each language.


1. If you use system (server) locale and you know the locale string (e.g. en_US), you
only need to set the locale setting,

224

PHPMaker 12 Help
2. If you do not know the correct locale string, you can set use_system_locale to "0"
to disable system locale and customize the other locale settings.
The time_zone setting is only used in Multi-Language project.
If you are not using Multi-Language, it is recommended that you set the locale settings in
the user interface (see PHP Settings(See 1.10.2)) although customizing language file also
works. Note that if use_system_locale is set to "0", the locale settings in language file will
override the settings in the user interface.
You can edit or even add your own phrases. Just open the language file with any text or XML
editor, edit/add your <phrase> nodes. Make sure you provide an unique id to each phrase.
The id must be alphanumerical only.
The phrases are not limited to text, you can also use HTML, e.g.

<phrase id="FieldRequiredIndicator" value="&lt;span


class=&quot;ewRequired&quot;&gt;&amp;nbsp;*&lt;/span&gt;"/> (see Note 1
below)
If you want to use an image instead of text for a phrase, you can use the "imageurl",
"imagewidth" and "imageheight" attributes, e.g.

<phrase id="UnmatchedValue" value="Value does not exist"


imageurl="{_images}/warn.gif" imagewidth="16" imageheight="15"/>
where {_images} is the image folder defined in control.xml, by default it is "phpimages",
you should place your own images in the generated image subfolder. Alternatively, you can
put your images in the "images" subfolder of the template.
Read Tools(See 1.13) on how to select language file(s) for a multi-language project before
generation.
Notes

1. Language file is an XML file, when you edit the file, make sure that you keep
it well-formed. If you use HTML tags or special characters in the attributes
of the XML tags, you need to use entity references. For example, to insert the
> symbol, you need to use &lt;. Make sure your characters are supported by the
encoding of the XML file specified in the processing instruction node (the first line).
You can load the file in your browser to check if the file is well-formed, if it is, the
browsers should be able to load and display it without any errors.
2. Only the English language file is provided by our products, you'll need to prepare the
language files for other languages yourself. You may check our website and see if
there are any user submitted language files. If you want to share your language files
with others (without any conditions), you can submit your language file to us too.

File Encoding
The template files and output files are in ASCII encoding by default. Since the phrases are
separated into XML language files in utf-8 encoding, ASCII encoding will suit most cases as
the scripts contain code only. When you customize a template, it is recommended you use
the language file also. If you have to put unicode characters directly in the template files,
you must always use utf-8 and save the file in utf-8 encoding with the byte order mark (EF
BB BF), and enable the Advanced Setting UTF-8 output Files (see Tools(See 1.13)) to
make the code generator output files in utf-8 encoding.

225

PHPMaker 12 Help

General Layout
To change the general layout, just modify the file "template.php" in the template. This file
will be generated as header and footer.

Images
If you want to add or change images, you can add to the "images" subfolder. The "images"
folder will be copied to the destination folder by default. If you replace the provided images
and the file names or dimensions are different from the original ones, remember to
customize the corresponding phrases in the language file(s) also.

Subfolders
Subfolders are defined in control.xml, if you want to add and copy additional subfolders, you
also need to add a <control> tag in the control file(See 1.14.1).

Template Tags and Object Properties


The code generator processes the Template Tags(See 1.14.5), assembles the output files
using the code snippets from template files and generate code according to Template Object
Properties(See 1.14.3). Template object properties are project settings either inputted from
the user interface or restored from a project file. Template Tags are in the format of HTML
comment, when you customize template you should use an editor that will not unexpectedly
alter or remove the HTML comments, otherwise incorrect result may occur.

User Code File


Advanced users can customize the dynamically generated code by overriding an existing
template tag using User Code. To override an existing template tag, you need to add your
own function in the User Code File. (See Using User Code(See 1.14.4).) By default, the
User Code File is named as "usercode.js" and can be found under the "src" subfolder of the
installed directory.
You can use your own custom functions in the template. To use custom functions, write and
put them in the User Code File. Then just use template tag to call them in the template.
(See Using User Code(See 1.14.4))

Extensions
Integrating third-party tools can be done by extensions. An extension is modification of
template to make the template supports additional feature(s) implemented in the extension.
Extensions may add or change code sessions in the template.
An extension has the same structure as template and you can modify them in exactly the
same way as modifying the main template.
Extensions files (in zipped format) must be placed under the subfolder "extensions" of the
installation folder. Each extension must have a XML description file so the product can load it

226

PHPMaker 12 Help
in the user interface for selection. You can open an XML file in the "extensions" subfolder to
see the content, which is self-explanatory. Unzip the extension and see how it is
implemented.
Read Tools(See 1.13) on how to select extensions for a project before generation.
An extension is NOT a template, do NOT select an extension as a template for
generation.
Note

Note that all extensions are provided as examples on how to customize and extend the
template only, the third party tools used in them are not developed by the author of
PHPMaker and are not part of PHPMaker, NO TECHNICAL SUPPORT WILL BE PROVIDED. Also
see Third-party Tools(See 1.7) for more information on the third-party tools.

Custom View Tags


Custom View Tags is same as extensions 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 modify them in exactly the same way.
Custom View Tag files (in zipped format) must be placed under the subfolder
"customviewtags" of the installation folder. Each Custom View Tag must have a XML
description file so the product can load it in the Field Setup page for selection.. You can open
an XML file in the "extensions" subfolder to see the content, which is self-explanatory. Unzip
the extension and see how it is implemented.
Read Field Setup(See 1.10.7) on how to select Custom View Tag for a field.
Note that all Custom View Tags are provided as examples how to customize and extend the
template only, the third party tools used in them are not developed by the author of
PHPMaker and are not part of PHPMaker, NO TECHNICAL SUPPORT WILL BE PROVIDED.

Also See:
Control File(See 1.14.1)
Template Tags(See 1.14.5)
Template Object Properties(See 1.14.3)
Using User Code(See 1.14.4)
Third-party Tools(See 1.7)
Tools(See 1.13)

1.14.1 Control File


The core of the template file is a control file named "control.xml". It is an XML file and it
contains all the necessary information for the generation process. It is structured in 3 levels,
namely the product, control and session level:
control.xml
<?xml version="1.0" standalone="yes"?>
<product>
<control>
<session/>
...

227

PHPMaker 12 Help
<session/>
</control>
...
<control>
<session/>
...
<session/>
</control>
</product>

1. <product>
The top level is the product level identified by the <product> tag. (The tag name "product"
will be replaced by unique product name identifier in respective products.) It gives a brief
description of the template and serves for product and version information purpose.
PHPMaker will check changes in this tag every time you generate scripts with a template.
Syntax:
<product
date="release_date"
version="version_number"
desc="description"
language="lang_name"
author="author_name">
...
</product>

AttributesDescription
date

Template created date (yyyy/mm/dd)

version

Template version number

desc

Brief description of the template

language

Language of the template

author

Author of the template

2. <control>
The next level is the control level identified by the <control> tag. Each <control> specify an
output file or a set of output files that will be generated by the code generator.
Syntax:
<control
id="control_id"
type="control_type"

228

PHPMaker 12 Help
ofile="output_file_name"
oext="output_file_extension"
ifiles="input_files"
space="True/False"
ofolder="output_file_folder"
cond="conditions">
...
</control>

AttributesDescription
ofile

Output file name

oext

Output file extension

type

Control type:
"table" - table-related files:
For example, the scripts that will perform "list", "view", "add", "edit" and "delete"
functions for the table. The output of this type is a set of file, one for each table.
"other" - include files:
These files are usually include files that may be included by other files. For
example, the header file and footer file.
"copy" - files that will be directly copied:
These files that will be copied directly from the templates, such as image files.
The target to be copied can be a file or a folder.

id

Control ID. This attribute identifies which page is being generated.


Example:
type="table"
id="list" - list page
id="add" - add page
id="edit" - edit page
id="delete" - delete page
id="view" - view page
id="search" - search page
type="other"
id="loginh" - login page (hard coded user id and password)
id="loginl" - login page (use information from table for user id and password)
id="logout" - logout page
type="copy"
all ids are treated as files to be copied

ifiles

List of input files to be processed (comma delimited)

ofolder

Output file folder (used for type="copy" only)

space

Remove empty lines (True / False)

cond

Condition for generation. (see below)

229

PHPMaker 12 Help
action

For use with extensions only.


"add" - add file or folder to the the main template, or
"change" - change file in the main template

3. <session>
The third level is the session level (identified by the <session> tag). For each <control>,
there can be multiple sessions that will constitute the output. Each session can be a specific
segment from the input files or an include statement.
Syntax:
<session
type="session_type"
value="session_value"
/>

AttributesDescription
type

Session type:
"key" - output the code segment identified by the key from the list of input files
"include" - create an include statement

value

Session value:
type="other"
key value of code segment (identified by session tags in input files)
type="include"
include file name

action

For use with extensions only.


"change" - change a session in the control level

Conditions
Condition checking is used extensively in templates to control the code generation process.
Codes will only be generated if the condition specified is met.
The syntax of condition checking is as follow:

condition1[,condition2...]
Condition format:

Object_Type/Object_Property/Operator/Value1[|Value2...]
Object Type and Object Property:
See Template Object Properties(See 1.14.3) for details

230

PHPMaker 12 Help
Operator:
EQ = equal
NE = not equal
GT = greater than
GE = greater than or equal to
LT = less than
LE = less than or equal to
IN = contain value
NI = not contain value
Value:
value for comparison
(Note that single/double quotes are NOT required for string type values.)

1.14.2 System Functions


USAGE: <FunctionName>
Function Name

Description

ew_SetDb(tablename) (v12+)

Set up current database for table name


Parms
tablename - table name

ew_GetDbId(tablename) (v12+)

Return database id for table name


Parms
tablename - table name

ew_DbType(dbid) (v12+)

Return database type for database id


Parms
dbid - database id

ew_MultiPageFldAttr(f) (v12+)

Return multi page field attribute


Parms
f - field object

ew_IsAutoSuggest(f)

Return if field is auto suggest


Parms
f - field object

ew_UseForLabel(f)

Return if field uses for label


Parms
f - field object

ew_HasUserTable() (v11+)

Return if user table is specified

ew_IsNotEmpty(val) (v9+)

Return if value is not empty


Parms
val - value

ew_IsEmpty(val) (v9+)

Return if value is empty


Parms
val - value

231

PHPMaker 12 Help
ew_InArray(val, ar) (v9+)

Return if value is in array


Parms
val - value
ar - array

ew_FormObj(ctlid) (v9+)

Return form object name


Parms
ctlid - control id

ew_GetLanguageFields(tbl, fld, name) (v9+)

Return field array for multi-language


Parms
tbl - table object
fld - field object
name - field property name

ew_SelectFieldName(arflds, idx) (v9+)

Return SELECT field from language field


array
Parms
arflds - field array
idx - language index

ew_AddSelectField(ar, tbl, arflds, cnt, alias)


(v9+)

Add SELECT fields to field array


Parms
ar - field array
tbl - table object
arflds - language field array
cnt - language count
alias - field alias

ew_RemoveAlias(fld) (v10+)

Remove Alias from field (i.e. <FIELD> AS


<ALIAS> => <FIELD>)
Parms
fld - sql field

ew_SelectFields(ar, idx, sep) (v9+)

Return SELECT field list from language field


array
Parms
ar - field array
idx - language index
sep - field separator

ew_SqlSelect(sSelectLimit, sDistinct, sSelect,


sFrom) (v9+)

Return SQL SELECT statement


Parms
sSelectLimit - SELECT LIMIT part
sDistinct - use SELECT DISTINCT
sSelect - SELECT part
sFrom - FROM part

ew_CustomScriptRowCnt() (v9+)

Return custom template script id

ew_CustomScriptRowStartVar() (v9+)

Return custom template row start variable

ew_CustomScriptRowVar() (v9+)

Return custom template row variable

232

PHPMaker 12 Help
ew_CustomScriptVar() (v9+)

Return custom template control variable

ew_CustomScriptId(name, type ,idx) (v9+)

Return custom template script id


Parms
name - script name
type - script type
idx - row index (list/delete page)

ew_CustomScriptTag(name, type, idx) (v9+)

Return custom template script tag


Parms
name - script name
type - script type
idx - row index (list/delete page)

ew_GetJsScript(html) (v9+)

Return JavaScript from HTML


Parms
html - source HTML

ew_RemoveJsScript(html) (v9+)

Remove JavaScript from HTML


Parms
html - source HTML

ew_CastFieldForLike(tbl, fld, type) (v9+)

Return SQL that cast non-string field for


LIKE statement
Parms
tbl - table object
fld - field SQL
type - field type

ew_ContainText(str, find)

Return if source string contains find string


Parms
str - source string
find - find string

ew_HasTagValue(fld, val) (v8.0+)

Return if field contains tag value


Parms
fld - field object
val - tag value

ew_FldTagValues(fld) (v8.0+)

Return field tag values


Parms
fld - field object

ew_SplitTagValues(str)

Split tag values to array


Parms
str - field tag values

ew_IsBinaryField(fld)

Return if field is binary field


Parms
fld - field object

ew_ImageViewUrl(tblvar, fld, bQuoted)

Return image view url


Parms
tblvar - table variable
fld - field object

233

PHPMaker 12 Help
bQuoted - return as quoted string
ew_GetTblObj(tablename) (v12.0+)

Return table object if exists. Otherwise


return null.
Parms
tablename - table name

ew_GetParentSelect(f, i) (v12.0+)

Return parent select field


Parms
f - field object
i - index (1-4)

ew_GetParentSelectTbl(f, i) (v12.0+)

Return parent select table


Parms
f - field object
i - index (1-4)

ew_CssInherit(val)

Return "inherit" if no value. Otherwise


return original value.
Parms
val - Css Value

ew_RowCntVar(v) (v7.0+)

Return row object name (using RowCnt)


Parms
v - object name

ew_RowCntVarQuoted(v) (v7.0+)

Return row object name (using RowCnt


with quote)
Parms
v - object name

ew_RowVar(v)

Return row object name


Parms
v - object name

ew_RowVarQuoted(v)

Return row object name (with quote)


Parms
v - object name

ew_AddSquareBrackets(varname, fld)

Add square brackets to variable


Parms
varname - variable name
fld - field object

ew_PageObj()

Return page object name

ew_GetPageObjByCtrlId(ctlid) (v8.0+)

Return page object name based on control


id
Parms
ctlid - control id

ew_GetCtrlById(id) (v8.0+)

Return control object based on control id


Parms
ctlid - control id

234

PHPMaker 12 Help
ew_Val(v) (v7.0+)

Return PHP TRUE/FALSE value


Parms
v - boolean value

ew_JsVal(v) (v7.0+)

Return JavaScript true/false value


Parms
v - boolean value

ew_SecurityCheck(sId, bSecurity, bUserlevel)

Return Security Checking codes


Parms
sId - control id
bSecurity - security is enabled
bUserLevel - user level is enabled

ew_PhpCode(php, typ)

Return codes in PHP tags (i.e. <?php ...


?>)
Parms
php - original PHP codes
typ - return codes in PHP tags if = 0

ew_RandomKey()

Return random key

ew_FolderPath(id)

Return folder path based on control id


Parms
id - control id

ew_GetFileNameByCtrlID(id)

Return file name based on control id


Parms
id - control id

ew_RelFolder(f)

Return relative folder to current output


folder
Parms
f - folder path

ew_RelPath(f1, f2)

Return relative folder of f1 to f2


Parms
f1 - folder path 1
f2 - folder path 2

ew_OutputRelPath(p)

Return output relative path


Parms
p - folder path

ew_DestRelPath(p)

Return output path relative to Destination


Parms
p - folder path

ew_AppRootRelPath(p)

Return output path relative to Application


Root
Parms
p - folder path

ew_EscapeString(sSrc, sEsc)

Return escaped string


Parms

235

PHPMaker 12 Help
sSrc - source string
sEsc - escape type (double quote for VB,
back slash for js)
ew_DoubleQuote(str, cnt)

Return string with correct number of


double quotes
Parms
str - source string
cnt - number of double quotes (0,1)

ew_Quote(str)

Escape double quote in string


Parms
str - source string

ew_Quote2(str)

Escape double quote in string (including $


sign)
Parms
str - source string

SQuote(str)

Escape single quote in string


Parms
str - source string

ew_UnformatName(name)

Unformat "=" and "," in name


Parms
name - name to be unformatted

ew_HtmlValue(str)

Return value for proper display in html


Parms
str - source string

ew_JsEncode(val)

Encode value properly for js


Parms
val - source value

ew_HtmlEncode(str)

Encode value properly for html


Parms
str - source string

ew_PhpValue(str)

Encode value properly for PHP


Parms
str - source string

ew_GetFieldType(ftype)

Return FIELD type based on ADO field type


Parms
ftype - ADO Field Type
Output
1 - Numeric
2 - Date
3 - String
4 - Boolean
5 - GUID
6 - Others
7 - Time

236

PHPMaker 12 Help
ew_SetDefaultValue(ftype, defvalue)

Return default value


Parms
ftype - ADO Field Type
defvalue - default value

ew_BoolFieldTagValues(ftype, tagvalues)

Return tag values for Boolean field


Parms
ftype - ADO Field Type
tagvalues - original tag values

ew_SQLPart(sSQL, sId)

Return part of the SQL


Parms
sSQL - original SQL
sId - token for different part of SQL
(SELECT,FROM,WHERE,GROUP
BY,HAVING,ORDER BY,LIMIT)

ew_RecPerPageList(sList, iRec)

Return record per page list (comma


separated)
Parms
sList - original record per page list
iRec - default record per page

ew_GetEditDateFormat(dateformat) (v9+)

Return edit date format


Parms
dateformat - original date format

ew_IsFldFloatFormat(fld) (v9+)

Return if field is floating point type


Parms
fld - field object

ew_IsFldVirtualLookup(fld) (v7.0+)

Return if field is a virtual lookup field


Parms
fld - field object

ew_IsFldForceSelect(fld) (v8.0+)

Return if field is force select (auto suggest)


Parms
fld - field object

ew_VirtualLookupFldSql(fld, idx) (v9+)

Return the SQL for the virtual lookup field


Parms
fld - field object
idx - language index

ew_VirtualLookupFldName(fld) (v7.0+)

Return the field name for the virtual lookup


field
Parms
fld - field object

ew_EscapeRegExChars(str) (v12.0+)

Escape the regular expression


Parms
str - regular expression string

ew_QuotedName(name) (v7.0+)

Return the properly quoted sql name


Parms

237

PHPMaker 12 Help
name - table/field name
ew_SqlConcatName(name1, name2, fld, idx)
(v9+)

Return the concat sql name


Parms
name1 - field name 1
name2 - field name 2
fld - field object
idx - language index

ew_FieldSqlName(fld) (v7.0+)

Return the sql name for the field


Parms
fld - field object

ew_FieldSqlNameBase(fld, tbl) (v12.0+)

Return the sql name for the field


Parms
fld - field object
tbl - table object

ew_CustomViewFieldName(fld) (v9+)

Return the field name for the field in the


custom view
Parms
fld - field object

ew_VirtualTableInCustomView(CustomSQL,
TblName) (v9+)

Return if virtual table is in the custom view


Parms
CustomSQL - custom view SQL
TblName - table name

ew_EncodeName(Name)

Encode name in alphabeticnumeric


Parms
Name - Source name

2. System Functions (Overridable)


USAGE: SYSTEMFUNCTIONS.<FunctionName>
Function Name

Description

CharSet()

Return <meta> tag for charset


specified

FavIcon() (v7.0+)

Return <link> tags for favicon


specified

CSSFile()

Return <link> tag for css file


specified

GetScript(ScriptType, CodeType, ScriptName)

Return server/client scripts


Parms
ScriptType - script type (Server /
Client)
CodeType - code type (Global /
Table / Other)

238

PHPMaker 12 Help
ScriptName - script name
GetTemplateScript(Type,Name) (v9+)

Return source custom template


Parms
Type - template type (Table / Other)
Name - template name

GetServerScript(CodeType, ScriptName)

Return server scripts

GetClientScript(CodeType, ScriptName)

Return client scripts

ScriptExist(ScriptType, CodeType, ScriptName)

Return if script exists


Parms
ScriptType - script type (Server /
Client)
CodeType - code type (Global /
Table / Other)
ScriptName - script name

ServerScriptExist(CodeType, ScriptName)

Return if server script exists

ClientScriptExist(CodeType, ScriptName)

Return if client script exists

CustomTemplateExist() (v9+)

Return if custom template exists

CustomMultiPageTemplateExist() (v9+)

Return if multi-page custom template


Exists

CustomListOptions() (v9+)

Return custom template list option


type (block/blocknotd/single)

CustomTemplateSearchExist() (v9+)

Return if list page custom search


template exists

GetCustomTemplate() (v9+)

Return translated custom template

GetCustomTemplatePage(pageid) (v9+)

Return translated custom template


for page (multi-page layout)
Parms
pageid - page id (1/2/3/...)

ParseTemplate(template,id) (v9+)

Return translated template


Parms
template - source template
id - template id

GetCustomTemplateSearch() (v9+)

Return translated list page custom


search template

RenderCustomTemplate() (v9+)

Return rendering codes for custom


template

RenderCustomTemplateSearch() (v9+)

Return rendering codes for list page


custom search template

239

PHPMaker 12 Help
GetCustomViewTemplate(fld) (v9+)

Return custom view template for field


Parms
fld - field object

ScriptTimeout()

Return PHP script timeout codes

IsBoolFld()

Return if field is boolean

PhpCgiPath()

Return PHP CGI path

PhpDirective()

Return PHP directives

IncludeFile(fn, parm)

Return PHP include file statement


Parms
fn - file control id
parm - extra parameter

Security()

Return PHP security checking codes

ScriptInsert()

Return PHP codes for inserting a


record

ScriptUpdate()

Return PHP codes for updating a


record

Script(ctlid)

Return PHP codes for


inserting/updating a record
Parms
ctlid - "insert" / "update"

ScriptUpdateFile()

Return PHP codes to update files for


file upload to folder

ScriptUpdateFileData()

Return PHP codes to prepare data for


file upload to folder

ScriptUpdateSpecial()

Return PHP codes for updating detail


key/parent/user id field

ScriptCommon()

Return PHP codes for rendering field


(common)

ScriptViewRefer()

Return PHP codes for rendering field


for VIEW (HREF)

ScriptEditRefer()

Return PHP codes for rendering field


for EDIT (HREF)

ScriptView()

Return PHP codes for rendering field


for VIEW

ScriptViewCall(cv, vv)

Return PHP codes for rendering field


for VIEW
Parms
cv - current value

240

PHPMaker 12 Help
vv - view value
ScriptViewNo(cv, vv)

Return PHP codes for rendering field


for VIEW (AutoNumber field)

ScriptViewText(cv, vv)

Return PHP codes for rendering field


for VIEW (TEXT field)

ScriptViewHighlightSearch(cv, vv)

Return PHP codes for rendering field


for search highlight

ScriptViewFormat(fld,parm) (v9+)

Return PHP codes to format field for


VIEW
Parms
fld - field object
parm - field to be formatted

ScriptViewPassword(cv, vv)

Return PHP codes for rendering field


for VIEW (PASSWORD field)

ScriptViewRadio(cv, vv)

Return PHP codes for rendering field


for VIEW (RADIO field)

ScriptViewTable(cv, vv, isedit)

Return PHP codes for rendering field


for VIEW (Link to Table field)

ScriptViewValues(cv, vv)

Return PHP codes for rendering field


for VIEW (Lookup Value field)

ScriptViewCheckbox(cv, vv)

Return PHP codes for rendering field


for VIEW (CHECKBOX field)

ScriptViewSelect(cv, vv)

Return PHP codes for rendering field


for VIEW (SELECT field)

ScriptViewTextarea(cv, vv)

Return PHP codes for rendering field


for VIEW (TEXTAREA field)

ScriptViewHidden(cv, vv)

Return PHP codes for rendering field


for VIEW (HIDDEN field)

ScriptViewFile(cv, vv)

Return PHP codes for rendering field


for VIEW (FILE field)

ScriptViewHref(cv, vv, ctlid)

Return PHP codes for rendering field


for VIEW (HREF field)

ScriptViewVirtual(wrk)

Return PHP codes for rendering


virtual lookup field
Parms
wrk - original rendering codes

ScriptAdd()

Return PHP codes for rendering field


for ADD

241

PHPMaker 12 Help
ScriptEdit()

Return PHP codes for rendering field


for EDIT

ScriptEditCall(cv, ev, ctlid)

Return PHP codes for rendering field


for ADD/EDIT/SEARCH
Parms
cv - current value
ev - edit value
ctlid - control id

ScriptEditFormat(ctl) (v9+)

Return PHP codes to format field for


EDIT
Parms
ctl - control

ScriptSearch()

Return PHP codes for rendering field


for SEARCH (Search Field 1)

ScriptSearch2()

Return PHP codes for rendering field


for SEARCH (Search Field 2)

ScriptEditDefaultValue()

Return PHP codes for rendering field


for Default Value

ScriptEditNo(cv, ev, ctlid)

Return PHP codes for rendering field


for EDIT (AutoNumber field)

ScriptEditText(cv, ev, ctlid)

Return PHP codes for rendering field


for EDIT (TEXT field)

ScriptEditPassword(cv, ev, ctlid)

Return PHP codes for rendering field


for EDIT (PASSWORD field)

ScriptEditRadio(cv, ev, ctlid)

Return PHP codes for rendering field


for EDIT (RADIO field)

ScriptEditTable(cv, ev, ctlid)

Return PHP codes for rendering field


for EDIT (Link to Table field)

ScriptEditUserID(cv, ev, ctlid, userid)

Return PHP codes for rendering field


for EDIT (User ID field)

ScriptEditValues(cv, ev, ctlid)

Return PHP codes for rendering field


for EDIT (Lookup Value field)

ScriptEditCheckbox(cv, ev, ctlid)

Return PHP codes for rendering field


for EDIT (CHECKBOX field)

ScriptEditSelect(cv, ev, ctlid)

Return PHP codes for rendering field


for EDIT (SELECT field)

ScriptEditTextarea(cv, ev, ctlid)

Return PHP codes for rendering field


for EDIT (TEXTAREA field)

242

PHPMaker 12 Help
ScriptEditHidden(cv, ev, ctlid)

Return PHP codes for rendering field


for EDIT (HIDDEN field)

ScriptEditFile(cv, ev, ctlid)

Return PHP codes for rendering field


for EDIT (FILE field)

ScriptAggregate()

Return PHP codes for rendering field


for Aggregation

FieldCaption()

Return field caption

FieldSearchCaption()

Return field caption for search (list


page)

FieldList()

Return field control for LIST

FieldAggregate()

Return field control for AGGREGATE

FieldView()

Return field control for VIEW

FieldViewCall(cv, vv, isedit)

Return field control for VIEW


Parms
cv - current value
vv - view value
isedit - edit mode

FieldViewCheckbox(cv, vv, isedit)

Return field control for VIEW


(CHECKBOX field)

FieldViewFile(cv, vv, isedit)

Return field control for VIEW (FILE


field)

FieldViewText(cv, vv, isedit)

Return field control for VIEW (TEXT


field)

FieldViewHref(ctl)

Return field control for VIEW (HREF


field)
Parms
ctl - control to be HREF

FieldUpdate()

Return field control for UPDATE

FieldEdit()

Return field control for EDIT

FieldEditPrimaryKey()

Return field control for EDIT (Primary


Key field)

FieldEditDetailKey()

Return field control for EDIT (Detail


Key field)

FieldAdd()

Return field control for ADD

FieldSearch()

Return field control for SEARCH


(Search field 1)

243

PHPMaker 12 Help
FieldSearch2()

Return field control for SEARCH


(Search field 2)

FieldEditCall(ctl, cv, ev, ctlid)

Return field control for EDIT


Parms
ctl - control
cv - current value
ev - edit value
ctlid - control id

FieldEditNo(ctl, cv, ev, ctlid)

Return field control for EDIT


(AutoNumber field)

FieldEditHidden(ctl, cv, ev, ctlid)

Return field control for EDIT (HIDDEN


field)

FieldEditRadio(ctl, cv, ev, ctlid)

Return field control for EDIT (RADIO


field)

FieldEditCheckbox(ctl, cv, ev, ctlid)

Return field control for EDIT


(CHECKBOX field)

FieldEditPassword(ctl, cv, ev, ctlid)

Return field control for EDIT


(PASSWORD field)

FieldEditSelect(ctl, cv, ev, ctlid)

Return field control for EDIT (SELECT


field)

FieldEditDynamicSelect(ctl, cv, ev, ctlid)

Return field control for EDIT


(Dynamic SELECT field)

FieldEditAjaxSelect(ctl, cv, ev, ctlid)

Return field control for EDIT (Ajax


SELECT field)

FieldEditAutofill(ctl, cv, ev, ctlid)

Return field control for EDIT (Auto Fill


field)

FieldEditFile(ctl, cv, ev, ctlid)

Return field control for EDIT (FILE


field)

FieldEditText(ctl, cv, ev, ctlid)

Return field control for EDIT (TEXT


field)

FieldEditTextarea(ctl, cv, ev, ctlid)

Return field control for EDIT


(TEXTAREA field)

FieldOperator()

Return field control for search


operator 1

FieldOperator2()

Return field control for search


operator 2

FieldOperatorCall(ctl, val, opr)

Return field control for search


operator
Parms

244

PHPMaker 12 Help
ctl - control
val - search value
opr - operator
FieldSearchCondition()

Return field control for search


condition (BETWEEN or 2nd Opr
enabled)

OrderByFieldSources()

Return ORDER BY field sources


(comma separated)

JsReqValidator()

Return JS validator for required field

JsReqErrMsg()

Return JS error message for required


field

JsValidator()

Return JS validator

JsDefaultMsg()

Return default JS error message

PhpReqValidator()

Return PHP validator for required


field

PhpReqErrMsg()

Return PHP error message for


required field

PhpReqDefaultMsg()

Return default PHP error message for


required field

PhpSearchValidator()

Return PHP validator for search field

PhpValidator()

Return PHP validator

PhpFileValidator()

Return PHP validator for file type

PhpValidatorCommon(fld, msg)

Return PHP validator


Parms
fld - field
msg - message

PhpErrMsg()

Return PHP error message

PhpDefaultMsg()

Return default PHP error message

IsAggregate()

Return if aggregate is enabled

HasFileField()

Return if any file fields exist

IsMultiPage()

Return if multi-page is enabled

IsAutofillMasterField(ctlid)

Return if field is auto fill master field


Parms
ctlid - control id

245

PHPMaker 12 Help
IsFileRelatedField(fldname)

Return if field is file related field


Parms
fldname - field name

LookupSql(bDistinct, arFields, sFilter,


sRunTimeFilterVar, bAddUserIDFilter, sSelectLimit,
bScript)

Return codes for lookup SQL


Parms
bDinstinct - use DISTINCT
arFields - field array
sFilter - filter SQL
sRunTimeFilterVar - run time filter
variable
bAddUserIDFilter - add user id filter
sSelectLimit - SELECT LIMIT
bScript - Generate SQL for script

LookupSql1(bDistinct, arFields, sFilter,


sRunTimeFilterVar, bAddUserIDFilter, sSelectLimit,
bScript) (v12.0+)

Return codes for lookup SQL (part 1)


Parms
bDinstinct - use DISTINCT
arFields - field array
sFilter - filter SQL
sRunTimeFilterVar - run time filter
variable
bAddUserIDFilter - add user id filter
sSelectLimit - SELECT LIMIT
bScript - Generate SQL for script

LookupSql2(bDistinct, arFields, sFilter,


sRunTimeFilterVar, bAddUserIDFilter, sSelectLimit,
bScript) (v12.0+)

Return codes for lookup SQL (part 2)


Parms
bDinstinct - use DISTINCT
arFields - field array
sFilter - filter SQL
sRunTimeFilterVar - run time filter
variable
bAddUserIDFilter - add user id filter
sSelectLimit - SELECT LIMIT
bScript - Generate SQL for script

SelectionList(ctlid)

Return selection list in JSON


Parms
ctlid - control id

ConnectionString(db) (v12.0+)

Return database connection string


Parms
db - database object

DatabaseConnection(db) (v12.0+)

Return database connection array


Parms
db - database object

1.14.3 Template Object Properties


Please refer to the following table for detailed description of Objects and their properties for
use with Template Tags(See 1.14.5).

246

PHPMaker 12 Help

I. Objects
Project

Description

CTRL

Control Object

PROJ

Project Object

MASTERDETAILS

Master Details Object

CUSTOMSCRIPTS

Custom Scripts Object

MENULIST

MenuList Object

DB

Database Object

TABLE

Table Object

FIELD

Field Object

PROJ.LINKDBS (v12.0+)

Link Databases Object

You can view the object properties by opening your Project File(See 1.12) with a text
editor. Project file is an XML file, each object is represented by an XML node in the project
file. The object properties are saved as attributes of the node. The property name is same as
the attribute name.
Note

II. Properties
You can use the standard dot notation to access properties of the objects.
Example

<!--##=PROJ.ProjName##-->
This line will write the project name in the output file.

CTRL Object
The CTRL Object points to the current control in control.xml that is being generated.
Property

Description

Data Type

CtrlId

Control id (e.g. list, view, edit, etc.)

String

CtrlType

Control type (e.g. table, report, field, other, copy, etc.)

String

PROJ Object
The PROJ Object points to the current project. You can access the current project properties
by PROJ.PropertyName.

247

PHPMaker 12 Help

Property

Description

Data
Type

ProjID (v9+)

Project ID (GUID)

String

ProjName

Project name

String

ProjVar

Project variable

String

MultiLanguage

Use multiple languages

Boolean

DefaultLanguageFile

Default language file

String

LanguageFiles

Language file list (comma separated)

String

AppCompatVersion

Compat version

Integer

AppRelatedProject

Related project file

String

SqlQuote

SQL quote identifier (Square Bracket / Double


Quote / Single Quote / Back Quote / None /
Default)

String

CodePage

Code page

Long

LCID

Locale id

Long

Cache

Allow cache

Boolean

CharSet

Character set

String

CSS

External CSS file

String

OutputNameType

Output file name option:


"" - No prefix or suffix
"Prefix" - Prefix with extension
"Suffix" - Suffix with extension

String

OutputNameExt

Output file name extension name

String

OutputNameLCase

Output file name in lowercase

Boolean

BodyTitle

Body title description

String

BodyFont

Body font

String

BodySize

Body size

String

BodyBgColor

Body background color

String

BodyTextColor

Body text color

String

BodyLnkColor

Body link color

String

248

PHPMaker 12 Help
BodyVLnkColor

Body vlink color

String

BodyALnkColor

Body alink color

String

BodyLeftMargin

Body left margin

Integer

BodyTopMargin

Body top margin

Integer

DocType (v6.0+)

Document Type

String

ApplicationTheme (v6.0+)

Application Theme

String

HeaderColor (v5.0+)

Page header color

String

HeaderLogo (v5.0+)

Page header logo file name

String

HeaderHeight (v5.0+)

Page header height

Integer

MenuColor (v5.0+)

Page menu color

String

FooterColor (v5.0+)

Page footer color

String

FooterFontColor (v5.0+)

Page footer font color

String

FooterText (v5.0+)

Page footer text

String

TblWidth

Table width

String

TblPadding

Table padding

Integer

TblBorder

Table border

Integer

TblSpacing

Table spacing

Integer

TblBgColor

Table background color

String

TblHdrFontColor

Table header font color

String

TblHdrColor

Table header background color

String

TblAltColor

Table use alternate row color

Boolean

TblAltColor1

Table alternate color 1

String

TblAltColor2

Table alternate color 2

String

Template

Template file location

String

Destination

Output destination folder location

String

SecType

Security type:
"None" - no security
String
"Hard Code" - use hard coded administrator login /
password
"Use Table" - use security table

249

PHPMaker 12 Help
"Both" - Use both security table & hard coded
administrator login / password
SecLoginID

Administrator login id

String

SecPasswd

Administrator password

String

SecTbl

Security table name

String

SecLoginIDFld

Security table login id field name

String

SecPasswdFld

Security table password field name

String

SecEmailFld

Security table email field name

String

SecForgetPwdPage

Generate forget password page

Boolean

SecChangePwdPage

Generate change password page

Boolean

SecChangeEmail

Send email for password change

Boolean

SecRegisterPage

Generate registration page

Boolean

RegisterReturnPage (v6.0+)

Registration return page

String

RegisterMultiPage (v6.0+)

Register page use multi page layout

Boolean

RegisterMultiPageLabels
(v6.0+)

Register page multi page labels (comma


separated)

String

SecRegisterConfirm (v5.0+)

Registration page needs confirm

Boolean

SecRegisterCaptcha (v5.0+)

Registration page uses captcha

Boolean

SecRegisterActivate (v5.0+)

Registration page needs activation

Boolean

SecRegisterActivateFld (v5.0+) Registration page activation field name

String

SecLogInOutAuditTrail (v5.0+) Login / logout page needs audit trail

Boolean

SecLoginCaptcha (v9+)

Login page uses captcha

Boolean

SecForgotPwdCaptcha (v9+)

Forgot password page uses captcha

Boolean

SecChangePwdCaptcha (v9+)

Change password page uses captcha

Boolean

SecRegisterEmail

Send email for registration

Boolean

SecSenderEmail

Sender email address

String

SmtpServer

Smtp server name

String

SmtpServerPort

Smtp server port

Long

250

PHPMaker 12 Help
SmtpSecureOption (v9+)

Smtp secure option (ssl/tls)

String

MemoCRLFReplace

Replace CRLF with BR for Memo Field

Boolean

SessTimeOut

Session timeout time

Integer

ServerScriptTimeout

Server script timeout time for reports

Integer

TestWebServer

Testing web server:


1 - IIS Express
2 - IIS

Integer

Default date format:


0 - General date (system)
1 - Long date (system)
2 - Short date (system)
3 - Long time (system)
4 - Short time (system)
5 - "yyyy/mm/dd"
6 - "mm/dd/yyyy"
7 - "dd/mm/yyyy"
8 - Short date + short time
9 - "yyyy/mm/dd hh:nn:ss"
10 - "mm/dd/yyyy hh:nn:ss"
11 - "dd/mm/yyyy hh:nn:ss"
12 - "hh:nn:ss"

Integer

DateSeparator

Date separator: "/", "-", "."

String

SetLocale

Set locale

Boolean

Locale

Locale id (e.g. en_US)

String

CGI

Use CGI

Boolean

CGIPath

CGI path

String

Ext

Extension

String

DefaultPage

Default page name

String

UseMySqli

Use mysqli extension

Boolean

StartPage (v9+)

Project start page

String

XMLEncoding

XML encoding charset

String

HighlightColor

List page row highlight color

String

SelectColor

List page row select color

String

EditBackColor

List page edit row background color

String

PagerBackColor

Pager background color

String

DefaultDateFormat

251

PHPMaker 12 Help
FooterBackColor

Footer (aggregated values) background color

String

UploadPath

File upload path

String

UploadAllowedFileExt

Allowed upload file extensions

String

CssStyles

User css style content

String

AutoSync

Auto synchronize when open project

Boolean

AutoBrowseURL (v9+)

Auto browse URL

String

AutoBrowse

Auto browse after generation

Boolean

OtherGen

Generate other scripts

Boolean

OtherGenList (v7.0+)

Generation list for other scripts. Format:


@db=1,@css=0,... (Generate "db" = Yes,
Generate "css" = No, etc...)

String

Expand the other generation list (for display)

Boolean

OtherExpanded (v7.0+)

OtherOverwrite (deprecated in
Overwrite other scripts
v7.0+)

Boolean

DynamicLoadDB

Load database dynamically

Boolean

MD5Password (v6.0+)

Use MD5 password

Boolean

CaseSensitivePassword (v6.0+) Use Case Sensitive password

Boolean

ServerValidate (v6.0+)

Use server validation

Boolean

ClientValidate (v6.0+)

Use client validation

Boolean

RptIndent

Report header indentation in pixels

Integer

RecPerPage

Records per page

Integer

RecPerPageList

Comma separated values for records per page (list


String
page only)

PrinterFriendly (v6.0+)

Printer Friendly

Boolean

ExportHtml

Export to HTML

Boolean

ExportWord

Export to Word

Boolean

ExportExcel

Export to Excel

Boolean

ExportXml

Export to XML

Boolean

ExportCsv

Export to CSV

Boolean

252

PHPMaker 12 Help
ExportEmail (v7.0+)

Export to email

Boolean

ExportPDF (v8.0+)

Export to PDF

Boolean

ExportType (v7.0+)

Export Type:
"SELECTED" = export selected records
"PAGE" = export current page
"ALL" = export all records

String

RecPerRow

Records per row (multi-column list page)

Integer

MultiDelete

Delete records by multiple selection

Boolean

SortType

Sort type
0 - no sort
1 - single column sort
2 - multi-column sort

Integer

Pager style:
1 - numeric pager
2 - nextprev pager

Integer

TopPageLink

Pager on top

Boolean

BottomPageLink (v5.0+)

Pager on bottom

Boolean

ViewExport (v5.0+)

View page export

Boolean

ListExport (v8.0+)

List page export

Boolean

LinkOnLeft

Links on Left

Boolean

InlineDelete

Inline delete

Boolean

DetailViewPaging (v5.0+)

Paging in view page

Boolean

DetailEditPaging (v10.0+)

Paging in edit page

Boolean

ModalSearch (v11.0+)

Use modal form for advanced search

Boolean

RepeatColumns

Repeat column count for radios and checkboxes

Integer

AppRootFolder

Application root folder

String

RootRelativePath

Root relative path

String

DeleteUploadedFile

Delete unused uploaded file

Boolean

AuditTrailPath

Audit trail path

String

RecipientEmail

Receiver email

String

SMTPServerUsername

Smtp server user name

String

PagerStyle

253

PHPMaker 12 Help
SMTPServerPassword

Smtp server password

String

FavIcon (v7.0+)

File path for FavIcon

String

LoginOption (v7.0+)

Login options: (comma separated list of following


options, e.g. "AUTO,USER,ASK")
"AUTO" - Auto login until logout explicitly
"USER" - Save user name
"ASK" - Always ask for user name and password

String

BlankPage (v8.0+)

Generate blank custom page

Boolean

UseButtonsForLinks (v10.0+)

Use buttons for links

Boolean

UseDropDownForExport
(v10.0+)

Use dropdown for export links

Boolean

UseDropDownForAction
(v10.0+)

Use dropdown for action links

Boolean

UseDropDownForListOptions
(v10.0+)

Use dropdown for list option links

Boolean

Multi page type:


"Tabs" - Bootstrap tabs
"Pills" - Bootstrap pills
"Accordion" - Bootstrap accordion

String

MultiPageType (v10.0+)

You can further define custom Project Level properties and put it in the "Advanced
Settings" file (under "src\settings.xml" in the program folder). The setting is accessible in
the UI via [Tools] -> [Advanced Settings] under the "Project" node. You can then access the
custom properties in the template by means of PROJ.GetV("<property name>"). To avoid
clashing with PHPMaker default project settings, always prefix your settings with "USER_".
Note

MASTERDETAILS Object
The MASTERDETAILS Object contains the collection of all master/detail relationships defined
in the current project. Each master/detail relationship has the following properties.
Property

Description

Data Type

MasterTable

Master table name

String

DetailTable

Detail table name

String

EnforceReferentialIntegrity (v10.0+) Enforce referential integrity

Boolean

CascadeUpdate (v10.0+)

Cascade update

Boolean

CascadeDelete (v10.0+)

Cascade delete

Boolean

FieldCount

Total number of master/detail key pairs

Integer

254

PHPMaker 12 Help
CurrentField

Current master/detail field key pair position Integer

CurrentMasterField

Current matser field key

String

CurrentDetailField

Current detail field key

String

CUSTOMSCRIPTS Object
The CUSTOMSCRIPTS Object contains the collection of all custom scripts defined in the
current project. Each custom script has the following properties.
Property

Description

Data Type

ScriptType

Script type (Server/Client)

String

ScriptCodeType

Script code type (Global/Table/Other)

String

ScriptName

Script name

String

ScriptCtrlID

Script control id

String

ScriptL1Key

Script level 1 key (table/other name)

String

ScriptL2Key

Script level 2 key (reserved for future use)

String

ScriptCode

Custom script code

String

MENULIST Object
The MENULIST Object contains the menu items defined in the current project. It has the
following properties.
Property

Description

Data Type

Count

Number of menu items in the menu list

Integer

Item(i)

The ith item in the menu

Item Object

The Item Object has the following properties.


Property

Description

Data Type

MenuID

Menu id

Integer

MenuText

Menu display text

String

MenuParentID

Menu parent id

Integer

MenuGroup (v8.0+)

Menu group item

Boolean

MenuSource

Menu source

String

255

PHPMaker 12 Help
MenuExtUrl

Menu external url

String

MenuAnonymous (v7.0+)

Menu allows anonymous access

Boolean

MenuSecurity

Menu security settings

String

MenuUrl

Menu url

String

MenuCustomUrl

Menu use custom url

Boolean

MenuLevel

Menu level

Integer

MenuShow

Menu show this item

Boolean

MenuDisplayOrder

Menu display order

Integer

DB Object
The DB Object points to the current database. You can access the current database
properties by DB.PropertyName.
Property

Description

Data Type

DBSeq (v12.0+)

Database sequence

Integer

DBID (v12.0+)

Database id

String

DBName

Database name

String

DBVar (v11.0+)

Database variable

String

DBType

Database type

String

DBPath

Database path

String

DBUseServerMapPath

Maps the relative path of the database to the


corresponding physical directory on the server (MS
Access only)

Boolean

DBPhyPath

Database physical path

String

DBUID

Database user id

String

DBPwd

Database password

String

DBQuoteS

Database start quote character

String

DBQuoteE

Database end quote character

String

DBConnstr

Database connection string

String

DBADOVer

ADO version

String

DBDBMSName

DBMS name

String

256

PHPMaker 12 Help
DBDBMSVer

DBMS version

String

DBOLEDBVer

OleDb version

String

DBProviderName

Provider name

String

DBProviderVer

Provider version

String

DBSchema

Schema name

String

MaxUploadSize

Maximum upload file size

Integer

SecUserLevelFld

User level field name

String

SecDefault

Default security setting

String

SecuUserIDFld

User id field name

String

SecUserProfileFld (v7.0+) User profile field name (used by the advanced security
features: concurrent user login / Login retry / Password String
expiry)
UseDynamicUserLevel

Use dynamic user level

Boolean

UserLevelTbl

User level table name

String

UserLevelIdFld

User level id field name

String

UserLevelNameFld

User level name field name

String

UserLevelPrivTbl

User level privilege table name

String

UserLevelPrivTblNameFld User level table name field name

String

UserLevelPrivUserLevelFldUser level user level name field name

String

UserLevelPrivPrivFld

User level privilege field name

String

SecuParentUserIDFld

Parent user id field name

String

TABLE Object
The TABLE Object points to the current table. You can access the current table properties by
TABLE.PropertyName.
Property

Description

Data Type

TblSchema (v7.0+)

Table schema name

String

TblName

Table name

String

TblType

String

Table type

257

PHPMaker 12 Help
(TABLE/VIEW/CUSTOMVIEW/REPORT/LINKTABLE)
TblKey

Table key

String

TblGen

Generate this table

Boolean

TblGenList (v7.0+)

Generation list for table scripts. Format:


info=1,list=0,... (Generate "info" = Yes, Generate String
"list" = No, etc...)

TblList

Show table in menu

Boolean

TblView

Table view enabled

Boolean

TblInlineEdit

Table inline edit enabled

Boolean

TblGridEdit (v5.0+)

Table grid edit enabled

Boolean

TblEdit

Table edit enabled

Boolean

TblEditConfirm (v5.0+)

Edit needs confirmation

Boolean

TblEditCaptcha (v7.0+)

Edit use captcha

Boolean

TblGridAdd (v7.0+)

Table grid add enabled

Boolean

TblAdd

Table add enabled

Boolean

TblAddReturnPage (v6.0+)

Table add return page

String

TblAddOpt (v6.0+)

Table add option enabled

Boolean

TblAddConfirm (v5.0+)

Add needs confirmation

Boolean

TblAddCaptcha (v5.0+)

Add use captcha

Boolean

TblInlineAdd (v5.0+)

Table inline add enabled

Boolean

TblInlineCopy (v5.0+)

Table inline copy enabled

Boolean

TblMultiUpdate (v5.0+)

Table multi-update enabled

Boolean

TblMultiUpdateConfirm (v5.0+) Multi update needs confirmation

Boolean

TblAnonymous (v5.0+)

Table anonymous access security

Integer

TblDelete

Table delete enabled

Boolean

TblCaption

Table caption

String

TblVar

Table variable name

String

TblSrchType

Table search type:


"NONE" - none
"BASIC" - basic search

258

String

PHPMaker 12 Help
"ADVANCED" - advanced search
"BOTH" - both basic & advanced search
TblSearchHighlight (v5.0+)

Search highlight

Boolean

TblSearchColor (v5.0+)

Search highlight color

String

TblSearch (v8.0+)

Table advanced search enabled

Boolean

TblBasicSearch (v8.0+)

Table basic search enabled

Boolean

TblExtendedBasicSearch
(v8.0+)

Table extended basic search enabled

Boolean

TblExtSearchFldPerRow
(v8.0+)

Table extended basic search fields per row

Integer

TblBasicSearchDefault (v9+)

Table basic search default value

String

TblBasicSearchTypeDefault
(v9+)

Table basic search type default value

String

TblDefault

Table link from default page

Boolean

TblCopy

Table copy enabled

Boolean

TblFilter

Table filter (sql where clause)

String

TblUserIDFld

Table user id field name

String

TblSecurity

Table security settings

String

TblUserIDAllow (v9+)

Table allow view all security level

Integer

TblExpanded (v7.0+)

Expand the table generation list (for display)

Boolean

TblLoaded

Table is loaded

Boolean

TblRptShowDetails

Show report details (reports only)

Boolean

TblRptShowGrandTotal

Show report grand total (reports only)

Boolean

OutputFolder (v11.0+)

Output folder (custom files only)

String

IncludeFiles (v11.0+)

Include PHP files (custom files only)

Boolean

TblReportType (v11.0+)

Report type ("custom" for custom files)

String

TblCustomSQL

Table custom sql (custom views only)

String

TblCustomError

Error loading custom views / reports

String

TblRptSrc

Report source table (reports only)

Boolean

259

PHPMaker 12 Help
TblRptIndent

Report indentation by pixels (reports only)

Integer

TblUseGlobal

Use global settings

Boolean

TblRecPerPage

Records per page (list page only)

Integer

TblRecPerPageList

Dynamic values for records per page (list page


only)

String

TblPrinterFriendly (v6.0+)

Printer Friendly

Boolean

TblExportHtml

Export to HTML

Boolean

TblExportWord

Export to Word

Boolean

TblExportExcel

Export to Excel

Boolean

TblExportXml

Export to XML

Boolean

TblExportCsv

Export to CSV

Boolean

TblExportEmail (v7.0+)

Export to email

Boolean

TblExportPDF (v8.0+)

Export to PDF

Boolean

TblExportType (v7.0+)

Export Type:
"SELECTED" = export selected records
"PAGE" = export current page
"ALL" = export all records

String

TblRecPerRow

Records per row (multi-column list page)

Integer

TblMultiDelete

Delete records by multiple selection

Boolean

TblSortType

Sort type
0 - no sort
1 - single column sort
2 - multi-column sort

Integer

Pager style:
1 - numeric pager
2 - nextprev pager

Integer

TblTopPageLink

Pager on top

Boolean

TblBottomPageLink (v5.0+)

Pager on bottom

Boolean

TblViewExport (v5.0+)

View page export

Boolean

TblListExport (v8.0+)

List page export

Boolean

TblLinkOnLeft

Links on Left

Boolean

TblInlineDelete

Inline delete

Boolean

TblPagerStyle

260

PHPMaker 12 Help
TblDetailViewPaging (v5.0+)

Paging in view page

Boolean

TblDetailEditPaging (v10.0+)

Paging in edit page

Boolean

TblModalSearch (v11.0+)

Use modal form for advanced search

Boolean

TblAuditTrail

Table use audit trail

Boolean

TblSendMailOnAdd

Send email on add

Boolean

TblSendMailOnEdit

Send email on edit

Boolean

TblSendMailOnDelete

Send email on delete

Boolean

TblShowBlankListPage

Show blank list page

Boolean

TblDetailShowCount (v7.0+)

Show detail record count

Boolean

TblDetailAdd (v9+)

Allow detail add

Boolean

TblDetailEdit (v9+)

Allow detail edit

Boolean

TblDetailView (v10.0+)

Allow detail view

Boolean

TblShowMultipleDetails
(v10.0+)

Show multiple details

Boolean

TblEditReturnPage (v6.0+)

Table edit return page

String

TblMultiPageLabels (v6.0+)

Table multi page labels (comma separated)

String

TblMultiPageAdd (v6.0+)

Table add multi page layout enabled

Boolean

TblMultiPageEdit (v6.0+)

Table edit multi page layout enabled

Boolean

TblMultiPageView (v6.0+)

Table view multi page layout enabled

Boolean

TblMultiPageSearch (v8.0+)

Table search multi page layout enabled

Boolean

TblCheckConcurrentUpdate
(v7.0+)

Check for concurrent update

Boolean

TblUserLevelPriv (v9+)

Use table in dynamic user level security

Boolean

TblDisplayRowCount (v10.0+) Display row count

Boolean

TblUseButtonsForLinks
(v10.0+)

Use buttons for links

Boolean

TblUseDropDownForExport
(v10.0+)

Use dropdown for export links

Boolean

TblUseDropDownForAction
(v10.0+)

Use dropdown for action links

Boolean

261

PHPMaker 12 Help
TblUseDropDownForListOptions
Use dropdown for list option links
(v10.0+)

Boolean

Multi page type:


"Tabs" - Bootstrap tabs
"Pills" - Bootstrap pills
"Accordion" - Bootstrap accordion

String

LinkDBID (v12.0+)

Link database id (for table type = "LINKTABLE"


only)

String

LinkTableName (v12.0+)

Linked table name (for table type = "LINKTABLE"


String
only)

LinkTableType (v12.0+)

Linked table type (for table type = "LINKTABLE"


only)

TblMultiPageType (v10.0+)

String

FIELD Object
The FIELD Object points to the current field. You can access the current field properties by
FIELD.PropertyName.
Property

Description

Data Type

FldName

Field name

String

FldAlias

Field alias name

String

FldSourceName

Field source name

String

FldSourceTable

Field source table name

String

FldSourceField

Field source field name

String

FldType

Field data type

Integer

FldTypeName

Field data type name

String

NativeDataType

Field native data type

Integer

FldSQL (v12.0+)

Field SQL (for custom field only)

String

FldIsCustom (v12.0+)

Field is custom field

Boolean

FldSupport

Field is supported

Boolean

FldSize

Field size

Long

FldUniqueIdx

Field has unique index

Boolean

FldZeroLen

Field support zero-length string (MS Access


only)

Boolean

262

PHPMaker 12 Help
FldReq

Field is required (NOT NULL)

Boolean

FldIsPrimaryKey

Field is primary key

Boolean

FldAutoIncrement

Field is auto increment field

Boolean

FldAttribute

Field ADO attributes

Long

FldMin

Minimum value for javascript validation

Variant

FldMax

Maximum value for javascripot validation

Variant

FldErrMsg

Error message if javascript validation failed

String

FldValidate

Validate format for javascript

String

FldServerValidateArgs (v7.0+)

Validate arguments (server side)

String

FldClientValidateArgs (v7.0+)

Validate arguments (client side)

String

FldRequired

Required field for javascript validation

Boolean

FldPopCalendar

Use popup calendar

Boolean

FldGenerate

Field generate enabled

Boolean

FldList

Field list enabled

Boolean

FldExport (v6.0+)

Field export enabled

Boolean

FldView

Field view enabled

Boolean

FldEdit

Field edit enabled

Boolean

FldAdd

Field add enabled

Boolean

FldAddOpt (v6.0+)

Field add option enabled

Boolean

FldSearch

Field search enabled

Boolean

FldBasicSearch

Field basic search enabled

Boolean

FldExtendedBasicSearch

Field extended basic search enabled

Boolean

FldRegister

Field enabled for registration page

Boolean

FldSrchOpr

Field search operator

String

FldSrchOpr2

Field second search operator

String

FldDefault

Field default value

Variant

FldSearchDefault (v9+)

Field search default value

String

263

PHPMaker 12 Help
FldSearchDefault2 (v9+)

Field search default value 2

String

FldDbDefault (v7.0+)

Field default value (database)

Variant

FldCaption

Field caption

String

FldVar

Field variable

String

FldViewTag

Field view tag

String

FldViewThumbnail (6.0+)

Field view as thumbnail (FILE type field only)

Boolean

FldHtmlTag

Field html tag

String

FldHtmlTagReadOnly

Field is read only

Boolean

FldTagSize

Field html tag size

Integer

FldTagMaxLength

Field html tag maximum length

Integer

FldTagHiddenValue

Custom value for hidden tag

String

FldSelectType

Field select type (Table/Values)

String

FldTagValues

Field value list

String

FldTagLnkTbl

Field link to table name

String

FldTagLnkFld

Field link to table key field name

String

FldTagLnkDisplay

Field link to table display field name

String

FldTagLnkDisp2

Field link to table display field 2 name

String

FldTagLnkDisp3 (v8.0+)

Field link to table display field 3 name

String

FldTagLnkDisp4 (v8.0+)

Field link to table display field 4 name

String

FldTagLnkOrderBy

Field link to table order by field name

String

FldTagLnkOrderType

Field link to table order type (ASC/DESC)

String

FldTagLnkDistinct

Field link to table use distinct value

Boolean

FldTagCols

Field column count (TEXTAREA)

Integer

FldTagRows

Field row count (TEXTAREA)

Integer

FldTagImgWidth

Image width (IMG)

Integer

FldTagImgHeight

Image height (IMG)

Integer

FldTagAType

Href type

String

264

PHPMaker 12 Help
FldTagATarget

Href target type (A)

String

FldTagAPrefix

Href prefix (A)

String

FldTagASuffix

Href suffix (A)

String

FldBold

Field bold enabled

Boolean

FldItalic

Field italic enabled

Boolean

FldAlign

Field alignment

String

FldFmtType

Field format type:


"Currency" - format as currency
"Date/Time" - format as date/time
"Number" - format as number
"Percent" - format as percent
"String" - format as string

String

FldDtFormat

Field date format:


See PROJ.DefaultDateFormat for details

Integer

FldNumDigits

Field number of digits after decimal

Integer

FldIncLeadDigit

Field include leading digit

Integer

FldUseParen

Field use parenthesis for negative

Integer

FldGpDigits

Field group digits

Integer

FileNameFld

File name field name (FILE)

String

FileTypeFld

File type field name (FILE)

String

FileSizeFld

File size field name (FILE)

String

ImageWidthFld

Image width field name (FILE)

String

ImageHeightFld

Image height field name (FILE)

String

FldHrefFld

Field hyperlink to field name

String

FldHrefFldOrig (v5.0+)

Href use original value

Boolean

FldStrFunc

Field string function name

String

FldUseDHTMLEditor

Use DHTML editor (MEMO)

Boolean

FldMemoMaxLength

Maximum length for memo field (list page only) Integer

FldSelectSize

Multiple selection list size

Integer

FldSelectMultiple

Use multiple selection list

Boolean

265

PHPMaker 12 Help
FldSelectFilter

Field select filter

String

FldAutoFillSourceFields (v9+)

Field auto fill source fields

String

FldAutoFillTargetFields (v9+)

Field auto fill target fields

String

FldSelectFilterFld

Dynamic combobox filter field name

String

FldSelectFilterFld2 (v9+)

Dynamic combobox filter field name 2

String

FldSelectFilterFld3 (v9+)

Dynamic combobox filter field name 3

String

FldSelectFilterFld4 (v9+)

Dynamic combobox filter field name 4

String

FldParentSelect

Dynamic combobox parent field name

String

FldParentSelect2 (v9+)

Dynamic combobox parent field name 2

String

FldParentSelect3 (v9+)

Dynamic combobox parent field name 3

String

FldParentSelect4 (v9+)

Dynamic combobox parent field name 4

String

FldParentSelectTbl (v12.0+)

Dynamic combobox parent field table name

String

FldParentSelectTbl2 (v12.0+)

Dynamic combobox parent field table name 2

String

FldParentSelectTbl3 (v12.0+)

Dynamic combobox parent field table name 3

String

FldParentSelectTbl4 (v12.0+)

Dynamic combobox parent field table name 4

String

FldSelectAllowAdd

Ajax add to combo box

Boolean

FldQuoteS

Field start quote character

String

FldQuoteE

Field end quote character

String

FldColumnWidth

List page field column width

String

FldColumnWrap

List page field column wrap

Boolean

FldAggregate

Field aggregation function name

String

FldGroupBy

Field grouping sequence (reports only)

Integer

FldGroupByShowSummary

Field grouping show summary (reports only)

Boolean

FldOrderBy

Field ordering sequence

Integer

FldOrder

Field order type (ASC/DESC)

String

FldRptAggSum

Aggregate field sum (reports only)

Boolean

FldRptAggAvg

Aggregate field average (reports only)

Boolean

266

PHPMaker 12 Help
FldRptAggMin

Aggregate field minimum (reports only)

Boolean

FldRptAggMax

Aggregate field maximum (reports only)

Boolean

FldRepeatColumns

Repeat column count for radios and checkboxes Integer

FldUploadPath

Field level upload path

String

FldUploadMultiple (v10.0+)

Upload multiple fields (comma separated)

Boolean

UploadAllowedFileExt (v11.0+)

Allowed upload file extensions (comma


separated)

Boolean

UploadMaxFileSize (v11.0+)

Upload maximum file size

Long

UploadMaxFileCount (v11.0+)

Upload maximum file count (multiple upload


only)

Long

FldCheckDuplicate

Check duplicate for field

Boolean

FldPageIndex

Field page index (multi page add/edit)

Integer

FldAjax

Field use Ajax

Boolean

FldAutoUpdateValue (v5.0+)

Field auto update value

String

FldUploadResize (v5.0+)

Resize file on upload (FILE)

Boolean

FldResizeWidth (v5.0+)

Resize file width

Integer

FldResizeHeight (v5.0+)

Resize file height

Integer

FldResizeInterpolation (v5.0+)

Resize file interpolation

Integer

FldMultiUpdate (v5.0+)

Field enabled multi-update

Boolean

FldTitle (v5.0+)

Field title attribute (INPUT)

String

FldAlt (v5.0+)

Field alt attribute (IMG)

String

FldEditCustomAttributes (v5.0+) Field edit tag custom attributes

String

FldViewCustomAttributes
(v5.0+)

Field view tag custom attributes

String

FldTagACustomAttributes
(v8.0+)

Field href tag custom attributes

String

FldSelectForceSelection (v6.0+) Field select force selection

Boolean

FldAutoFill (v6.0+)

Field auto fill

Boolean

FldMemoCRLFReplace (v6.0+)

Field replace CrLf with <br>

Boolean

267

PHPMaker 12 Help
FldTooltipFld (v7.0+)

Field tool tip field

String

FldTooltipWidth (v7.0+)

Field tool tip width (px)

Long

FldVirtualLookup (v7.0+)

Field use virtual lookup (for sort and search)

Boolean

FldViewTemplate (v9+)

Field custom view template

String

FldOptionTemplate (v12.0+)

Optional template for auto fill/auto suggest

String

FldDropdown (v12.0+)

Use bootstrap dropdown for field

Boolean

FldDropdownWidth (v12.0+)

Dropdown width

Integer

FldDropdownHeight (v12.0+)

Dropdown height

Integer

PROJ.LINKDBS Object
The PROJ.LINKDBS Object contains the collection of all link databases defined in the current
project. The object can be accessed via PROJ.LINKDBS as follows.

for (var i = 1, len = PROJ.LINKDBS.Count(); i <= len; i++)


var db = PROJ.LINKDBS.Seq(i);
Each link database has the same properties as the DB object above.

1.14.4 Using User Code


To provide full code generation flexibility. It is allowed to override an existing code
generating function or create your own custom code generating function to suit your needs.
To do this you need to write your JavaScript functions and place them in the User Code File
for the changes to take effect.
By default, the User Code File is named as "usercode.js" and can be found under the "src"
subfolder of the installed directory. However, you can rename it or put it elsewhere if
necessary. In that case, you need to modify the following registry key:

HKEY_CURRENT_USER\Software\<product name>\<version>\Settings\General
Value name: UserCode
Using User Code requires knowledge in JScript. If you are not familiar with the scripting
language, refer to the JScript. In most cases you only need to use the most basic string
functions.
Note

I. Overriding System Function


In the User Code File, you can override virtually all exposed functions. Refer to the System
Functions(See 1.14.2) list for functions that you can override.
Although there are many system functions, in real applications you usually only need to
customize a few of them, for example,

268

PHPMaker 12 Help
Script_View - This function generates code to render the fields in list, view and delete
pages.
Script_Edit - This function generates insert/update codes for the fields in add/copy and edit
pages.
FieldView - This function outputs code for displaying the field in list, view and delete pages.
FieldEdit - This function outputs code for the field as form elements in add/copy, edit and
search pages.
In general, you compare the generated codes with the corresponding page in the template,
find out which tag generate the codes you want to customize. Then you can call the replace
or concat method of the system function in the User Code File. Both mehtod is same as the
JavaScript replace and concat methods.

SYSTEMFUNCTIONS.<Function>.replace("original code", "your code");


SYSTEMFUNCTIONS.<Function>.concat("your code 1", "your code 2", ...);

where <Function> is the system function name.


Follow the following steps to override a system function. For example, if you want to
override the function FieldView,
Step 1 - View the original code first, make sure the codes you want to replace is indeed
generated by the function.
Example

SYSTEMFUNCTIONS.FieldView.modifiers.push(function() {
alert(this.result); // View the old value
});

Step 2 - Generate scripts, view the generated code, copy the code you want to replace,
modify it as you need.
Step 3 - Replace it.
Example 1 - Directly replace part of the code

SYSTEMFUNCTIONS.FieldView.replace(<old_code>, "new_code"); // Replace


part of the code
<old_code> is part of the old code to be replaced, it can be a string or regular expression.
Example 2 - Find the part of code to be replaced and then modify and replace it

var OriginalCode = SYSTEMFUNCTIONS.FieldView.result;


var StartPos = OriginalCode.indexOf("start_code"); // Find the start
position of the old code
var EndPos = OriginalCode.indexOf("end_code", StartPos); // Find the
end position of the old code
if (StartPos > -1 && EndPos > -1 && EndPos > StartPos) { // Found
var OldCode = OriginalCode.substring(StartPos, EndPos +
"end_code".length); // Extract the code starting with "start_code" and
ends with "end_code"
var NewCode = ...OldCode...; // Write your code to modify the old
code as you need

269

PHPMaker 12 Help
SYSTEMFUNCTIONS.FieldView.replace(OldCode, NewCode); // Replace
the old code
}
Example 3 - Append your code to the end of the original code

SYSTEMFUNCTIONS.<function>.concat("<code_1>", "<code_2>", ...);


Example 4 - Use your own function to modify the code. Add your function to the System
Function's modifiers which is an array of functions, you can add as many modifier functions
as you need.

SYSTEMFUNCTIONS.FieldView.modifiers.push(function() {
//alert(this.result); // View the old value
var newvalue = <your code here>; // Modify the oldvalue or write
your own code
this.result = newvalue; // Overwrite value
});

II. User functions used in Extensions


The user functions used in Extensions must take the following form:

var <Ext> = {
FieldEdit_Prefix: function(ctl, ctlid) {
return "...";
}
FieldEdit_Suffix: function(ctl, ctlid) {
return "...";
}
}
It is a user object with name <Ext> which should be the same as the extension name. It
contains two methods "FieldEdit_Prefix" and "FieldEdit_Suffix". The "FieldEdit_Prefix"
method returns a prefix value which is appended to the start of the output from the
"FieldEdit" system function. Similarly, the "FieldEdit_Suffix" method returns a suffix value
which is appended to the end of the output from the "FieldEdit" system function. Both
methods take on a parameter "ctl" which contains the name of the field control to be
created. The parameter "ctlid" contains an ID which denotes the mode of the control, e.g.
"add", "edit", etc.. (See usercode.js in the "jscalendar" and "fckeditor" extensions as
examples.)

Also See:
Customizing Template
(See 1.14)Template Tags(See 1.14.5)
Template Object Properties(See 1.14.3)
System Functions(See 1.14.2)

270

PHPMaker 12 Help

1.14.5 Template Tags


The code generator processes the following template tags inside the templates to generate
the working codes, intermediate or advanced users can make use of these tags to create
custom templates. These tags are case-insensitive. All template tags have the same basic
syntax:
Syntax:
<!--##...##-->
Due to the HTML comment style format, these script blocks will be treated as HTML
comments in any editors. Therefore, you can use your favorite editor to edit the template
provided that these special tags are kept in place.
It is important to understand how templates tags works. During code generation, the code
generator reads the template file, executes the scripts in the template tags, and finally,
write the codes to the output file.

1. Session Tags
Syntax:
<!--##session session_name##-->
...session content here...
<!--##/session##-->
Notes

1. The keyword "session" is immediately after the start tag <!--##,


2. The session_name is the name of the session, only alphanumerical characters should
be used, no spaces, and it is not quoted,
3. The tags must be in pairs, with a start session tag and an end session tag,
4. The end session tags contain a "/" immediately after the tag, i.e. <!--##/.
The code generator locates the source of a output file according to the sequence of sessions
specified in the control.xml of the template. Each session tag carries a session name that
identifies the lines of code that will be extracted.

2. Script Block
To generate codes according to the project settings, there are many script blocks in each
session. Each script block is enclosed by special start and end tags.
Syntax:
<!--##
...Script here...
##-->
The scripting language used in the script block is JScript provided by Windows Script. To
customize template, you need to know JScript.
In a script block, you can create variables and constants, use conditional statements, do
looping, write procedures, etc. You can also access all settings in the project within the

271

PHPMaker 12 Help
script block. (See Template Object Properties(See 1.14.3) for details.) With script blocks,
you can generate virtually any codes you want.
Example

<!--## if (TABLE.TblType == "VIEW") { ##-->


...code here...
<!--# } ##-->
In this example the codes in between will only be generated if the table is a view. "TABLE" is
a template object and "TblType" is one of its properties.

3. Function Block
Function block output an object property as string or output a string return by a function.
Syntax:
<!--##=...##-->
Note the "=" symbol immediately after the start tag.
The function can be a built-in system function or an user function defined in user code file
(see Using User Code(See 1.14.4)). You can refer to the System Functions(See 1.14.2) list
for functions that you can call or override.

Format
Syntax:

<!--##=Object.Property##-->

Example 1 - Accessing object property

<!--##=PROJ.ProjName##-->
This line will write the project name in the output file.
Example 2 - Calling a function

<!--##
// This is a script block
function MyFunction() {
return "This is my custom function";
}
##-->
<!--##=MyFunction()##-->
This line calls the function "MyFunction" and write the string returned by the function in the
output file. In real cases, the returned string is the code you want to generate.

4. Function Block with Indentation

272

PHPMaker 12 Help
Syntax:
<!--##~...##-->
Note the "~" symbol immediately after the start tag. This function is same as function block
above except that output block will be indented with the space before the block.

Also See:
Template Object Propeties(See 1.14.3)
System Functions(See 1.14.2)
Using User Code(See 1.14.4)

1.15 Tutorials

Master/Detail(See 1.15.2)

File Upload to Database(See 1.15.3)

File Upload to Folder (See 1.15.4)

Dynamic Selection Lists(See 1.15.5)

Field Aggregation(See 1.15.6)

User Registration System(See 1.15.7)

Inline Add, Inline Copy, Inline Edit, Grid Add and Grid Edit(See 1.15.8)

Advanced Security - User ID Security(See 1.15.9)

Advanced Security - Static User Level Security(See 1.15.10)

Advanced Security - Dynamic User Level Security(See 1.15.11)

Custom View(See 1.15.12)

Report(See 1.15.13)

Integrating with Existing PHP Report Maker Project(See 1.15.14)

273

PHPMaker 12 Help

1.15.1 Connecting Remote MySQL using


PHPMaker Connection Script
In this tutorial we will show you how to use the new connection method which can connect
to any remote database using a PHP script provided by PHPMaker.
Steps to Setup Remote Connection
1. Uploading the PHP script to your site
The connection is named phpmaker.php and can be found under the installation folder,
e.g. C:\Program Files\PHPMaker 12. Upload the script to site first.
Always use the script shipped with your version of PHPMaker. PHPMaker may not
work with script shipped with previous versions.
Important

2. Testing the script


If this is the first time to use this connection method, you may want to test the script and
get to understand how it works. You don't need to test the script as described in this step
next time. Instead, you can simply press the [Test] button in PHPMaker to test the script
after entering the URL.
a.

Browse to the script using your browser

b.
Enter the connection information and and select the encoding if necessary, click
[Get Database List], a combobox populated with the available databases should be shown.
Select the Database you want to connect, click [View Schema]

274

PHPMaker 12 Help

c.
If you can view the schema of database in XML like the follows, the script is working
properly. PHPMaker will talk to this script similarly and get the database schema over HTTP.

3. Loading PHPMaker
Open PHPMaker, enter the connection information, URL of the script and encoding if
necessary.
Note that you are actually connecting to your database through the PHP script on the server,
so in most cases the host/server name is "localhost" unless the database server is not
installed on the same server as the Web server.

275

PHPMaker 12 Help
Click the dropdown button of database combobox, you should be able to see the available
database. Select your database, click the [Connect] button. The database info should be
loaded and displayed in the left pane.

Using File URL


If for some reason you cannot get the database schema using HTTP, you can also save the
schema in your browser (Step 3.c. above) as a local .xml file and enter the file URL, e.g.
"file://C:\phpmaker.xml", to connect.

1.15.2 Master/Detail
In this tutorial we will show you how to setup Master/Detail table view in PHPMaker. We will
use the demo database for demonstration.
In the demo, there are two tables called "orders" and "orderdetails". We will set up the
master/detail relation between these two tables.
Fields in Table "orders"

276

PHPMaker 12 Help

Fields in Table "orderdetails"

Steps to Setup Master/Detail Records


1. Loading PHPMaker
Open PHPMaker and connect to the demo database.
2. Setting up Master/Detail Relationship
Select either the master or detail table in the Database tree view (the left pane). In this
example, we choose the master table - "orders" table. The Table Setup page is displayed in
the right pane.

277

PHPMaker 12 Help

Then in [Master/Detail] panel at the bottom right corner of the page, click [Modify...] to
bring up the visual master/detail relationship editor. Drag the detail table from the table list
on the left to the diagram on the right.

Then create a relationship between them by dragging from the master field (key field in
master table) to the detail field (foreign key field in the detail table).

278

PHPMaker 12 Help

If there are more linked field, repeat the step until all the relationships are setup. In this
tutorial, we only have one detail field (`orderdetails`.`OrderID`) and one master field
(`orders`.`OrderID`).
PHPMaker supports multiple master/detail, if the table has other master tables or detail
tables, just repeat above process. In this example, we have only one master/detail
relationship, so we click [OK] to confirm. The master/setail relationship is setup.

If you want referential integrity, you can enable Referential Integrity, Cacade Delete
and/or Cascade Update, see Table Setup(See 1.10.6) -> Master/Detail(See 1.10.6) for
detail.
If you want to enable Master/Detail-Add, Master/Detail-Edit and/or Master/DetailView, enable them for the detail table in the Table Setup page:

279

PHPMaker 12 Help

If the master table has more than one detail tables, you can choose Multiple detail tables.
By default each detail table occupies a column in the main table of the List page, if Multiple
detail tables is enabled, the columns will be combined as one.
If you have the Preview extension (for registered users only) and want to enable detail
record preview by Ajax, you can click Tools(See 1.13) -> Extensions(See 1.13) to enable it.
Also see Third-Party Tools(See 1.7).

Enable the extension and then click the Advanced tab to set your settings for each table:

280

PHPMaker 12 Help

Notes

1. The Preview extension works best when the number of the fields and number of
records are not too many so the size of the preview area will not be too large.
Otherwise the preview area may exceed the browser area and therefore the detail
records cannot be viewed completely at a glance.
2. If PreviewRow is enabled, the individual detail table columns will become hidden.
3. PHP Script Generation
Click the [Generate PHP] icon to go to the [Generate] tab, click the [Generate] button.
PHPMaker will generate the required PHP scripts automatically.
4. Running the PHP Application
Click on the link to the "orders" table, there will be a new column for the "orderdetails "
table. Click on the "orderdetails" button to access the order details for the selected record.
Click the down arrow button and then click Master/Detail View, Master/Detail Edit or
Master/Detail Copy to view/edit/copy and selected record and its detail records.

281

PHPMaker 12 Help

If you have enabled Preview extension and enable PreviewOverlay, move your mouse
cursor over the "orderdetails" button and you'll see detail records preview:

If you have enabled Preview extension and enable PreviewRow, click the [+] button in
the row and and you'll see the preview row:

282

PHPMaker 12 Help

Click the Master/Detail View link/button, the View page of the master table with a detail
table grid of the detail table will be shown.

283

PHPMaker 12 Help

Click the Master/Detail Edit link/buttonk, the Edit page of the master table with a detail
table grid of the detail table will be shown.

284

PHPMaker 12 Help

Click the Master/Detail Copy link/button, the Add page (in Copy mode) of the master
table with a detail table grid of the detail table will be shown.
Click the Add orders/ordertails button in the paging section, the Add page of the master
table with a detail table grid of the detail table will be shown.

285

PHPMaker 12 Help

In Master/Detail-Add/Copy/Edit mode, you can click Add Blank Row or Delete button to
add or delete rows wiithout refreshing the page. Note this feature is implemented by
JavaScript.

1.15.3 File Upload to Database


In this tutorial we will show you how to setup File/Image Upload in PHPMaker. We will use
the demo database for demonstration.
Fields in Table "Cars":

286

PHPMaker 12 Help

We want to setup the "Picture" field in the "Cars" table for image upload to database.
Note

You must choose a field of binary type.

Steps to Setup File/Image Uploading


1. Loading PHPMaker
Open PHPMaker and connect to the demo database.
2. Setting File Upload Properties
Go to the PHP -> General Options tab.
If you want to change the file size limit on uploading, enter a limit in bytes for the Max file
size field. The installation default is 2,000,000 bytes.
Note: Configurations of PHP, web server and database affects max file size also, read PHP
Settings(See 1.10.2).
In Allowed file type, enter the file extensions that you allow user to upload.
Since we upload to database, the uploaded files will be stored in database as binary data,
there is no need to set the Upload folder and Delete file on update/delete.

287

PHPMaker 12 Help

3. Setting File/Image Properties


To set up the file/image properties for the "Picture" field, select the "Cars" Table on
Database pane and then click on the "Picture" field.

You can optionally set up the following fields in Edit Tag panel. If the files to be uploaded
are of normal browser supported image types (e.g. jpg/gif), you can skip the file type field,
otherwise the File Type Field should be set.
File type field - save the file content type of the uploaded file/image (Mandatory)
File name field - save the name of uploaded file/image (Optional)
File size field - save the size of uploaded file/image (Optional)

288

PHPMaker 12 Help
Image width field - save the width of the image (Image Only, Optional)
Image height field - save the height of the image (Image Only, Optional)
Once setup, PHPMaker will use these fields for storing/displaying the uploaded file/image
information.
Do not specify file name field if you want IE to open the file automatically. (IE may fail
to open non-image files retrieved from database.) Only use file name field if you want IE to
popup a File Download dialog for user to save the file with the filename specified in the file
name field.
Note

Again, since we upload to database, the uploaded files will be stored in database as binary
data, there is no need to set the Upload folder.
If you are uploading image, you can choose to resize the image. Check Resize image and
enter the Resize width and Resize height.
Note

Requires PHP GD extension and supports GIF, JPEG and PNG only.

4. Change File/Image Display Style

289

PHPMaker 12 Help

You can choose to display the file/image field using the Formatted Text
Image

View Tag or

View Tag. Default is Formatted Text.

Formatted Text View Tag will display the field as a hyperlink to the file/image.
Image View tag will display the field as image using <IMG> tag and is also hyperlinked to
the image. To change image display style to Image, click on the Image
Tag Panel for the settings.

icon in the View

Only image files can use the Image View Tag. Other files such as PDF cannot be
displayed as image. If the field contains mixed file types, do not use Image View Tag.
Note

If the dimensions of the image you want to display are different from the stored image, you
can choose to Resize image. If enabled, the image will be resized to the specified width
and/or height on display. Again, resizing requires PHP GD extension, see the note above.
If you want to add hyperlink to the image, set the HREF field. If you want the image linked
to the file, select the field itelf as the HREF field. If you want to image linked to other URL,
select another field which stores the URL. You can also optionally set the target of the
hyperlink.
5. PHP Script Generation
Click the Generate button and PHPMaker will generate the required PHP scripts
automatically.
6. Running the PHP Application
Click on the link to the Cars table. You should now be able to add, view, edit and delete
records with file/image fields.
Formatted Text View Tag will display the field as a hyperlink to the file/image if you have
selected the field itself as the HREF field:

Image View tag will display the field as image using <IMG> tag and is also hyperlinked to
the image:

290

PHPMaker 12 Help

The Add/Edit page will allow you to delete or upload another file/image:

Also see:
File/Image Upload to Folder(See 1.15.4)

1.15.4 File Upload to Folder


In this tutorial we will show you how to setup file upload to folder in PHPMaker. We will use
the demo database for demonstration.
Fields in Table "Cars":

291

PHPMaker 12 Help

We want to setup the "PictureName" field in the "Cars" table for image upload to folder. Note
that unlike in the tutorial File Upload to Database(See 1.15.3) in which we used a binary
field ("Picture") to store data in database, this time we choose "PictureName" which is a text
field only. It is because this field will be used for storing the filename, the uploaded file will
be stored in the upload folder as a physical file.
Note

You must choose a field of string type.

Steps to Setup File/Image Uploading


1. Loading PHPMaker
Open PHPMaker and connect to the demo database.
2. Setting File Upload Properties
Go to the PHP -> General Options tab.
If you want to change the file size limit on uploading, enter a limit in bytes for the Max file
size (bytes) field. The installation default is 2,000,000 bytes.
NoteConfigurations

of PHP, web server and database affects max file size also, read PHP
Settings(See 1.10.2).
In Allowed file type, enter the file extensions that you allow user to upload.
Then, you need to enter the Upload folder. (Do NOT leave it empty.) This folder should be
a subfolder relative to the root of the PHP application. For example, you can enter "uploads/"
(use slashes "/" as path delimiter). If the root of the PHP application is
C:\Inetpub\wwwroot\projectname\, then the upload folder is
C:\Inetpub\wwwroot\projectname\uploads\.
Make sure that the Web server user has read/write access to the folder. See Application
Root(See 1.11).

292

PHPMaker 12 Help
NoteThe

Max file size (bytes), Allowed file type and Upload Folder here are global
settings for all fle upload fields, you can also enter field specific settings in the Edit Tag
panel (see below).
If want to delete the uploaded file when the field value is replaced, removed or if the record
is deleted, check Delete file on update/delete.
If Delete file on update/delete is enabled, the uploaded file will be deleted. If the deleted
record is a copied record, deleting the uploaded files will affect the original record. To
prevent such possible problem, enable Advanced Setting Create upload file on copy (see
Advanced Settings(See 1.13)) to duplicate the uploaded file when copying a record.

3. Setting File/Image Properties


To set up the file/image properties for the "PictureName" field, select the "Cars" Table on
Database pane and then click on the "PictureName" field.

293

PHPMaker 12 Help

In the Edit Tag Panel, click the File Upload icon


type="file">).

to select the Edit Tag as "FILE" (<input

If you want to allow mulitple file upload, enable Multiple. If enabled, the field value will
store comma separated file names of the uploaded files.
File type field, File name field, File size field, Image width field and Image
height field are NOT applicable to upload to folder. It is because the files uploaded to folder
are physical files on your server, there is no need to store the file information in the
database except the file name for identifying the file.
Note

If you are uploading image, you can choose to resize the image. Check Resize image and
enter the Resize width and Resize height.
Note

Requires PHP GD extension and supports GIF, JPEG and PNG only.

If you have field specifc settings for Upload folder, Allowed file types, Max file size
(bytes) and Max number of files, enter them as needed. See Field Settings(See 1.10.5)
for detail.

4. Change File/Image Display Style

294

PHPMaker 12 Help

You can choose to display the file/image field using the Formatted Text
Image

View Tag or

View Tag. Default is Formatted Text.

Formatted Text View Tag will display the field as a hyperlink to the file/image.
Image View tag will display the field as image using <IMG> tag and is also hyperlinked to
the image. To change image display style to Image, click on the Image
Tag Panel for the settings.

icon in the View

Only image files can use the Image View Tag. Other files such as PDF cannot be
displayed as image. If the field contains mixed file types, do not use Image View Tag.
Note

If the dimensions of the image you want to display are different from the stored image, you
can choose to resize it. If enabled, the image will be resized to the specified width and/or
height on display. Again, resizing requires PHP GD extension, see the note above.
If you want to add hyperlink to the image, set the HREF field. If you want the image linked
to the file, select the field itelf as the HREF field. If you want to image linked to other URL,
select another field which stores the URL. You can also optionally set the target of the
hyperlink.
5. PHP Script Generation
Click the Generate button and PHPMaker will generate the required PHP scripts
automatically.
6. Running the PHP Application
Click on the link to the Cars table. You should now be able to add, view, edit and delete
records with file/image fields.
Formatted Text View Tag will display the field as a hyperlink to the file/image.

Image View tag will display the field as image using <IMG> tag and is also hyperlinked to
the image:

295

PHPMaker 12 Help

The edit page will allow you to delete or replace an existing file/image:

If you upload files to folder and the destination file already exists, the file name will be
changed automatically. By default an index in the format of "(n)" will be appended to the
end of the file name where n is an integer. If you prefer renaming the file with another
name, you can use Row_Updating and/or Row_Inserting server event and change the
file name field value, see Server Events and Client Scripts(See 1.10.9).
Note

Also see:
File Upload to Database(See 1.15.3)

1.15.5 Dynamic Selection List


In this tutorial we will show you how to setup a selection list with options that change
dynamically based on option selected in another selection list . We will use the demo
database for demonstration. The "cars", "trademarks" and "models" tables will be used in
the example.
We'll generate Add or Edit page for the "cars" table, in the page two selection lists will be
generated for the "Trademark" and "Model" fields using the "SELECT" Edit Tag. When the
user choose a trademark in the trademark selection list, the options in the model selection
list will be changed accordingly. Only models belonged to the selected trademark will be
shown. We refer to the "Trademark" field as the parent field and the "Model" field as the
child field.
Table "cars" having 2 fields named "Trademark" and "Model"

296

PHPMaker 12 Help
Table "trademarks" - Lookup Table for the parent field "Trademark" in "cars" table

Table "models" - Lookup Table for the child field "Model" in "cars" table

Each child field's lookup table must have a Filter field storing key field value of the
parent field.
Note

In this example, the "Models" table has an integer field named "Trademark" storing the
trademark ID of the model.

Steps to Setup selection list with dynamic options


1. Loading PHPMaker
Open PHPMaker and connect to the demo database.
2. Setting up the selection lists
Click "cars" table on the Database pane.
Select field "Trademark" and click on [SELECT] on the [Edit Tag Panel]. Check [Use
Lookup Table] checkbox on the [Edit Tag] panel and enter the following setting.

To set up child fields, click [Child lookup fields...] and enter the following settings:

297

PHPMaker 12 Help

[Link field] is the field (in lookup table) whose value is actually saved. In this example, the
field value of models.ID (NOT models.Model) will be saved to the field cars.Model.
[Filter field] is the field (in lookup table) by which the lookup table records are filtered.
Only records with a Filter field value matching the selected value of the parent selection list
will be shown. In this example, only models with Trademark field value matching the
selected Trademark ID in the parent selection list are shown.
Click [OK] to confirm.
If you now select the Model field, you'll see:

You can optionally check Use Ajax for both selection lists. If Use Ajax is enabled, the
selection list will be updated by Ajax. The advantage of using Ajax is that if you have large
lookup tables, the time to load the page will be much shortened because there are only
Note

298

PHPMaker 12 Help
selected option(s) in the selection lists initially. The disadvantage is that it takes some time
for Ajax to populate the selection lists after the page is loaded in the browser.
3. PHP Script Generation
Click the [Generate] button and PHPMaker will generate the required PHP scripts
automatically.
4. Running the PHP Application
Click on the link to the "Cars" table and go to the Edit page. The options in the model
selection list will be changed automatically when the selected option in trademark selection
list is changed:

1.15.6 Field Aggregation


In this tutorial we will show you how to setup Field Aggregation in PHPMaker. We will use
the demo database for demonstration.
PHPMaker supports three types of Field Aggregation:

Total
Count
Average

The "Order Details Extended" view in the demo will be used in this example. We will set up
"Field Average" for the Quantity field and "Field Total" for the ExtendedPrice field.
Fields in view "Order Details Extended"

299

PHPMaker 12 Help

Steps to Setup Field Aggregation


1. Loading PHPMaker
Open PHPMaker and connect to the demo database.
2. Setting up Field Aggregation
To set up the Field Average for the "Quantity" field, select the "Order Details Extended" View
on Database pane and then click on the "Quantity" field. Select "AVERAGE" for the
"Aggregate" column of this field.

To set up the Field Total for the "ExtendedPrice" field, select "TOTAL" for the "Aggregate"
column of the "ExtendedPrice" field.

300

PHPMaker 12 Help
3. PHP Script Generation
Click the [Generate] button and PHPMaker will generate the required PHP scripts
automatically.
4. Running the PHP Programs
The Field Aggregate will be shown in the footer of the "Order Details Extended" list page as
follow:

1.15.7 User Registration System


In this tutorial we will show you how to setup User Registration System in PHPMaker. We will
use the demo database for demonstration.
We want to set up the "Employees" table for Registration System.
Fields in the User Table, "Employees":

301

PHPMaker 12 Help
Steps to Setup Registration System
1. Loading PHPMaker
Open PHPMaker and connect to the demo database.
2. Enabling Security and Setting up User Table
Advanced Security has to be enabled first. Click the [Security] tab, check [User Existing
Table], select the [Table], the [Login Name Field] and the [Password Field]. The
[Advanced] button will be enabled.

3. Setting up Registration System


Click the [Advanced] button, the Advanced Security window will appear. Click [User Login
Options] node in the left pane.

302

PHPMaker 12 Help

In this example, we use the following options:


User Registration Page

Generate user registration page and add a link in login page.


Enabled - Enable registration page
CAPTCHA (required extension) - Optionally use CAPTCHA for
registraion form
Confirm before submit - Optionally let user view the input
before submitting the registraion form
Send email - Optionally send email confirmation after
registraion
Requires activation - Optionally requires user click an
activation link in the email sent after registration to activate the
user account. (Send email is required.)

Change Password Page

Enabled - Enable change password page


Send email - Optional email confirmation after changing
password

Password Recovery PageEnabled - Generate password recovery page (forgot password


page) and add a link in login page. User name and password will
be sent to the user's email address.

303

PHPMaker 12 Help
Email Field

User Email Address Field in user table used for sending email

Activated Field

User Activated Field in user table used for storing the status of
user. A boolean field is recommended, although an integer field
or a string field will also work.
To enable user account activation, the Requires activation
and Send email options under User Registration Page must
be checked. The user needs to click an activation link in the
email sent after registration to activate the user account.
Note

See Security Settings(See 1.10.4) for complete description of the options.


For user registration page, you can select which fields to be included in the page. Click the
[...] button in the [Fields] row.

Click [>] to select the field or [>>] to select all fields to be included in registration page.
Note that the password field is mandatory. Since we have chosen options that will send
emails, the Email field must be included also.
If you use User Level Security also, you should not include the User Level field because a
new user is not supposed to choose his/her own User Level. If the User Level field is not
included, the default User Level for new user will be 0 (Anonymous). You can assign a
suitable User Level to the user later by logging in as an administrator. Alternatively, you can
also set a default value for the User Level field in your database or in PHPMaker. Then the
new user will get the default User Level immediately after registration.
Click [OK] to finish.
If you have enabled any of the email sending features, you must enter the SMTP server
information in the [PHP]->[Email Settings] tab:

304

PHPMaker 12 Help

See Email Settings in PHP Setup(See 1.10.2) for details.


4. PHP Script Generation
Click the [Generate] button and PHPMaker will generate the required PHP scripts
automatically.
5. Running the PHP Application
Run the generated scripts. In login page, the "Register" link and "Forgot Password" link are
displayed.

Click the "Register" link, you will be redirected to the registration page. Note that a "Confirm
Password" field and JavaScript validation are added automatically.

305

PHPMaker 12 Help

Click the "Forget Password" link, you will be redirected to the request password page.

If the email address entered by the user can be found in the user table, the password will be
sent to the email address.
After login, a "Change Password" link is added in the menu before "Logout". Click it and
you'll be redirect to the change password page.

The contents of the email contents can also be modified in the template. The files are
register.html, changepwd.html and forgotpwd.html.
For example, the forgot password email content template (forgotpwd.html) is like the
follows. The format is self-explanatory.

Subject: Password Request


From: <!--$From-->
To: <!--$To-->

306

PHPMaker 12 Help
Cc:
Bcc:
Format: HTML
<p>Dear Sir/Madam,</p>
<p>Please see below for the requested information:</p>
<p>
Username: <!--$UserName--><br>
Password: <!--$Password-->
<p>
<p>Please feel free to contact us in case of further queries.</p>
<p>
Best Regards,<br>
Support
</p>
The following special tags are used in the email templates:

<!--$From--> is sender email address


<!--$To--> is user email address
<!--$UserName--> is user login name (for forgotpwd.html only)
<!--$Password--> is user password (for forgotpwd.html and changepwd.html only)
<!--FieldName--> (without the $ symbol) is the field value (for register.html only), e.g.
<!--LastName--> is the field value of the field "LastName".
<!--FieldCaption_FieldName--> (without the $ symbol) is the field caption (for
register.html only), e.g. <!--FieldCaption_LastName--> is the field captionof the field
"LastName".
You can also dynamically change the email by code using Email_Sending event before the
email is sent. (See Server Events and Client Scripts)(See 1.10.9)

1.15.8 Inline Add, Inline Copy, Inline Edit,


Grid-Add and Grid-Edit
In this tutorial we will show you how to setup Inline/Grid Add/Copy/Edit in PHPMaker. We
will use the demo database for demonstration.
Inline Edit allows users edit a record without going to edit page but in the list page.
We'll set up the "Suppliers" table for Inline Edit.
Fields in Table "Suppliers"

307

PHPMaker 12 Help

Steps to Setup Inline Edit


1. Loading PHPMaker
Open PHPMaker and connect to the demo database.
2. Setting Inline Edit
Click the [Tables] node on the database pane or click the [Tables/Views] icon on the
toolbar. The Table Setup page in the database is displayed. Select Suppliers and check on
the [Inline Add], [Inline Copy], [Inline Edit] and [Grid-Edit].

Note: Make sure you table has primary key, or records cannot be located and
edited.
Click the table "Suppliers" on the database pane. The Field Setup page for the table
Suppliers is displayed.

308

PHPMaker 12 Help

The fields to be displayed in the list page is shown in the [List] column under the [List
Page] Section. These fields are editable in the Inline/Grid Add/Copy/Edit mode.
3. PHP Script Generation
Go to the [Generate] tab, click the [Generate] button and PHPMaker will generate the
required PHP scripts automatically.
4. Running the PHP Application
Run the scripts in your browser, click on the link to the "Suppliers" table, there will be new
links for "Inline Add", "Inline Edit", "Inline Copy", "Grid Add" and "Grid Edit".

Click on the "Inline Edit" link to enter Inline Edit mode. The selected record will be
highlighted and entered into Inline Edit mode. Click on the "Update" link to update the
record or click "Cancel" to cancel update.

309

PHPMaker 12 Help

Now, click on the "Inline Copy" link for a record to enter Inline Copy mode.

Click on the "Insert" link to insert the new record or click "Cancel" to cancel.
Now click on the "Inline Add" link to enter Inline Add mode.

Click on the "Insert" link to insert the new record or click "Cancel" to cancel.
Now click on the "Grid Edit" link to enter Grid-Edit mode.

310

PHPMaker 12 Help

Click on the "Save" link to update the records or click "Cancel" to cancel.
Now click on the "Grid Add" link to enter Grid-Add mode.

Click on the "Insert" link to insert the new record or click "Cancel" to cancel.
In Grid-Add/Edit mode, you can click "Add Blank Row" or "Delete" to add or delete rows
without refreshing the page. Note that this feature is implemented by JavaScript.

1.15.9 Advanced Security - User ID Security


In this tutorial we will show you how to setup User ID Advanced Security Access in
PHPMaker. We will use the demo database for demonstration.
User ID
User ID Security secures data at record level. Protected tables must have an User ID field
for identifying which user a record belongs to. The User ID field names can be different in
tables though. When User ID security is enabled, users can only access their own data.
The "Employees" table and "Orders" table in the demo will be used in this example.
Fields in Table "Employees"

311

PHPMaker 12 Help

Fields in Table "Orders"

Steps to Setup Advanced Security


1. Loading PHPMaker
Open PHPMaker and connect to the demo database.

312

PHPMaker 12 Help
2. Setting up Security
Click on the [Security] tab, there are two sections for the login process:
Administrator Login
If you tick this option, a hard-coded Administrator account will be generated which has all
access right to all tables/views.
Use Existing Table
Tick this option to set up the user access levels. You should select the security table and the
corresponding Login Name and Password fields.

To set up the user ID, click on the [Advanced] button. A popup window will appear.
3. Setting up User Access Own Data
You can set up the [User ID] Field and [Parent User ID] as follow:

313

PHPMaker 12 Help

As the caption suggests, the User ID Field is a field to identify users. The field values for
each user must be unique. So typically the primary key of the User Table is used as User ID
Field.
To identify the records owned by a user, the records must also have a field to store the User
ID value. Therefore, all protected tables must have an User ID field, the field names can be
different though. To setup User ID field for each table,
1. Click on User ID in the left pane,
2. Select the User ID field from your user table, (otherwise the feature is disabled)
3. In the User ID Field column, select the User ID Field for the tables/views that
requires User ID security
[Parent User ID] field stores the parent User ID that the user belongs to. For example, a
parent user can be the manager that the employee reports to. You can select an Parent User
ID for users so the parent user can modify the child users' records as his/her own.
(otherwise the feature is disabled)
Parent User ID is hierarchical, parent users can access the records owned by the child
users of their child users, and there is no limit of levels.
Note

In this example, we set the Parent User ID Field as the "ReportsTo" field.
4. PHP Script Generation
Click the [Generate] button and PHPMaker will generate the required PHP scripts
automatically.
5. Running the PHP Programs
Login as employee #1 using "nancy" and user name and "1234" as password. Go to the
"Orders" table. As we have used User ID security for the table, although we can still view all
the records, we can only modify employee #1 (nancy)'s records.

314

PHPMaker 12 Help

If you now log out and login again as employee #3 using "janet" as user name and "1234"
as password, you can only modify employee #3 (janet)'s records:

But if you now logout and login again as employee #2 using "andrew" as user name and
"1234" as password, you can only access employee #1(nancy), #3 (janet), #4(margaret),

315

PHPMaker 12 Help
#5(steven) and #8(laura)'s records because "andrew" is the parent user of them, all these
users report to "andrew".

Notes

1. Only Administrator can manage User ID and Parent User ID.


2. There are two types of Advanced Security - User ID Security and User Level
Security. User ID Security secures data at record level and User Level Security
secures data at table level. They can work independently or work together. See the
following tutorials on User Level Security also.
Also see:
Advanced Security - Static User Level Security
Advanced Security - Dynamic User Level Security (See 1.15.10)

1.15.10 Advanced Security - Static User Level


Security
In this tutorial we will show you how to setup static User Level Security in PHPMaker. We will
use the demo database for demonstration.
User Level
User Level Security secures data at table level. Each user level is granted with specific
permissions to tables in the database. Users with different access levels are restricted with
different add/copy, list/search/view, delete and edit rights.

316

PHPMaker 12 Help
There are 2 types of User Level security:
1. Static User Levels - the User Levels and the permissions are defined in the project and
the User Levels are not to be changed after script generation.
2. Dynamic User Levels - the User Levels and the permissions are defined in 2 tables in
the database, the User Levels can still be changed with the generated scripts.
In this tutorial we use static User Level Security.
The "Employees" table and "Orders" table in the demo will be used in this example.
Fields in Table "Employees"

Fields in Table "Orders"

317

PHPMaker 12 Help

Steps to Setup Static User level Security


1. Loading PHPMaker
Open PHPMaker and connect to the demo database.
2. Setting up User Access Levels
Click on the [Security] tab, there are two sections for the login process:
Administrator Login
If you tick this option, a hard-coded Administrator account will be generated which has all
access right to all tables/views.
Use Existing Table
Tick this option to set up the user access levels. You should select the security table and the
corresponding Login Name and Password fields.

318

PHPMaker 12 Help

To set up the user levels, click on the [Advanced] button. A popup window will appear.
Click on the [User Levels] button. Select the User Level Field.
The User Level field must be of integer data type. Non integer fields will not be
seen in the User Level Field combobox.
Important

There are three built-in user levels:


Anonymous - Anonymous is a built-in user level for anonymous users (i.e. users that have
not logged in). The User Level ID of Anonyous is -2.
Administrator - Administrator is a built-in user level that has all permissions plus the
privileges to modify User IDs and User Levels. Its permissions are same as that of the hardcoded Administrator. The User Level ID of Administrator is -1.
Default - Default user level is built-in user level with user level = 0. Since User Level field is
an integer field, if you set a default value of 0 for this field, this user level will become the
default user level for the user after registration and before the Administrator assigning
another higher user level.

319

PHPMaker 12 Help

Click
finish.

to add a new user level. Enter the description, and default permissions. Click OK to

For each user level, you can set refine the permission for different tables/views. Click OK to
finish.

320

PHPMaker 12 Help

If you go to Field Setup Page now and view the Edit Tag for the User Level Field, you should
see that the Edit Tag has been setup as "SELECT" and the user levels have been added
automatically in the value list:

3. PHP Script Generation


Click the [Generate] button and PHPMaker will generate the required PHP scripts
automatically.
4. Running the PHP Application
To assign different user level for the users, login as Administrator and go to the user table
(the "Employees" table in this case). You'll find that the Edit Tag of the User Level Field is
setup as "SELECT" (combobox) and the combobox is populated with the user levels we
defined above automatically.

321

PHPMaker 12 Help

We assign a password and the user level "Sales" to the employee #1 (the employee with
EmployeeID equals 1). Then we logout.
To see the Advanced Security works, we login again as employee #1 using "nancy" as user
name and "1234" as password.
According to the user level defined by us, users with "Sales" level has view and add
permissions to the "Orders" table only. They are not allowed to update or delete records.
Employee #1 belongs to the "Sales" level, so we do not see the links to the edit/delete page.

Notes

1. Users have no right to change his own user level. Only Administrator can change an
user's user level. If you want to assign user levels in the generated scripts, a hardcoded administrator login account must also be created. Alternatively, an user must
be assigned with the Administrator level. However, you may still need to use the
hard-coded Administrator Login to log in and assign user levels to users initially. Of
course, you can also modify data in your database directly. The value of the
Administrator level is -1.
2. Since User Level works at table level only, if an user has permissions to the User
Table, he/she may be able to modify personal information (including user level and
user id) of other users. Therefore you should not expose the User Table to normal
users. If you want to expose the User Table and restrict users to access their own
data only, you need to use User ID Security, which controls permissions at record
level. (See Advanced Security - User ID Security) (See 1.15.9)

322

PHPMaker 12 Help
3. There are two types of Advanced Security implemented in PHPMaker - User ID
Security and User Level Security. User ID Security secures data at record level; User
Level Security secures data at table level. They can work independently or work
together. (See Advanced Security - User ID Security) (See 1.15.9)

Also see:
Advanced Security - User ID Security(See 1.15.11)
Advanced Security - Dynamic User Level Security(See 1.15.9)

1.15.11 Advanced Security - Dynamic User


Level Security
In this tutorial we will show you how to setup User Level Security in PHPMaker. We will use
the demo database for demonstration.
User Level
User Level Security secures data at table level. Each user level is granted with specific
permissions to tables in the database. Users with different access levels are restricted with
different add/copy, list/search/view, delete and edit rights.
There are 2 types of User Level security:
1. Static User Levels - the User Levels and the permissions are defined in the project and
the User Levels are not to be changed after script generation.
2. Dynamic User Levels - the User Levels and the permissions are defined in 2 tables in
the database, the User Levels can still be changed with the generated scripts.
In this tutorial we use dynamic User Level Security.
The "Employees" table and "Orders" table in the demo will be used in this example.
Fields in Table "Employees"

323

PHPMaker 12 Help

Fields in Table "Orders"

Dynamic User Level Security stores the User Level information in the database, so you need
to add 2 tables to your database - User Level Table and User Level Permission Table
which must have the following fields, note the data types, User Level ID and the Permission
fields must be of integer type, the field names can be different though:

324

PHPMaker 12 Help

You can create these 2 tables in the database yourself or you can use PHPMaker to create
these 2 tables for you, please see below.

Steps to Setup Advanced Security


1. Loading PHPMaker
Open PHPMaker and connect to the demo database.
2. Setting up User Access Levels
Click on the [Security] tab, there are two sections for the login process:
Administrator Login
If you tick this option, a hard-coded Administrator account will be generated which has all
access right to all tables/views.
Use Existing Table
Tick this option to set up the user access levels. You should select the security table and the
corresponding Login Name and Password fields.

325

PHPMaker 12 Help

To set up the user levels, click on the [Advanced] button. A popup window will appear.
Click on the [User Levels] button. Select the User Level Field.
The User Level field must be of integer data type. Non integer fields will not be
seen in the User Level Field combobox.
Important

To use dynamic User Levels, switch to the [Dynamic User Levels] and check [Enable
Dynamic User Levels].

326

PHPMaker 12 Help
If you want PHPMaker to create these 2 tables in your database, click the [Create tables]
button, the following form will display for you to change the table/field names if necessary.
You can change the table/field names and then click OK to continue.

If you have projects created by previous versions of PHPMaker you may want to use
dynamic User Levels and migrate the previously defined static User Levels in the project to
the database. After selecting or creating the User Level and User Level Permission
tables/fields, just click the [Migrate] button to let PHPMaker do that for you.
You'll need to specify the User Level Table and the User Level Permission Table and the
related fields. (If you use PHPMaker to create the tables, PHPMaker will set up the
tables/fields automatically also.)
User Level Table - the table for storing the User Levels
User Level ID Field - the ID of an User Level, this field must be integer type
User Level Name Field - the name of an User Level, this field should be string field
A typical User Level Table should contain data like this:

Note that there are three built-in user levels:


Anonymous - Anonymous is a built-in user level for anonymous users (i.e. users that have
not logged in). The User Level ID of Anonyous is -2.
Administrator - Administrator is a built-in user level that has all permissions plus the
privileges to modify User IDs and User Levels. Its permissions are same as that of the hardcoded Administrator Login. The User Level ID of Administrator is -1.

327

PHPMaker 12 Help
Default - Default user level is built-in user level with user level = 0. Since User Level field is
an integer field, if you set a default value of 0 for this field, this user level will become the
default user level for the user after registration and before the Administrator assigning
another higher user level.
You can add your own User Levels with User Level ID starting from 1.
User Level Permission Table - the table for storing the permission of the User Levels
Table Name Field - the table name of each table in the database, this field should be of
string type
User Level ID Field - the ID of an User Level, this field must be integer type
Permission Field - the permission of the specified User Level ID in the specified table, this
field must be integer type also.
A typical User Level Permission Table should contain data like this: (Note: Table names will
be prefixed with Project ID, see Project File(See 1.12).)

Click OK to close the Advanced Security Setup form.


If you go to Field Setup Page now and view the Edit Tag for the User Level Field, you should
see that the Edit Tag has been setup as "SELECT" and the User Level table has been setup
as lookup table automatically:

328

PHPMaker 12 Help

3. PHP Script Generation


Click the [Generate] button and PHPMaker will generate the required PHP scripts
automatically.
4. Running the PHP Application
Login as Administrator, go to the List page of the User Level table and add some user
levels.
Notes

1. Only administrators can manage User Levels, you must login as the hard coded
administrator or as a member of the built-in Administrator User Level.
2. You manage the User Level permissions via the scripts generated for the User Level
Table and the User Level Permssions page (userpriv.php), NOT via the scripts
generated for the User Level Permission Table directly. If you go to the scripts for
the User Level Permission Table directly, you'll only see the permissions in integer
format.

.
If the User Level table is not created by PHPMaker, you may not have the Anonymous,
Administrator and Default User Level in the table yet. You'll need to add them yourself.
Note

329

PHPMaker 12 Help
In this example, we add 2 more user levels - Sales and Manager, click the Add link and enter
the User Level ID, User Level name and default permissions as follows:

Click "Add" button to confirm. If you click the "Permission" link now, you can set refine the
permission for different tables/views:

Similarly, add the "Manager" User Level.


To assign different user level for the users, go to the user table (the "Employees" table in
this case). You'll find that the Edit Tag of the User Level Field is setup as "SELECT"
(combobox) and the combobox is populated with the user levels we defined above
automatically.

We assign a password and the user level "Sales" to the employee #1 (the employee with
EmployeeID equals 1). Then we logout.
To see the Advanced Security works, we login again as employee #1 using "nancy" as user
name and "1234" as password.
According to the user level defined by us, users with "Sales" level has view and add
permissions to the "Orders" table only. They are not allowed to update or delete records.
Employee #1 belongs to the "Sales" level, so we do not see the links to the edit/delete page.

330

PHPMaker 12 Help

Notes

1. Users have no right to change his own user level. Only Administrator can change an
user's user level. If you want to assign user levels in the generated scripts, a hardcoded administrator login account must also be created. Alternatively, an user must
be assigned with the Administrator level. However, you may still need to use the
hard-coded Administrator Login to log in and assign user levels to users initially. Of
course, you can also modify data in your database directly. The value of the
Administrator level is -1.
2. Since User Level works at table level only, if an user has permissions to the User
Table, he/she may be able to modify personal information (including user level and
user id) of other users. Therefore you should not expose the User Table to normal
users. If you want to expose the User Table and restrict users to access their own
data only, you need to use User ID Security, which controls permissions at record
level. (See Advanced Security - User ID Security) (See 1.15.9)
3. There are two types of Advanced Security implemented in PHPMaker - User ID
Security and User Level Security. User ID Security secures data at record level; User
Level Security secures data at table level. They can work independently or work
together. (See Advanced Security - User ID Security) (See 1.15.9)

Also see:
Advanced Security - User ID Security(See 1.15.11)
Advanced Security - Static User Level Security(See 1.15.10)

1.15.12 Custom View


WARNING! Custom View expects simple SELECT statements only, they are NOT designed
to and cannot replace views provided by the database. PHPMaker supports creating database
view, you should always use database views whenever available. Views provided by

331

PHPMaker 12 Help
database allow you to use them more like regular tables. If you use MySQL 5, you should
ALWAYS use MySQL view.
Note

Before reading this tutorial, please read Using Custom View(See 1.10.11) first.

In this tutorial we will show you how to create a Custom View. We will use the demo
database for demonstration.
We will build a SELECT statement which can show the customer's company name, the
product name and total price of an order item. Four tables, "orderdetails", "orders",
"customers" and "products" table.
Fields in Table "orderdetails".

Fields in Table "orders".

Fields in Table "customers".

332

PHPMaker 12 Help

Fields in Table "products".

Steps to Setup Custom View


1. Loading PHPMaker
Open PHPMaker and connect to the demo database.
2. Creating the Custom View
Right click [Custom Views] in database pane and select [Add Custom View], or click
[Edit] in the main menu and then select [Add Custom View].
The Custom View Setup window will show up:

333

PHPMaker 12 Help

Build the SELECT statement as follows:


1. Drag "customers", "orders", "orderdetails" and "Product" tables from table pane into
builder area,
2. Create the joins, always start from the main table. In this case, the main table is
"orderdetails", others are just lookup tables. (We join Orders and then Customers
table to lookup the CompanyName, and join the Products table to lookup the
ProductName.) So we drag OrderDetails.OrderID to Orders.OrderID, and
OrderDetails.ProductID to Products.ProductID, then drag Orders.CustomerID to
Customers.CustomerID,
3. Check the required fields.

334

PHPMaker 12 Help

Click [SQL] tab and edit the SELECT statement in the SQL editor directly, add a calculated
field in the SELECT clause:

OrderDetails.UnitPrice * OrderDetails.Quantity * (1 OrderDetails.Discount) AS `Extended Price`

Change the name of the custom view from the temporary name "CustomView1" to that you
want, in this example, we use "Order Details Extended".
On the toolbar, there is a checkbox labeled [Copy field settings from source table
(when applicable)]. We keep this checked so the Field level setup (Edit Tag, View tag,
etc.) will be copied from the field's source table.

335

PHPMaker 12 Help
Click [OK] to finish. The custom view is added under [Custom Views] in database pane.

3. PHP Script Generation


Go to the [Generate] tab, click the [Generate] button and PHPMaker will generate the
required PHP scripts automatically.
4. Running the PHP Application
Run the scripts, click the [Order Details Extended] custom view link and we'll see the result
we want.

336

PHPMaker 12 Help

1.15.13 Report
Note

Before reading this tutorial, please read Using Report(See 1.10.12) first.

In this tutorial we will show you how to create a report using custom view with summary in
PHPMaker. We will use the demo database for demonstration.
We will use "Order Details Extended" custom view in the Custom View Tutorial(See 1.15.12)
to create a report which shows the order items in orders of each customer.
SQL of Custom View "Orders Details Extended":

337

PHPMaker 12 Help

Steps to Create the Report


1. Loading PHPMaker
Open PHPMaker and connect to the demo database.
2. Adding a report
Right click [Reports] on the database pane then click [Add Report], or click [Edit] in the
main menu and then select [Add Report].
The Report Setup window will show up, enter the report name, for example, we use "Sales
by Customer". Select the Custom View "Order Details extended" as source table. Select all
the field by clicking the [>>] button.

Click the [Grouping Levels] tab, since we want to group the order items by company and
then by order, we select "CompanyName" and then "OrderID" as grouping level. We check
[Show summary] for both levels (the [Summary Values] tabs become visible).

338

PHPMaker 12 Help

Click the [Sort Order] tab, since we want to sort the order items by product name, we
select "ProductName" as sorting field. (If you want to sort in descending order, click the
button next to the field to switch the order.)

339

PHPMaker 12 Help

Now click the [Summary Values] tab. We want to see total price and average quantity of
order item in an order, so we check [Avg] for the field "Quantity" and check [Sum] for the
field "Extended Price".
We want to see details of each order item, so we use the default option [Details and
summary]. We also leave [Show grand summary] checked as default because we want
to know the total price and average quantity of order item for all orders.

340

PHPMaker 12 Help

Click [OK] to finish.


The report will be added in database pane. Field level setup will be copied from the source
table.
3. PHP Script Generation
Go to the [Generate] tab, click the [Generate] button and PHPMaker will generate the
required PHP scripts automatically.
4. Running the PHP Application
Run the scripts. The "Sales by Customer" report link is at the bottom of the menu. Click and
see the result.

341

PHPMaker 12 Help

Summary values are shown at the end of each level.

The grand summary is also shown at the end of report.

342

PHPMaker 12 Help

1.15.14 Integrating with PHP Report Maker


Project
In this tutorial we will show you how to put scripts generated by PHP Report Maker together
with scripts generated by PHPMaker. We'll use security in both projects and demonstrate
how you can make them compatible with each other.
To make PHPMaker and PHP Report Maker projects work together, there are 3 requirements:
1. The projects share the same web folder. In general, the projects share the same
application root and destination folder.
2. The projects share the same project name.
3. If Advanced Security is used, they shares the same Advanced Security settings,
including the User ID field, Parent User ID field, User Level field and User Levels.
Project name in PHP Report Maker or PHPMaker is used in session variable to distinguish
projects. For example, if the project name of your PHPMaker project is named as "project1",
the session variable of the logged in status is session variable "project1_status". If your
project name of your PHP Report Maker project is named as "project2", when users browse
from PHPMaker generated pages to PHP Report Maker generated pages, you will be
considered as not logged in and be redirected to the login page. Therefore, to make PHP
Report Maker project compatible with PHPMaker project, we need to use the same project
name for both projects.
Select one of your PHPMaker projects that uses security, check the project name (see
Project File(See 1.12)) by clicking [Tools] -> [Advanced Settings].
In this example, the project name of the PHPMaker project is "demo", we'll use the same
project name in PHP Report Maker.
On the other hand, PHP application generated by PHP Report Maker is self-contained, it has
its own header, footer, login, logout and default page. However, if you have an existing PHP
application generated by PHPMaker, you may already have those pages already. Since those
pages typically have the same name like "header.php", "footer.php", "login.php",
"logout.php" and "index.php", generating your PHP Report Maker project to the same folder
may create several problems:
1. The header, footer, login, logout and default page of the existing application may be
overwritten.
2. Even if they are different (so they will not be overwritten), you'll need to maintain 2
sets of header and footer. To make the look and feel of your site consistent, you'll
need to make the 2 sets of header and footer look the same too.
3. If both projects uses security, each project has its own login and logout page, users
will need to login or logout twice.
To solve these problem, PHP Report Maker allows you to enable Compatibility Properties.
When enabled, PHP Report Maker will behaves a little differently during generation. If
existing paths are specified, the header, footer, login, logout and default pages will not be
generated so they won't overwrite existing files. Instead, the generated scripts will use the
paths of header, footer, login, logout and default pages specified by the Compatibility
Properties so both PHP application shares the common files. Therefore, once you have
customized the header and footer for use with both PHP applications, they will not be
overwritten when you re-generate scripts using PHP Report Maker.

343

PHPMaker 12 Help
Steps to Setup Compatibility Properties
1. Make Sure the Advanced Security Settings in Both Projects Are the Same
The Advanced Security settings in both projects must be the same. Open the PHP Report
Maker project you previously used in the Advanced Security tutorials (Tutorial - User ID
Security(See 1.15.9) or Tutorial - User Level Security(See 1.15.10)). Compare the Advanced
Security settings with that in your PHPMaker project. Check the User ID field, Parent User ID
field, User Level field and User Levels.
Close the project. (In next step, PHPMaker may need to change your project settings, so you
should not open the project in PHP Report Maker.)
2. Setting up Compatibility Properties
Compatibiltiy can be set up easily in the PHPMaker project. PHPMaker can load the PHP
Report Maker project, set up above properties automatically and load the menu items from
the PHP Report Maker project to the PHPMaker project. Since PHPMaker will update your PHP
Report Maker project, to avoid overwriting each other, you should save your PHP Report
Maker project and close PHP Report Maker first. Then in PHPMaker, open the Menu Editor,
click the [Import] button in the toolbar,

Note: This is menu editor in PHPMaker.


Select your PHP Report Maker 8 project, click [OK]. The imported menu items will be
represented by orange icons, you can then re-arrange the display order of the menu items if
necessary.

344

PHPMaker 12 Help

If you change User Level settings in your PHP Report Maker project later, the imported
menu items in the PHPMaker project will NOT be updated automatically, you'll need to
repeat above again.
Note

If you open your report project again in PHP Report Maker (not PHPMaker) and click [Tools]
-> [Compatibility Properties], you should see that PHPMaker has changed some settings
for compatibility:
1. The project name has been set as the same as that of PHPMaker project,
2. [Enable compatibility properties] is enabled,
3. The file names of the shared files has been setup. If they are not correct, enter the
file name of the header, footer, login, logout and default pages in your PHPMaker
project.

345

PHPMaker 12 Help

Click [OK] to save.


3. PHP Script Generation
Go to the [Generate] tab, select the same [Application root folder] and [Destination
folder] as in your PHPMaker project. Click the [Generate] button and PHP Report Maker
will generate the required PHP scripts automatically.
4. Running the PHP Application
Run your existing PHP application with your browser. If use security and you have not
logged in, you'll be redirected to the login page, If your PHPMaker project uses security, you
should find yourself been redirected to the login page from the PHPMaker project.
Login so you can browse the existing PHPMaker pages.
Now click the new links in the menu to view the reports. You'll be redirected to the default
report you specified in your PHP Report Maker project without the need to login again.
Check the User ID security or User Level security by browsing the reports and you'll find that
it works as expected.

346