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('netgen-content-browser.css', 'ngcb_css') }}">
<script src="{{ asset('netgen-content-browser.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 document ready with jQuery and the plugin which are included in netgen-content-browser.js.

If you use another CSS class, or if you add content browser HTML code via AJAX to your page, you will need to manually initialize the plugin on those elements:

// ngc_jquery variable holds jQuery included with Netgen Content Browser
ngc_jquery('.js-input-browse').input_browse(); // for single item select
ngc_jquery('.js-multiple-browse').multiple_browse(); // for multiple item select

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-config-name" 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