BEdita | Semantic Content Management Framework - blog

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 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 variegate needs that you can encounter developing a frontend application, BEdita comes with a series of callback methods that allowing to find and handling 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 the next 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 corresponding 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 the next 3.1 release) main callbacks always called that can be used to insert logic before or after controller actions:

beforeCheckLogin (present from next 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 next 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 next 3.1 release) nickname replacing "-" with "_" in method name, i.e. [section-nickname]BeforeFilter (and [content-nickname]BeforeFilter from next 3.1 release) and [section-nickname]BeforeRender (and [content-nickname]BeforeRender from next 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 paginate 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 sumarized 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 sorting by title^[1] in ascendant mode. Set dir to false to reverse the order of items. The coupple "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 have 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 for now.

^[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 to not 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 that everyone behave differently.

In these cases the $sectionOptions attribute of the FrontendController class comes to help us.

The first solution: semantic separation for all sections

In this first case we want that in our frontend application the objects inside every section are 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.

Embedding multimedia objects

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

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 visualizzation 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)}    {/if} {/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.

BEdita shell: introducing command line tools

Wed, 22 Jul 2009 17:33:22 +0200

Command line tools are an important (and not known) part of the BEdita framework.
There are many commands available to accomplish many tasks:

export or import a complete instance
send notification mails or newsletter
create a new BEdita instance
check instance status
remove cache and compiled templates

How do I use them?

There is a simple shell/batch script (cake.sh for Linux/Max/Unix cake.bat for Windows) to launch those tasks.
Point to the root BEdita directory with the command line where you have bedita-app, bedita-db, cake, vendors directories.

Under Linux or MacOSX (or other UNIX-like systems) type:

./cake.sh bedita help

Under Windows

cake.bat bedita help

You will get some informations and usage hints regarding the main bedita script.
Now you can play with this script and discover what services it provides.

To name a few (without cake.sh/bat):

bedita cleanup - cache and compiled templates cleanup
bedita export/import - exports or imports a complete BEdita instance
bedita modules - adds/removes instance modules
bedita checkApp - checks application status, missing config files, db connections, checks main URLs, paths and permissions on filesystem

Besides the main script (bedita) there are other BEdita shell tools available:

dbadmin: some methods to check/fix some db data, some to insert test objects
gettext: parses views/php files, extracts i18n entries and updates .po files (gettext format)
mail: sends notification mail and newsletters
migrate: data migration scripts from previous BEdita versions
newsletter: some newsletter related tools (data import)

How to manage free semantic relations

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

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 of it 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(34), "right" => array(21) ) );

Here I define that the "speakers" relation is estabilished between some object types. On the left I have card objects (34 is the id of card in object_types table) and on the right I have event objects (id=21). 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(34), "right" => array(21,22) ) );

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 to desire that the relation is showed 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.

Hallo BEdita

Wed, 13 May 2009 16:33:28 +0200

The first public beta is here!

After two years of hard work we are really pleased to announce the first public beta release of BEdita 3 (pronounced [bi'εdita]): a framework for Web2.0 applications that aims to be a standard tool in the next Web3.0 and in the future Semantic Web.

As you may already know, the beta is here http://www.bedita.com/be-download

Framework or CMS?

BEdita shares many aspects with a CMS (Content Management Systems), often we call it that way for simplicity, in fact it follows its definition (at least in part): a tool that enables technical and non technical staff to create, edit, manage and finally publish a variety of content (such as text, graphics, video, documents etc). But on the publishing side it doens't have, on purpose, a default unique and finished/ready solution.

A good definition of software framework may help us understand things better: a framework is incomplete, though concrete, driving solution to recurring high-value problem. BEdita actually is:

incomplete– it's not a software that can solve needs/problems of a standard user; instead it's a powerful tool for [web]designers/[web]developers to build frontend applications;
driving solution to recurring high-value problem – it's useful in every situation where you may want to create applications (frontend) that handle complex multimedia contents and their semantic relations; for a designer/developer it prevents to challenge and solve typical annoying related issues.

Architecture

Two are the main elements of the semantic framework:

a backend Web application to manage contents and their semantic relations, with an innovative ergonomic user interface, providing an original chromatic association between object types, extensive use of drag'n'drop and other AJAX techniques;
a frontend API, services and specifications to build frontend applications; mainly Web apps, but also desktop/mobile apps taking advantage of its native REST/XML interface.

The backend application is unique and the same for every setup or instance, instead more frontend applications can be built using an API and inheriting from the core system Model classes and business logic layer: they can be made of few lines of PHP code, or they can be much more complex. This separation is a choice made for security reasons, efficiency, scalability and to let maximum freedom to the designer/developer.