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 options
         'fields' => array(
             'item_per_page' => array(
                 'label' => __('Item per page:'),
                 'form' => array(
                     'type' => 'text',
                     'value' => 10, // This is only the default
                 ),
             ),
         ),
     );

The fields syntax is identical to the CRUD configuration, with the ability to use renderers.

When you configure only the fields without specifying popup.layout, the controller will add a default layout for you automatically:

 <?php

 return array(
     // Automatically generated by the controller when it finds a 'fields' configuration
     'popup' => array(
         'layout' => array(
             'fields' => array(
                 'view' => 'nos::form/fields',
                 'params' => array(
                     'fields' => array(/* List of all the specified 'fields' */),
                     'begin' => ' ',
                     'end' => ' ',
                 ),
             ),
         ),
     ),
 );

If you want to change this default layout (for example, to add a 2nd view and include JavaScript), you must fill it entirely (including the nos::form/fields if you also need it).

Within the popup views, the following variables are accessibles :

  • $enhancer_args : Old enhancer configuration ;
  • $fieldset : if you specified fields, a Fieldset is instanciated in this variable.

Change preview

« Form » enhancer

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
     'fields' => array(
         // Already 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 getUrlEnhanced():

<?php

namespace Nos\Blog;

class Controller_Front extends \Nos\Controller_Front_Application
{
    public static function getUrlEnhanced($params = array())
    {
        $item = \Arr::get($params, 'item', false);
        if ($item) {
            $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.
Read the Docs v: latest
Versions
latest
dubrovka
chiba.2
chiba.1
0.2
0.1
Downloads
PDF
HTML
Epub
On Read the Docs
Project Home
Builds

Free document hosting provided by Read the Docs.