BEdita | Semantic Content Management Framework - Blog

i18n - translation gettext for plugins

Fri, 31 Aug 2012 15:29:45 +0200

In order to generate/merge .po/.pot files for a specific plugin, you can use BEdita gettext shell script.

The syntax for this command is like:

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

If something goes wrong - 4 steps

Mon, 19 Mar 2012 18:10:21 +0100

4 simple steps to follow if your BEdita applications are not working

Your application is not responding, you have a blank page, some elements are not displayed, page layout is broken, you get mysterious error messages.....but you don't know what's going wrong and how to fix it? Ok, don't panic :-)

Here a simple checklist in four steps to use in such situations:

debug level - core.php - it's a common practice to set a debug level during development/testing of your application, you do so by setting Configure::write('debug', 1); in bedita-app/config/core.php in backend or in frontends/[frontend-name]/config/core.php in your specific [frontend-name] frontend. It may help: additional information should be displayed in your browser and in log files. Remember to remove debug level by setting Configure::write('debug', 0) for a production system.
view BEdita log files - backend log files are in bedita-app/tmp/logs folder for backend and in frontends/[frontend-name]/tmp/logs for your [frontend-name] frontend. Look at error.log file first, then view debug.log
view web servers log files - if you're using Apache usually these files are located in a common log directory for your web server, but you can specify other custom log directories for both backend and frontend. In typical Unix setup you may find these files in /var/log/apache2/ (without custom log directories). Read error.log first, then look at access.log.
get online support - if the problem is still obscure, write to our google group to get support

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.

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.

Error logs: 'missingController' message

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

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

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

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

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

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

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

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

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

Typical messages are classic HTTP 404/500 error messages like

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

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

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

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

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

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.

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

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

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.

BEdita shell: introducing command line tools

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

A collection of useful command line tools to execute simple tasks from shell

Command line tools are an important (and not well 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

Define and customize relations between BEdita objects

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

BEdita objects

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

Where do I define relations between objects?

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

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

$config["objRelationType"]

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

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

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

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

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

Customizing a relation between some object types

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

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

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

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

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

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

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

One way relations

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

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

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

Relations in frontend

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

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

At the end

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

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.