BEdita Documents and Resources | Core

Event System and Callbacks

Tue, 21 Apr 2015 18:40:57 +0200

Since version 3.6.0 BEdita is shipped with a basic event system, along with a callback manager that enables the binding of model events simply plugging callback behaviors, without the need to edit the model configuration itself, hence leaving core code intact.

Automatic callback behaviors

By giving a special name to your behaviors, you can attach listeners to some built-in CakePHP's model events without editing the core code. Such callback system is handled by the CallbackBehavior which is automatically attached to every BEObject in "callback manager" mode.

`CallbackBehavior` configuration

CallbackBehavior has an optional setting callbackManager that allows you to decide if you want to attach your behaviors' methods as listeners for events handled by BeCallbackManager (see below for detailed documentation) or you prefer to use standard CakePHP behaviors system. By default, BeCallbackManager will be used.

Adding custom callbacks

Let's say you need to execute a custom piece of code every time an Event is saved. Normally, you would create a behavior and then add the newly-born behavior to the Event::$actsAs attribute, but this would involve the editing of a piece of source code.

Thanks to CallbackBehavior you can attach your behavior automatically to the Event model by naming it EventDoSomethingCallbackBehavior (where DoSomething can be replaced by anything you wish), and then enable it as an add-on, or place it within an enabled module.

This way, CallbackBehavior will take care of attaching your custom behaviors following such naming convention to the respective models, and the event listeners they implement will be correctly triggered.

Unbinding custom callbacks

If you chose to attach CallbackBehavior with callbackManager set to true, you might also decide to unbind single listeners. For example, if you had a custom callback behavior like this:

class EventTestingCallbackBehavior extends ModelBehavior {
    public function afterSave() {
        $this->log('afterSave', 'callback');
    }
    public function afterDelete() {
        $this->log('afterDelete', 'callback');
    }
}

If later on you wanted to get rid of its afterDelete() callback while doing a specific operation, you might call:

BeLib::getObject('BeCallbackManager')->unbind('Event.AfterDelete', array(
    'EventTestingCallbackBehavior', 'afterDelete'
));

This way, the EventTestingCallbackBehavior::afterDelete() method would be detached from the Event.AfterDelete event. Please, read BeCallbackManager::unbind() documentation for further details.

Adding callbacks on-the-fly

If you chose to attach CallbackBehavior with callbackManager set to true, you might also decide to add custom listeners on the fly to model events. For example, if you attached CallbackBehavior to the Event model, you would have the chance to listen to those events: Event.Beforefind, Event.AfterFind, Event.BeforeValidate, Event.BeforeSave, Event.AfterSave, Event.BeforeDelete, Event.AfterDelete.

Thus, this would work:

BeLib::getObject('BeCallbackManager')->bind('Event.BeforeValidate', function ($model) {
    /* Do some custom validation rules. */
    return true;
});

Please, refer to the documentation for BeCallbackManager::bind() for further details.

`BeCallbackManager` class reference

BEdita implements a basic event system. You can attach custom functions as listeners for built-in events, and you can even trigger your custom events.

`function bind(string $eventName, mixed $listener)`

Bind a listener to an event.

Params

$eventName: name of the event to be listened.
$listener: callable to be invoked when the event is triggered.

This can be either an anonymous function (PHP ≥ 5.3.0) or a fully qualified name of a callable method, like a string (e.g.: 'my_function') or an array containing a class name and one of its methods (e.g.: array('MyClass', 'myPublicMethod')). Please note that CakePHP's ClassRegistry will be used in this case to obtain an instance of the given class.

Examples

Bind a closure to an event:

$eventManager = BeLib::getObject('BeCallbackManager');

$eventManager->bind('MyModel.AfterSave', function ($model, $created, $event) {
    CakeLog::write('callback', 'Saved object of type "MyModel"');
});

Bind a model method to a custom event:

$eventManager = BeLib::getObject('BeCallbackManager');

$eventManager->bind('Cart.AfterPurchase', array('PurchaseHistory', 'purchaseCompleted'));

`function unbind(string $eventName = null, mixed $listener = null)`

Unbinds a listener from an event. If called without any argument, all events listeners are cleared.

Params

$eventName: name of the event. If omitted or null, the given $listener will be removed from all events.
$listener: callable to be unbinded. If omitted or null, the given $eventName will be completely cleared.

Examples

Unbind a closure from an event:

$eventManager = BeLib::getObject('BeCallbackManager');

$listener = function ($model, $query, $event) { /* Do something... */ };
$eventManager->bind('MyModel.BeforeFind', $listener);
// ...
$eventManager->unbind('MyModel.BeforeFind', $listener);

Clear all listeners for an event:

$eventManager = BeLib::getObject('BeCallbackManager');

$eventManager->bind('MyModel.MyEvent', function () { /* ... */ });
$eventManager->bind('MyModel.MyEvent', function () { /* ... */ });
// ...
$eventManager->unbind('MyModel.MyEvent');

`function trigger(string $eventName, array $eventData = array())`

Trigger an event (possibly any event) passing custom data.

For model-related events (or class-related events in general), $eventName is usually the class name the event refers to, followed by a dot, followed by a self-explanatory event name (both model name and event name are camel cased). You are encouraged to follow this convention.

Params

$eventName: name of the event to be triggered.
$eventData: array of data to be passed as arguments to listeners. The event will be always passed as last argument.

Return values

The triggered event is returned.

Examples

Trigger a custom event:

$eventManager = BeLib::getObject('BeCallbackManager');

$eventManager->bind('MyEvent', function ($a, $b, $event) {
    CakeLog::write('callback', $event->name . '_' . ($a + $b));
    return 42;
});
$evt = $eventManager->trigger('MyEvent', array(2, 3));  // Will result in logging 'MyEvent_5' to 'callback.log'.
echo($evt->result);  // Outputs: '42'.

Exception handling

Fri, 10 Apr 2015 11:15:27 +0200

Since 3.6.0 version BEdita ships with a redesigned exception handling system that gives better error responses to client requests.

With this new design every html/json/xml request will be served with the right response content type (text/html, application/json, text/xml). In this way all errors thrown by an Exception are consistent, output the expected type and set up the same $error var to the view.

In order to achieve this the following new components have been introduced:

new HTTP exceptions
a new Exception handler
new ResponseHandler components, JsonView and XmlView

HTTP Exceptions

In bedita-app/bedita_exceptions.php common http error status codes are mapped with exceptions as BeditaBadRequestException, BeditaNotFoundException, etc..

Every Exception sets the right status code and a corresponding message, if any is passed.
For example

/**
* Represents an HTTP 404 error
*/
class BeditaNotFoundException extends BeditaException {
	/**
	* Constructor
	*
	* @param string $message If no message is given 'Not Found' will be the message
	* @param mixed $details The exception details
	* @param $res The result status
	* @param int $code Status code, default to 404
	*/
	public function __construct($message = null, $details = null, $res = self::ERROR, $code = 404) {
		if (empty($message)) {
			$message = 'Not Found';
		}
		parent::__construct($message, $details, $res, $code);
	}
}

Introducing new Exception Handler

While previously exceptions were handled through a try {} catch() {} block in index.php now in bedita-app/config/bootstrap.php we are using set_exception_handler() PHP function.
For shell scripts the exception handler is defined in BeditaBaseShell::__construct() instead.

In order to adopt new errors handling in old frontend apps be sure to remove the try catch block from app/webroot/index.php replacing it with

$Dispatcher = new Dispatcher();
$Dispatcher->dispatch();

The default exception handler instantiates an AppError class located at bedita-app/app_error.php that takes care of preparing error data for the client and tries to render a view.

$error var is identical for any type of response (html/xml/json) and contains the following keys:

'status' => null, // http status code
'code' => null, // error code
'message' => null, // error message
'details' => null, // error details
'moreInfo' => null, // url to look for more information
'url' => null // url that caused the error

Note that at the current state some keys are always empty.

Following this schema the AppError::setError() method sets the App::error property to be serialized and sends the right header to the client based on the http error code thrown.

$this->controller->ResponseHandler->sendStatus($this->error['status']);
$this->controller->set(array(
	'error' => $this->error,
	'_serialize' => array('error')
));

Setup custom exceptions handler

By default bedita-app/libs/errors/be_exception_handler.php is used but it is possible to write a custom handler and set it up from configuration. To do so in frontend app you can edit frontend.cfg.php in app/config folder

Configure::write('Exception', array(
	'handler' => array(
		'class' => 'MyExceptionHandler',
		'method' => 'myHandleExceptions'
	)
));

The custom class should be placed in bedita-app/libs/errors or app/libs/errors in frontend app.

Rarely you would use custom exceptions handling in backend, in this case you need to configure it in bedita-app/config/bedita.cfg.php (possible, but NOT recommended)

The custom method accepts an Exception as argument and it has to be defined as public static, so following the above configuration we should create the file app/libs/errors/my_exception_handler.php

class MyExceptionHandler extends Object {

	/**
	* Custom method to handle Exceptions
	*
	* @param Exception $exception
	* @return void
	*/
	public static function myHandleExceptions(Exception $exception) {
		// code here
	}

}

ResponseHandler Component, JsonView and XmlView

It is responsible to respond in the right way to client requests. It's used by AppError to send the correct status code and set the $error var that ResponseHandler, will eventually serialize it in the right format (json, xml) setting up the right view (JsonView, XmlView)

Debug toolkit activation

Wed, 08 Apr 2015 17:23:15 +0200

Since BEdita 3.4 it is possibile to use the CakePHP DebugKit: a debugging toolbar and enhanced debugging tools for CakePHP applications.

Steps to activate:

get the forked version of debug_kit via github (1.3 branch only) simply using: git clone -b 1.3 --single-branch https://github.com/bedita/debug_kit.git bedita-app/plugins/debug_kit from BEdita core root folder [NOTE: --single-branch option is valid from git version 1.7.10].
write $config['debugKit'] = true; in bedita-app/config/bedia.cfg.php (activate for both backend/frontend) or just in frontend.cfg.php (frontend only)
now reload your application, you will see the cake toolbar in the upper right corner

Happy debugging :)

NOTE: to see sql queries in sql_log you should write as usual Configure::write('debug', 2); in config/core.php

ResponseHandler Component

Fri, 13 Mar 2015 14:15:20 +0100

This component is always attached to any controller and automatically takes care of rendering the right type of view when json or xml are requested. It checks "Accept" request header, parses url extensions (.json/.xml) and tells the controller to use JsonView or XmlView.

For example in a frontend app: calling from a client an url like http://example.com/sample.json or using jQuery

$.ajax({
	url: '/other_sample',
	type: 'get',
	dataType: 'json'
});

we force ResponseHandler to respond as json to client.

JsonView and XmlView views check if a special key named _serialize is in viewVars and serialize all viewVars found in it to present the payload to client.

Following the example above

public function otherSample() {
	$langs = array('eng' => 'English', 'ita' => 'Italian');
	$this->set({
		'langs' => $langs,
		'_serialize' => array('langs')
	});
}

outputs to client

{
	"langs": {
		"eng": "English",
		"ita": "Italian"
	}
}

Sending Headers

The ResponseHandler component is also very useful to send http status code to clients, for example

$this->ResponseHandler->sendStatus(400);

Sends a "Bad Request" header.

or to send any generic header

// send content type image/png header to client
$this->RequestHandler->sendHeader('Content-Type: image/png');
// the same as above
$this->RequestHandler->sendHeader('Content-Type', 'image/png');

Setting Type

To force a specific type (json or xml)

$this->ResponseHandler->setType('json');

or do it globally

public $components = array(
	'ResponseHandler' => array('type' => 'json')
);

Disabling Automatic Response

If you don't want to use ResponseHandler you can disable it in any method of your controller

$this->ResponseHandler->enabled = false;

or globally

public $components = array(
	'ResponseHandler' => array('enabled' => false)
);

Pay attention that disabling ResponseHandler you lose the magic json/xml handling, you have to manage it manually.

JsonView and XmlView

Fri, 13 Mar 2015 13:43:51 +0100

Whenever you need to output json or xml content you can use those special views. Normally BEdita apps automatically use the right View through ResponseHandler component but you can use them whenever you want: for example if you have disabled the ResponseHandler (not recommended) or if you want to force some output.

To use those views setup them in your controller like

$this->view = 'Json';

$this->view = 'Xml';

Those views check if a special key named "_serialize" is in viewVars and if so serialize all viewVars found in "_serialize" to present the payload to client.

For example:

$this->view = 'Json';
$this->set('section', $this->Section->find('all'));
$this->set('otherData', array(...));
$this->set('_serialize', array('section', 'otherData'));

will output the json_encode() of View::viewVars['section'] and View::viewVars['otherData'].

Here a frontend app example where ResponseHandler is disabled and json response is handled manually

class PagesController extends AppController {
public $components = array(
'ResponseHandler' => array('enabled' => false)
);
public function myMethod() {
$this->view = 'Json';
$this->RequestHandler->respondAs('json');
$this->set('object', $this->loadObj('nick-object');
$this->set('_serialize', array('object'));
}
}

If no "_serialize" view var is found the JsonView or XmlView will try to render a standard view file. It is useful for example if you need to manipulate data before serializing it. Removing "_serialize" from above example you need to add a view file named my_method.tpl in views/pages/ folder and manually build the json you want to output.

XmlView accepts another special key named "_rootNode" that you can define to explicit the xml root tag. If it's not defined the < response >< /response > tag is used.
Example:

$this->set(array(
'object' => $object,
'_serialize' => 'object',
'_rootNode' => 'object'
));

will output $object in xml format using object tag as root


   1
   ...

while

$this->set(array(
'object' => $object,
'_serialize' => 'object'
));

will output


  
    1
    ...

How to set up and configure external authentication services [backend]

Tue, 29 Apr 2014 10:45:54 +0200

From version 3.4 BEdita supports by default 3 external authentication services: Facebook, Twitter and Google.

In order to make this services work, we need to add some configuration parameters in the backend configuration file (bedita.cfg):

$config['extAuthParams'] = array(...);

Facebook auth service setup.

Facebook communicates with other websites through Facebook Apps. So, we need to create a Facebook App first:

Go to https://developers.facebook.com/
Click "Apps" in the dropdown top menu
Select "Create a New App"
A modal window will open
Insert the name of the App, the namespace (optional) and a Category, then click the "Create App" button

Once the app is created, the relative page is shown. Here we can find the App ID and the App Secret keys for our params array. Finally, we need to set our domain application:

Open "Settings" tab from the Facebook App Page
Add a platform
Select website from the modal window
Fill the "Site url" field in the "Website" section
Save changes

An example of the params array:

$config['extAuthParams'] = array(
[...]
    'facebook' => array(
        'keys' => array(
            'appId' => '[insert your appId]',
            'secret' => '[insert your app secret key]'
        ),
        'extraUserData' => array(), //additional permissions that the app requires
    ),
[...]
);

Twitter auth service setup

Also Twitter uses Apps for the external communication. Let's see how to create a twitter app:

go to https://apps.twitter.com
click the "Create a New App" button
fill all requested field for app creation
fill also the "callback url" field with your backend http address. Afterwards, the BEdita component can auto generate a custom callback url based on the login page, but Twitter needs this field however.

Once the app is created, the relative page is shown. We can find the App Key and the App Secret keys switching to "API keys" tab, but we need to add another setting:

Switch the "Setting" tab in the Twitter App Page
Check "Allow this application to be used to Sign in with Twitter"
Update settings

An example of the params array:

$config['extAuthParams'] = array(
[...]
    'twitter' => array(
        'keys' => array(
            'appId' => '[insert your API key]',
            'secret' => '[insert your secret key]'
        )
     ),
[...]
);

Google auth service setup

Let's see how to create a google app to use for our auth integration:

go to https://console.developers.google.com
click the "Create project" button
give the project name and project id

Once the app is created, the relative page is shown. Before the generation of secret keys, we need to set the permissions:

Switch the "APIs & auth" tab in the Google App Page and select the "API" sub tab
Look for "Google+ API" and activate it
Now switch to "Credentials" sub tab
Click on "Create new client id" button
Check "web application"
Fill "Authorized redirect URI" with your bedita url
Click on "Create Client ID"

Now we have a Client ID and a Client secret.

An example of the params array:

$config['extAuthParams'] = array(
[...]
    'google' => array(
        'keys' => array(
            'appId' => '[your client id]',
            'secret' => '[your client secret]'
        ), //the permission that the app required 
        'extraUserData' => array(), //additional permissions that the app requires
    )
[...]
);

Profile your BEdita application with XHProf

Mon, 03 Mar 2014 19:08:10 +0100

In BEdita 3.4 we are introducing XHProf integration.

XHProf is a nice tool to profile your application performance that, unlike XDebug and other tools, you can use in production systems not affecting too much the overall performance.

Steps:

install XHprof - remember to define output directory xhprof.output_dir=/path/to/dir, with correct permissions, then verify that the script works as expected in the default UI - initially you will see and empty list of "runs"
enable profiling in BEdita, simply write $config['enableProfiling'] = true; in bedita-app/config/bedia.cfg.php
now use your application and point to the xhprof_html frontend script, you will see your runs - that's it!

NOTE: Profile run file names will have this form

[run-id].[url-controllername-action].xhprof

url, is the full base url of your app without dots. You can then select the interesting "runs".

With configuration explained above you will profile backend application and every frontend application you have in frontends.

To profile only a frontend application simply comment out the line at 2. in bedita.cfg.php and write the same line in frontends/[your-frontend]/config/frontend.cfg.php

To profile only backend application, put in every frontends/[your-frontend]/config/frontend.cfg.php
$config['enableProfiling'] = false;

TECH NOTE: profiling starts at AppController::beforeFilter and ends at AppController::afterFitler, so there's still some code not profiled, mainly bootstrap and inital config file loading.

Gettext shell script

Fri, 31 Aug 2012 11:55:54 +0200

Manage i18n po files using bedita

Every template (backend, frontend, plugin) can have translationable content, which is a string (a single word or a sentence) enclosed by {t} and {/t} special tag. For example, in a .tpl file:

{t}Title{/t}: {$object.title}

You can create translations for these contents editing properly .po files, located in i18n folders:

$BEDITA_HOME/bedita-app/locale/LC_MESSAGES/< lang >/default.po
$FRONTEND_PATH/locale/LC_MESSAGES/< lang >/default.po
$BEDITA_MODULES_PATH/locale/LC_MESSAGES/< lang >/< plugin-name >.po

These files can be updated/created through BEdita gettext shell script.

BEdita shell script gettext

BEdita use gettext internazionalization and localization (i18n) system.

Usage of the shell script method update:

 ./cake.sh gettext update [-frontend < frontend-path >] [-plugin < plugin-name >]

To generate/merge .po/.pot files for BEdita backend:

./cake.sh gettext update

To generate/merge .po/.pot files for a frontend (creating frontend master.pot looking at < frontend path > [use frontend /app path]):

./cake.sh gettext update -frontend < frontend-path >

To generate/merge .po/.pot files for a plugin (create .pot and po files for specific plugin):

./cake.sh gettext update -plugin < plugin-name >

For more details:

./cake.sh gettext help

Migrating plugins from BEdita 3.1 to 3.2

Thu, 26 Jan 2012 18:06:23 +0100

A brief guide to the changes to be made to upgrade BEdita framework.

In order for plugins to work in BEdita 3.2 some changes may be needed for a plugin built with BEdita 3.1 to work properly.

As you will see, some of the changes indicated in Migrating frontends from BEdita 3.1 to 3.2 are also valid for plugins.

Since BEdita 3.2 is build upon CakePHP 1.3.x, whereas 3.1 used CakePHP 1.2, you may need to look at this guide in CakePHP cook book that describes migration of cakephp apps from 1.2 to 1.3.

Vendors

Support for vendors/css, vendors/js, and vendors/img for plugins has been removed. They have been replaced with plugin (bedita module) webroot/css, webroot/js, and webroot/img directories.
So if you have custom files in those folder, simply move css img and js folders from your_module/vendors/ to your_module/webroot/

If you need to keep BEdita 3.1 compatibility don't move your css js img folders but copy them into webroot, keep a copy in vendors for BEdita 3.1.

View and Helpers

HtmlHelper::css() no longer has an $inline parameter. Use $options['inline'] instead, for example if you had:

{$html->css("ui.datepicker", null, null, false)}

you have to change it to:

{$html->css("ui.datepicker", null, ['inline'=>false])}

or to:

{assign_associative var="params" inline="false"}
{$html->css("ui.datepicker", null, $params)}

if you need BEdita 3.1 compatibility.

flash() no longer auto echos. If you used Smarty as template engine you should replace:
```
{if $session->flash('error')}{/if}
```
with:
{$session->flash('error')}and simila.
JavascriptHelper is deprecated, you should replace:
```
$javascript->link()
```
with:
$html->script()
The array of smarty assign_concat function now must begin with 1, if you had something like:
{$assign_concat var="test" 0=$a 1=$b}simply change it to:
```
{$assign_concat var="test" 1=$a 2=$b}
```

Newsletter shell script

Wed, 09 Nov 2011 12:55:38 +0100

List of methods for script, to have updated list use

./cake.sh newsletter help

import: import data from specific source (default phplist)

Usage: import -f [-mailgroup ] [-from ] [-sep ] [-v] [-force]

-f file to import
-mailgroup mailgroup id to associate imported users
-from import source type for example from phplist csv export
-sep separator (if needed, for example if you import from csv)
-v verbose mode
-force try to save with validation errors too

createFilesListsFromPhplist: create files for each list found in the phplist export file

addCards: add cards to mailgroup, all or by category

Usage: addCards -mailgroup [-c ]

-mailgroup name of mail group / list
-c select cards by category (default: all)

merge: merge a mailgroup into another

Usage: merge -from -to

-from name of source mail group / list
-to name of destination mail group / list

Addressbook shell script

Wed, 09 Nov 2011 12:41:03 +0100

List of methods for script, to have updated list use

./cake.sh addressbook help

import: import vcf/vcard or microsoft outlook csv file, or generic csv file

Usage: import -f [-c ] [-m ]

-f vcf/vcard or csv file to import
-c comma separated to use on import (created if not exist)
-m name of mail group to associate with imported cards

export: export to vcf/vcard or microsoft outlook csv file

Usage: export -f [-t ]

-f vcf/vcard or csv file to export
-t 'vcard' or 'csv'

Dbadmin shell script

Wed, 09 Nov 2011 12:39:05 +0100

List of methods for script, to have updated list use

./cake.sh dbadmin help

rebuildIndex: rebuild search texts index

checkLangStatus: update lang texts 'status' using master object status

Usage: checkLangStatus -lang

buildHashMedia: insert 'hash_file' for media file.

Usage: buildHashMedia [-all]

-all rebuild all 'hash_file'

setImageDimensions: get images size and update db

Usage: setImageDimensions [-all]

-all set dimension for all images, otherwise only for image with dimensions no defined in db

updateVideoThumb: update video thumbnail from external provider

Usage: updateVideoThumb [-id]

-all update all video, otherwise only video with no thumbnail defined in db

annotate: add comment/editor notes to object

Usage: annotate [-id ] [-type ]

-id object id to annotate
-type 'editor_note' or 'comment'

orphans: searche and remove orphaned objects (not in tree)

Usage: orphans -type

-type model type like 'section' or 'document'

importCsv: import objects from csv file

Usage: importCsv -f -type

-f csv file path
-type model type like 'document' or 'event' to import

updateStreamFields: update name (if empty), mime_type (if empty), size and hash_file fields of streams table

checkConsistency: check objects for consistency on database

updateTreeRoot: update area_id field in trees table

checkDbNames: check database table/column names

Usage: checkDbNames [-schema]

-schema use schema file - otherwise read directly from db (default)

cleanup: remove old items from log/job tables

Usage: cleanup -days

-days number of days to preserve from today in cleanup

updateCategoryName: update all categories and tags unique name

-objectType update categories for a specific object type (for example: document)

importXml: import BE objects from XML (in a section)

Usage: importXml -f [-s ]

-f xml file path
-s section id to import

exportXml: export BE objects to XML

Usage: importXml -o -t

-o xml output file path
-t object type: document, short_news, event,.....

Bedita shell script

Wed, 09 Nov 2011 11:59:14 +0100

List of methods for script, to have updated list use (in bedita folder)

./cake.sh bedita help

init: initialize a new BEdita instance from scratch

initDb: initialize database with bedita-db sql scripts, new database with minimum data (BEdita user, basic groups one publication, one section, module data, )

Usage: initDb [-db ] [-data ] [-nodata] [-media ]

-db use db configuration specified in config/database.php
-nodata don't insert data
-data use data dump, use absolute path if not in bedita-db/
-media restore media files in

cleanup: cleanup cache, compile, log files

Usage: cleanup [-frontend ] [-logs] [-media]

-frontend clean files in [use frontend /app path]
-logs remove log files
-media clean media files in 'mediaRoot' (default no)

checkMedia: check media files on db and filesystem

export: export media files and data dump in a .tar or .tar.gz file

Usage: export [-f ] [-compress]

-f file to export, default bedita-export.tar.gz
-compress gz compression (automagically applied if file extension is .gz)
-nomedia don't export media files in tar

import: import media files and data dump

Usage: import [-f ] [-db ] [-y]

-f file to import, default bedita-export.tar.gz
-db use db configuration specified in config/database.php
-y answer always 'yes' to questions...

checkApp: check app files ... (core.php/database.php/index.php...)

Usage: checkApp [-frontend ]

-frontend check files in [use frontend /app path]

modules: simple operations on BEdita modules list/enable/disable

Usage: modules [-list] [-enable ] [-disable ]

mimeTypes: update config/mime.types.php from standard mime.types file

Usage: mimeTypes -f

updateObjectTypes: update object_types table

Shell scripts reference

Tue, 08 Nov 2011 17:46:37 +0100

Core shell scripts available in BEdita

To call shell scripts point to bedita root folder (containing bedita-app, cake,...) and type:

./cake.sh [shell-script] [options]

on *nix systems (Linux, MacOSX,...) or

cake.bat [shell-script] [options]

on windows

For example: ./cake.sh bedita cleanup - a common/quick way to remove compilations, cache, temporary files in general

To get all available shell scripts type:

./cake.sh help

To get help for a specific script type:

./cake.sh [shell-script] help

Core scripts

Here the main BEdita scripts

bedita: general purpose main script, db operations, data import/export, modules enable/disable....
addressbook: import/export addressobook items
dbadmin: generic db operations
gettext: create and merge gettext .po files (gettext php module is needed)
mail: internal script to send newsletter/notifications - to use in cron jobs mainly
newsletter: mass imports, mailgroup merge and other newsletter operations
module: plug/unplug modules, generate schema for plugins - module plugins

BEdita Objects: models

Fri, 07 Jan 2011 16:43:58 +0100

This article explain how the Objects Models works in BEdita

Every BEdita object is represented by a model that has to extend BEAppObjectModel class or its sublcasses and that has to define some class attributes.

Usually is preferable to extend a subclass of BEAppObjectModel where attributes and base associations are already defined. You can find a complete set of them in bedita/bedita-app/app_model.php file.

Every model of BEdita object has to be associated by a "hasOne" relation with models that manage base object tables (BEObject, that uses objects table).

So having a look at Image model located in bedita/bedita-app/models/objects/content/image.php we can see that it extends BeditaStreamModel that has an hasOne relation with BEObject, Content and Stream ie with the tables objects, contents and streams.

Required class attributes

array $modelBindings
It defines bindings with other models used in method find() of CakePHP. For example the "detailed" key is used automatically when you view an object detail in BEdita backend. This attribute is used by Containable behavior of CakePHP.

array $actsAs
It defines the behaviors used by model. Define it as an empty array if you don't need it.

array $objectTypesGroups
It contains a list of groups of object type.

"leafs" tells if an object can be put on the publication tree structure
"related" tells if an object will appear in the relation list when not specific list of object types is been defined (free semantic relation).
"multimedia" tells if an object is a multimedia object

Define as an empty array if you don't need it.

array $searchFields
It contains the score/importance of database fields used for full text search (only MySQL now) in a 1-10 range. For example:

public $searchFields = array(
   "title" => 10,
   "creator" => 6,
   "description" => 6,
   "subject" => 4,
   "abstract" => 4,
   "body" => 4
);

Meaning that "title" field is more important (10) than "description" (6) which is more important than "abstract" (4).

Error logs: 'missingController' message

Tue, 15 Mar 2011 16:26:04 +0100

This article is about error log messages and the strange/mysterious 'missingController' message

As you may know BEdita uses standard CakePHP log files for its own logging system.

You have different sets of log files for your backend application and for every frontend application/site, namely:

in bedita/bedita-app/tmp/logs for backend error.log/debug.log files
in bedita/frontends/www.myfrontend.com/tmp/logs for every frontend, where path will change (substitute www.myfrontend.com with the actual frontend dir name), with usual error.log/debug.log files

To write in these log files use the $this->log() method inside every BEdita controller or model.

Here you will find, for example, exceptions related messages, such as stack traces, like:

2011-01-11 11:11:11 Error: BeditaException - Error: object type not found File: bedita-app/models/objects/b_e_object.php - line: 522 Trace:
#0 bedita-app/controllers/frontend_controller.php(1211): BEObject->getType(false)
#1 [internal function]: FrontendController->section('blog', 'img', 'loadingAnimatio...')
#2 bedita-app/controllers/frontend_controller.php(1382): call_user_func_array(Array, Array)
...

That refers to some unexpected error. You may inspect this log file to find possbile bugs or unwanted behaviours of your application. These log messages can be hard to understand but if you follow source files/line numbers you may find out what the problem is.

Typical messages are classic HTTP 404/500 error messages like

2010-12-13 18:47:21 Error:  500 Internal Error - missingTable: array (...)
...

Other log messages are definitely more cryptic/mysterious. For example this one that we were investigating these days:

2011-03-10 10:43:42 Error:  404 Not Found - missingController: array (
   'BEAuthUser' => ...
   'controller' => 'JsController',
   'controllerName' => 'Js',
)

Seems like an attempt to retrieve something through an URL like /js/... that is normally used for javascript files. This indicates that some of your javascript links are broken, you are probably linking to a missing js file. Same applies to css or image files, for which you will find a missing CssController o ImgController in your log files.

To easily find out which links are broken we suggest you to use a tool like Firebug: enable "Net" view and look for 404 errors in HTTP GET calls highlited in red. Look at the screenshots in this page for an example.

BEdita Objects: database tables

Fri, 07 Jan 2011 13:28:38 +0100

Description of BEdita object database table structure

As you can read in the overview article a BEdita Object consists of one or more tables. All BEdita objects have the objects table as a common element, and they can have specific fields defined in other tables linked by a one-to-one relationship with objects table.

Every BEdita object has one row and the same id in every table involved. For example the image object type is defined by four tables: objects, contents, streams and images. When a new image is added to BEdita a new row with the same id will be inserted in each tables.

However a BEdita object can have other properties than those defined through the base object tables. It can have tags, categories, and others with their own table and are linked to the BEdita object.

Integrity constraints are used between BEdita object tables and properties involved for ensure consistency of data and to perform cascading delete. In this way deleting a row on the objects table will remove all references to that object in the database. This is powerful but requires attention when creating schemas for new tables.

For example you can see below a portion of the contents schema table (MySQL version here):

CREATE TABLE `contents` (
`id` INTEGER UNSIGNED NOT NULL,  
`start_date` DATETIME NULL ,  
...  
PRIMARY KEY(id),  
FOREIGN KEY(id) REFERENCES objects(id) ON DELETE CASCADE ON UPDATE NO ACTION) ENGINE=InnoDB DEFAULT CHARSET=utf8 COMMENT = 'general contents data' ;

in particular:

FOREIGN KEY(id) REFERENCES objects(id) ON DELETE CASCADE ON UPDATE NO ACTION

defines the integrity constraints between contents.id and objects.id:

no row on contents can be inserted without a relative row in objects
when a row in objects is deleted then the relative row on contents will be removed

To see more examples have a look at bedita/bedita-app/config/sql/bedita_mysql_schema.sql

BEdita Objects overview

Fri, 07 Jan 2011 09:33:20 +0100

Understanding BEdita objects

A BEdita Object is the main item on which is built BEdita. There are many types of objects in BEdita as document, gallery, section, image, etc... and you can create as many as you want through new modules and addons. You can see a list of these objects in object_types table where the field module_name is the main module where you can handle the corresponding object.

From the database point of view a BEdita Object consists of a common base element (the base table objects) that may be extended with other object elements (i.e. other tables such as contents, cards, etc..) that add specific persistent properties to objects and other common properties/metadata such as categories, tags, geo tags, etc...

You don't necessarily need to add tables to create a new object type; instead you can create as many objects as you want maintaining the database unchanged (for example documents, events and short_news objects uses the same two tables objects and contents). If you need to add a table for your object you will have already a base on which building it.

From the model point of view a BEdita Object is a CakePHP model that has to extend BEAppObjectModel class or one of its subclasses (located in bedita/bedita-app/app_model.php) and has to define some required class attributes.

Remember that the object type names (in object_types table) are underscored while the relative model class names are CamelCased. So if you have a model class named MyFantasticObject the object type name will be my_fantatstic_object.

How to Create BEdita Translations

Tue, 04 Jan 2011 16:19:00 +0100

A brief introduction on how to create a BEdita translation

To see how to enable translations have a look at "Enable translation" paragraph.

BEdita translations are located in bedita-app/locale folder and each language package consists of a folder named with relative ISO-639-3 codes. The structure is:

bedita/bedita-app/locale/(lang-code)/LC_MESSAGES/default.po

where default.po is the translation file. There are two methods you can follow to create your translation: in each method you'll have to edit a po file. Unless you're familiar with their format you should use a po editor. There are free tools such as PoEdit which make editing and updating your po files an easy task but if you want use your favourite text editor assure to use UTF-8 to avoid problems.

Method one (shell script)

To work properly this method need gettext utilities installed so if you don't or you can't install it read method two.
As first thing you have to prepare your language .po file with a correct header entry (UTF-8 charset is important).

So for example if you want create a russian translation you have to create a file named default.po in bedita/bedita-app/locale/rus/LC_MESSAGES folder. Then you will need to edit the file headers entry. Copy them from bedita/bedita-app/locale/eng/LC_MESSAGES/default.po file:

msgid ""
msgstr ""
"Project-Id-Version: BEdita 3\n"
"POT-Creation-Date: 2011-01-04 16:26:49\n"
"PO-Revision-Date: \n"
"Last-Translator: \n"
"Language-Team: Bedita I18N & I10N Team\n"
"Language: \n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=2; plural=(n != 1);\n"

Save file, then open a shell, go to bedita folder and write:

./cake.sh gettext update

this shell script will update master.pot file and all default.po file in locale subfolders. You will see also a translation percentage for any language. This script mantains updated every language adding new entry to translate or remove entry no more used.

Once the script runs edit your default.po file translating every msgid entry with relative msgstr.

Method two (copy by hand)

Copy bedita/bedita-app/locale/eng/LC_MESSAGES/default.po in your translation folder and edit every msgid entry with relative msgstr.

Remember to use UTF-8 charset to edit po file.

Customizing BEdita with addons

Fri, 19 Feb 2010 17:13:37 +0100

Extending BEdita using addons folder to enhance your features in backend and frontend apps.

Designing frontend application you could need to extend BEdita with components, models or helpers to use in backend and frontend apps too. To not mess BEdita core with not core items you should use the addons folder. Addons is a place where CakePHP will search for models, components, helpers and vendors. It's a conventional folder where you can put no core classes.

The addons folder that you can find in bedita root folder presents some directories that are automatically added to CakePHP paths to retrieve the relative classes.

addons
|--components
|--config
|--helpers
|--models
|--vendors

For Example CakePHP will search components in bedita/bedita-app/controllers/components and in bedita/addons/components and so on for models, helpers and vendors.

Adding new BEdita object type

If you need a new BEdita object type that not require a new BEdita module you should put your Model in addons/models folder then you'll have to enable the object type to be written in configuration and so to be used correctly in any part of BEdita. To do it go in administration module and click on addons in the left menu. There you can enable/disable BEdita object type and see a complete list of all addons available on the system.

If you want manage your new BEdita object type in a module already present, add to your model the attribute $module. For example if you have created a Place model and you want to see it in Addressbook module, write in you model class:

public $module = "addressbook";

according with field "name" in table "modules". Then enable your addon.

In config folder you can create a config.php file and put in some global configurations that you'll have available in BEdita. For example when you add a new BEdita object you could need a free semantic relations that involve it with other BEdita objects. Write your configuration like an array named $config.

Note that disabling a BEdita object addon all objects belonging to it will be deleted, but you will have to edit config.php if you want to remove any configuration related to that model.

For more information about BEdita objects see the "BEdita objects" articles.

BEdita module as a CakePHP plugin

Mon, 08 Feb 2010 11:59:28 +0100

This article shows how to create a new BEdita module through a CakePHP plugin

Creating a new module in BEdita is simple like writing a CakePHP plugin. Generally a module will have a controller, one or more models, some views, at least a css that defines the module color and a special file named bedita_module_setup.php that contains some rules and definitions to start up and hook correctly the module to BEdita. Without this file the plugin will not be recognized from BEdita as a valid module. Each BEdita module has to be stay in the modules folder that you can find in bedita root folder.

You can find a sample plugin module in bedita-app/modules/sample_module : start from here, changing files and folder names and editing some other stuff

Otherwise you can build the new module from scratch using this sample module as reference. Once your module is configured properly it can be activated by the admin module web interface.

Here you can find some basic rules to build your module:

modules folder

The name of your module will be the name of your plugin folder. Pay attention that the module name isn't the module label that you can see in BEdita backend square and that you will define in bedita_module_setup.php how you can see below.

The name of your module controller file has to be the same of the plugin folder. So the structure will be:

bedita-app/modules/sample_module/controllers/sample_module_controller.php

config folder

This folder contains the fundamental bedita_module_setup.php and a config.php (optional) file with some global configurations. The first one will contain an array like:

$moduleSetup = array(
    "publicName" => "Sample Module",
    "author" => "Channelweb and Chialab",
    "website" => "http://www.bedita.com",
    "emailAddress" => "info@bedita.com",
    "description" => "Example of BEdita's module plugin",
    "version" => "0.1",   
    // minimum BEdita version required by this module
    "BEditaMinVersion" => "3.1",
    // maximum BEdita version supported by this module
    //"BEditaMaxVersion" => "3.1",
    // model names that are BEdita objects: i.e. extend BEAppObjectModel  
   "BEditaObjects" => array("SampleObject"),
    // extra database tables used/needed by this module
    // "tables" => array("sample_objects"),
);

publicName that is the module label you can see in the square box on BEdita that refers to your module, the author, a website of the author, a referent email, the version, the BEdita minimum compatible version, a description and an array of new BEdita objects (new model names that are BEdita objects, not just simple models) involved by module. If your module needs you can define here a BEdita maximum version supported and an array of tables used by your module.

If you needed to define some global configurations (like relations with other objects) put it in config/config.php file and it will be loaded in every BEdita page. For example if your module defines a new free relation with document object add this:

$config["objRelationType"] = array(
   "custom_relation" => array(
      "hidden" => false,
      "left"      => array("sample_object"),
      "right"  => array("document")
   )
);

controller

Controller name, as we said, has to be the same as the plugin folder with _controller suffix.
Controller has to extend the ModulesController abstract class located in the app_controller.php file. If the module uses only a BEdita object the controller has to override some basic methods: index, view, save, delete, deleteSelected, forward. If your module use two or more BEdita objects then implement specific method viewBEditaObjectModel, saveBEditaObjectModel, deleteBEditaObjectModel instead of view, save and delete. ModulesController methods (view, save, delete) will take care of routing at the correct method of your controller.

A required attribute of your module controller class is:

protected $moduleName = 'sample_module';

that will be the controller name with underscores.

model

Your module models can be of two types. A standard cakePHP model or a BEdita object model. In the second case the model will have to follow some guidelines that you can read in BEdita object articles. However if your module uses one or more new BEdita objects, their names (class names) should be placed in bedita_module_setup.php at the key "BEditaObjects". Automatically they'll be inserted in object_types table and put in the cached configuration.

views

In modules/sample_module/views/sample_module folder reside the views of your module. Commons BEdita tabs like (text, tags, translations, etc....) are CakePHP elements so you can reuse it from your plugin calling:

{$view->element('elementName')}

In all views should be present modulesmenu.tpl element that contains the on top modules navigation. view.tpl should contain form_common_js.tpl element to load standard BEdita javascript form functions.

css

Folder /sample_module/vendors/css has to contain the module_color.css file where you can specify the module color. This file is linked in every BEdita backend page: all modules color are always available. If you need specific css for you module put it in a file named module.css that will be linked only in the module pages.

js

Like css also for specific javascript you want to use in your module put it in vendors/js/module.js file. It will be linked only in the module pages.

How to create schema.php for extra tables

When you have extra tables in your setup ($moduleSetup["tables"]), you have to create correctly the following files: config/sql/schema.php, config/sql/mysql_schema.php. In order to do that, you should use cake module script. Let see how to do that, with an example in 3 steps.

1. First of all, create your database table(s), and don't loose your sql creation script (you could use it, later).

2. Launch cake module script as follows:

./cake.sh module schema -name sample_module

The module script creates files config/sql/schema.php and config/sql/mysql_schema.sql.

3. Check config/sql/mysql_schema.sql and if it's not correct, overwrite it with sql creation script that you used at step one. Cake schema can lose some table information, like constraints, that's why you could need to overwrite it with your original sql script.

It's done! You can plug-in/plug-out your new pluginModule from BEdita Administration Plugin Module Section.

How to manage free semantic relations

Fri, 29 May 2009 18:08:58 +0200

Define and customize relations between BEdita objects

One of the most powerful features of BEdita is the possibility to define and use free semantic relations between objects. In this article I'm going to show you how build and use them.

BEdita objects

BEdita is completely object-oriented, so every element is an object with a specific object type. The object type itself defines some particular behaviors like the possibility to be showed in a certain module, the possibility to stay in the tree structure and the way to relate with other object types. You can find the BEdita object types inside the table object_types that contains id, name and module fields. To create a new relations we'll use the id of the object types.

Where do I define relations between objects?

The first thing to know is that these relations have to be defined in a configuration file, in particular in bedita-app/config/bedita.cfg.php. You can find some default relations in bedita-app/config/bedita.ini.php but this file shouldn't be touched (may be overwritten during an update of BEdita), so have a look at the relations in this file only as reference.

In bedita.cfg.php you can find the configuration variable:

$config["objRelationType"]

commented. Uncomment it and let's customize your relations.
Choose a name for your relations for example "speakers":

$config["objRelationType"] = array(
   "speakers" => array()
);

In this way I'm going to define a free relation named "speakers" that can link all objects. Now go to Addressbook module (this module use Card objects, as you can see in object_types table) and click on create "new card". Have a look at Relationship tab and you can see that the new relation appears in it (figure 1).

Now you can click on "Connect new items" button to link other objects to this one, change order of related objects by drag & drop (figure 2) and then save the card to estabilish the relation.

In this way we have defined the relation for all object types so if you look at other modules like Documents, Events, Galleries, etc... you'll find the "speakers" relation in the Relationship tab. But if I want that the relation is estabilished only between some objects, how can I do it?

Customizing a relation between some object types

Suppose that I have to manage a festival site. I can create all festival events thorugh Events module and all people that partecipate to the festival through Addressbook module. Some of this people will be speakers so I will have to associate the events to the cards of the speakers through the "speakers" relation. I want to use my "speakers" relation only to link events to cards, I don't want to see and to use this relation in Galleries module, for instance. Edit $config["objRelationType"] in this way:

$config["objRelationType"] = array(
   "speakers" => array(
      "left" => array("card"),
      "right" => array("event")
   )
);

Here I define that the "speakers" relation is estabilished between some object types. On the left I have card objects and on the right I have event objects. Note that the order of the object types in "left", "right" key is indifferent.

In this way only in Events and Addressbook mdoules you can see "speakers" in Relationship tab.

If you want to use this relation for other object types it's enough add ids to "left" or "right" key so, for example:

$config["objRelationType"] = array(
   "speakers" => array(
      "left" => array("card"),
      "right" => array("event","documents")
   )
);

With this definition I can associate documents and events from a card object and I can associate only cards from a document or an event object.

One way relations

The relations are built in both directions by default, so I can see the association from both the objects involved. In some rare case I could desire that the relation were shown only in one direction. In these cases we can build a one way relation always editing bedita.cfg.php file.

$config["cfgOneWayRelation"] = array(
   "speakers", 
   "other one way relation"
);

Now if I create a "speakers" relation from card to event I will see the relation inside the card object but I will not see it inside the event object.

Relations in frontend

As explained in "My first frontend" you'll find the semantic relations between objects in an array named "relations" so for example in an event related with some card by "speakers" relation I will have:

[relations] => Array (
[speakers] => array( 
   0 => card1, 
   1 => card2, 
   ...
)

At the end

At the end of this article you should be able to build your custom semantic relations between objects in simple or complex way to model your BEdita instance according to your needs.

BEdita Documents and Resources | Core

Event System and Callbacks

Automatic callback behaviors

CallbackBehavior configuration

Adding custom callbacks

Unbinding custom callbacks

Adding callbacks on-the-fly

BeCallbackManager class reference

function bind(string $eventName, mixed $listener)

Params

Examples

function unbind(string $eventName = null, mixed $listener = null)

Params

Examples

function trigger(string $eventName, array $eventData = array())

Params

Return values

Examples

Exception handling

HTTP Exceptions

Introducing new Exception Handler

Setup custom exceptions handler

ResponseHandler Component, JsonView and XmlView

Debug toolkit activation

ResponseHandler Component

Sending Headers

Setting Type

Disabling Automatic Response

JsonView and XmlView

How to set up and configure external authentication services [backend]

Profile your BEdita application with XHProf

Gettext shell script

Migrating plugins from BEdita 3.1 to 3.2

Vendors

View and Helpers

Newsletter shell script

Addressbook shell script

Dbadmin shell script

Bedita shell script

Shell scripts reference

BEdita Objects: models

Required class attributes

Error logs: 'missingController' message

BEdita Objects: database tables

BEdita Objects overview

How to Create BEdita Translations

Method one (shell script)

Method two (copy by hand)

Customizing BEdita with addons

Adding new BEdita object type

BEdita module as a CakePHP plugin

modules folder

config folder

controller

model

views

css

js

How to create schema.php for extra tables

How to manage free semantic relations

BEdita objects

Where do I define relations between objects?

Customizing a relation between some object types

One way relations

Relations in frontend

At the end

`CallbackBehavior` configuration

`BeCallbackManager` class reference

`function bind(string $eventName, mixed $listener)`

`function unbind(string $eventName = null, mixed $listener = null)`

`function trigger(string $eventName, array $eventData = array())`