Skip to main content

Additions

UI Additions are used to bind a specific behaviour to dom elements marked with a specific selector. The autosize addition for example is bound to all textareas with an .autosize class attribute and enables an automatic resize of the textarea.

UI Additions are automatically applied on full or pjax page loads. In case you need to apply additions to other dom elements you can manually apply additions.

Register Additions

New additions can be registered by calling the ui.additions.register() method as follows

require('ui.additions').register('toggle', '.toggle', function($match) {
$match.on('click', function() {
$(this).toggle();
});
});

In this example we added a toggle addition which will be applied to all nodes with a .toggle class selector.

Note: custom additions should be registered within your modules init function, in this case your addition will be automatically be applied within the initialization phase.

Tip: You should only add new additions in case they are used regularly within your application, since each new addition will add an additional selector search to your initialization process.

Register Addition without selector (since v1.4)

It is also possible to register additions without a selector as in the following example:

require('ui.additions').register('someAddition', function($match) {
$match.on('click', function() {
$(this).toggle();
});
});

The actual selector for such an addition would be [data-ui-addition="someAddition"].

Note: This way of defining additions is preferred since we save additional addition queries.

Extend Additions:

The register method also accepts an optional options parameter after the handler function, which can be used to extend already registered additions.

The following options are available:

  • extend can be used to extend an existing addition by either adding a handler or adding a selector, if this option is not set a registration call for an already registered addition will be ignored.
  • prepend will prepend the new handler to the addition handler chain in case of an extend call if set to true

Our previous toggle addition can be extended as follows

additions.register('toggle', '.toggle', function($match) {
$match.on('dblclick', function() {
// some other handler...
});
}, {extend: true});

// or
additions.extend('toggle', '.toggle', function($match) { /* ... */ });

Manually apply Additions

By default the document body will be parsed for additions within the humhub initialization phase. If you require to apply additions to nodes inserted after the initialization phase e.g. nodes loaded by ajax, you'll either have to call the applyTo() function on your new nodes as

client.get(url).then(function(response) {
$('#myContainer').html(response.output);
additions.applyTo($('#myContainer'));
}).catch(function(e) {
module.log.error(e,true);
});

or add a MutationObserver to your container as follows

additions.observe($('#myContainer'));

Info: You won't have to worry about the applying of additions when using the modal or stream API .

You can also just apply specific additions by using the apply options filter:

    // only apply the toggle addition to #myContainer
additions.applyTo($('#myContainer'), {
include: ['toggle']
});

// or respectively
additions.observe($('#myContainer'), {
include: ['toggle']
});

Core Additions

  • autosize - .autosize: adds the autosize behaviour to textarea fields
  • select2 - [data-ui-select2]: transforms a dropdown to a select2 dropdown
  • tooltip - .tt: adds an jQuery tooltip to the element on hover
  • popover - .po: adds the bootstrap popover behaviour to the given elements
  • form_elements, :checkbox, :radio: renders styled radiobuttons and checkboxes
  • showMore, [data-ui-show-more]: used for cutting long texts (e.g in stream entries)
  • ui.widget, [data-ui-init]: used for widgets with eager initialization

Further Addition Features

  • switchButtons can be called to switch to buttons with a bounceIn effect
// simple switch with bounceIn animation accepts either an selector or node or jQuery instance
additions.switchButtons('#hideMe', '#showMe');

// change animation
additions.switchButtons('#hideMe', '#showMe', {'animation': 'fadeIn'});

// remove the old button afterwards
additions.switchButtons('#hideMe', '#showMe', {'remove': true});
  • highlight adds an background highlight animation to a node
// accepts either an string selector or node or jQuery instance
additions.highlight('#myTextNode');