Add an enhancer
###############



1. Configuration in :file:`metadata` file
=========================================

Metadata of an enhancer are described in the :ref:`API documentation <api:metadata/enhancers>`.


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 :file:`my_app::classes/controller/admin/enhancer.ctrl.php` extending ``Controller_Admin_Enhancer``.

.. code-block:: php

    <?php

    namespace My\App;

    class Controller_Admin_Enhancer extends \Nos\Controller_Admin_Enhancer
    {

    }

As most Novius OS controllers, we can add a configuration file:
:file:`my_app::config/controller/admin/enhancer.config.php`

.. code-block:: php

    <?php

    return array(
        // Empty, for the moment
    );

Configuration popup
-------------------

Popup display depends on the ``dialog`` key in the :file:`metadata.config.php` file.

.. code-block:: php

    <?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 :file:`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 :file:`mon_appli::config/controller/admin/enhancer.config.php` file:

.. code-block:: php
   :emphasize-lines: 4-13

        <?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:

.. code-block:: php
   :emphasize-lines: 4-16

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

.. _app_create/enhancer/preview:

Change preview
--------------

.. image:: images/metadata_enhancer.png
	:alt: « Form » enhancer
	:align: center

The preview added into the WYSIWYG is loaded by calling ``previewUrl`` key in the :file:`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).

:file:`my_application::config/controller/admin/enhancer.config.php` :

.. code-block:: php
   :emphasize-lines: 8-18

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

.. _app_create/enhancer/front:

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
:file:`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 :file:`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 :file:`my_app::controller/front.ctrl.php`

.. code-block:: 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);
        }
    }


.. _app_create/enhancer/url:

4. URL enhancers
================

URL enhancer are capable of managing URLs.

Concretely, if your URL enhancer has been added to the :file:`my/page` page, then it will be able to manage urls
begining with :file:`my/page/**.html`, as:

- :file:`my/page.html`
- :file:`my/page/first_level.html`
- or :file:`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 :

.. code-block:: php

    <?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();
        }
    }


.. _app_create/enhancers:

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()``:

.. code-block:: php
    :emphasize-lines: 7-29

    <?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 :ref:`API documentation <api:php/behaviours/urlenhancer>`.


Example :

.. code-block:: php

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