Netgen Content Browser Documentation¶

Netgen Content Browser is a Symfony bundle that provides an interface which selects items from any kind of backend and returns the IDs of selected items back to the calling code. Main use case is to provide a way to hook into a CMS backend and select items from the backend from apps built on top of that same CMS.

For example, Netgen Layouts uses Content Browser to select items which will be added to block collections.

Out of the box, Netgen Content Browser has the following plugins:

Selecting content and locations from eZ Platform CMS
Selecting tags from Netgen Tags Bundle for eZ Platform
Selecting products and taxons from Sylius eCommerce

Note

These plugins have their own separate packages, so if you wish to use Content Browser integrated into eZ Platform, install and activate netgen/content-browser-ezplatform package.

If you wish to use Content Browser integrated into Sylius, install and activate netgen/content-browser-sylius package.

Note

This documentation assumes you have a working knowledge of the Symfony Framework. If you’re not familiar with Symfony, please start with reading the Quick Tour from the Symfony documentation.

Reference¶

Installation instructions¶

Use Composer¶

Run the following command to install Netgen Content Browser:

$ composer require netgen/content-browser

Activate the bundle¶

Activate the Content Browser in your kernel class together will all other required bundles:

$bundles = [
    ...

    new Sensio\Bundle\FrameworkExtraBundle\SensioFrameworkExtraBundle(),
    new Netgen\Bundle\ContentBrowserBundle\NetgenContentBrowserBundle(),
    new Netgen\Bundle\ContentBrowserUIBundle\NetgenContentBrowserUIBundle(),

    new AppBundle\AppBundle(),
];

Activate the routes¶

Add the following to your main routing file to activate Content Browser routes:

netgen_content_browser:
    resource: "@NetgenContentBrowserBundle/Resources/config/routing.yaml"
    prefix: "%netgen_content_browser.route_prefix%"

Install assets¶

Run the following from your repo root to install Content Browser assets:

$ php bin/console assets:install --symlink --relative

Configuration reference¶

Configuration of Content Browser is done per item type.

To register the new item type in Content Browser, you need to add it to the list of item types in configuration:

netgen_content_browser:
    item_types:
        my_item_type:
            ...

The following lists all configuration options available in Netgen Content Browser for every item type:

Item type configuration¶

Configuration for each item type can be configured separately and can be accessed from Symfony DIC with the service name netgen_content_browser.config.<item_type> where <item_type> should be replaced with the actual identifier of your item type.

`name`¶

This is the human readable name of your item type. You can use a translation placeholder here, which will be translated with ngcb catalog.

type: string, required: Yes, example: item_types.my_item_type

`min_selected`¶

This is the number of items that needs to be selected at minimum to be able to close the selection dialog.

Set this to 0 to disable the limit. This configuration can be overridden when calling the dialog.

type: int, required: No, default: 1

`max_selected`¶

This is the number of items that needs to be selected at maximum to be able to close the selection dialog.

Set this to 0 to disable the limit. This configuration can be overridden when calling the dialog.

type: int, required: No, default: 0

`parameters`¶

With this, you can transfer a custom list of parameters to the item configuration, together with all other configuration values described in this document.

type: array, required: No, default: []

`tree`¶

enabled¶

Controls if the tree panel will be displayed or not.

This configuration can be overridden when calling the dialog.

type: bool, required: No, default: true

`search`¶

enabled¶

Controls if the search panel will be displayed or not.

This configuration can be overridden when calling the dialog.

type: bool, required: No, default: true

`preview`¶

enabled¶

Controls if the preview panel will be displayed or not.

This configuration can be overridden when calling the dialog.

type: bool, required: No, default: true

template¶

Specifies the template that will be used to render the preview panel.

type: string, required: Yes, example: @App/ngcb/my_item_type.html.twig

`columns`¶

Specifies the list of columns that are available for the item type.

At least a column with identifier name must exist and either template or value_provider configuration must be specified for each of the columns.

name¶

This is the human readable name of your column. You can use a translation placeholder here, which will be translated with ngcb catalog.

type: string, required: Yes, example: columns.my_item_type.some_column

template¶

Specifies the template that will be used to render the cell in the column.

type: string, required: No, example: @App/ngcb/my_item_type/some_column.html.twig

value_provider¶

Specifies the identifier of a value provider that will be used to provide the cell value.

type: string, required: No, example: my_item_type\some_column

`default_columns`¶

Specifies the list of columns that will be shown when the dialog is first opened.

type: array, required: Yes, example: ['name', 'other_column']

Full configuration example¶

The following code block shows the full configuration example of an item type with identifier my_item_type:

netgen_content_browser:
    item_types:
        my_item_type:
            name: item_types.my_item_type
            min_selected: 1
            max_selected: 0
            tree:
                enabled: true
            search:
                enabled: false
            preview:
                enabled: true
                template: '@App/ngcb/my_item_type.html.twig'
            columns:
                name:
                    name: columns.name
                    value_provider: name
                some_column:
                    name: columns.my_item_type.some_column
                    template: '@App/ngcb/my_item_type/some_column.html.twig'
                other_column:
                    name: columns.my_item_type.other_column
                    value_provider: my_item_type\other_column
            default_columns: [name, some_column]

Available Symfony services¶

A number of Symfony services is available for usage in your code:

`netgen_content_browser.registry.backend`¶

This service is a registry which holds all available backends. It is a class with Netgen\ContentBrowser\Registry\BackendRegistry type and you can use it to manually load Content Browser items by their ID.

$backendRegistry = $this->get('netgen_content_browser.registry.backend');
$eZLocationBackend = $backendRegistry->getBackend('ezlocation');

$item = $eZLocationBackend->loadItem(42);

Configuration services¶

Every backend has its own configuration service which can be used by the backend to access all config options specified in Symfony semantic config, as well as any custom parameters passed to the backend by the calling code. These services are all instances of Netgen\ContentBrowser\Config\Configuration class.

The names of these services are netgen_content_browser.config.ITEM_TYPE. So for ezlocation item type, service name would be netgen_content_browser.config.ezlocation.

Symfony dependency injection tags¶

The following lists all dependency injection tags and their usage available in Netgen Content Browser:

`netgen_content_browser.backend`¶

Purpose: Adds a new backend to the system

A backend is a service that provides methods to load the list of items and locations in Content Browser interface. A backend needs to implement Netgen\ContentBrowser\Backend\BackendInterface interface.

When registering a new backend, you need to use the item_type attribute in the tag to specify the item type the backend is used for:

app.content_browser.my_backend:
    class: AppBundle\ContentBrowser\MyBackend
    tags:
        - { name: netgen_content_browser.backend, item_type: my_backend }

`netgen_content_browser.column_value_provider`¶

Purpose: Adds a new column value provider for a single item column

A column value provider is a service that provides a value to a column displayed in Content Browser interface for a specific item. Column value provider needs to implement Netgen\ContentBrowser\Item\ColumnProvider\ColumnValueProviderInterface interface.

When registering a new column value provider, you need to use the identifier attribute in the tag to attach a unique identifier to the provider:

app.content_browser.my_item.custom_column:
    class: AppBundle\ContentBrowser\MyItem\CustomColumn
    tags:
        - { name: netgen_content_browser.column_value_provider, identifier: my_item\custom_column }

Upgrades¶

Upgrading from 0.7.0 to 0.8.0¶

Upgrade `composer.json`¶

In your composer.json file, upgrade the version of netgen/content-browser package to ~0.8.0 and run the composer update command.

Breaking changes¶

The following breaking changes were made in version 0.8 of Content Browser. Follow the instructions to upgrade your code to this newer version.

sections config has been removed from configuration of item types since overriding sections has never been properly implemented. Remove the section from your own item type definitions.

The concept of item serializer handlers is removed. Previously, they were used to specify how certain data will be serialized for an item. One method that the Netgen\ContentBrowser\Item\Serializer\ItemSerializerHandlerInterface provided has been moved to Netgen\ContentBrowser\Item\ItemInterface, so you need to move your implementation there:

// Before

<?php

namespace AppBundle\ContentBrowser\Item\Serializer\Handler;

use Netgen\ContentBrowser\Item\ItemInterface;
use Netgen\ContentBrowser\Item\Serializer\ItemSerializerHandlerInterface;

class MyItemSerializerHandler implements ItemSerializerHandlerInterface
{
    /**
     * Returns if the item is selectable.
     *
     * @param \Netgen\ContentBrowser\Item\ItemInterface $item
     *
     * @return bool
     */
    public function isSelectable(ItemInterface $item)
    {
        // Determine if the item is selectable
    }
}

// After

<?php

namespace AppBundle\ContentBrowser\Item\MyItem;

use Netgen\ContentBrowser\Item\ItemInterface;

class Item implements ItemInterface
{
    /**
     * Returns if the item is selectable.
     *
     * @return bool
     */
    public function isSelectable()
    {
        // Determine if the item is selectable
    }
}

The concept of item template value providers is removed. Previously, they were used to provide the variables that will be used by the templates to render the item preview and columns. Now, one single variable called item is injected to all Twig templates. This variable holds the actual item which is rendered, which means that your Netgen\ContentBrowser\Item\ItemInterface objects need to provide everything that will be used to render the templates.

// Before

<?php

namespace AppBundle\ContentBrowser\Item\Renderer\TemplateValueProvider;

use Netgen\ContentBrowser\Item\ItemInterface;
use Netgen\ContentBrowser\Item\Renderer\TemplateValueProviderInterface;

class MyItemTemplateValueProvider implements TemplateValueProviderInterface
{
    /**
     * Provides the values for template rendering.
     *
     * @param \Netgen\ContentBrowser\Item\ItemInterface $item
     *
     * @return array
     */
    public function getValues(ItemInterface $item)
    {
        $thingOne = ...;
        $thingTwo = ...;

        return array(
            'thingOne' => $thingOne,
            'thingTwo' => $thingTwo,
        );
    }
}

// After

<?php

namespace AppBundle\ContentBrowser\Item\MyItem;

use Netgen\ContentBrowser\Item\ItemInterface;

class Item implements ItemInterface
{
    /**
     * Returns thing one.
     *
     * @return mixed
     */
    public function getThingOne()
    {
        return ...;
    }

    /**
     * Returns thing two.
     *
     * @return mixed
     */
    public function getThingTwo()
    {
        return ...;
    }
}

In your templates, instead of directly using variables thingOne and thingTwo, you will now use item.thingOne and item.thingTwo.

Upgrading from 0.8.0 to 0.9.0¶

Upgrade `composer.json`¶

In your composer.json file, upgrade the version of netgen/content-browser package to ~0.9.0 and run the composer update command.

Breaking changes¶

The following breaking changes were made in version 0.9 of Content Browser. Follow the instructions to upgrade your code to this newer version.

Many services that should not be used directly and are not part of public API are now marked as private in service container. Remove usage of those services in your code. Note that some of the services (forms and event subscribers) were not marked as private due to incompatibilities with Symfony 2.8, but will be marked as such in a future update.
Most of the internal protected dependencies and methods were made private and classes made final. Rather than extending internal classes, you need to use other patterns when changing built in behaviour.
ezlocation and ezcontent backends have been merged to one backend that handles both eZ location and content items. This means that eZ location and eZ content specific items and column value providers have also been merged into one. You need to adapt your code that uses them to use the new backend, item and column value providers.

Names of the CSS and JavaScript assets have been changed:

Before:

{{ asset('netgen-content-browser.css', 'ngcb_css') }}
{{ asset('netgen-content-browser.js', 'ngcb_js') }}

After:

{{ asset('main.css', 'ngcb_css') }}
{{ asset('main.js', 'ngcb_js') }}

CSS class js-config-name in HTML markup has been renamed to js-item-type. If you have any custom code that calls the content browser (e.g. overridden form type templates or code that calls the browser directly), update the CSS class name to the new value.
Virtual services netgen_content_browser.current_backend and netgen_content_browser.current_config have been renamed to netgen_content_browser.backend and netgen_content_browser.config respectively.

eZ Platform specific breaking changes¶

Minimum supported version of eZ Platform is now 2.5 or 3.0
All container parameters that had ezpublish as part of their names have been renamed to ezplatform instead.

Container parameters that allow specifying the item, preview and thumbnail templates have been renamed to remove default_ part of their name.

Old name	New name
`netgen_content_browser.ezpublish.default_item_template`	`netgen_content_browser.ezplatform.item_template`
`netgen_content_browser.ezpublish.default_preview_template`	`netgen_content_browser.ezplatform.preview_template`
`netgen_content_browser.ezpublish.default_thumbnail_template`	`netgen_content_browser.ezplatform.thumbnail_template`
`netgen_content_browser.eztags.default_item_template`	`netgen_content_browser.eztags.item_template`

All services that had EzPublish as part of their FQCN have been renamed to EzPlatform instead.
All services that had ezpublish as part of their service name have been renamed to ezplatform instead.
Identifiers of column value providers have been renamed from having the ezpublish\ prefix to having the ezplatform\ prefix. This also includes the related translations, which have been renamed from columns.ezpublish. prefix to columns.ezplatform. prefix.

Upgrading from 1.0.0 to 1.1.0¶

Upgrade `composer.json`¶

In your composer.json file, upgrade the version of netgen/content-browser package and all other related packages (like netgen/content-browser-ui, netgen/content-browser-ezplatform and others) to ~1.1.0 and run the composer update command.

Remove unused bundles¶

Netgen Content Browser 1.1 does not depend on WhiteOctober Pagerfanta bundle any more. If you did not require and use it in your project, it will be automatically uninstalled. You will need to remove it from your list of activated bundles manually.

Changelog¶

Added support for PHP 7.4
Added support for Symfony 5

Breaking changes¶

There were no breaking changes in 1.1 version of Netgen Content Browser.

Upgrading from 1.1.0 to 1.2.0¶

Upgrade `composer.json`¶

In your composer.json file, upgrade the version of netgen/content-browser package and all other related packages (like netgen/content-browser-ui, netgen/content-browser-ezplatform and others) to ~1.2.0 and run the composer update command.

Changelog¶

eZ Platform integration now allows to perform searches in media and users section
Minimum supported PHP version is now 7.3

Deprecations¶

BackendInterface::search and BackendInterface::searchCount methods are deprecated and will be removed in 2.0. Implement replacement methods BackendInterface::searchItems and BackendInterface::searchItemsCount to remove the deprecation. These new methods will be added to the interface in 2.0.

The purpose of the new methods is to provide more stable method signature when extending search capabilities of Content Browser planned in future versions.

Breaking changes¶

There were no breaking changes in 1.2 version of Netgen Content Browser.

The cookbook¶

The cookbook provides a handful of recipes with which you can learn how to extend and use Netgen Content Browser.

The cookbook¶

The cookbook provides a handful of recipes with which you can learn how to extend and use Netgen Content Browser.

Implementing a custom backend¶

Implementing a custom backend is a way to add support for your CMS of choice to the content browser.

The concept of a backend revolves around the concept of locations and items. Locations are comparable to folders in a file system, while items are comparable to files. The location is used to build the tree structure that holds the items, and items are what is actually selectable in the content browser dialogue. Types of items are identified by their string identifier and every backend needs to work with and return only one item type.

When implementing a backend and all its required services, it is left up to you to define whether some locations can also be items, (like in eZ Platform, where all locations in a tree are selectable), or not (like in Sylius, where locations are built from Sylius taxons and are not selectable), or some other combination (like in Netgen Tags, where the root location is a virtual one and thus not selectable, while all other are).

Items need to implement Netgen\ContentBrowser\Item\ItemInterface while locations need to implement Netgen\ContentBrowser\Item\LocationInterface. When a location is also an item, it needs to implement both LocationInterface and ItemInterface.

Implementing a backend involves the following:

Configuring and enabling your new item type
Creating a Symfony service implementing Netgen\ContentBrowser\Backend\BackendInterface
Creating objects implementing ItemInterface and LocationInterface which will be returned by the methods from the backend service
Creating and configuring the templates used to render the columns or creating a Symfony service implementing Netgen\ContentBrowser\Item\ColumnProvider\ColumnValueProviderInterface for every column you add that’s not using a template for rendering

Configuring and enabling your new item type¶

Once you decide on your new item type identifier (in these examples, we will use my_item_type), enabling it inside Content Browser is done with the following minimum configuration, which defines the item human readable name, the template used to render the item preview and a list of columns:

netgen_content_browser:
    item_types:
        my_item_type:
            name: item_types.my_item_type # Will be translated with "ngcb" catalog
            preview:
                template: '@App/ngcb/my_item_type.html.twig'
            columns:
                # At least a "name" column must exist
                name:
                    name: columns.name # Will be translated with "ngcb" catalog
                    value_provider: name # Using a built in "name" value provider
            default_columns:
                - name

For the list of all available configuration options, take a look at the configuration reference.

Creating a Symfony service for the backend¶

Every item type needs to have a Symfony service called backend. Backend’s job is to hook into the CMS and return the data from the CMS needed to build locations and items. Backend must only return the items of a single type, the one it is registered for.

Every backend needs to implement Netgen\ContentBrowser\Backend\BackendInterface, which defines the number of methods used by the user interface to fetch the locations and items. Most of these methods are straightforward. They either return a list of locations/items under specified location or with the specified name, or a single location/item with provided ID.

getSections method should return a list of LocationInterface objects that will act as root locations of different sections of the location tree. For example, eZ specific backend would return three LocationInterface objects here, the one representing “Home” eZ location, the one representing “Media” eZ location and the one representing “Users” eZ location.

Once implemented, backend needs to be registered in Symfony DIC and connected to the item type by using netgen_content_browser.backend tag:

app.content_browser.backend.my_item_type:
    class: AppBundle\ContentBrowser\Backend\MyItemTypeBackend
    tags:
        -  { name: netgen_content_browser.backend, item_type: my_item_type }

Creating `ItemInterface` and `LocationInterface` objects¶

As already mentioned, backend needs to return objects implementing Netgen\ContentBrowser\Item\LocationInterface and Netgen\ContentBrowser\Item\ItemInterface, that represent Content Browser locations and items, respectively. It is up to you to implement these objects, either by building them directly in the backend, using a dedicated service to build them or in some other way you find appropriate. ItemInterface object will be injected in all templates (either when rendering a preview of an item or a single column), so make sure that it contains any data that you will need to render the templates.

Creating a preview template for the item¶

As already mentioned, you can enable a preview of your items with the following configuration:

netgen_content_browser:
    my_item_type:
        preview:
            template: '@App/ngcb/my_item_type.html.twig'

Creating this template is a simple task. The template receives the item in question in an item variable, which you can use to render the template.

Implementing columns rendered via templates¶

Content Browser allows you to implement your custom columns by specifying a template that will be used to render the cell data in the column.

To enable this behaviour, simply specify that a template should be used in your column definition:

netgen_content_browser:
        my_item_type:
        columns:
            column_one:
                name: columns.my_item_type.column_one
                template: '@App/ngcb/my_item_type/column_one.html.twig'

Just as with a preview template, creating this template is a simple task. Again, the template receives the item in question in an item variable, which you can use to render the template.

Implementing columns rendered via column value providers¶

If rendering a column via Twig template is not suitable for you, you can use a separate Symfony service to render the cell data of a column.

To create the service, you need to implement Netgen\ContentBrowser\Item\ColumnProvider\ColumnValueProviderInterface interface. This interface has a single getValue method which receives the item in question and should return a value that will be displayed inside the cell.

Once you create the service, register it in Symfony DIC, tag it with netgen_content_browser.column_value_provider tag and attach a unique identifier to the tag:

app.content_browser.template_value_provider.my_item_type.column_two:
    class: AppBundle\ContentBrowser\ColumnValueProvider\MyItemType\ColumnTwo
    tags:
        - { name: netgen_content_browser.column_value_provider, identifier: my_item_type\column_two }

After that, you simply need to reference the identifier of the value provider in column definition:

netgen_content_browser:
    my_item_type:
        columns:
            column_two:
                name: columns.my_item_type.column_two
                value_provider: my_item_type\column_two

Implementing a custom column for existing item types¶

Implementing a custom column for existing item types is not any different from implementing a column for your own custom item type.

The process involves adding a bit of configuration to enable the column:

netgen_content_browser:
    ezlocation:
        columns:
            my_column:
                name: columns.ezlocation.my_column
                # Either specify a template or a value provider identifier
                template: '@App/ngcb/ezlocation/my_column.html.twig'
                # value_provider: ezlocation\my_column

And then you need to either create a template that will render the cell of the column, or create and register a Symfony service that does the same. For more details, read the relevant sections in the chapter about creating a custom backend.

Usage in Symfony forms¶

Netgen Content Browser supports calling the browser from Symfony forms. To facilitate this, three custom Symfony form types have been implemented:

Single content browser type
Multiple content browser type
Dynamic content browser type

Requirements¶

Before you can use the Content Browser, you need to include its assets in your page head:

<meta name="ngcb-base-path" content="{{ path('ngcb_root') }}">
<link rel="stylesheet" href="{{ asset('main.css', 'ngcb_css') }}">
<script src="{{ asset('main.js', 'ngcb_js') }}"></script>

or just include the provided Twig template:

{% include '@NetgenContentBrowser/page_head.html.twig' %}

All HTML code blocks which have js-input-browse or js-multiple-browse CSS class will be automatically initialized on window load with the included JavaScript code.

If you use another CSS class, or if you wish to add Content Browser markup via AJAX to your page, you will need to manually initialize the plugin on those elements. In that case, you don’t have to include JavaScript assets in your page head. Instead, you will need to install Content Browser via Yarn/NPM and import the plugin in your own JavaScript code manually.

Content Browser JavaScript module was preinstalled for you when you installed Content Browser via Composer. Activate it in your setup with:

$ yarn add file:vendor/netgen/content-browser-ui

or

$ npm install file:vendor/netgen/content-browser-ui

Import and initialize the Content Browser plugin:

import { InputBrowse, MultipleBrowse } from '@netgen/content-browser-ui';

// initialize single item select plugin
[...document.getElementsByClassName('js-input-browse')].forEach(el => new InputBrowse(el));

// initialize multiple item select plugin
[...document.getElementsByClassName('js-multiple-browse')].forEach(el => new MultipleBrowse(el));

Single content browser type¶

Single content browser type allows you to select a single item of a predefined item type.

Form type class¶

Netgen\ContentBrowser\Form\Type\ContentBrowserType

Available options¶

item_type

This option defines which item type will the browser select

type: string, required: Yes
start_location

This option defines in which location the Content Browser will start.

type: int|string, required: No, default value: null
custom_params

This option is used to transfer any custom parameters to your backend.

type: array, required: No, default value: []

Other options¶

Parent of this type is the Symfony TextType type, so any options available in that type can be used in this type too.

Multiple content browser type¶

Multiple content browser type allows you to select one or more items of a predefined item type.

Form type class¶

Netgen\ContentBrowser\Form\Type\ContentBrowserMultipleType

Available options¶

item_type

This option defines which item type will the browser select

type: string, required: Yes
min

This option defines how many items must at least be selected before the dialog can be closed. Use null to disable the limit.

type: int, required: No, default value: null
max

This option defines how many items must at maximum be selected for dialog to be closed. Use null to disable the limit.

type: int, required: No, default value: null
start_location

This option defines in which location the Content Browser will start.

type: int|string, required: No, default value: null
custom_params

This option is used to transfer any custom parameters to your backend.

type: array, required: No, default value: []

Other options¶

Parent of this type is the Symfony CollectionType type, so any options available in that type can be used in this type too.

Dynamic content browser type¶

Dynamic content browser type allows you to select a single item, however, in contrast to ContentBrowserType type, this type allows you to select the item type before calling the dialog.

This type is the composite one, meaning it is constructed from two child forms, one that will hold the selected item type (named item_type) and the one that will hold the selected item ID (named item_id).

Form type class¶

Netgen\ContentBrowser\Form\Type\ContentBrowserDynamicType

Available options¶

item_types

This option defines which item types will be available to select from

type: array of string values, required: Yes
start_location

This option defines in which location the Content Browser will start.

type: int|string, required: No, default value: null
custom_params

This option is used to transfer any custom parameters to your backend.

type: array, required: No, default value: []

Usage in HTML¶

Content browser can be called at will anywhere from your HTML code by including a piece of specially crafted HTML.

Requirements¶

Before you can use the Content Browser, you need to include its assets in your page head:

<meta name="ngcb-base-path" content="{{ path('ngcb_root') }}">
<link rel="stylesheet" href="{{ asset('main.css', 'ngcb_css') }}">
<script src="{{ asset('main.js', 'ngcb_js') }}"></script>

or just include the provided Twig template:

{% include '@NetgenContentBrowser/page_head.html.twig' %}

All HTML code blocks which have js-input-browse or js-multiple-browse CSS class will be automatically initialized on window load with the included JavaScript code.

If you use another CSS class, or if you wish to add Content Browser markup via AJAX to your page, you will need to manually initialize the plugin on those elements. In that case, you don’t have to include JavaScript assets in your page head. Instead, you will need to install Content Browser via Yarn/NPM and import the plugin in your own JavaScript code manually.

Content Browser JavaScript module was preinstalled for you when you installed Content Browser via Composer. Activate it in your setup with:

$ yarn add file:vendor/netgen/content-browser-ui

or

$ npm install file:vendor/netgen/content-browser-ui

Import and initialize the Content Browser plugin:

import { InputBrowse, MultipleBrowse } from '@netgen/content-browser-ui';

// initialize single item select plugin
[...document.getElementsByClassName('js-input-browse')].forEach(el => new InputBrowse(el));

// initialize multiple item select plugin
[...document.getElementsByClassName('js-multiple-browse')].forEach(el => new MultipleBrowse(el));

Calling the Content Browser from your HTML¶

Use the following piece of HTML code to call the Content Browser, and replace the relevant pieces of data to suit your needs (item type, CSS ID for the value input and data- attributes).

After you select some items and close the Content Browser dialog, selected value will be available in a hidden input with a js-value CSS class.

Take care not to remove or change any other predefined CSS classes or HTML structure as this will break the Content Browser dialog.

data- attributes are all optional. data- attributes modify the behaviour of the interface, like limiting the number of items which can be selected, or showing/hiding certain aspects of the interface. One special data- attribute is used to modify the behaviour of the backend, by transferring it to the backend via query parameters. Basically, every data- attribute which starts with data-custom-, will be transferred to the backend so you can use it to modify the behaviour as you see fit. In the backend, you can inject the configuration object, as explained in the list of available Symfony services, which will then hold the list of all custom parameters.

Tip

To help you reach the selected value, you can attach custom CSS ID to hidden input where value is stored, as shown below.

<div class="js-input-browse item-empty"
    data-min_selected="1"
    data-max_selected="1"
    data-start_location="42"
>
    <div class="input-browse">
        <span class="js-clear"><i class="material-icons">close</i></span>

        <a class="js-trigger" href="#">
            <span class="js-name" data-empty-note="No item selected">Select an item</span>
        </a>
    </div>

    <input type="hidden" class="js-item-type" value="MY_ITEM_TYPE" />
    <input type="hidden" class="js-value" id="CSS_ID" value="" />
</div>

Calling the Content Browser from your Twig template¶

Alternatively, you can just use a handy Twig template and set the wanted options via an include tag:

{% include '@NetgenContentBrowser/content_browser.html.twig'
    with {
        input_id: 'my-location',
        item_type: 'ezlocation',
        item_name: 'My item',
        no_item_message: 'No item selected',
        required: false,
        min: 2,
        max: 3,
        custom_params: {param1: 'value1', param2: ['value2', 'value3']},
        start_location: 42,
        show_tree: true,
        show_search: false,
        show_preview: true
    }
%}

The following lists all available parameters that can be transferred to the template.

Required parameters¶

input_id

ID of the input where selected value will be placed, required

type: string
item_type

Item type to select in the dialog, required

type: string

Optional parameters¶

item_name

Item name to render when you already have a value

type: string
no_item_message

Message to show if no value is selected

type: string
required

If undefined or set to false, will render a button to clear the value

type: bool
min

Minimum number of items to select, defaults to configuration if undefined

type: int
max

Maximum number of items to select, defaults to configuration if undefined

type: int
custom_params

The list of custom parameters to transfer to the backend

type: array
start_location

This option defines in which location the Content Browser will start

type: int
show_tree

Whether to show the tree or not, defaults to configuration if undefined

type: bool
show_search

Whether to show the search or not, defaults to configuration if undefined

type: bool
show_preview

Whether to show the preview or not, defaults to configuration if undefined

type: bool

Usage in JavaScript¶

Content Browser can be called at will anywhere from your JavaScript code.

Installing the Content Browser plugin¶

Content Browser JavaScript module was preinstalled for you when you installed Content Browser via Composer. Activate it in your setup with:

$ yarn add file:vendor/netgen/content-browser-ui

or

$ npm install file:vendor/netgen/content-browser-ui

Usage¶

To initialize Content Browser and use it in JavaScript on custom events you can use the Browser plugin.

Import and initialize the plugin:

import { Browser } from '@netgen/content-browser-ui';

// create new Content Browser instance
const browser = new Browser(config);

// open the browser
browser.open();

Plugin accepts JavaScript object as options for that instance. For example:

import { Browser } from '@netgen/content-browser-ui';

// create new Content Browser instance
const browser = new Browser({
  overrides: {
    has_preview: false,
    max_selected: 4,
  },
  itemType: 'ezlocation',
  onConfirm: function(selected) {
    // onConfirm function returns selected items
    console.log(selected);
  },
  onCancel: function() {
    console.log('Browser closed');
  },
});

// open the browser
browser.open();

Required parameters for Content Browser config¶

itemType

Item type to select in the dialog.

type: string

Optional parameters for Content Browser config¶

onCancel

Function that is called after browser is closed without selecting the items.

type: function
onConfirm

Function that is called after selecting the items and confirming in Content Browser.

Function returns an array of selected items.

type: function
disabledItems

Array of item IDs that should be disabled for selection in Content Browser.

type: array
overrides

Object with overrides for configuration initially specified via backend REST API after opening Content Browser.

type: object

Using CSS¶

You need to include the CSS file for Content Browser for it to be displayed properly. You can import the styles in your SCSS file:

@import "@netgen/content-browser-ui/bundle/Resources/public/css/main";

You also need to configure sass-loader to understand imports from node_modules directory:

{
  loader: 'sass-loader',
  options: {
    includePaths: ['./node_modules']
  }
}

or import the file with a path relative to your SCSS file:

@import "../node_modules/@netgen/content-browser-ui/bundle/Resources/public/css/main";

eZ Platform integration¶

This section provides a handful of recipes with which you can learn how to extend eZ Platform integration in content browser.

eZ Platform integration¶

This section provides a handful of recipes with which you can learn how to extend eZ Platform integration in content browser.

Custom preview template for eZ content types¶

Implementing custom preview templates for eZ Platform content types is as easy as adding a new eZ view type in your content view configuration.

For every content type you wish to add the preview for, you need to define an override template for ngcb_preview view type, which will then automatically be used by the Content Browser to display the preview.

For example, to add the preview for your custom content type with identifier my_content_type, add the following config to your eZ Platform config:

ezpublish:
    system:
        default:
            content_view:
                ngcb_preview:
                    my_content_type:
                        template: '@App/ngcb/preview/my_content_type.html.twig'
                        match:
                            Identifier\ContentType: my_content_type

@App/ngcb/preview/my_content_type.html.twig is then a regular eZ Platform content view template, meaning you have access to content and location variables, which you can use to render what ever you wish.

Custom backend parameters¶

eZ location and eZ content backends support two custom parameters for now:

Overriding content types which will be shown in the tree
Overriding content types which will be selectable

Overriding content types which will be shown in the tree¶

To override which content types will be used to build the location tree, use location_content_types custom parameter, e.g.:

<div class="js-input-browse item-empty"
    data-custom-location_content_types="folder,category"
>
    ...
</div>

or in case of Twig template usage:

{% include '@NetgenContentBrowser/content_browser.html.twig'
    with {
        input_id: 'my-location',
        item_type: 'ezlocation',
        custom_params: {location_content_types: ['folder', 'category']}
    }
%}

Overriding content types which will be selectable¶

To override which content types will be selectable in the list of items, use allowed_content_types custom parameter, e.g.:

<div class="js-input-browse item-empty"
    data-custom-allowed_content_types="news,blog_post"
>
    ...
</div>

or in case of Twig template usage:

{% include '@NetgenContentBrowser/content_browser.html.twig'
    with {
        input_id: 'my-location',
        item_type: 'ezlocation',
        custom_params: {allowed_content_types: ['news', 'blog_post']}
    }
%}

Old block prefix	New block prefix
`ng_content_browser`	`ngcb`
`ng_content_browser_dynamic`	`ngcb_dynamic`
`ng_content_browser_multiple`	`ngcb_multiple`

Netgen Content Browser Documentation¶

Reference¶

Reference¶

Installation instructions¶

Use Composer¶

Activate the bundle¶

Activate the routes¶

Install assets¶

Configuration reference¶

Item type configuration¶

name¶

min_selected¶

max_selected¶

parameters¶

tree¶

search¶

preview¶

columns¶

default_columns¶

Full configuration example¶

Available Symfony services¶

netgen_content_browser.registry.backend¶

Configuration services¶

Symfony dependency injection tags¶

netgen_content_browser.backend¶

netgen_content_browser.column_value_provider¶

Upgrades¶

Upgrades¶

Upgrading from 0.7.0 to 0.8.0¶

Upgrade composer.json¶

Breaking changes¶

Upgrading from 0.8.0 to 0.9.0¶

Upgrade composer.json¶

Breaking changes¶

Upgrading from 0.9.0 to 0.10.0¶

Upgrade composer.json¶

Breaking changes¶

Upgrading from 0.10.0 to 0.11.0¶

Upgrade composer.json¶

Breaking changes¶

Upgrading from 0.11.0 to 0.12.0¶

Upgrade composer.json¶

Breaking changes¶

Upgrading from 0.12.0 to 0.13.0¶

Upgrade composer.json¶

Breaking changes¶

Upgrading from 0.13.0 to 1.0.0¶

Upgrade composer.json¶

Breaking changes¶

eZ Platform specific breaking changes¶

Upgrading from 1.0.0 to 1.1.0¶

Upgrade composer.json¶

Remove unused bundles¶

Changelog¶

Breaking changes¶

Upgrading from 1.1.0 to 1.2.0¶

Upgrade composer.json¶

Changelog¶

Deprecations¶

Breaking changes¶

The cookbook¶

The cookbook¶

Implementing a custom backend¶

Configuring and enabling your new item type¶

Creating a Symfony service for the backend¶

Creating ItemInterface and LocationInterface objects¶

Creating a preview template for the item¶

Implementing columns rendered via templates¶

Implementing columns rendered via column value providers¶

Implementing a custom column for existing item types¶

Usage in Symfony forms¶

Requirements¶

Single content browser type¶

Form type class¶

Available options¶

Other options¶

Multiple content browser type¶

Form type class¶

Available options¶

Other options¶

`name`¶

`min_selected`¶

`max_selected`¶

`parameters`¶

`tree`¶

`search`¶

`preview`¶

`columns`¶

`default_columns`¶

`netgen_content_browser.registry.backend`¶

`netgen_content_browser.backend`¶

`netgen_content_browser.column_value_provider`¶

Upgrade `composer.json`¶

Upgrade `composer.json`¶

Upgrade `composer.json`¶

Upgrade `composer.json`¶

Upgrade `composer.json`¶

Upgrade `composer.json`¶

Upgrade `composer.json`¶

Upgrade `composer.json`¶

Upgrade `composer.json`¶

Creating `ItemInterface` and `LocationInterface` objects¶