Add an enhancer¶
1. Configuration in metadata file¶
Metadata of an enhancer are described in the API documentation.
2. [Back-office] Create the enhancer’s controller¶
In order to manage the configuration popup as well as the enhancer’s preview, we need a controller.
Create the file my_app::classes/controller/admin/enhancer.ctrl.php extending Controller_Admin_Enhancer.
<?php
namespace My\App;
class Controller_Admin_Enhancer extends \Nos\Controller_Admin_Enhancer
{
}
As most Novius OS controllers, we can add a configuration file: my_app::config/controller/admin/enhancer.config.php
<?php
return array(
// Empty, for the moment
);
Configuration popup¶
Popup display depends on the dialog key in the metadata.config.php file.
<?php
return array(
'enhancers' => array(
'my_app' => array(
'dialog' => array(
'contentUrl' => 'admin/my_app/enhancer/popup',
'ajax' => true,
),
),
),
);
Here, the popup will call the function action_popup() of the Mon\Appli\Controller_Admin_Enhancer class using ajax.
As any change on a metadata.config.php file, you need to apply changes in the application manager.
From now on, when we add an enhancer into a WYSIWYG, a popup appears, but the configuration form is empty.
Standard controller we extended expects a configuration in order to add options into the popup. In the mon_appli::config/controller/admin/enhancer.config.php file:
<?php
return array(
// Popup configuration
'popup' => array(
'layout' => array(
'view' => 'my_app::enhancer/popup',
),
),
);
The file refers to the mon_appli::enhancer/popup view which doesn’t exist, we need therefore to create. It will contain form inputs managing configuration:
<h3>Options</h3>
<p>
<label for="item_per_page"><?= __('Item per page:') ?></label>
<input type="text" name="item_per_page" id="item_per_page" value="<?= \Arr::get($enhancer_args, 'item_per_page', 10) ?>" />
</p>
Old enhancer configuration can be accessed with the $enhancer_args variable (useful for pre-fill form with existing configuration).
Change preview¶
The preview added into the WYSIWYG is loaded by calling previewUrl key in the metadata.config.php configuration file.
Generally, the same controller than the popup is called, only the action is changed to action_preview().
View provided by default uses an icon, a title (default value is the 64x64 application icon, and the enhancer title), as well as a layout (additional view files called).
my_application::config/controller/admin/enhancer.config.php :
<?php
return array(
// Popup configuration
'popup' => array(
// Alreay dealt with in previous part
),
// Preview configuration
'preview' => array(
// (optional) view to be used in order to render (default value is written beneath):
//'view' => 'nos::admin/enhancer/preview',
// (optional) additional view files (included par la view au-dessus)
//'layout' => array(),
'params' => array(
// (optional) default value is enhancer title
'title' => "Mon super enhancer",
// 'icon' (optional) default value is application 64x64 icon
),
),
);
Value can be callback functions for title and icon. This callback will receive only one parameter: the enhancer configuration.
One example is the « Form » enhancer where the selected form title is also displayed.
3. [Front-office] Display content on the website¶
Once the page has been save and published, the enhancer will appear on the website.
The content will be generated by the controller defined on keys enhancer or urlEnhancer of the metadata.config.php file (whether we wanted a simple or URL enhancer). Don’t forget to apply changes in the application manager if you change metadata.config.php.
For instance, the value of the enhancer key for the « Form » application is noviusos_form/front/main, so it will call the action_main() method of Controller_Front of the noviusos_form application ( Nos\Form\Controller_Front class).
The first parameter of this action is the configuration table defined by user on the configuration popup.
Create a controller in my_app::controller/front.ctrl.php
<?php
namespace My\App;
class Controller_Front extends \Nos\Controller_Front_Application
{
public function action_main($enhancer_args = array())
{
// Testing
return print_r($enhancer_args, true);
}
}
4. URL enhancers¶
URL enhancer are capable of managing URLs.
Concretely, if your URL enhancer has been added to the my/page page, then it will be able to manage urls begining with my/page/**.html, as:
- my/page.html
- my/page/first_level.html
- or my/page/first_level/second_level.html
There is no limitation on the level you can manage.
As on previous part, content is generated by the main action, but it is possible to get the extended url with $this->main_controller->getEnhancerUrl();.
The controller can therefore switch content depending the called URL. Here is an (simplified) example taken from the « Blog » application :
<?php
namespace Nos\Blog;
class Controller_Front extends \Nos\Controller_Front_Application
{
public function action_main($enhancer_args = array())
{
// Complete url == 'my/blog/category/ski.html'
// => $enhancer_url == 'category/ski' (without .html)
$enhancer_url = $this->main_controller->getEnhancerUrl();
$segments = explode('/', $enhancer_url);
if (empty($enhancer_url))
{
// URL is 'mon/blog.html' (page URL)
// Display list of blog posts (first page)
}
else if (count($segments) == 1)
{
// URL is 'mon/blog/blog_title.html'
// Blog post 'blog_title' is displayed
}
else if (count($segments) == 2)
{
if ($segments[0] == 'page')
{
// URL is 'my/blog/page/number.html'
$page = $segments[1];
// Display page number of blog posts list
}
else if ($segments[0] == 'category')
{
// URL is 'my/blog/category/category_name.html'
$category = $segments[1];
// Display blog posts list of 'ski' category
}
}
// URL called isn't managed by the enhancer (404 error)
throw new \Nos\NotFoundException();
}
}
When an enhancer manage URLs for some models (ORM), it must know the mapping between models and URLs. This is allowed by the static method get_url_model():
<?php
namespace Nos\Blog;
class Controller_Front extends \Nos\Controller_Front_Application
{
public static function get_url_model($item, $params = array())
{
$model = get_class($item);
$page = isset($params['page']) ? $params['page'] : 1;
switch ($model)
{
// Blog post URL
case 'Nos\Blog\Model_Post' :
return urlencode($item->virtual_name()).'.html';
break;
// Category URL
case 'Nos\Blog\Model_Category' :
return 'category/'.urlencode($item->virtual_name()).($page > 1 ? '/'.$page : '').'.html';
break;
}
return false;
}
}
This function is related to the Behaviour_URLenhancer and url() and urls() model methods. In order to understand how to configure them, take a look at the API documentation.
Example :
<?php
// Selecting the category which ID value is 1
$category = Nos\Blog\Model_Category::find(1);
$url = $category->url(array('page' => 2));
$url value will be my/blog/category/ski/2.html:
- my/blog : Page URL;
- ski : Category virtual url ;
- 2 : Page number.