Please enable JavaScript to view this site.

Navigation: Advanced topics > Programming topics

How to create a custom Edit control plugin

Scroll Prev Next More


PHPRunner comes with an ability to create custom edit control plugins. In this article, we are going to show you how to create ColorPicker and SignaturePad plugins.


The ColorPicker and SignaturePad edit controls as seen in the browser:




ColorPicker control

Let's say we want to add a color picker control that allows users to select colors similarly to Adobe Photoshop. Since our software comes bundled with jQuery, let's search the web for "jQuery colorpicker".


This search returns several results, and the one we are going to use is miniColors. It looks nice and is easy to integrate. Sources can be found at Github.


create a new folder under <Documents>\PHPRunnerPlugins\edit named ColorPicker;

copy files EditMyField.js and EditMyField.php from MyField folder to the ColorPicker folder;

rename those files to EditColorPicker.js and EditColorPicker.php, respectively;

if your plugin needs extra files, copy them to the ColorPicker folder while keeping the folder structure;

open EditColorPicker.js in any text editor and replace all occurrences of EditMyField with EditColorPicker. Do the same with the EditColorPicker.php file.

use the addJSFiles() function in EditColorPicker.php to add references to external JavaScript files:




Note: you may need to specify the loading order of JavaScript files. In this example file, second.js is loaded after first.js:

$this->pageObject->AddJSFile("second.js", "first.js");


use addCSSFiles() function to add CSS files:




In the EditColorPicker.php file find the buildUserControl() function. This is were you build HTML code for your control.


If you leave the predefined code as is, it will display a simple text edit box. You can change this edit box, for example, by using a black theme:




Lets see how to turn this edit box into a colorpicker control. According to colorpicker instructions we need to call for miniColors JavaScript referencing the edit box. We can do so adding the following code to constructor function:


letterCase: 'uppercase'


The letterCase option tells the control to convert the manually entered color values to the upper case. this.valContId is the id of the control.


This is it; the control is ready. You can now launch PHPRunner and select the ColorPicker as Edit as type for any text field.

Additional enhancements

1. It would be nice if instead of the hex color value, we could show the visual representation of the selected color on the List/View pages. We can do so by choosing the View as type as Custom and adding the following code there:


$value="<span style='padding: 5px; background: ".$value."'>".$value."</span>";


2. By default, PHPRunner sets focus on the first edit control when an Add or Edit page is loaded. This may not be a desired behavior for the ColorPicker control, as the popup window will open every time the page is loaded. To prevent this from happening, implement the setFocus function, and return "false" every time.


Note: If you need to change the control behavior, check the functions and events in the source\include\common\runnerJS\Control.js file.


The SignaturePad plugin allows adding a signature pad to your forms. SignaturePad works with both mouse and touch devices. We use a SignaturePad jQuery plugin that comes with excellent documentation and examples.


The basic setup is the same: create new folder for the SignaturePad plugin, copy and rename files, add files that plugin needs to the plugin directory.


This plugin is a bit more complicated and takes a few extra steps to integrate.

1. Build the HTML code

Here is how to do this in the buildUserControl() function:


echo '
<div class="sigPad" style="width: '.($this->width+2).'px;">
<ul class="sigNav">
<li class="clearButton"><a href="#clear">Clear</a></li>
<div class="sig sigWrapper">
<div class="typed"></div>
<canvas class="pad" width="'.$this->width.'" height="'.$this->height.'"></canvas>
<input id="'.$this->cfield.'" type="hidden" '
.'name="'.$this->cfield.'" class="output">

2. Convert signature data to image

The signature data is recorded in a JSON format as a sequence of lines and is passed to the web server this way. We need to convert the JSON data to a PNG file and save it in the files folder on the web server.


Luckily all the hard work was already done, and all we need to do is to add a few lines of code to the readWebValue() function:


if ($this->webValue) {
  // save signature to file
  require_once 'signature-to-image.php';
  $img = sigJsonToImage($this->webValue, array(
          'imageSize' => array($this->width, $this->height)
           ,'bgColour' => $this->bgcolor
  $filename= $this->folder."/".generatePassword(15).".png";
  imagepng($img, $filename);
  $filesize = filesize($filename);
  // prepare image info to be saved in db
  $result[] = array("name" => $filename,
  "usrName" => 'signature.png', "size" => $filesize, "type" => "image/png",
  "searchStr" => 'signature.png'.":sStrEnd");
  $this->webValue = my_json_encode($result);


Note: You can read more info about the JSON to image conversion here.


Note the way the file info is stored in the database. Since this version offers multiple files to upload, we need to be able to store more info than just the file name.


Besides the file name itself, we also save the file size, file type, and the path to the file in the JSON format. Here is how a typical file upload field looks like in the database:


[{"name":"files\/h8hsoz5hd23b0ik.jpg", "usrName":"Chrysanthemum.jpg", "size":879394,"type":"image\/jpeg", "searchStr":"Chrysanthemum.jpg:sStrEnd"},
{"name":"files\/2p85jz854o6fbv8.jpg", "usrName":"Desert.jpg","size":845941, "type":"image\/jpeg", "searchStr":"Desert.jpg:sStrEnd"},
{"name":"files\/pm4fu8uv2u6xc1w.jpg", "usrName":"Hydrangeas.jpg", "size":595284,"type":"image\/jpeg", "searchStr":"Hydrangeas.jpg:sStrEnd"}]

3. Customization

Now we can customize our plugin. Users may need to change the appearance and behavior of the signature pad, for example:


change the width and height of the signature pad;

change the background color;

change the folder where the image files are stored;

make the signature pad field required.


As the first step, we need to learn to pass the settings from the PHPRunner wizard to the plugin. Proceed to the Edit as dialog in PHPRunner and click the Add initialization script button. Here is a sample set of settings for the SignaturePad control:


// signature field height
$this->settings["height"] = 100;
// signature field width
$this->settings["width"] = 300;
// signature background color
$this->settings["bgcolor"] = array(0xff, 0xff, 0xff);
// set it to true to make signature field required
// folder to store signature files


This code is self-descriptive; you can pass any number of settings there. If you create a custom edit control plugin, place the sample initialization script to the sample.php file that needs to be located in the plugin folder.


Now we can access those settings in the plugin initUserControl() function. We can also pass the settings to the JavaScript part of the plugin.


// setting default value
$this->required = false;
// saving settings to the local variable
if ($this->settings["required"])
// passing settings to JavaScript
$this->addJSSetting("required", $this->required);

Adding new functionality

Making the signature field required

In the JavaScript init() function, add the following code:


if (this.required)


The signature is not required by default. To make it required, add the following line of code to the initialization script under Edit as properties:



Setting the width and height of the signature pad

Passing the width and height from the Edit as settings in PHPRunner:


$this->settings["height"] = 100;
$this->settings["width"] = 300;


Then we can use $this->width and $this->height in the buildUserControl() function to specify the width and height of our control:


<canvas class="pad" width="'.$this->width.'" height="'.$this->height.'"></canvas>

Changing the folder where the signature images are stored

Passing the folder name from the Edit as settings in PHPRunner:




Using this variable in the readWebValue() function:


$filename= $this->folder."/".generatePassword(15).".png";

Changing the signature pad background color

Passing the background color from the Edit as settings in PHPRunner:


$this->settings["bgcolor"] = array(0xff, 0xff, 0xff);


The bgcolor array contains the color value in an RGB format (Red, Green, Blue, each color ranges from 0 to 255), 0xff is a hexadecimal representation of 255. array(0xff, 0xff, 0xff) means white color.


Now we can use this.bgColor in the JavaScript control constructor function to pass the background color to the SignaturePad control:


$('.sigPad').signaturePad({drawOnly:true, bgColour: this.bgColor});


We also need to pass the backgound color to the sigJsonToImage() function that converts the JSON signature data to image. We use $this->bgcolor variable here in readWebValue() PHP function.


$img = sigJsonToImage($this->webValue, array(
    'imageSize' => array($this->width, $this->height)
     ,'bgColour' => $this->bgcolor


This is it. As you can see, creating a custom edit control plugin is relatively easy. You can do it with a few lines of code.


If you develop a new edit control plugin and want to share it with other users, feel free to contact our support team.


We have a plugin marketplace where you can sell the plugins you have created.

See also:

JavaScript API: Control object > addValidation()

JavaScript API: Control object > add CSS Class

"Edit as" settings: ColorPicker

"Edit as" settings: SignaturePad

"View as" settings: Custom

About Control object


Created with Help+Manual 7 and styled with Premium Pack Version 3 © by EC Software