community.egroupware.org: Community wiki

  
Community wiki
How to port an app to eTemplate2
How to port an application to et2?

If you have an application which still runs under any versions below than 14.1, and you wonder how to port it to et2, here is how.

As case scenario, we would like to port app Timesheet from epl 11.1 which uses etemplate to et2.


Step 1: Use new etemplate class

We need to instantiate our template from etemplate_new class instead of etemplate class.


Original code:

---
function edit($content = null,$view = false)
	{
		$etpl = new etemplate ('timesheet.edit');

---

New code:
function edit($content = null,$view = false)
	{
		$etpl = new etemplate_new ('timesheet.edit');

Step 2: Add dependency

We need to add new version dependency in our app dependency. For instance, add version 14.1 to our timesheet dependencies in setup:

timesheet/setup/setup.inc.php

Original code:
/* Dependencies for this app to work */
$setup_info[TIMESHEET_APP]['depends'][] = array(
	 'appname' => 'phpgwapi',
	 'versions' => Array('1.7','1.8','1.9')
);
$setup_info[TIMESHEET_APP]['depends'][] = array(
	 'appname' => 'etemplate',
	 'versions' => Array('1.7','1.8','1.9')
);


New code:

/* Dependencies for this app to work */
$setup_info[TIMESHEET_APP]['depends'][] = array(
	 'appname' => 'phpgwapi',
	 'versions' => Array('14.1')
);
$setup_info[TIMESHEET_APP]['depends'][] = array(
	 'appname' => 'etemplate',
	 'versions' => Array('14.1')
);


Step 3: Add app.js in order to use client-side APIs

In order to actually get advantage of et2 technology and uses our client side APIs, its a good practice to define a app.js under AppFolder?/js folder. In our timesheet case:

Create app.js file:
timesheet/js/app.js

app.classes.timesheet = AppJS.extend(
{
	appname: 'timesheet',
	/**
	 * et2 widget container
	 */
	et2: null,
	/**
	 * path widget
	 */

	/**
	 * Constructor
	 *
	 * @memberOf app.timesheet
	 */
	init: function()
	{
		// call parent
		this._super.apply(this, arguments);
	},

	/**
	 * Destructor
	 */
	destroy: function()
	{
		delete this.et2;
		// call parent
		this._super.apply(this, arguments);
	},

	/**
	 * This function is called when the etemplate2 object is loaded
	 * and ready.  If you must store a reference to the et2 object,
	 * make sure to clean it up in destroy().
	 *
	 * @param et2 etemplate2 Newly ready object
	 */
	et2_ready: function(et2)
	{
		// call parent
		this._super.apply(this, arguments);

	},

});



Inline Scripts and Content Security Policy (CSP): As you may noticed et2 uses CSP which is very restricted about inline scripts, therefore in order to take advantage of CSP we should make our code compatible with it by not using inline scripts and instead trying to implement them in our app.js. For instance in our timesheet scenario we do have couple of inline javascript statements which we need to port them, like:

function index($content = null,$msg='')
{
            ...
            ...
      $content['nm'] = array(
				...
                                ...

				'filter_onchange' => "set_style_by_class('table','custom_hide','visibility',this.value == 'custom' ? 'visible' : 'hidden'); if (this.value != 'custom') this.form.submit();",
                                ...
                                ...
				
			);


New code

function index($content = null,$msg='')
{
            ...
            ...
      $content['nm'] = array(
				...
                                ...

				'filter_onchange' =>"app.timesheet.filter_change();",
                                ...
                                ...
				
			);


And we need to implement our filter_change method in app.js file, like:

filter_change: function()
{
	var filter = this.et2.getWidgetById('filter');
	var dates = this.et2.getWidgetById('timesheet.index.dates');
	if (filter && dates)
	{
		dates.set_disabled(filter.value !== "custom");
	}
},

As you see in filter_change method we used some API methods which may not be familiar for you. In order to get more information about et2 client-side APIs and widgets you may have a look at etemplate/js files which contains all widgets and you can browse widgets by widget browser in etemplate->etemplate2 Reference (see fig.01)

(Widget browser fig. 01)
You are here