BEdita Documents and Resources | Frontends

URL-friendly content translations

Mon, 31 Aug 2015 11:40:51 +0200

As of version 3.6.0, BEdita is distributed with an improved system to serve content translations in a URL-friendly way. This new feature is fully backwards-compatible, though it may need some minor changes in your frontend PHP code to actually gain advantage of it.

Routing

The first change that will need to be made in your frontend is about routes. To achieve URL consistency in a easy and reliable way, as well as leaving developers some flexibility on how internationalized URLs are shown to end-users, a change needs to be made in your frontend's config/routes.php:

/***** FROM *****/
Router::connect('/*', array('controller' => 'pages', 'action' => 'route'));
/****** TO ******/
Router::connect('/lang/:lang/*', array('controller' => 'pages', 'action' => 'route'), array('lang' => '[a-z]{2,3}', 'persist' => array('lang')));
Router::connect('/*', array('controller' => 'pages', 'action' => 'route'));

Of course, you can change /lang/:lang/* to whatever you want (you could choose to leave just /:lang/*, for instance), as long as the :lang placeholder appears somewhere in your route. You should take care of avoiding conflicts with existing routes and/or other URLs of any kind.

Linking to translated content

To provide consistent links to translated content, a further update in your code will likely be needed.

If you took advantage of CakePHP's HtmlHelper::url() and HtmlHelper::link() methods by passing them an array of routing elements as argument, then you are already done.

On the other hand, if you used pre-built strings to generate links within your frontend (i.e. $html->url('/my-section/my-document')), you might want to use BeHtmlHelper::url() and BeHtmlHelper::link() to achieve URL consistency without having to rewrite all internal links. Please be aware and always keep in mind that this is not the preferred method: you should always pass an array to those function to link internal resources, so consider this as your last resort.

Using `BeHtmlHelper`

First of all, your frontend's PagesController must declare BeHtmlHelper in the list of used helpers:

public $helpers = array('BeHtml' => array(), 'BeFront');

Please note that it should be added before BeFrontHelper and with an empty array of options. This is due to the way CakePHP handles helpers' instances.

Now BeHtmlHelper is loaded and can be used in your view templates. All you have to do is mass-replace any instance of $html->url('/some/url') and $html->link('title', '/some/url') with $beHtml->url('/some/url') and $beHtml->link('title', '/some/url') respectively in your templates to fully achieve URL consistency within and across translations.

Generating meta-tags

Last of all, you should provide spiders and bots a list of translations available for the current resource. This can easily be achieved with BeFrontHelper::metaAlternate() function:

echo $beFront->metaAlternate();  // To generate meta-tags for all languages in `$conf['frontendLangs']`.
echo $beFront->metaAlternate(['en', 'it', 'fr']);  // To generate meta-tags for a list of languages.
echo $beFront->metaAlternate(false);  // For contents with no translation available.

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
    ...

Frontends: a brief overview

Mon, 30 Mar 2009 18:41:32 +0200

A question that sooner or later you will ask yourself using BEdita is:

"Ok, nice software, now I have all my contents, videos, images into BEdita...what can I do with it?"

Right, now it's time to find out how frontends are built.

BEdita has been developed in a way to let complete freedom in building and setting up frontends: that means, all contents will be used in different ways, and maybe there is not going to be a web interface at all for your publishing. Anyway, a frontend web interface is what you normally would create, and that is what we are going to describe.

At this stage BEdita has a very simple sample frontend template (you will find it in frontend/site.example.com), but not a predefined reference: a common thing in most Web CMS systems out there. That means: you need at least a basic knowledge of HTML, CSS, PHP to create/setup your own frontend. Sure you can use some of the templates you'll find... but BEdita is mostly a powerful tool for webdesigners/webdevelopers.

BEdita provides a rich API and tools to model and manipulate your backend contents easily and concentrate only on the visual frontend creation process (also well known as view in MVC standard pattern).

Without writing a single line of code you will have contents and sections data available as PHP Arrays or XML or RSS and in few simple steps you will be able to display your contents by type, paginate, order them, etc etc..

Embedding Images with beEmbedMedia

Mon, 14 Sep 2009 17:28:00 +0200

A quick look into BEdita helper to show and manipulate images

Embedding images is probably the most common use of the BeEmbedMedia Helper. You just have to pass the $object array corresponding to an image object to the helpers object() method.

This helper will generate cached versions of thumbnails (or other image transformations) of your images the first time you call object() method. Subsequent calls will use cached version and will be obviously much more fast.

Imagemagick or GD library

The thumbnails can be generated using Imagemagick as well as GD library. Imagemagick is preferred beacuse it consumes less memory and it's more speedy so the Helper will try to use it, anyway a fallback on GD is present. So at least the GD PHP module must be installed on your system.
Anyhow if you want to force the use of GD you would want override the default configuration option

$config['media']['image']['preferImagemagick'] = true;

located in in bedita-app/bedita.ini.php setting it to false in bedita-app/bedita.cfg.php

Using BeEmbedMedia Helper

In the following examples we will refer to BEdita 3.2, and we will use the new Smarty 3 syntax for arrays.

The parameters that are used for image manipulation are:

longside, width and height

At least, one of this parameters is required for displaying an image, and the value must be an integer. If no parameters has specified, the default values ['image']['thumbWidth'] and ['image']['thumbHeight'] in bedita.ini.php will be used. The longside parameter specifies that the longest side of the image will be resized at the specified size and the helper automatically ignores the other two parameters.
Otherwise width and height are used to resize the image in the canonical way but if only one dimension is used, the mode param will be forced to resize.

mode and modeparam

When we want to display thumbnails, we will write something like:

{$beEmbedMedia->object($media, ['width'=>200, 
  'height'=>200, 'mode'=>'crop'])}

The mode param specifies the type of scaling applied to the image. It's not mandatory, if not specified default bedita.ini.php parameter ['image']['thumbMode'] is used.
In the case above, the output result is:

where the image was resized proportionally with the main side of 200px.
Other mode valid parameter type are: croponly and resize as displayed below.

modeparam parameter is optional and depends on which mode is specified. If the mode is croponly then we can specify the starting point for the zone to crop of the image with a string: 'C', 'T', 'B', 'L', 'R', 'TL', 'TR', 'BL', 'BR' .
For example, the code:

{$beEmbedMedia->object($media, [ 'width'=>300, 'height'=>300, 
 'mode'=>'croponly', 'modeparam'=>'BL' ] )}

generates the following images, cropped from the Bottom-Left angle:

As long as the code:

{$beEmbedMedia->object($media, ['width'=>300, 'height'=>300, 
 'mode'=>'croponly', 'modeparam'=>'TR'] )}

generates the following image, cropped from the Top-Right angle:

If mode is set on resize, then we can specify the type of resize with the fill or stretch string in the modeparams parameter.
The following code:

{$beEmbedMedia->object($media, ['width'=>100, 'height'=>300, 
  'mode'=>'resize', 'modeparam'=>'stretch'] )}

Will resize the image exactly to the dimension required:

Otherwise, using the fill options in the modeparam:

{$beEmbedMedia->object($media, ['width'=>400, 'height'=>100, 
'mode'=>'resize', 'modeparam'=>'fill', 'bgcolor'=>'CCCCCC' )}

Will resize the image proportionally, filling the remaining space with the color specified in the bgcolor param. Note that the bgcolor param is considered only with the mode="resize" modeparam="fill" combination.

type

The type param is used to force the output type of the image as gif or png or jpg.

upscale

It's a boolean parameter with the default bedita.ini.php ['image']['thumbUpscale'] that allows or not the upscaling of an image.

Filtering section's objects

Tue, 08 May 2012 15:26:54 +0200

Learn how to filter section's objects according to your need

Usually the section's objects that BEdita loads automatically are what you need for your frontend app, but sometimes you would want filter objects inside a section to obtain a more specific list of items to use in views.

In these cases the FrontendController::sectionOptions attribute is what suits you. Through this attribute you can control pagination results and other things, like how many and which contents get and in which order you want them.

Overriding the key "filter" in this class attribute you can easily handle children's section results. You can override $sectionOptions for an entire frontend redefining it in PagesController, but usually you'll override it just in some specific section. To do so you should use the section callback nicknameBeforeFilter, before section data loading, to set your filter.

Default behavior

Suppose that you have a section nicknamed "my-section" that contains different kind of object type (documents, galleries, events, ...) and that you want to fetch only documents, then you can set the filter option as

protected function my_sectionBeforeFilter() {
	$this->sectionOptions['childrenParams']['filter'] = array(
		'object_type_id' => Configure::read('objectTypes.document.id')
	);
}

where object_type_id is a field of objects table. See also $config[objectTypes] definition. Note also that in BEdita 3.2 or higher the method name would camelize i.e. mySectionBeforeFilter.

The SQL conditions

WHERE object_type_id = '22'

will be generated.

If you want to select galleries too then write

$this->sectionOptions['childrenParams']['filter'] = array(
	'object_type_id' => array(
		Configure::read('objectTypes.document.id'),
		Configure::read('objectTypes.gallery.id')
	)
);

The SQL conditions

WHERE object_type_id IN ('22', '29')

will be generated.

You can of course add other kind of fliters, for example using specific database table fields want to add other filter. Say you want to filter using publication start_date you may want to use this

$this->sectionOptions['childrenParams']['filter'] = array(
	'object_type_id' => array(
		Configure::read('objectTypes.document.id'),
		Configure::read('objectTypes.gallery.id')
	),
	'Content.start_date' => ">= '2011'"
);

In that way a one to one relation is used to join objects to contents table and the SQL conditions

WHERE object_type_id IN ('22', '29') AND Content.start_date >= '2011'

is used.

Other filter rules

Some other filter rules are defined in BuildFilter Behavior located in bedita-app/models/behaviors folder. These rules are usually used in BEdita backend but you can use it for your need. Every rule is defined with a method named with the rule name followed by "Filter" word.

For example you could use the category filter to filter objects by category.

$this->sectionOptions['childrenParams']['filter'] = array(
	'category' => 'documentation'
);

where "documentation" is the name of the category you want to filter for.

Pay attention on the fact that not all filter rules that you find in BuildFilter Behavior are useful in frontend app, if used through $sectionOptions attribute, because filter results are refined at a later stage.
For example, if you want to use a filter in order to add fields to results you must use model bindings instead.
So if your section's objects have to show the user that has created them and you apply the filter

$this->sectionOptions['childrenParams']['filter'] = array(
	'user_created' => true
);

the result does not reflect what you would expect, because it is refined getting objects' details through model bindings. You should instead check that all objects bindings contain UserCreated.

Create your own rules

From BEdita higher than 3.1.6 the filter is highly customizable extending the BuildFilter Behavior class and following some simple rules.
We're going to explain how to do it in a next article.

Understand how the View is chosen

Wed, 25 Jan 2012 14:53:55 +0100

Let's see which view file is chosen in a BEdita frontend call

Understand how the view file is chosen is fundamental if you want mastering frontend customization. In the standard frontend flow the requested url is processed by BEdita to load a section or a content by nickname then it renders the view file named section.tpl located in app/views/pages folder. This view uses the BeFrontHelper::chooseTemplate() method to determine which tempate file has to be included following the schema below:

1. Check frontendMap currentContent nickname

First of all the chooseTemplate() method checks if you have configured the file app/config/mapping.cfg.php to map nicknames or ids to views. If so and if the page points to a content nickname (located in view array $section['currentContent']) mapped then the view specified is searched and eventually used.

Example: app/config/mapping.cfg.php file contains

$config["frontendMap"] = array(
    "example-one" => "sample_template"
);

url: http://www.example.com/example-one where "example-one" is the nickname of a content
view file searched: app/views/pages/sample_template.tpl

The same view is searched if browser points to http://www.example.com/demo/example-one where demo is the nickame of the parent section of example-one.
If view file doesn't exist then it goes on to the next step.

2. Check frontendMap section nickname

If first check fails then the method checks if the current section is mapped in mapping.cfg.php and eventually uses it.

Example: app/config/mapping.cfg.php file contains

$config["frontendMap"] = array(
    "demo" => "demo_template"
);

url: http://www.example.com/demo/example-one
view file searched: app/views/pages/demo_template.tpl

3. View with same name as currentContent nickname

If point 2 fails, then the method try to search a view named as current content nickname.

Example:

url: http://www.example.com/demo/example-one where "example-one" is the nickname of a content.

If it's present a view file named example-one.tpl in app/views/pages folder then it will be used.

4. View with same name as section nickname

Successive check is the same of point 3 but with section nickname instead of content nickname. So if view file with the same name as the section nickname is found in app/views/pages folder then it's used.

5. View with same name as parent sections nickname

if point 4 fails the next step is to check the presence of a view file named as one of the parent section of current section using the $section['pathSection'] array. First view file

6. Object type template name

The last check is done with object type of current content. A view file named as the object type is searched. For example, if you create an event.tpl file in app/views/pages then it is used every time a BEdita object of type event is loaded as a request of an url.

7. Default fallback

If none of the previous checks is satisfied then the fallback mode selects the view file app/views/pages/generic_section.tpl

Localize your frontend

Wed, 04 Jan 2012 16:50:18 +0100

To localize your frontend app you have to follow the steps below:

Prepare you frontend editing the configurations vars in frontend-app/config/frontend.ini.php file
- $config['frontendLang'] with the default language (i.e. 'eng')
```
$config['frontendLang'] = 'eng';
```
- $config['frontendLangs'] with an array of supported languages, for example
```
$config['frontendLangs'] = array(
    'ita' => 'italiano',
    'eng' => 'english'
);
```
- Eventually edit the config var $config['frontendLangsMap'] according to your needs to add or remove maps of languages to autodetecting language choice
```
$config['frontendLangsMap'] = array(
	'it' => 'ita',
	'en' => 'eng',
	'en_us' => 'eng',
	'en-us' => 'eng',
	'en_gb' => 'eng'
);
```
  where the key is the language comes from HTTP client request and the related value is the language you have defined in $config['frontendLangs']
- Choose a name for the cookie where the language will be wrote on (always in frontend.ini.php)
```
$config["cookieName"] = array(
	"langSelect" => "basicExampleLang"
);
```
translate your contents from BEdita backend through out the Translations module;
use the Smarty tag {t}text to translate{/t} and/or the CakePHP method __('text to translate', true) to write all the static parts of your frontend;
translate these static parts. Read 'How to Create BEdita translations' and apply it to your frontend. You have to use the locale frontend folder to put the .po files and launch the shell script
```
./cake.sh gettext update -frontend path/to/your/frontend
```
to update .po files with the strings to translate;
if some static translations you have wrote in .po files doesn't appear you should cleanup the cached file with
```
./cake.sh bedita cleanup -frontend path/to/your/frontend
```

Now your frontend app is ready to be browsed in different languages.

When a visitor comes to your frontend app the system tries to autodetect the language choice through $config['frontendLangsMap'].
If autodetecting fails, the default language defined in $config['frontendLang'] is used. The language is wrote in session and a cookie with the language used is automatically set, so if a user returns to visit your frontend he starts to navigate with the language of his last visit. The cookie name can be found and edited in $config["cookieName"]["langSelect"] variable in frontend.ini.php as indicated in the above point 3.

Change language on the fly

You can change the frontend language from a language to another, for example from english to italian, simply with:

http://www.example.com/lang/ita

The language will be set to italian and the client will be redirected to the referred, so if you have loaded the page http://www.example.com/my-page and you write in the address bar http://www.example.com/lang/ita the language will be changed to italian and the http://www.example.com/my-page will be reloaded.

Instead to change language and redirect to a specific section (or content) with nickname my-nickname you could write in the address bar

http://www.example.com/lang/ita/my-nickname

and so on for all the other languages.

The view

At this point you could add an element to switch language in the view of your frontend app. In the view you'll have the current language in the $currLang variable while $conf is an object that contains all the configuration variables. Therefore a simple example of Smarty view can be:

{foreach from=$conf->frontendLangs key="lang" item="label"}
	{if $currLang == $lang}
		{$label} | 
	{else}
		< a href="{$html->url('/lang/')}{$lang}" >{$label}< /a > |
	{/if}
{/foreach}

Create custom error 404 and error 500 pages

Wed, 14 Mar 2012 11:05:08 +0100

Create views for common HTTP errors in your frontend

On your frontend applications you may want to have nice and useful error pages for your users (both human and non-human: bots, spiders...).

Typical cases of page not found (Error 404) or internal error (Error 500) are already handled by BEdita: correct HTTP error codes are sent to user-agent/browser, some basic information is displayed for the user, details of what happened are written to error log file.

Customizing the view for your users in these cases is straightforward and very easy, you simply have to modify these files:

views/layouts/error.tpl - this is the common layout for your error pages, it could be similar to views/layouts/default.tpl - i.e. your default template layout - here a meta code snippet example

< html>
< head>
	< meta name="..." content="..."> 

	< title>There was an error...

	{$html->css('....')}
	{$javascript->link('.....')}
< /head>
< body>
  {$view->element('header')}

  {$content_for_layout}

  {$view->element('footer')}
< /body>
< /html>

You don't have to write this template: if you don't write it, the default one is used, which contains just
{$content_for_layout}

views/errors/error404.tpl - here you can specify what to display in {$content_for_layout} in case of a page not found/404 error, it could be a complete HTML page if you didn't create your common error layout, or something like this code snippet

This page is missing

The page you requested is not available. You may have followed a corrupt external link or mis-typed a URL.

Please.....

views/errors/error500.tpl - this is the equivalent page for "internal server error"/500 error page, where you can specify your {$content_for_layout} in this case - it works exactly like the error404.tpl page

Routing rules in frontend applications

Fri, 25 Nov 2011 10:09:10 +0100

This article explains how to build routing rules for redirecting web requests

In frontend applications you will normally have just this rule in your config/routes.php file [standard CakePHP file for routing rules]:

Router::connect(
   '/*', 
   array( 
      'controller' => 'pages', 
      'action' => 'route'
   )
);

That means: every URL (/*) should be passed to PagesController::route() (inherited from FrontendController class) . This route() method will decide which actions to take.

Most of the URLs handled will be in the form /my-section-name/my-content-name - that will cause loading of section with unique name my-section-name and content with unique name my-content-name located in my-section-name section.

But the general routing rules, in route() method, are as follows:

if there aren't url arguments (i.e. "/") then will be used the reserved word "homePage" for calling the method with the same name.
Url: www.example.com
Method used: FrontendController::homePage()
Action performed: load first Section of the relative Publication or the Publication if no section is found (see Publication module on BEdita backend).
You can ovverride this method in your controller to fit your home page at your needs;
if first url argument is a reserved word (defined in configuration variables "defaultReservedWords" and "cfgReservedWords") it means that no object will have this unique name. So it will try to call a method with this same reserved name. Some reserved words have an own method in FrontendController that you may override in your controller.
Url: www.example.com/reservedWord
Method used: PagesController::reservedWord()
if first url argument is a public method of your controller then it will be called
Url: www.example.com/myMethod
Method used: PagesController::myMethod()
if first url argument is a valid unique name and there is a public method of your controller with a corresponding name (as defined in bedita-app/lib/BeLib::variableFromNickname()), it will be called.
Url: www.example.com/my-beautiful-nickname
Method used: PagesController::myBeautifulNickname()
if first url argument is a valid unique name, it calls the corresponding FrontendController::section() or FrontendController::content() method. Here an example:
Url: www.example.com/my-section/my-content
Method used: section my-section will be loaded in FrontendController::section() method, that will load my-content object through FrontendController::content() method
if none of the above points are matched then an exception is thrown causing a 404 http error

Before and after every method called from FrontendController::route() (except), two callbacks methods are triggered if they exist: methods with same name and suffix -BeforeFilter / -BeforeRender . For example when the homePage() method is used, the flow will be:

PagesController::homePageBeforeFilter() (if it exists)
PagesController::homePage()
PagesController::homePageBeforeRender() (if it exists)

Showing a list of tags

Thu, 19 Jan 2012 11:15:07 +0100

Get a tag cloud or tag list in your frontend application

Let's see how you can show a list or cloud of tags in BEdita frontends.

If you want to show them in every page of your frontend you should use the beditaBeforeRender() callback in your PagesController:

protected function beditaBeforeRender() {
   $this->loadTags();
}

in this way an array named $listTags will be set for the view. That array will contain all tags ordered by label related to, at least, a content in your publication. You can customize your tags list/cloud with some parameters.

loadTags( $tplVar=null, $cloud=true, $shuffle=false, $tagShowed=null )

where:

$tplVar is the name of view variable
$cloud says if has to be set a css class for cloud view. Possible css class values are smallestTag, largestTag, largeTag, mediumTag, smallTag
$shuffle says if the tags have to be shuffled or shown in order by label
$tagShowed is the number of tags that will be in the result array

So if you want to load 30 tags shuffled in cloud mode you will call

$this->loadTags(null, true, true, 30);

Tags view

In the view you will have $listTagsarray as:

Array (
    [0] => Array (
       ['id'] => 1
       ['area_id'] => 
       ['label'] => 'my tag'
       ['name'] => 'my-tag'
       ['object_type_id'] => 
       ['priority'] => 
       ['parent_id'] => 
       ['parent_path'] => 
       ['status'] => 'on'
       ['url_label'] => 'my-tag'
       ['weight'] => 100
       ['class'] => 'largeTag'
    ),
   [1] => Array(...)
   ...
);

where you can see that tag named "my tag" is related to 100 items (weight) and the css class largeTag should be applied to "my tag" to generate the cloud. The name and url_label fields are equal for backward compatibility but we suggest to use only name field because url_label will be deprecated in the future.

A new element to use in views named tag_cloud will be added soon, but for now you can create one by your own. It's straightforward: add the file app/views/elements/tag_cloud.tpl and, for example, add the code:

{if !empty($listTags)}
    < h2 >{t}Tag cloud{/t}< /h2 >
    {foreach from=$listTags item=tag}
        < a class="tagCloud {$tag.class|default:" title="{$tag.weight}" 
             href="{$html->url('/tag/')}{$tag.name}" >{$tag.label}< /a >
    {/foreach}
{/if}

add to your CSS something as:

.smallestTag {
    font-size:1em;
}
.smallTag {
    font-size:1.2em;
}
.mediumTag {
    font-size:1.4em;
}
.largeTag {
    font-size:1.8em;
}
.largestTag {
    font-size:2.2em;
}

and you will have your tag cloud ready to use. Now you can call the element wherever you want using:

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

in your views.

Managing Users History

Wed, 18 Jan 2012 13:05:02 +0100

Manage easly users history in frontend applications (and in backend too)

Manage users navigation history is a common scenario developing frontend applications and BEdita comes with an integrated system to handle it.

To activate history tracking just edit config/frontend.ini.php in your frontend application and uncomment:

$config["history"] = array(
   "sessionEntry" => 5,
   "showDuplicates" => false,
   "trackNotLogged" => false
);

where:

sessionEntry is the number of history items you want to have in session
showDuplicates says if duplicate history items have to show in session
trackNotLogged says if history of unsigned users has to be active

Automatically BEdita will trace users activity in history table and fill History array in session.

In $BEAuthUser variable (views variable for user session info) you will have for example:

['History'] => Array(
   [0] => Array(
      ['area_id'] => 1
      ['object_id'] => 3
      ['title'] => //This is the title of content
      ['url'] => //url-to-that-content
      ['user_id'] => 1
      ['id'] => 1
   ),
   [1] => Array(...)
   ...
);

Ajax and Flash calls are not inserted in history and you can always control what you want to end up in history through out the AppController::historyItem property. Setting it to null you avoids to register history in some cases.

For example if you don't want access to a content with unique name "mycontent" to be tracked, then you can add to PagesController:

protected function mycontentBeforeFilter() {
   $this->historyItem = null;
}

If you need you can also manage users history in BEdita backend: just uncomment from bedita-app/config/bedita.cfg.php $config["history"] array.

Frontend Application Flow and callback methods

Tue, 03 Jan 2012 14:51:16 +0100

To help the frontend developers BEdita comes with a series of callback methods that allowing to filter and handling data. Understanding how the flow of frontend applications works and which callbacks the developer has in hand is one of the fundamental things to start developing a custom frontend

To fit variegated needs that you can encounter developing a frontend application, BEdita comes with a series of callback methods that allows to find and handle data. Before having a look at this callbacks let's go to see what happens in a standard frontend flow.

Frontend Application Flow

Supposing we have a BEdita publication reachable from http://www.example.com and we want to see the contents of a section with nickname section-one, in browser address bar we'll write

http://www.example.com/section-one

Everything is handled by route method that decide what to do. So if you have a custom method in Pages Controller you can call it in standard CakePHP mode

http://www.example.com/myCustomMethod

route method gets first parameters passed by URL (in our case section-1), check if it's a reserved word as defined in configuration files and eventually try to call method with that name.

If none reserved word or controller public method is found then BEdita consider the parameter a nickname, check if it corresponds to a section object or not and call respectively section method or content method. These two methods will load all section and contents data and set to view the array $section.

Finally the view is rendered.

Note: for the complete list of route rules followed in frontend apps it's raccomended to read Routing rules in frontend applications article.

Callback Methods

There are four main callbacks always called that can be used to insert logic before or after controller actions:

beforeCheckLogin called by FrontendController::initAttributes method is executed before check login operation is performed. It's useful if you want to skip the user check login operation for specific items setting to true the AppController::$skipCheck attribute. Note that the checkLogin method is called before beditaBeforeFilter.
beditaBeforeFilter called by AppController::beforeFilter method is executed before every action in the controller;
beditaBeforeRender called by AppController::beforeRender method is executed after controller action but before view is rendered.
beditaAfterFilter called by AppController::afterFilter method is executed after the render is done. It's the last thing made by controller.

In addition some specific callbacks are called if respective method exists. If exists a callback [methodToCallBeforeFilter is called before the main method (for example sectionBeforeFilter is called before section method) and another callback [methodToCall]BeforeRender is called soon after the main method.

Similar callbacks are handled in section and contents methods using the section/content unique name as defined in bedita-app/lib/BeLib::variableFromNickname(), i.e. [sectionNickname]BeforeFilter and [contentNickname]BeforeFilter and [sectionNickname]BeforeRender and [contentNickname]BeforeRender. In our example the callbacks will be sectionOneBeforeFilter() and sectionOneBeforeRender().

So you can define these callback methods in Pages Controller to customize punctually the way to find results and manipulate the $section array before render view.

In particular the [sectionNickname]BeforeFilter callback can be used to set parameters and class attributes to put the section method in the condition to find the expected result. For example changing the FrontendController::$sectionOptions attribute like you can see in the blog posts "Customizing Frontend Applications" part 1, 2 and 3 you can paginate sections' contents, group BEdita objects for type, etc... .

Instead the [sectionNickname]BeforeRender callback usually can be used to manipulate the $section array that is set in section method (you can find it in $this->viewVars["section"]).

Recap

The frontend flow of a section/content request can be summarized in this way:

browser request
call beforeCheckLogin method
call beditaBeforeFilter method
if exists call sectionBeforeFilter or contentBeforeFilter through route method
routing section/content method through route method
if exists call [sectionNickname]BeforeFilter method
if exists and content is requested call [contentNickname]BeforeFilter method
recover section and content data by nickname
if exists call [sectionNickname]BeforeRender method
if exists and content is requested call [contentNickname]BeforeRender method
if exists call sectionBeforeRender or contentBeforeRender through route method
call beditaBeforeRender method
render view
call beditaAfterFilter method

Get more or less information from your content

Thu, 20 Oct 2011 17:55:51 +0200

How to handle BEdita objects model bindings in frontend applications

In frontend application you can control how many informations you want from your content. This means to read more or less fields from database throughout CakePHP associations and Containable Behavior. To see the associations of BEdita object models you should have a look at models definitions.

In every BEdita object model you can also see a class property named $modelBindings that is an array of different level of bindings. In frontend applications the default modelBindings should be defined from "frontend" key of array, for example in Document model you have:

$modelBindings = array(
   "detailed" => array(...),
   "default" => array(...),
   "minimum" => array(...),
   "frontend" => array(
      "BEObject" => array(
         "LangText",
         "UserCreated",
         "RelatedObject",
         "Category",
         "Annotation"
      ),
      "GeoTag"
   )
);

Document::modelBindings["frontend"] is the default bindings used when a document is loaded. Of course you can override this default in many way. Every time that a BEdita object is loaded through FrontendController::loadObj() method (that is the standard way to load every BEdita object in frontend applications) BEdita chooses what model bindings to use follow the below order:

FrontendController::modelBindings["BEditaObjectName"]
You can set $modelBindings property in your controller to define in general or in a specific point what associations have to be used. If you use it in a specific method remember to reset the property to avoid using those model bindings everywhere.
$config["modelBindings"] in app/config/frontend.ini.php
This is useful if you want that your default model bindings for a frontend are different from those defined in the respective model.
BEditaObjectModel::modelBindings["frontend"] the default as explained above
Example: Document::modelBindings["frontend"]
BEditaObjectModel::modelBindings["minimum"], this is the fallback if default above is not defined
if it also miss "minimum" model bindings then an exception is thrown. In this case your model is buggy. Fix it.

How to subscribe users to frontend apps

Wed, 23 Feb 2011 10:25:05 +0100

This article explains what you have to do to register users through a frontend application

Register users in a frontend application is a common scenario. The subscribing action is handled out of the box by BEdita 3.1 through two methods of FrontendController. The first one is FrontendController::subscribe() action that takes care of showing the proper signup form in the view.

Assuming your frontend app is www.example.com then point your browser to www.example.com/subscribe/user.

If you are developing your frontend starting from bedita/frontends/dummy.example.com (if not you should) you will have views/pages/subscribe.tpl that uses views/elements/signup.tpl, view templates that you can easily modify if necessary.

In the browser you should see a subscribtion form with some data to fill. Form submission will start the subscribe process calling FrontendController::hashjob() method.
A user and an associated card object (that you can see/handle in Addressbook module) will be created and an email will be sent to the user to confirm the subscription through a link with unique hash. The user will be in "invalid" mode (login blocked) until the subscription will be confirmed. If you don't want to create the card object remove the input:

Instead if you want more card details add others input according to cards table, for example:

The fields street_address and company_name of cards table will be populated by the input form data.

By default a subscribed user will be associated also to the groups defined in "authorizedGroups" array in frontendapp/config/frontend.ini.php file. If the array is empty the user will be associated to all non-backend groups, that you can manage in Administration module .

Alternatively you can use the hashjobBeforeFilter() callback, writing in PagesController something like:

function hashjobBeforeFilter() {
   if (!empty($this->passedArgs[0]) && $this->passedArgs[0] == "user_sign_up") {
      $this->data["groups"] = array("group_1", "group_2");
   }
}

Once user is activated he can log in frontend app pointing to www.example.com/login

Template development - beFront helper

Wed, 09 Mar 2011 09:17:03 +0100

This article explains how to use BeFrontHelper in frontend template development

When you work on templates using CakePhp, you use (or should use) cake helpers (for instance: FormHelper, HtmlHelper, JavascriptHelper, etc.). If you don't know what an Helper is, take a look at cakephp documentation page about helpers, before continuing to read this article.

In BEdita you can use CakePhp helpers and BEdita helpers as well, powered by the Smarty Template Engine syntax (more details about Smarty syntax can be found in Smarty Documentation). BEdita helper names start with "Be": BeEmbedFlashHelper, BeEmbedMediaHelper, BeFrontHelper, BeThumbHelper, BeTimeHelper, BeToolbarHelper, BeTreeHelper, BeurlHelper (check them in BEdita API documentation).

No matter the type of the Web application or site or whatever you are building, in frontend templates development you have to face several common tasks: the default template page usually contains a title, a description, a block of keywords, some metadata, a menu, some statistics, feeds, a breadcrumb block, and so on.
BeFrontHelper's aim is to help template developer with most common tasks, dealing with "templates topics" more than "controller/business logic". Developing BeFrontHelper, BEdita staff studied deeply SEO issues and metadata management: business logic reflects some decisions taken by BEdita developers discussing SEO documentation.

Let's see an example from dummy example site in bedita "ulmus" release: bedita-3.1-ulmus/frontends/dummy.example.com/views/layouts/default.tpl.

{$html->docType('xhtml-trans')}
< html xmlns="http://www.w3.org/1999/xhtml" lang="{$currLang}" dir="ltr" >
   < head >
      {$html->charset()}
      < title >
         {$beFront->title()}
      < / title >
      {$beFront->metaAll()}
      {$beFront->metaDc()}
      < link rel="icon" href="{$html->webroot}favicon.png" type="image/png" / >
      {$beFront->feeds()}
      {$scripts_for_layout}
   < / head >
   < body >
      {$view->element('header')}
      {$content_for_layout}
      {$view->element('footer')}
      {$beFront->stats()}
   < / body >
< / html >

In this example, BeFrontHelper is used in 5 calls, respectively the methods are "title", "metaAll", "metaDc", "feeds" and "stats". Lets see what these methods (and some others) do.

{$beFront->title()}

BeFrontHelper function title return a default title for a page, according to page content and/or section/publication.

The title is like: "publication title/publication name" - "section title/current content title".
A good SEO point: distinguish titles inside a Web application or Website, according to real context content of a page.
This method works in that direction.

{$beFront->metaAll()}

{$beFront->metaAll()} generates html tags for content metadata: "description", "author", "http-equiv" and "generator".
"Description" is the first not empty value among the following:

currentContent["description"]
currentContent["abstract"] truncated to 255 characters
currentContent["body"] truncated to 255 characters
section["description"]
publication["description"]

Note: meta "description" can be obtained separately calling the method:

{$beFront->metaDescription()}

"Author" meta tag can be omitted, in case "license" field is not found in the following objects:

currentContent
section
publication

{$beFront->metaDc()}

It returns html-DC tags DC.title, DC.description, DC.format, DC.language, DC.creator, DC.publisher, DC.date, DC.modified, DC.identifier, DC.rights, DC.license. For more details about Dublin Core Html Tags, look at Expressing Dublin Core in HTML/XHTML meta and link elements.

{$beFront->feeds()}

When there are feeds, this method display feeds links; for instance:

< link rel="alternate" type="application/rss+xml" title="Blog" href="/rss/blog" / >
< link rel="alternate" type="application/rss+xml" title="News" href="/rss/news" / >

{$beFront->stats()}

It returns publication stats code, if set (only if frontend app is not staging site).

{$beFront->menu()}

Tree structure returned in html unordered list, with links to the contents.

{$beFront->breadcrumb()}

It returns the breadcrumb trail for the page.

--
Let's say something about smarty variables used in the examples of this article.

The variables {$currentContent}, {$section}, {$publication} refer to BEdita objects set by FrontendController.

{$currentContent} is the main object of the page (can be referred directly through url like http://www.bedita.com/blog/template-development-befront-helper). {$currentContent["description"]}, {$currentContent["abstract"]} and {$currentContent["body"]} refer to the content of Document->description, Document->short text and Document->long text of the Document view in Bedita backend application (for example http://mybeditaapp/documents/view/).

{$section} and {$publication} are respectively Section and Publication objects for the url, if any. For example this document is inside Section "blog" of Publication "BEditafrontsite", and the {$currentContent} in this page is the Document that you are reading.

Migrating frontends from BEdita 3.1 to 3.2

Thu, 17 Feb 2011 12:19:46 +0100

A brief guide to upgrade your frontends from 3.1

BEdita 3.2 comes with CakePHP 1.3.x series that introduces some changes. You can see a full guide to migrate CakePHP 1.2.x to 1.3.x in CakePHP cook book, here instead we'll discuss what you have to change in your frontend apps to work properly.

First of all replace in your frontend apps config/core.php and webroot/index.php. You can use the corresponding files bundles in BEdita 3.2, for example copy frontends/dummy.example.com/config/core.php and frontends/dummy.example.com/webroot/index.php to the corresponding paths of your frontend apps.

Router

A small change has also been done to routing params. Routed params should now only consist of alphanumeric chars, - and _ or /[A-Z0-9-_+]+/. This involve frontend-app/config/route.php because the old rule:

Router::connect(
   '/(?!pages)(.*)', 
   array(
      'controller' => 'pages', 
      "action" => "route"
   )
);

will not work anymore. Replace it with:

Router::connect(
   '/*', 
   array(
      'controller' => 'pages', 
      'action' => 'route'
   )
);

It has to be the last router rule and it delegates routing to FrontendController::route() method.

Config

The bootstrap chain is changed, now all necessary configurations file are included from bedita.ini.php, so edit frontend-app/config/frontend.ini.php replacing:

require_once(BEDITA_CORE_PATH . DS . "config" . DS . "bedita.ini.php") ;

if (file_exists (BEDITA_CORE_PATH . DS . "config" . DS . "bedita.cfg.php") ) {
   include(BEDITA_CORE_PATH . DS . "config" . DS . "bedita.cfg.php") ;
}

if (file_exists (APP. "config" . DS . "mapping.cfg.php") ) {
   include(APP. "config" . DS . "mapping.cfg.php") ;    
}

with:

require BEDITA_CORE_PATH . DS . "config" . DS . "bedita.ini.php";
include(APP. "config" . DS . "mapping.cfg.php");

The modelBinding structure has changed: GeoTag is part of BEObject. In frontend-app/config/frontend.ini.php use GeoTag 'inside' BEObject, like in the following example:

$config['modelBindings'] = array(
   'Document'=>array(
      'BEObject'=>array(
         "LangText",
         "RelatedObject",
         "GeoTag"
      )
   ),
//...
);

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])}
```
flash() no longer auto echos. If you used Smarty as a template engine you should replace:
```
{if $session->flash('error')}{/if}
```
with:
```
{$session->flash('error')}
```
and similar.
Moreover in SessionComponent::setFlash() second param is used for setting an element instead of layout, so in your applications you will need to:
1. Move message.tpl from views/layouts into views/elements
2. In message.tpl rename $content_for_layout variable to $message
JavascriptHelper is deprecated, you should replace:
```
$javascript->link() 
```
with:
```
$html->script()
```
The array of smarty assign_concat function now must begin from 1
MediaProviderHelper::$themeWeb no longer exist

BEdita modules (CakePHP plugins)

Support for vendors/css, vendors/js, and vendors/img in plugin (bedita module) has been removed. They have been replaced with plugin (bedita module) webroot directories.
If you are using some additional modules you should update them.
If you created a personalized module you have to move your_module/vendors/css, your_module/vendors/js, your_module/vendors/img folders in your_module/webroot relative folders.

Frontend callbacks

If you used the nickname's callback feature in your PagesController you have to change the name because now the nickname is camelized to make the callbacks consistent with other methods names. In practice:

3.1 (old)

With this-is-my-content it called this_is_my_contentBeforeFilter(), ....

3.2 (new)

With this-is-my-content it calls thisIsMyContentBeforeFilter(), ...

Frontend Application Flow and callback methods

Mon, 22 Feb 2010 17:38:12 +0100

To help the frontend developers BEdita comes with a series of callback methods that allows to filter and handle data. Understanding how the flow of frontend applications works and which callbacks the developer has in hand is one of the fundamental things to start developing a custom frontend

To fit variegated needs that you can encounter developing a frontend application, BEdita comes with a series of callback methods that allow to find and handle data. Before having a look at this callbacks let's go to see what happens in a standard frontend flow.

note: the italic grey text parts referred to BEdita 3.1 version. In BEdita 3.0.x series is missing.

Frontend Application Flow

Supposing we have a BEdita publication reachable from http://www.example.com and we want to see the contents of a section with nickname section-1, in browser address bar we'll write

http://www.example.com/section-1

Everything that doesn't start with pages is handled by route method that decide what to do. So if you have a custom method in Pages Controller you can call it in standard CakePHP mode

http://www.example.com/pages/myCustomMethod

route method gets first parameters passed by URL (in our case section-1), check if it's a reserved word as defined in configuration files and eventually try to call method with that name. So you could put in your bedita-app/config/bedita.cfg.php the reserved word myCustomMethod

$config["cfgReservedWords"] = array("myCustomMethod");

and call directly http://www.example.com/myCustomMethod

If none reserved word is found then BEdita consider the parameter a nickname, check if it corresponds to a section object or not and call respectively section method or content method. These two methods will load all section and contents data and set to view the array $section.

Finally the view is rendered.

Callback Methods

There are two (four in 3.1 release) main callbacks always called that can be used to insert logic before or after controller actions:

beforeCheckLogin (present from 3.1 release) called by FrontendController::initAttributes method is executed before check login operation is performed. It's useful if you want to skip the user check login operation for specific items setting to true the AppController::$skipCheck attribute. Note that the checkLogin method is called before beditaBeforeFilter.
beditaBeforeFilter called by AppController::beforeFilter method is executed before every action in the controller;
beditaBeforeRender called by AppController::beforeRender method is executed after controller action but before view is rendered.
beditaAfterFilter (present from 3.1 release) called by AppController::afterFilter method is executed after the render is done. It's the last thing made by controller.

In addition some specific callbacks are called if respective method exists. When a reserved word is found a callback [reservedWord]BeforeFilter (my_custom_methodBeforeFilter) is called before reservedWord method and another callback [reservedWord]BeforeRender (my_custom_methodBeforeRender) is called soon after reservedWord method.

Similar callbacks are handled in section method using the section (and content from 3.1 release) nickname replacing "-" with "_" in method name, i.e. [section-nickname]BeforeFilter (and [content-nickname]BeforeFilter from 3.1 release) and [section-nickname]BeforeRender (and [content-nickname]BeforeRender from 3.1 release). In our example the callbacks will be section_1BeforeFilter() and section_1BeforeRender().

So you can define these callback methods in Pages Controller to customize punctually the way to find results and manipulate the $section array before render view.

In particular the [section-nickname]BeforeFilter callback can be used to set parameters and class attributes to put the section method in the condition to find the expected result. For example changing the FrontendController::$sectionOptions attribute like you can see in the blog posts "Customizing Frontend Applications" part 1, 2 and 3 you can page sections' contents, group BEdita objects for type, etc... .

Instead the [section-nickname]BeforeRender callback usually can be used to manipulate the $section array that is setted in section method (you can find it in $this->viewVars["section"]).

Recap

The frontend flow of a section/content request can be summarized in this way:

browser request
call beforeCheckLogin method (from 3.1 BEdita version)
call beditaBeforeFilter method
routing section/content method through route method
if exists call [section-nickname]BeforeFilter method
if exists and content is requested call [content-nickname]BeforeFilter method (from 3.1 BEdita version)
recover section and content data by nickname
if exists call [section-nickname]BeforeRender method
if exists and content is requested call [content-nickname]BeforeRender method (from 3.1 BEdita version)
call beditaBeforeRender method
render view
call beditaAfterFilter method (from 3.1 BEdita version)

Customizing Frontend Applications [part 3]: time for pagination

Mon, 22 Feb 2010 10:41:22 +0100

Paginating items in a frontend application

The third episode of our "Customizing Frontend Applications" saga will be focused on pagination. Sooner or later each web developer/designer working on a web site will have to deal with contents pagination.
BEdita comes with an easy way to do it, allowing a default pagination setting for the entire frontend application and/or a specific one for each section you want.

Once again we'll use the FrontendController::$sectionOptions attribute, in particular we are interested in childrenParams key.

Overriding this class attribute in our PagesController we can set a default pagination for all our sections:

protected $sectionOptions = array(
   "showAllContents" => true,
   "itemsByType" => false,
   "childrenParams" => array(
      "order" => "title",
      "dim" => 10,
      "dir" => true
   )
);

In this way we are saying to show 10 items for page sorted by title^[1] in ascendant mode. Set dir to false to reverse the order of items. The couple "page" => 1 is implied but if you want to show your items starting from page 2 you can add it to childrenParams.

Change page, sort or page dimension is very very simple. We can use the named params convention used by CakePHP, so

http://www.example.com/section-1/page:2

will switch automagically to page 2 and similary we can change the order

http://www.example.com/section-1/order:created

the order direction

http://www.example.com/section-1/dir:0

or several things at once

http://www.example.com/section-1/page:2/dir:0

The only thing you can do it at this point is build your toolbar pagination and to do this you have a toolbar array available inside $section array, for example:

['toolbar'] => Array (
   ['first'] => 1
   ['prev'] => 1
   ['next'] => 3
   ['last'] => 5
   ['size'] => 9
   ['pages'] => 5
   ['page'] => 2
   ['dim'] => 2
   ['start'] => 3
   ['end'] => 4
)

where:

first is equal to 0 if we are in the first page
prev is the previous page
next is the next page
last is the last page and is equal to 0 when we are in the last page
size is the total number of items
pages is the total number of pages available
page is the current page number
dim is the dimension of items for page
start is the numeric position of first current page's item
end is the numeric position of last current page's item

So you could build your own helper to show the pagination toolbar or you can use the BeToolbar helper of BEdita core.

Change the default pagination for a section

As usual (if you read the previous articles 1-2) you can change the default $sectionOptions["childrenParams"] attribute for a specific section thorugh out the section-nicknameBeforeFilter callback.

That's it.

^[1] Note that "title" is a field of "objects" table used by BEObject model, so if you want to be sure to avoid ambiguous fields you should specify the model field you want to order by i.e. "order" => "BEObject.title". We'll see in other post how to filter the selection of items using "filter" key in "childrenParams". This filter can be build using fields of other tables that can collide with BEObject fields.

Customizing Frontend Applications [part 2]: how to load only selected content in a section

Fri, 27 Nov 2009 13:16:47 +0100

Improve speed performance by narrowing your requests to the API

While programming, you can request the content of a certain section by URL, with something like http://www.example.com/section-nickname/content-nickname. The requested content is loaded into the $section["currentContent"] array, while more content – actually every content in the same section – is placed into the $section["childContents"] array. This additional content is loaded in "base level mode" (cfr. the API manual, "baseLevel"), which means that only basic informations about various objects are given (such as the title, the description, its ID and a few more).

Now this is indeed useful in standard scenarios: when you are showing a particular content and listing, at the same time, related contents in the same section. Imagine you are showing an article and you want to put links to more contents in a contextual menu. This is common, but sometimes you are interested only in a single object, while you don't really need to load all related stuff.

In these cases you can improve the data loading performance by excluding this additional content (you actually give up the option of having also $section["childContents"] array). Obviously the improvement will be much more evident when that particular section is burdened, it has got many objects inside.

However, moving forward into the discussion started in the previous article "Customizing Frontend Applications [part 1]: divide objects by type in a section", we're going to use the Frontend Controller attribute $sectionOptions. This time too, we may proceed in two different ways, the choice depending on whether we want a custom behavior for a specific section (1) or alternatively we prefer to modify the default behavior for the whole frontend application (2).

So I'm showing you both:

1. Custom behavior for a section

Like we did in the previous post, we are going to use the nicknameBeforeFilter callback: It is automatically called before section data are loaded, so in the controller:

protected function section-nicknameBeforeFilter() {
   $this->sectionOptions["showAllContents"] = false;
}

(pay attention to change "section-nickname" with the exact nickname of your section).

2. Change the default behavior

To change the way the API answers to requests, edit your Pages Controller. You have to change the $sectionOptions attribute, by setting the showAllContents property to false:

protected $sectionOptions = array(
   "showAllContents" => false, 
   "itemsByType" => false, 
   "childrenParams" => array()
);

When showAllContents is set to false, we say to the API not to load all related content when a specific content is requested.

Customizing Frontend Applications [part 1]: divide objects by type in a section

Mon, 16 Nov 2009 12:08:24 +0100

Organize your BEdita objects in $section array to have a semantic separation of contents.

With this post we start a series of documents that explain how customize your frontend application for all your needs.

In any Frontend Application the standard organization of contents in a section reflects the backend visualization. So, supposing to have a section named "section 1" structured like in figure 1, we'll have in frontend view the array $section with different content types mixed together:

Array(
   ['id'] => section 1
   ['nickname'] => section-1
   ...
   ['childContents'] => Array(
      [0] => Array(...),
      [1] => Array(...)
      ...
   )
);

This is ok in many situation i.e. when I want to list contents in sequential order, but when I want contents to assume a specific behavior based on their semantic meaning this structure is limited.

In every object array I have a key named object_type that identify the type of the item (Document, Event, Gallery, etc...) so we can iterate the $childContents array and check that key to choose the right behavior. But this is not a good practice in some situations: for example if I want that in a 3 columns layout documents are shown in the first column, events in the second and galleries in the third column. Infact I should iterate the childContents array three times. Another example could be this one: we don't know which types of objects are in a section but we want everyone to behave differently.

In these cases the $sectionOptions attribute of the FrontendController class helps us.

The first solution: semantic separation for all sections

In this first case we want in our frontend application the objects inside every section divided by type. To do this we will override the $sectionOptions attribute in Pages Controller like this:

class PagesController extends FrontendController {
   protected $sectionOptions = array(
      "showAllContents" => true, 
      "itemsByType" => true, 
      "childrenParams" => array()
   );
   ...
}

setting itemsByType to true we force BEdita objects inside a section to be divided by object type. Instead of "chidContents" we'll have "children" array:

Array(
   ['id'] => 'section 1',
   ['nickname'] => 'section-1',
   ...
   ['children'] => Array(
      ['Document'] => Array(
         [0] => Array(...),
         [1] => Array(...)
      )
      ['Event'] => Array(...)
      ...
    )
);

The second solution: semantic division only for that section

In this case we'll use the nicknameBeforeFilter callback called automatically before section data are loaded (note that "-" char in nickname is replaced with "_" in method name):

protected function section_1BeforeFilter() {
   $this->sectionOptions["itemsByType"] = true;
}

The result will be an array like that above.

Frontend folder structure

Tue, 13 Oct 2009 17:19:46 +0200

A typical frontend application folder structure

Each frontend application is a CakePHP application. The bigger difference is that a BEdita frontend application comes with a powerful set of API to allow webdesigners/webdevelopers start to work without write any single row of business logic and focusing on views.

Of course you are free to customize your application editing PagesController or creating other controllers/components/models/plugins like a classic CakePHP application.

frontends folder

Inside this folder you can find four BEdita frontend applications and here is where you should create yours. BEdita package comes with these frontends:

debug.example.com site.example.com dummy.example.com wp.example.com

In every frontend application you'll have a configuration file named frontend.ini.php in config folder, a controller named pages_controller.php in controller folder and some templates in views folder.

debug.example.com

This is a tool to find out how data are structured, how you can use i18n, what helper/views/elements you have available for building a frontend application. Views and elements are available both as Smarty templates (.tpl) and CakePHP native templates (.ctp). In this way when you're starting a new project you may use your preferred template engine and having a starter kit of templates ready to use.

site.example.com

This is a simple example of a website.

dummy.example.com

Use it copying or renaming for create your own frontend application.

wp.example.com

This is a frontend application example inspired by the 2010 theme TwentyTen for WordPress.The main stylesheet is the TwentyTen (twentyten.css) and an adjustament.css is used for some correction. Have a look at README.txt located in the frontend root folder for some tips.

Embedding multimedia objects

Mon, 28 Sep 2009 17:49:14 +0200

An overview on the multimedia embedding feature, using the BeEmbedMedia Helper.

The BeEmbedMedia helper is used to create and display every type of multimedia object as Video, Audio, Image, Application (like Flash object) or generic multimedia file (BEFile). This helper is always included in backend AppController, as well as in every frontend application by inheritance, so inserting a video, a Flash swf file or an image is as easy as using a CakePHP helper. The helper uses Flowplayer as internal flash player for native visualization of video and audio objects but also allow the embedding of provider players when there's no direct link to flv file (i.e youtube see figure 1, 2).
Let's see how:

Essentially this helper provides a function called "object" that works generically for any Bedita object:

public function object ( $obj, $params = null, $htmlAttributes=array() )

The $obj parameter represent the BEdita object that has to be displayed in the frontend. Generically in your view code, you'll have a multidimensional array:

$section["currentContent"]["relations"]["attach"]

which contains a list of all related media objects, i.e. all the media objects which share a "relation" of type "attach" with "currentContent" inside the "section".

$params

$params represent an array of specific parameters related to the type of object to display. There's few parameters handled internally by BEdita. The main of those is "presentation" params which define how the multimedia objects have to be shown. This parameter has a default value for any multimedia object so while for an image object will be create a thumbnail, for video object will be loaded the flash player.

You can force presentation type passing the value in $params associative array. It can be "thumb" , "full" or "link".
For example, the code:

{assign_associative var="params" presentation="thumb" width=200 mode="crop"}
{foreach from=$section.currentContent.relations.attach item="media"}
   {$beEmbedMedia->object($media,$params)}
{/foreach}

Will try to show the contents of array "attach" with thumbnails, regardless of the specific object. For example in case of a video object, will display the associated thumbnail if present, while in case of an image stored on BEdita, will try to generate thumbnail runtime or reusing a thumbnail previously created.

The "presentation=full" type will display the full visualization of the object embedding directly the video or the audio or the images object.
The code:

{assign_associative var="params" presentation="full"}
{foreach from=$section.currentContent.relations.attach item="media"}
   {$beEmbedMedia->object($media,$params)}
{/foreach}

Will try to display the video and audio object type with the internal default player, if "useProviderPlayer" variable is present in $params the function will try to embed the object using directly the related provider player. The image object type will be shown in their real dimension using the original file uploaded.

Moreover, $params can contain object-specific parameters such as flashvar variables for customize Flowplayer or, more generically, any type of variable that is required to displaying multimedia objects.
For examples:

{assign_associative var="clips" autoPlay=true}
{assign_associative var="flashVars" clip=$clips}
{assign_associative var="params" flashvars=$flashVars}
{foreach from=$section.currentContent.relations.attach item="media"}
    {$beEmbedMedia->object($media,$params)}
{/foreach}

Enable the autoplay function, when display a video with flowplayer.

The "presentation=link" parameter will produce a well formatted anchor pointing to the resource itself, with the title of the object inserted inside anchor tag.
Finally the URLonly parameter will force the helper to return only the URL, that can be useful when you want use manually the "img" tag.

{assign_associative var="params" presentation=link URLonly=true}
{foreach from=$section.currentContent.relations.attach item="media"}
   < img src="{$beEmbedMedia->object($media,$params)}" alt="" />
{/foreach}

$htmlAttributes

The $htmlAttributes represents the html parameters of the embedding object. Here you can specify all the html attributes like rel, width, height, id, etc...

These was just an overview of the main features of the BeEmbedMedia helper, you can try by yourself all options and eventually ask help on the official forum. Some useful links are reported in the right column.

My first frontend

Mon, 30 Mar 2009 18:46:41 +0200

How to build a simple frontend in BEdita.

BEdita package contains a folder named frontends. This is where you will find some frontend samples, we'll start from here.

In this article we are going to use a debug frontend (frontends/debug.example.com) to better understand some basic conepts. As you may already know, there are two other frontends available: wp.example.com, a simple web site based on Twenty Ten Wordpress theme, dummy.example.com, a dummy/empty publication and html5.example.com a dummy HTML 5 frontend.

Suppose that frontends/debug.example.com is reachable at

http://www.example.com

Write it in the browser address bar and you could see a page with the language in use, current section, publication and configuration details, template data available and sections tree.
This root page is defined in config/routes.php that lead to FrontendController::route() method to load the first section of the publication related to frontend through $config['frontendAreaId'] variable you can find in config/frontend.ini.php file.
If it doesn't work check your webroot/index.php and config/bedita.sys.php, or use bedita shell script (cake.sh bedita checkApp) to check your settings.

By default Smarty is BEdita's default template engine but you can use CakePHP's View class simply setting in beditaBeforeFilter method of controllers/pages_controller.php

$this->view = 'View';

and using .ctp file extension instead of .tpl. In frontends/debug.example.com/view you will find the views/templates. You can play with this frontend and learn how frontends in BEdita work simply by using it.

Nickname and id

In the following paragraphs and examples we will make heavy use of nicknames. A nickname is a unique alphanumeric semantic name for every BEdita object of an instance: you will find it in the Advanced Properties block of every object detail in backend (sections, documents, news, images,....). Let's use that nickname or the object id from now on.

So, for a specific section you've created digit

http://www.example.com/section-nickname

using a real nickname instead of section-nickname. Now you are on this section page, and you will see how content/section details are changed.

The page you see refers to views/pages/generic_section.tpl view, but if you create a template named views/pages/section-nickname.tpl then this will be used.

In this way every section is highly customizable and you can be able to create a different template for each section of your site.

Here's a url list on how to reach the same section:

http://www.example.com/section-nickname http://www.example.com/section/section-nickname http://www.example.com/section-nickname/sub-section-nicknamehttp://www.example.com/section/section-nickname/sub-section-nickname

And so on... the same using numeric id's instead of nicknames.

$section array

Let's see the main features of $section array that you will have available in the view when you make a call like above. Have a look at "current section: $section" paragraph and click on show/hide.

You will see the array dump that contains section data like "title", "description", etc...

Array (
  ['id'] => 2
  ['syndicate'] => 'on'
  ['priority_order'] => 'asc'
  ['object_type_id'] => 3
  ['status'] => 'on'
  ['created'] => '2008-04-23 08:29:46'
  ['modified'] => '2008-04-23 08:29:46'
  ['title'] => 'section title'
  ['nickname'] => 'section-nickname'
  ['description'] =>
  ['current'] => 1
  ['lang'] => 'ita'
  ['ip_created'] => '127.0.0.1'
  ['user_created'] => 1
  ['user_modified'] => 1
  ['rights'] =>
  ['license'] =>
  ['creator'] =>
  ['publisher'] =>
  ['note'] =>
  ['fixed'] => 0
  ['comments'] => 'off'
  ...
);

besides these you'll find

languages

array containing all the available translations.

['languages'] => Array (
  ['eng'] => Array ( 
     ['title'] => //section title 
  ),
  ['deu'] => Array(...),
  ...
);

pathSection

array that contains the sections parents. It's build using sections id as array keys and ordered by depth: the first element will be the more distant ancient and the last element the parent.

canonicalPath

canonical section path in the form /main-section/sub-section/sub-subsection...

childSections

array containing sections children

childContents

array containing all objects, sections excluded

These last arrays could be divided by object type

currentContent

array containing the current content of a section. With

http://www.example.com/section-nickname/content-nickname

currentContent contains the object with nickname as content-nickname. With

http://www.example.com/section-nickname

currentContent contains the first child of section with nickname as section-nickname

toolbar

array of pagination data:

['toolbar'] => Array (
   ['first'] => 0,
   ['prev'] => 0,
   ['next'] => 0,
   ['last'] => 0,
   ['size'] => 2,
   ['pages'] => 1,
   ['page'] => 1,
   ['dim'] => 100000,
   ['start'] => 1,
   ['end'] => 2
);

Get a specific object

So far we have seen how to get section data, but how can I get another object? Nothing could be easier:

http://www.example.com/content-nickname

BEdita will understand if the object is a section or a content and if it's a content will search the first section that contains it and load the $section array like we saw above. Moreover in the currentContent array will be placed the searched object and will be setted to true the $section["contentRequested"] variable.
If an object is present in more than one section then you just specify the section in the URL

http://www.example.com/section-nickname/content-nickname

What's inside an object?

The array structure of all objects is similar to $section with regard to general data and object languages. It will have some specific data like GeoTag, Category, Tag, etc... and

relations

this array contains semantic relations between objects, some of these are already defined, but you could build your specific relations. The array structure is:

['relations'] => Array (
   ['attach'] => array( [0] => object1, [1] => object2, ...)
   ['seealso'] => array( [0] => object1,[1] => object2, ...)
   ...
   ['place'] => array( [0] => object1, [1] => object2, ...)
   ...
) ;

What else?

To finish this first frontend overview we see how to do REST calls to obtain the same $section array but in XML or JSON format.

XML

Write in address bar:

http://www.example.com/xml/section-nickname

or if you prefer having data in XML tags format

http://www.example.com/xml/section-nickname/format:tags

JSON

Likewise it's simple to obtain a JSON object, for example to use in an Ajax call.

http://www.example.com/json/nickname-section

BEdita Documents and Resources | Frontends

URL-friendly content translations

Routing

Linking to translated content

Using BeHtmlHelper

Generating meta-tags

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

Frontends: a brief overview

Embedding Images with beEmbedMedia

Imagemagick or GD library

Using BeEmbedMedia Helper

longside, width and height

mode and modeparam

type

upscale

Filtering section's objects

Default behavior

Other filter rules

Create your own rules

Understand how the View is chosen

1. Check frontendMap currentContent nickname

2. Check frontendMap section nickname

3. View with same name as currentContent nickname

4. View with same name as section nickname

5. View with same name as parent sections nickname

6. Object type template name

7. Default fallback

Localize your frontend

Change language on the fly

The view

Create custom error 404 and error 500 pages

This page is missing

Routing rules in frontend applications

Showing a list of tags

Tags view

Managing Users History

Frontend Application Flow and callback methods

Frontend Application Flow

Callback Methods

Recap

Get more or less information from your content

How to subscribe users to frontend apps

Template development - beFront helper

{$beFront->title()}

{$beFront->metaAll()}

{$beFront->metaDc()}

{$beFront->feeds()}

{$beFront->stats()}

{$beFront->menu()}

{$beFront->breadcrumb()}

Migrating frontends from BEdita 3.1 to 3.2

Router

Config

View and Helpers

BEdita modules (CakePHP plugins)

Frontend callbacks

3.1 (old)

3.2 (new)

Frontend Application Flow and callback methods

Frontend Application Flow

Callback Methods

Recap

Customizing Frontend Applications [part 3]: time for pagination

Change the default pagination for a section

Customizing Frontend Applications [part 2]: how to load only selected content in a section

1. Custom behavior for a section

2. Change the default behavior

Customizing Frontend Applications [part 1]: divide objects by type in a section

The first solution: semantic separation for all sections

The second solution: semantic division only for that section

Using `BeHtmlHelper`