====== Custom PageBuilder Add-on ======

This tutorial describes how to create Add-Ons for PageBuilder and package them.

You will see how easy it is to extend the PageBuilder with your own scripts and features.

In the tutorial below we will start with a very simple PHP Add-On script and then move to a more advanced Javascript Add-on script that we will incrementally improve.

We will go from the start to finish and do the full Add-On creation cycle including the package creation.

===== Minimal Add-on =====
The minimum you need to create an add-on script is 2 files:
  - An Add-on script file
  - A tool list.

==== Add-on script ====

They are PHP file stored in the **includes/** folder with the **.script.inc.php** extension.

Open the WebIDE, click on the WebPage tab and click on the green plus or link **Create a new web page**
Lets copy and paste the code below in a new file called **includes/user_connexion_info.script.inc.php** that we will store in the **includes/** folder of our project.

<code php>
<?php 
    /**
     * This is a script that displays user information.
     *
     <template>
<b> Here is some information on your current connections</b>
<?php
  echo "<br/>Your on page:".$_SERVER\['PHP_SELF'\];
  echo "<br/>Your IP address is:".$_SERVER\['REMOTE_ADDR'\];
  echo "<br/>Your browser is:".$_SERVER\['HTTP_USER_AGENT'\];
  echo "<br/><br/>Cookies set by this server are:";
  foreach ($_COOKIE as $cookie_name => $cookie_value) {
     echo "<BR/><b>".$cookie_name."</b>=".$cookie_value ;
  }
?>
    </template>
     **/
?>
</code>

Escaping the “[“ and “]” between the <template> tag is very important.

When the PageBuilder inserts this script in a Web Page it inserts the entire content of what is between the <template> </templates>. 







==== Add-on Tool List ====

In the Pagebuilder Add-Ons are listed under the **Add-On** icon or listed on the left side. 

To add a new tool list you need to create a file that ends with .tools.inc.php in the includes directory.
In our case lets create a file call **includes/user_info.tools.inc.php** with the content below and save it in the includes/ directory.
<code php>
<?php
  /**************************************************
   *  user_info.tools.inc.php
   *  Tool bar with the user information type of scripts.
   ***/  
   
$e_addLayer = new Event("pagebuilder.addLayer", "add") ;
$e_addLayer->addParam("layertype", "script") ;
$e_addLayer->addParam("height", 35) ;
$e_addLayer->addParam("width", 100) ;
$e_addLayer->addParam("top", 140) ;
$e_addLayer->addParam("left", 140) ;
// for now unnamed, should be script name with incremental number.
?>
    <tr>
        <td>
<?php   
 $e_addLayer->addParam("blockname", "user_connexion_info.script.inc.php");
 $e_addLayer->addParam("layername", "UserInformation");
 $e_addLayer->addParam("border_style", "");    
?>
<?php echo getToolLink($e_addLayer->getUrl(), "User Connexion Information");?>
        </td>
    </tr>
</code>

The tools scripts are includes and listed based on their names.
It creates an Event that will trigger the pagebuilder.addLayer Event Action. For a full understanding of how events work see the [core:developer_documentation|Radria Core Developer documentation].

The “blockname” parameter is the name of the file that contain the add-on script.
The “layername” parameter is the default name that will be used for that layer. (css div id)
The “border_style” is a default CSS style for the layer. It sometimes needs to add a border in case the scripts do not display anything by default. To show a border change it to:
 $e_addLayer->addParam("border_style", "thin"); 

To add another script to your add-on tool bar list duplicate the line from <TR> to </TR> included.

The getToolLink function accepts 4 parameters with the first two required:
<code php>
<?php echo getToolLink($e_addLayer->getUrl(), "User Connexion Information");?>
</code>

The second parameter is the label that will be displayed in the Add-Ons tool list.

The two other ones are optional. The third parameter is the text of the tool tips that will appear when the user leaves the mouse over the link for a couple of seconds.
The 4th parameter is a link to the documentation that will describe what that Add-on script do.
<code php>
<?php echo getToolLink($e_addLayer->getUrl(), 
                       "User Connexion Information", 
                       "Display the Users network connexion informations", 
                       "docs/mypackagename/pagesname.html#secionname");
?>
</code>
If the url of the help is provided a little (?) will appear on the right scripts name.




==== Testing our new Add-On ====
Now you can open the PageBuilder and in the Add-On list you should see a new item: ** User Info ** and when you click on it you see the Add-on script: ** User Connexion Information **

Click on it and the PageBuilder will add in your web page a div layer with the content of whats in the <template> tags in the **includes/user_connexion_info.script.inc.php** add-on script.

Now lets see how we can catch user input.

===== User Input & parameters =====

Some scripts will need user input in order to configure or set them up in a web page.

For that in the Template tag <template> we create variable with special variable in *[]* that will be replaced with the User Input.

==== Countdown script ====

Lets use as an example a simple count down script in Javascript.
Its a javascript code that uses a date variable and some text messages to calculate the number of days left before a specific date and display custom messages accordingly.

The original Javascript code is:

<code javascript>
<script type="text/javascript"> 
<!-- Countdown script distributed by http://www.hypergurl.com 

var today=new Date() 

//Enter the date for your countdown. Month first then day. Example 6th month 26th day. 
var countdown=new Date(today.getFullYear(), 6, 26) 

//Enter your message here! Change words below to suit 
var beforedayText="left until whatever day you want" 
var ondaytext="Today is the day. Happy Whatever Day!" 

var monthtext=new Array("Jan","Feb","Mar","April","May","June","July","Aug","Sep","Oct","Nov","Dec") 
countdown.setMonth(countdown.getMonth()-1) 
//change to 0-11 month format 
var showdate="("+monthtext[countdown.getMonth()]+" "+countdown.getDate()+")" 
var one_day=1000*60*60*24 
var calculatediff="" 
calculatediff=Math.ceil((countdown.getTime()-today.getTime())/(one_day)) 
if (calculatediff<0){ 
  var nextyeartoday=new Date() 
  nextyeartoday.setFullYear(today.getFullYear()+1) 
  calculatediff=Math.ceil((nextyeartoday.getTime()-today.getTime())/(one_day)+calculatediff) 
} 
var pluraldayornot=(calculatediff==1)? "day" : "days" 
if (calculatediff>0) 
  document.write("<b>"+calculatediff+" "+pluraldayornot+" "+beforedayText+" "+showdate+"!</b>") 
else if (calculatediff==0) 
    document.write("<b>"+ondaytext+" "+showdate+"!</b>") 
--> 
</script>
</code>

<box round blue>
This scripts needs 4 parameters: 
  - Month 
  - Day
  - Message before the day
  - Message when the day has arrived
</box>



Lets create the scripts **includes/countdown.js.script.inc.php** with the following content:

<code php>
<?php 
    /**
     * This is a script that display user information.
     *
     <template>
<?php     
     $countdown_month = "[Target_Month]";
     $countdown_day = "[Target_Day]";
     $beforedaytext = "[Message_before_the_day]" ;
     $ondaytext = "[Message_on_the_date]"   ; 
?>
<script type="text/javascript"> 
<!--
   var countdown_month=<?php echo $countdown_month; ?>;
   
   var countdown_day=<?php echo $countdown_day; ?>;
   
   var beforedayText="<?php echo $beforedaytext; ?>";
   
   var ondaytext="<?php echo $ondaytext; ?>";
   
 
var today=new Date() 
 
var countdown=new Date(today.getFullYear(), countdown_month, countdown_day) 
 
var monthtext=new Array("Jan","Feb","Mar","April","May","June","July","Aug","Sep","Oct","Nov","Dec") 
countdown.setMonth(countdown.getMonth()-1) 
//change to 0-11 month format 
var showdate="("+monthtext\[countdown.getMonth()\]+" "+countdown.getDate()+")" 
var one_day=1000*60*60*24 
var calculatediff="" 
calculatediff=Math.ceil((countdown.getTime()-today.getTime())/(one_day)) 
if (calculatediff<0){ 
  var nextyeartoday=new Date() 
  nextyeartoday.setFullYear(today.getFullYear()+1) 
  calculatediff=Math.ceil((nextyeartoday.getTime()-today.getTime())/(one_day)+calculatediff) 
} 
var pluraldayornot=(calculatediff==1)? "day" : "days" 
if (calculatediff>0) 
  document.write("<b>"+calculatediff+" "+pluraldayornot+" "+beforedayText+" "+showdate+"!</b>") 
else if (calculatediff==0) 
    document.write("<b>"+ondaytext+" "+showdate+"!</b>") 
--> 
 
</script>
    </template>
     **/
?>

</code>

Now the <template> tag is a mix of php and javascript. 
The PHP part is use to setup the parameters for the user input.
<code php>
<?php     
     $countdown_month = "[Target_Month]";
     $countdown_day = "[Target_Day]";
     $beforedaytext = "[Message_before_the_day]" ;
     $ondaytext = "[Message_on_the_date]"   ; 
?>
</code>

In the example above the entire code between the <template> tag will be inserted in the web page and all the variable in *[]* will be replaced by the user input values.
We assign the values from the the users to PHP variables, we can then use those variables anywhere in our script.


<note important>
The **[** **]** define the parameter that will be replace by the user input. The text between the **[]** will be use as label for the form.
When our Add-On is inserted in a web page each variables defined in the **[]** will be asked to the users in a form and the values provided will then be assigned to the PHP variables.
</note>

To transfer the PHP variables to the javascript code we echo them.
<note warning>
In all the PHP and Javascript code enclosed in the **<template>** tags the [ ] that are not variables need to be escaped with \[ and \].
Otherwize they will be used as parameters.   **Watch your arrays**.
</note>



 



==== Adding it to our Add-on Tool list ====

At the end of the **User_info.tools.inc.php** add the following code:
<code php>
    <tr>
        <td>
<?php   
 $e_addLayer->addParam("blockname", "countdown.js.script.inc.php");
 $e_addLayer->addParam("layername", "CountDown");
 $e_addLayer->addParam("border_style", "");    
?>
<?php echo getToolLink($e_addLayer->getUrl(), "Count Down");?>
        </td>
    </tr>
</code>










===== Include script =====
In the last script the entire content of whats between the <template> tag is inserted into the page. 
This means that if you have a bug fix later on for that code you will have to edit and update all the pages. 

The solution for this is to include the script and only keeping the user input variable in the <template> tag.

Then on the next upgrade of that script the new code will be used in all the pages without having to edit the pages.

Lets modify our **includes/countdown.js.script.inc.php** script:

<code php>
<?php 
    /**
     * This is a script that display user information.
     *
     <template>
<?php     
     $countdown_month = "[Target_Month]";
     $countdown_day = "[Target_Day]";
     $beforedaytext = "[Message_before_the_day]" ;
     $ondaytext = "[Message_on_the_date]"   ; 
     include("includes/countdown.js.script.inc.php");
?>
    </template>
     **/
?>
<script type="text/javascript"> 
<!--
   var countdown_month=<?php echo $countdown_month; ?>;
   var countdown_day=<?php echo $countdown_day; ?>;
   var beforedayText="<?php echo $beforedaytext; ?>";
   var ondaytext="<?php echo $ondaytext; ?>";
 
var today=new Date() 
 
var countdown=new Date(today.getFullYear(), countdown_month, countdown_day) 
 
var monthtext=new Array("Jan","Feb","Mar","April","May","June","July","Aug","Sep","Oct","Nov","Dec") 
countdown.setMonth(countdown.getMonth()-1) 
//change to 0-11 month format 
var showdate="("+monthtext[countdown.getMonth()]+" "+countdown.getDate()+")" 
var one_day=1000*60*60*24 
var calculatediff="" 
calculatediff=Math.ceil((countdown.getTime()-today.getTime())/(one_day)) 
if (calculatediff<0){ 
  var nextyeartoday=new Date() 
  nextyeartoday.setFullYear(today.getFullYear()+1) 
  calculatediff=Math.ceil((nextyeartoday.getTime()-today.getTime())/(one_day)+calculatediff) 
} 
var pluraldayornot=(calculatediff==1)? "day" : "days" 
if (calculatediff>0) 
  document.write("<b>"+calculatediff+" "+pluraldayornot+" "+beforedayText+" "+showdate+"!</b>") 
else if (calculatediff==0) 
    document.write("<b>"+ondaytext+" "+showdate+"!</b>") 
--> 
 
</script>
</code>

In the php code with have added an include statement and moved the javascript code out side the **<template>** tag.

Now if you include the script in multiple pages you just need to update one file (includes/countdown.js.script.inc.php) to modify its code for all the pages.

<note> A common error is to forget the include of the add-on script
<code php>
     include("includes/countdown.js.script.inc.php");
</code> in the **<template>** tag.
</note>





===== Advanced user forms =====

Using the "[]" is very convenient as a fast and easy way to provide user input.
But often we need more than just a text field for the user input. 

To add custom field type, the simplest is to use a [[core:registry:registry_object|Registry object]] and if you need more advanced feature you can create a custom form.















==== Using a Registry ====
You can get more information on the [[core:registry:registry_object|registry]] in [[core|Radria Core documentation]], also the pagebuilder support additional fields type not in the default Radria distribution.

A registry is a description of the Fields you want to use in your form, they are web application Field Type, this mean that they have more features than simple database field types.
Some Field type includes drop down list box, radio buttons, checkboxes
Additional fields types exist and can be added with the Package Manager: html editors, ajax suggest, date popup fields, color picker, highlighted syntax source code editor...


=== Creating a registry object ===

You can create your Registry Object with the WebIDE.  th
In the registry tab create a new registry called **countdown.js.script.inc.php.reg.xml** with a field for each of your Add-On parameter in **[]**.

<note>
The registry name is the Add-On script file name + **.reg.xml** at the end.  
The name of the registry field need to be exactly the one of your parameters inside the **[]**. Its case sensitive.
</note>

The source code of the Registry file: **countdown.js.script.inc.php.reg.xml** would look like:
<code xml>
<?xml version="1.0"?>
<registry>
  <rfield name="Target_Month">
    <rdata type="label">Month</rdata>
    <rdata type="listlabels">January:February:March:April:May:June:July:August:September:October:November:December</rdata>
    <rdata type="listvalues">01:02:03:04:05:06:07:08:09:10:11:12</rdata>
    <rdata type="default">12</rdata>
    <rdata type="fieldtype">strFBFieldTypeListBoxSmall</rdata>
  </rfield>
  <rfield name="Target_Day">
    <rdata type="label">Day</rdata>
    <rdata type="listlabels">01:02:03:04:05:06:07:08:09:10:11:12:13:14:15:16:17:18:19:20:21:22:23:24:25:26:27:28:29:30:31:</rdata>
    <rdata type="listvalues">01:02:03:04:05:06:07:08:09:10:11:12:13:14:15:16:17:18:19:20:21:22:23:24:25:26:27:28:29:30:31:</rdata>
    <rdata type="default">30</rdata>
    <rdata type="fieldtype">strFBFieldTypeListBoxSmall</rdata>
  </rfield>
  <rfield name="Message_before_the_day">
    <rdata type="default">Until count down ends</rdata>
    <rdata type="hidden"></rdata>
    <rdata type="html"></rdata>
    <rdata type="label">Message before the day</rdata>
    <rdata type="readonly"></rdata>
    <rdata type="required"></rdata>
    <rdata type="textline">60:200</rdata>
    <rdata type="css_form_class"></rdata>
    <rdata type="css_disp_class"></rdata>
    <rdata type="css_form_style"></rdata>
    <rdata type="css_disp_style"></rdata>
    <rdata type="id"></rdata>
    <rdata type="fieldtype">strFBFieldTypeChar</rdata>
  </rfield>
  <rfield name="Message_on_the_date">
    <rdata type="fieldtype">strFBFieldTypeText</rdata>
    <rdata type="default">Today is the Day, Count down has ended</rdata>
    <rdata type="html"></rdata>
    <rdata type="htmleditor"></rdata>
    <rdata type="label">Message on the Date</rdata>
    <rdata type="required"></rdata>
    <rdata type="textarea">40:10:</rdata>
    <rdata type="css_form_class"></rdata>
    <rdata type="css_disp_class"></rdata>
    <rdata type="css_form_style"></rdata>
    <rdata type="css_disp_style"></rdata>
    <rdata type="id"></rdata>
  </rfield>
</registry>
</code>

=== Pagebuilder FieldTypes ===

The PageBuilder contains its own fields types that automatically resized uploaded images, list all the available style sheet and the Web Pages or the project.
You will find them in the WebIDE with the prefix **PB_**

  * [[pagebuilder:fieldtype:PageBuilderFieldImage|Image auto Resize]]
  * [[pagebuilder:fieldtype:PageBuilderFieldListStyles|Available CSS styles]]
  * [[pagebuilder:fieldtype:PageBuilderFileListBox|PageBuilder Web Page list]]

==== Custom Form =====

<note warning>The custom form requires a Registry. So before going forward create a registry file.</note>

In addition of the <template> tag you can added a <templateform> its an HTML (PHP and javascript can be used) template with fields names in *[]*.

This enable additional flexibility to the Form provided to the user for entering the Add-On parameters.

Lets start with the example, in **includes/countdown.js.script.inc.php** just after the closing **</template>** tag and inside the PHP comment add:
<code html>
    <templateform>
<h3>Count down script</h3>
<b>Target date:</b><br>
[Target_Day] [Target_Month]<br>
<br>
<b>Message when waiting the target date</b><br>
[Message_before_the_day]<br>
<br>
<b>Message to display on the target date</b><br>
[Message_on_the_date]<br>
<br>
<h3>Help</h3>
This script display a count down of days from a defined target date.<br>
On the day it will display a custom message.
    </templateform>
</code>

Now our countdown Add-On script will display the parameters using this custom form.

<note> The content of the **<templateform>** is not limited to HTML, you can add PHP, Javascript, Ajax calls in it to make it work and display the way you want.</note>

==== Internationalization ====

FIXME


====== Package the Add-On ======

Once your Add-On is done and working the best way to install it on other projects or distributing it, its to build a [[:the_packages|Package]].

It takes only a few minutes using the package builder.












===== Package Builder =====
From the [[tools:Site Manager]] install the following packages from the Tools repository:

    contentadmin
    package_builder

Then click on the **Package Builder** from the tools list and sign in the ContentAdmin.

<box blue round|Package Builder Steps>
  - You will arrive on a form to create a new package.
    * Package Name: //user_info//
    * Package Version: //0.1//
    * Description: //This is a PageBuilder Add-On package to display user info and a Javascript count down in a web page//
    * Dependency Package: //pagebuilder-3.0//
  - On the next page select the following files:
    * includes/countdown.js.script.inc.php
    * includes/user_connexion_info.script.inc.php
    * includes/user_info.tools.inc.php
    * registry/countdown.js.script.inc.php.reg.xml
  - In the Database select nothing.
  - On the parameters add in the __HTML file to upload__ enter **none** and in //PHP Files to upload//: 
     * includes/countdown.js.script.inc.php 
  - Click **Continue** and download your new PageBuilder Add-On ready to be installed.

</box>

You can now upload this package to one of your repositories or install it manually on the projects.

<note>Each time you create a new version of your Add-On increase the Package version number by 0.1 or more. This will automatically, for package in repositories, prompt for Upgrade on project that uses the older one</note>

You will find more information on building packages at [[core:Radria Application Package]]