Skip to content

Mediabrowser

Introduction

Mediabrowser

The MediaBrowser provides access to ressources (Content Manager Pages, MediaSource Files/Objects). Additionally, it allows the upload of new files (through component Uploader).

Integration

Client-side integration

In "backend" mode MediaBrowser is always loaded and can be configured and triggered
using JavaScript. The following binds the click event of <element> to a
MediaBrowser with the given configuration:

1
2
3
4
5
6
7
8
9
cx.mb.bind(
    <element>,
    <availableViews>,
    <startView>,
    <availableMediatypes>,
    <startMediatype>,
    <clickCallback>,
    <closeCallback>
);
  • <element>: Element to bind the click event to
  • <availableViews>: Any combination of "filebrowser,", "uploader," and "sitestructure," (take care of the trailing comma!)
  • <startView>: One of "filebrowser", "uploader", "sitestructure"
  • <availableMediatypes>: "all" or a list of any registred MediaSource. I.e.: "files", "media1", "media2", "media3", "media4", "attach", "shop", "gallery", "access", "mediadir", "downloads", "calendar", etc.
  • <startMediatype>: Any registered MediaSource (see above).
  • <clickCallback>: Callback to call when the button is pressed. Receives the original click event with e.preventDefault() already called on it.
  • <closeCallback>: Callback to call when MediaBrowser is closed

Image chooser

In "backend" mode ImageChooser can by triggered by creating the necessary
markup and calling cx.mb.imagechooser.init(el, mediatypes = "all", startMediatype = "files") on it.

Server-side integration

Image chooser

If you want to let the user choose an image you can use the image chooser integration. See Cx\Core_Modules\MediaBrowser\Model\Entity\MediaBrowser::getImageChooserMarkup().

Warning

Currently, this only works in backend.

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
$mediaBrowser = new \Cx\Core_Modules\MediaBrowser\Model\Entity\MediaBrowser();
$template->setVariable(
    'MY_IMAGE',
    $mediaBrowser->getImageChooserMarkup(
        <inputName>,
        <currentImgFile>,
        <initialMediaType>,
        <availableMediaTypes>,
        <currentImgThumbnailFile>,
        <startView>,
        <availableViews>,
        <placeholderImgFile>
    )
);

Only <inputName> and <currentImgFile> are required.

Button

To include the MediaBrowser in your own component through a HTML-button element, do as follows:

  1. Create new instance of \Cx\Core_Modules\MediaBrowser\Model\Entity\MediaBrowser:

    1
    $mediaBrowser = new \Cx\Core_Modules\MediaBrowser\Model\Entity\MediaBrowser();

  2. Configure MediaBrowser using options. I.e.:

    1
2
3
4
5
6
    $mediaBrowser->setOptions(array(
    'type' => 'button',
    'id' => 'myMediaBrowserBtn',
    'views' => 'uploader,filebrowser,sitestructure,',
    'startview' => 'sitestructure',
));

  3. Register the name of a JavaScript callback (that will be triggered once the user did select a ressource in the MediaBrowser):

    1
    $mediaBrowser->setCallback('javascript_callback_function');

    See Callback arguments

  4. Call the method MediaBrowser::getXHtml($label) on your instance to fetch the HTML-snippet:

    1
    $html = $mediaBrowser->getXHtml($_ARRAYLANG['TXT_CORE_CM_BROWSE']);

    $label will be used as display name of the button

  5. Insert the fetched HTML-snippet in the (Sigma) template:

    1
    $this->template->setVariable('MEDIABROWSER_BUTTON', $html);

This will create a HTML-button with the label $label set. On trigger, the MediaBrowser will appear on the screen.

Custom layout integration

If you want to open the MediaBrowser not through the default HTML-button (as generated through MediaBrowser::getXHtml($label), but instead through a custom trigger, then simple hide the generated HTML-button (using CSS) and trigger the click-event on the button manually. This allows dynamic customization of the MediaBrowser, by passing a specific config (see available options) to the click-event.

1
2
3
4
5
6
7
8
9
const mediabrowser__closed_callback = function (callback) {
    ...
}

cx.variables.get('jquery', 'mediabrowser')('#mediabrowser_button').trigger("click", {
    callback: mediabrowser__closed_callback,
    cxMbViews: 'filebrowser,uploader',
    cxMbStartview: 'filebrowser'
});

With this method you can also add temporary options and an individual callback.

Options

The following options allow customization of the MediaBrowser modal.

Options can either be set in PHP using Cx\Core_Modules\MediaBrowser\Model\Entity\MediaBrowser::setOptions() or dynamically in JavaScript (through jQuery) when using a custom layout integration.

PHP

1
2
3
$mediaBrowser->setOptions(array(
    '<option>' => '<value>'
));

JavaScript (jQuery)

1
2
3
4
5
6
7
const mb = cx.variables.get("jquery", "mediabrowser")("#mediabrowser_button");
let options = {
    callback: mediabrowser__closed_callback,
    cxMbViews: "filebrowser,uploader",
    cxMbStartview: "filebrowser",
};
mb.trigger("click", options);

Note

A vanilla JavaScript integration is currently not supported, as the MediaBrowser does internally depend on jQuery (using instance cx.variables.get("jquery", "mediabrowser")) to track its state.

PHP option name jQuery option name Possible datatypes Possible values Default value Description
type - string button Set the type attribute of the HTML-input element
id - string Set the id attribute of the HTML-input element.
views cxMbViews string sitestructure / uploader / filebrowser all Set the views (as comma-separated list) that shall be loaded and be available in the left navigation pane.
startview cxMbStartview string sitestructure / uploader / filebrowser filebrowser Set the default view to display when loading the MediaBrowser. Note: If you do register your own view, you can also set that as startView.
startmediatype cxMbStartmediatype1 string Any registred MediaSource. I.e.: files / media1 / media2 / media3 / media4 / attach / shop / gallery / access / mediadir / downloads / calendar / etc. files Set initial MediaSource to display (for view filebrowser)
mediatypes cxMbMediatypes string all or a list of any registred MediaSource. I.e.: files / media1 / media2 / media3 / media4 / attach / shop / gallery / access / mediadir / downloads / calendar / etc. all Set the list of available MediaSources in view filebrowser.
multipleselect cxMbMultipleselect boolean true / false false Whether or not the selection of multiple ressources is permitted
modalopened cxMbModalopened mixed false / name of callback as string false Set JavaScript callback to be called after the MediaBrowser has been opened. I.e.: $mediabrowser->setOption(array('modalopened' => 'mediabrowser__opened_callback',));window.mediabrowser__opened_callback = function(){...};
modalclosed cxMbModalclosed mixed false / name of callback as string false Can be used instead of MediaBrowser::setCallback(). I.e.: $mediabrowser->setOption(array('modalclosed' => 'mediabrowser__closed_callback',));window.mediabrowser__closed_callback = function(data){...};
- startPath undocumented undocumented Last accessed path of MediaSource Allows overriding the entry point of a MediaSource.

Callback arguments

Depending on the user's action, the data passed to the modalclose callback has the following form:

File has been selected

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
{
    type:"file",
    data:[{
         datainfo:{
            filepath:"/images/content/Screenshot-from-2014-11-24-104815.png",
            name:"Screenshot-from-2014-11-24-104815.png",
            size:"341.94 KB",
            cleansize:350150,
            extension:"Png",
            preview:"/images/content/Screenshot-from-2014-11-24-104815.thumb_thumbnail.png",
            active:false,
            type:"file",
            thumbnail: {
                "150":"/images/content/Screenshot-from-2014-11-24-104815.thumb_thumbnail.png",
                "300":"/images/content/Screenshot-from-2014-11-24-104815.thumb_medium.png",
                "640":"/images/content/Screenshot-from-2014-11-24-104815.thumb_large.png"
            }
        },
        $$hashKey:"object:740"
    }]
}

Content Manager Page has been selected

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
    type:"page",
    locale: "de",
    data:[{
        click:"javascript:{setUrl('[[NODE_HOME]]',null,null,'de/Willkommen','page')}",
        name:"Willkommen",
        extension:"Html",
        level:0,
        url:"/Willkommen",
        node:"[[NODE_HOME]]",
        localization: [{
            de: {
                name: "Willkommen",
                node: "[[NODE_HOME_DE]]",
                url: "/Willkommen"
            },
            en: {
                name: "Willkommen",
                node: "[[NODE_HOME_EN]]",
                url: "/Welcome"
            },
            ...
        }],
        $$hashKey:"object:789"
    }]
}

Nothing selected

If the user has closed the MediaBrowser without any selection:

1
2
3
4
{
    type:"close",
    data:[]
}

Add own view

To add your own view, do as follows:

  1. Register an EventLister to event MediaBrowser.Plugin:initialize in ComponentController:

    1
2
3
4
5
6
    public function registerEventListeners() {
    $this->cx->getEvents()->addEventListener(
        'MediaBrowser.Plugin:initialize',
        new \Cx\Modules\<component>\Model\Event\MyEventListener($this->cx)
    );
}

  2. Register view in \Cx\Modules\<component>\Model\Event\MyEventListener:

    1
2
3
    public function mediaBrowserPluginInitialize() {
    $this->getComponent('MediaBrowser')->registerCustomJs('modules/<component>/View/Script/MediaBrowser.js');
}

  3. Implement a JsonData adapter as provider for the view's data

  4. Inject view into MediaBrowser in modules/<component>/View/Script/MediaBrowser.js

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
    cx.ready(function() {
    angular.module('MediaBrowser')
    .config(["dataTabsProvider", function(dataTabsProvider) {
        dataTabsProvider
        .add({
            label: cx.variables.get(
                'TXT_MODULE_MYCOMPONENT', 'mediabrowser'),
            icon: 'icon-myicon',
            controller: 'MyCtrl',
            name: 'myview',
            templateUrl: cx.variables.get('basePath', 'contrexx') +
                'modules/<component>/View/Template/MyView.html',
            // force listing of tab in every section
            always: true
        });
    }])
    .service('MyService', ['$q',
        function($q) {
            return {
                refresh: refresh
        };
            function refresh() {
                var deferred = $q.defer();
                // fetch data from above implemented JsonData adapter
                cx.ajax('MyComponent','getEntries')
                .success(function(response) {
                    if (response.data instanceof Object) {
                        deferred.resolve(response.data);
                    } else if (response.match(/login_form/)) {
                        deferred.reject(cx.variables.get(
                            'TXT_FILEBROWSER_LOGGED_OUT', 'mediabrowser'));
                    } else {
                        deferred.reject("An error occured while fetching Entries");
                    }
                }).error(function() {
                    deferred.reject("An error occured while fetching Entries");
                });
                return deferred.promise;
            }
        }
    ])
    .controller('MyCtrl', [
        '$scope', 'mediabrowserConfig', 'MyService',
        function(
            $scope, mediabrowserConfig, MyService
        ) {
            $scope.dblclick = dblclick;
            if (!$scope.entriesLoaded) {
            MyService.refresh().then(function(entities) {
                    $scope.entriesLoaded = entities;
                    if ($scope.entriesLoaded) {
                        $scope.entries = $scope.entriesLoaded[cx.variables.get('language', 'mediabrowser')];
                    }
                });
            }
            function dblclick(entry) {
                var fn = mediabrowserConfig.get('callbackWrapper');
                if (typeof fn === 'function') {
                    fn({
                        type: 'MyEntry',
                        data: entry
                    });
                }
                $scope.closeModal();
            }
        }
    ]);
});

  5. Add template for view in modules/<component>/View/Template/Generic/MyView.html

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
    <div id="myview" ng-controller="MyCtrl">
    <div class="fileOptions">
        <input type="search" id="myFilter" class="searchterm"
            placeholder="{{::'TXT_FILEBROWSER_SEARCHTERM_PLACEHOLDER'| translate}}"
            ng-model="searchterm">
    </div>
    <div class="tabMediaBrowserContent contentWithOptions">
        <div class="mediaBrowserListCtrl">
            <div class="loadingPlatform" ng-hide="entries || error">
                <i class="icon-loading"></i>
                <div class="loadingText1">
                    Loading
                </div>
            </div>
            <table class="adminlist my-list-entries" ng-show="entries">
                <tbody>
                    <tr>
                        <th>
                            Entry
                        </th>
                    </tr>
                    <tr ng-repeat="entry in entries| filter: {name:searchterm}"
                        ng-class="{active: true === entry.active}"
                        ng-if="entries"
                        class="data-row files animation">
                        <td>
                            <a ng-dblclick="dblclick(entry)">
                                <div class="fileName">
                                    {{::entry.name}}
                                </div>
                            </a>
                        </td>
                    </tr>
                    <tr ng-show="error">
                        <td>
                            {{::'TXT_FILEBROWSER_ERROR_HAS_HAPPEND'| translate }}
                        </td>
                    </tr>
                </tbody>
            </table>
        </div>
    </div>
    <div class="tabMediaBrowserFooter">
        <button type="submit" class="btn btn-primary"
            ng-disabled="noFileSelected">
            {{::'TXT_FILEBROWSER_CHOOSE_FILE'| translate }}
        </button>
        <button type="submit" class="btn btn-primary"
            ng-click="cancel()">
            {{::'TXT_FILEBROWSER_CANCEL'| translate }}
        </button>
    </div>
</div>

  1. Is ignored if already set through PHP. ↩