Upgrade Guide

Upgrading from 0.13.x to 1.0.0

We wrote this guide to help you to upgrade from Chico UI 0.13.x to Chico UI 1.0.0.

Our APIs have been redesigned, following these goals:

Reuse our code: Mobile + Desktop!
Extend our components (using prototypal inheritance).
Add performance improvements.
Be Modular.

Core (ch)

Removed ch.cache object.
Removed ch.debug() method.
Removed ch.version property.
Removed ch.instances collection.
Removed ch.blink method.
Removed ch.keyboard; use ch.shortcuts.
Removed ch.Widget class; use ch.Component.
Removed ch.Controls class.
Removed ch.Floats class; use ch.Popover.
Removed ch.events; use the followings properties: ch.onchangelayout, ch.onkeybackspace, ch.onkeydownarrow, ch.onkeyenter, ch.onkeyesc, ch.onkeyinput, ch.onkeyleftarrow, ch.onkeyrightarrow, ch.onkeytab, ch.onkeyuparrow, ch.onpointerdown, ch.onpointerenter, ch.onpointerleave, ch.onpointermove, ch.onpointertap, ch.onpointerup, ch.onresize, ch.onscroll

ch.support

Removed ch.support.fixed.
Added ch.support.fx.
Added ch.support.touch.

ch.util

Removed ch.util.hasOwn() method.
Removed ch.util.inDom() method.
Removed ch.util.index property.
Removed ch.util.isSelector() method.
Removed ch.util.isTag() method.
Removed ch.util.use() method.
Added ch.util.getOffset(el) method.
Added ch.util.getOuterDimensions(el) method.
Added ch.util.getScroll(el) method.

ch.Positioner

### Options

Removed reposition option.
Removed element option; use target.
Removed context option; use reference.
Removed points option; use side and align.
Removed offset option; use offsetX and offsetY.
Added positioned option.

Methods

Added refresh() method (standalone version).
Removed position('refresh') from Popovers; use refreshPosition().

Example

Old

ch.Positioner({
    'element': '#element',
    'context': '#context',
    'points': 'lt rt',
    'offset': '10 0'
});

New

new ch.Positioner({
    'target': $('#element'),
    'reference': $('#reference'),
    'offsetX': 10,
    'offsetY': 0,
    'side': 'center',
    'align': 'center',
    'positioned': 'fixed'
});

ch.Content

We updated the content(options) ability to content(content, [options]).

Parameters

Added content parameter.

AJAX.

component.content('http://www.some-url.com');

Plain text.
```
component.content('Some plain text.');
```

HTML Element.

var paragraph = document.createElement('p');

paragraph.innerHTML = 'Some text';

component.content(paragraph);

Query Selector.

Old

component.content('#element');

New

component.content($('#element'));

Added options (optional) parameter.

// Use only with AJAX content
component.content('http://www.some-url.com',  {
    'method': 'POST',
    'params': 'x-request=true',
    'cache': false,
    'async': true,
    'waiting': '<div class="ch-loading-big"></div>'
});

Events

Removed contentLoad event; use contentdone.
Removed contentError event; use contenterror.
Added contentwaiting event.

ch.Viewport

The viewport has been redesigned to ease viewport management.

### Properties

Removed element property; use $el.
Added orientation property.

Methods

Removed getOffset() method; use calculateOffset().
Removed getSize() method; use calculateDimensions().
Removed getPosition() method; use offsetTop, offsetBottom, offsetRight or offsetLeft options.
Added calculateOrientation() method.
Added inViewport() method.
Added isVisible() method.
Added refresh() method.
Added ch.EventEmitter methods: on(), once(), off(), emit(), listener().

Events

Added ch.onresize event.
Added ch.onscroll event.

ch.Calendar

Options

Removed onSelect option; suscribe to the select event.
```
calendar.on('select', function () {...});
```
Removed onNextMonth option; suscribe to the nextmonth event.
```
calendar.on('nextmonth', function () {...});
```
Removed onPrevMonth option; suscribe to the prevmonth event.
```
calendar.on('prevmonth', function () {...});
```
Removed onNextYear option; suscribe to the nextyear event.
```
calendar.on('nextyear', function () {...});
```
Removed onPrevYear option; suscribe to the prevyear event.
```
calendar.on('prevyear', function () {...});
```

Properties

Removed type property; use name.
Removed element property; use $container.

Methods

Removed reset() method.
Removed today() method; use getToday().
Removed to() method; use setTo().
Removed from() method; use setFrom().
Removed next() method; use nextMonth() or nextYear() methods.
Removed prev() method; use prevMonth() or prevYear() methods.
Removed trigger() method; use emit().
Added getListeners() method.
Added require() method.
Added destroy() method.
Added enable() method.
Added disable() method.

Events

Added nextmonth event.
Added nextyear event.
Added prevmonth event.
Added prevyear event.

ch.Countdown

Properties

Removed type property; use name.
Removed element property; use $trigger.
Added $container property.

Methods

Removed trigger() method; use emit().
Added getListeners() method.
Added require() method.
Added destroy() method.
Added enable() method.
Added disable() method.

Events

Added exceed event.

ch.Datepicker

### Options

Removed onSelect option; suscribe to the select event.
```
datepicker.on('select', function () {...});
```
Removed points option; use side and align.
Removed closable option; use hiddenby.
Added positioned option.
Added offsetX option.

Added offsetY option.

Old

$('#element').datepicker({
    'closable': 'click',
    'points': 'lt lt'
});

New

$('#element').datepicker({
    'hiddenby': 'pointers-only',
    'side': 'bottom',
    'align': 'center'
});

Properties

Removed type property; use name.
Removed element property; use $field.
Added $trigger property.

Methods

Removed trigger() method; use emit().
Removed prev() method; use prevMonth() or prevYear().
Removed next() method; use nextMonth() or nextYear().
Added getListeners() method.
Added require() method.
Added destroy() method.
Added enable() method.
Added disable() method.

Events

Added show event.
Added hide event.
Added reset event.
Added nextmonth event.
Added nextyear event.
Added prevmonth event.
Added prevyear event.

ch.Expandable

### Options

Removed open option.
Removed onShow option; suscribe to the show event.
```
expandable.on('show', function () {...});
```
Removed onHide option; suscribe to the hide event.
Added toggle option.
Added content option.
Added container option.

Old

$('#element').expandable({
    'open': true
});

New

$('#element').expandable().show();

$('#element').expandable({
    'toggle': true,
    'content': 'Some content!',
    'container': $('#container')
});

Properties

Removed element property; use $trigger.
Removed type property; use name.
Added $container property.

Methods

Removed isActive() method; use isShown().
Removed trigger() method; use emit().
Added getListeners() method.
Added require() method.
Added destroy() method.
Added enable() method.
Added disable() method.
Added content() method.

Events

Removed contentLoad event; use contentdone.
Removed contentError event; use contenterror.
Added contentloading event.

ch.Popover

Previously known as ch.Floats. It includes ch.Layer, ch.Modal, ch.Tooltip, ch.Transition, ch.Zoom and add the new component ch.Bubble (used for validation errors).

The Floats were redesigned as Popover to be the basic unit of a dialog window. It can be instantiated as a generic component too. Components that inherits from Popover, just adds specific functionality. For example, a Modal window shows and hides an underlay.

Popover also has the ability to be instantiated without the need of an existent element. It means you no longer need to create an element in memory (usually implemented with an <a> tag) to create a component:

Old way

$('<a>').modal();

New way

$.modal();

Options

Removed reposition option.

Removed onShow option; suscribe to the show event.

$('#element').layer().on('show', function () {});

Removed onHide option; suscribe to the hide event.

$('#element').layer().on('hide', function () {});

Removed onContentLoad option; suscribe to the contentdone event.
```
$('#element').layer().on('contentdone', function () {});
```
Removed onContentError option; suscribe to the contenterror event.
```
$('#element').layer().on('contenterror', function () {});
```
Removed classes option; use addClass.
Removed points option; use side and align.
Removed offset option; use offsetX and offsetY.
Removed event option; use shownby. The possible values are: shownby: 'pointertap' instead of event: 'click' (default), shownby: 'pointerenter' instead of event: 'hover' or shownby: 'none'
Removed closable option; use hiddenby.
Removed closeButton option; the Close button appears with 'hiddenby': 'button-only' or 'hiddenby': 'all' options.
Updated fx:Boolean option; use fx:Boolean || String.
Updated width:Number || String option; use width:String.
Updated height:Number || String option; use height:String.
Added positioned option.
Added waiting option.

Old

$('#element').layer({
    'classes': 'test',
    'points': 'lt lb',
    'offset': '0 10',
    'event': 'click',
    'closable': 'button',
    'closeButton': true,
    'fx': true,
    'width': 100,
    'height': 50
});

New

$('#element').layer({
    'addClass': 'test',
    'side': 'bottom',
    'align': 'left',
    'offsetX': 0,
    'offsetY': 10,
    'shownby': 'pointerenter',
    'hiddenby': 'button',
    'fx': 'fadeIn',
    'width': '100px',
    'height': '50px',
    'positioned': 'absolute',
    'waiting': '<div class="ch-loading ch-loading-centered"></div>'
});

Properties

Removed element property; use $trigger.
Removed type property; use name.
Added $container property.

Methods

Removed closable() method.
Removed trigger() method; use emit().
Removed isActive() method; use isShown().
Removed position() method; use refreshPosition(). By using when the component is hidden, it will refresh the position. Using when the component is shown, it will reconfigure the position.
Updated width(Number || String) parameters; use width(String).
Updated height(Number || String) parameters; use height(String).
Added init() method.
Added enable() method.
Added destroy() method.
Added disable() method.
Added getListeners() method.
Added require() method.
Added constructor() method.

Events

Removed contentLoad event; use contentdone.
Removed contentError event; use contenterror.
Added contentwaiting event.

ch.Dropdown

The Dropdown was redesigned to share most of its code (and its public API) with components with similar behavior. That's why now it's part of ch.Popover.

Options

Removed open option.
Removed icon option.

Removed reposition option; reposition manually using the method inViewport() in ch.Viewport and use this CSS for upwards Dropdown:

.ch-dropdown[data-side="top"] {
    border-radius: 5px 5px 5px 0px;
}

.ch-dropdown-trigger-on[data-side="top"],
.ch-dropdown-trigger-on[data-side="top"]:hover {
    border-radius: 0 0 3px 3px;
}

Removed onShow option; suscribe to the show event.

$('#element').dropdown().on('show', function () {});

Removed onHide option; suscribe to the hide event.

$('#element').dropdown().on('hide', function () {});

Removed points option; use side and align.
Updated fx:Boolean option; use fx:Boolean || String.
Added addClass option.
Added offsetX and offsetY.
Added shownby option. The possible values are: shownby: 'pointertap' (default), shownby: 'pointerenter' or shownby: 'none'
Added hiddenby option.
Added skin option. This replaces the old way of instantiate a Dropdown skin, where you added the CSS class ch-dropdown-skin to the main HTML element.
Added shortcuts option.
Added width option.
Added height option.
Added positioned option.
Added waiting option.

Old

$('#element').dropdown({
    'open': false,
    'icon': true,
    'reposition': true,
    'points': 'lt lb',
    'fx': false
});

New

$('#element').dropdown({
    'side': 'bottom',
    'align': 'left',
    'fx': 'fadeIn',
    'offsetX': 0,
    'offsetY': 10,
    'shownby': 'pointerenter',
    'hiddenby': 'pointerleave',
    'skin': true,
    'shortcuts': true,
    'width': '100px',
    'height': '50px',
    'positioned': 'absolute',
    'waiting': '<div class="ch-loading ch-loading-centered"></div>'
});

Properties

Removed element property; use $trigger.
Removed type property; use name.
Added $container property.

Methods

Removed trigger() method; use emit().
Removed isActive() method; use isShown().
Removed position() method; use refreshPosition().
Added init() method.
Added enable() method.
Added destroy() method.
Added disable() method.
Added getListeners() method.
Added require() method.
Added constructor() method.
Added width method.
Added height method.
Added content method.

Events

Added contentdone event.
Added contenterror event.
Added contentwaiting event.

ch.Carousel

Options

Removed page option.
Removed width option; it's an adaptive component, so set a width in CSS for the element that wraps the Carousel in your layout.

Removed onNext option; suscribe to the next event.

$('#element').carousel().on('next', function () {});

Removed onPrev option; suscribe to the prev event.

$('#element').carousel().on('prev', function () {});

Removed onRedraw option; suscribe to the redraw event.

$('#element').carousel().on('redraw', function () {});

Removed onSelect option; suscribe to the select event.

$('#element').carousel().on('select', function () {});

Removed onItemsAdded option; suscribe to the itemsadd event.

$('#element').carousel().on('itemsadd', function () {});

Removed asyncData and asyncRender options; use async option and itemsadd event:

$('#element').carousel({
    'async': 10
}).on('itemsadd', function ($items) {
    // Inject content into the added <li> elements
    $.each($items, function (i, e) {
        $(e).html('Content into one of newly inserted <li> elements.');
    });
});

Removed maxItems option; use limitPerPage.
Updated arrows:String option; use arrows:Boolean. Now, when there is no arrows, you should handle the mask margin with CSS:
```
.my-own-carousel .ch-carousel-mask {
    margin: 0;
}
```

Old

$('#element').carousel({
    'width': 300,
    'page': 2,
    'asyncData': ['First', 'Second', 'Third'],
    'asyncRender': function (a) { return a + 'element'; },
    'maxItems': 2,
    'arrows': 'over'
});

New

$('#element').carousel({
    'async': 3, // Use 'itemsadd' events to inject content into the new <li> elements
    'limitPerPage': 2,
    'arrows': false
});

Properties

Removed type property; use name.
Removed element property.

Methods

Removed arrows() method.
Removed page() method.
Removed itemsPerPage() method.
Removed play() and pause() methods; use the extension ch.carousel.autoSliding.js from the /extension folder in repository.
Removed redraw() method; use refresh().
Removed trigger() method; use emit().
Added init() method.
Added enable() method.
Added destroy() method.
Added disable() method.
Added getListeners() method.
Added require() method.
Added constructor() method.

Events

Removed redraw event; use refresh.
Removed itemsAdded event; use itemsadd.

ch.Tabs

### Options

Removed onSelect option; suscribe to the select event.
```
tabs.on('select', function () {...});
```
Removed onContentLoad option; suscribe to the contentdone event.
```
tabs.on('contentdone', function () {...});
```
Removed onContentError option; suscribe to the contenterror event.
```
tabs.on('contenterror', function () {...});
```
Removed selected option.

Properties

Removed element property; use $container.
Removed children collection; use tabpanels.
Removed type property; use name.
Added $panel property.
Added $triggers property.

Methods

Removed isActive() method; use isShown().
Removed trigger() method; use emit().
Removed select() method; use show().
Added getListeners() method.
Added require() method.
Added destroy() method.
Added enable() method.
Added disable() method.
Added content() method.
Added getShown() method.

Events

Removed contentLoad event; use contentdone.
Removed contentError event; use contenterror.
Added contentloading event.
Added select event.

ch.Menu

### Options

Removed onSelect option; suscribe to the select event.
```
menu.on('select', function () {...});
```
Removed selected option.

Properties

Removed element property; use $container.
Removed type property; use name.
Added fold collection.

Methods

Removed trigger() method; use emit().
Removed select() method; use show().
Added getListeners() method.
Added require() method.
Added destroy() method.
Added enable() method.
Added disable() method.
Added content() method.
Added hide() method.

ch.Form

The ch.Form API has been redesigned to easy manipulation. Now, you have more control on the submit event and you decide what you want to do.

Options

Removed beforeSubmit option.
Removed afterSubmit option.
Removed afterValidate option.
Removed beforeValidate option; suscribe to the beforevalidate event.
```
form.on('beforevalidate', function () {...});
```
Removed onValidate option; suscribe to the success event.
```
validation.on('success', function () {...});
```
Removed onError option; suscribe to the error event.
```
validation.on('error', function () {...});
```
Removed onClear option; suscribe to the clear event.
```
validation.on('clear', function () {...});
```
Removed onReset option; suscribe to the reset event.
```
validation.on('reset', function () {...});
```

Properties

Removed messages property.
Removed element property; use $container.
Removed type property; use name.
Removed children collection; use validations.
Added errors collection.

Methods

Removed submit() method.
Removed trigger() method; use emit().
Removed isValidated() method; use hasError().
Added getListeners() method.
Added require() method.
Added destroy() method.
Added enable() method.
Added disable() method.

Events

Removed beforeSubmit, afterSubmit and submit events. Use native event:

Old

form.on('beforeSubmit', function () {...});
form.on('submit', function () {...});
form.on('afterSubmit', function () {...});

New

$('.myForm').on('submit', function (event) {
    
    // Some code here!
    
    if (!form.hasError()) {
        event.preventDefault();

        // Some code here!
    }
});

Removed afterValidate event.

Removed validate event; use success.

form.on('success', function (event) {
    event.preventDefault();

    // Some code here!
});

Removed beforeValidate event; use beforevalidate.
Updated error event; it now receives a collection with errors:
```
form.on('error', function (errors) {...});
```

Old events timeline

Old events

New events timeline

New events

ch.Validation

The ch.Validation API has been redesigned to easy manipulation. You can use validations interfaces: ch.Custom, ch.Required, ch.String, ch.Email, ch.Url, ch.MaxLength, ch.MinLength, ch.Number, ch.Max and ch.Min.

Removed ch.Price

Options

Removed classes option.
Removed beforeValidate option.
Removed afterValidate option.
Removed beforeValidate option; suscribe to the beforevalidate event.
```
validation.on('beforevalidate', function () {...});
```
Removed onValidate option; suscribe to the success event.
```
validation.on('success', function () {...});
```
Removed onError option; suscribe to the error event.
```
validation.on('error', function () {...});
```
Removed onClear option; suscribe to the clear event.
```
validation.on('clear', function () {...});
```

Removed content option; use message.

$('#element').required({
    'message': 'Some message!'
})

Removed condition option; use conditions.
Removed context option; use reference.
Removed points option; use side and align.
Removed offset option; use offsetX and offsetY.

Old

$('#element').validation({
    'condition': {
        'name': 'required'
    },
    'context': '#context',
    'points': 'lt rt',
    'offset': '10 0'
});

New

$('#element').validation({
    'conditions': [
        {
            'name': 'required'
        },
        {
            'name': 'custom-name',
            'fn': function (value) { return value === "custom";},
            'message': 'This is a custom validation.'
        }
    ],
    'reference': $('#reference'),
    'offsetX': 10,
    'offsetY': 0,
    'side': 'left',
    'align': 'top'
});

Properties

Removed validatorproperty.
Removed element property; use $trigger.
Removed helper property; use bubble.
Removed float property; use bubble.
Removed type property; use name.
Added error property.
Added conditions property.

Methods

Removed toggleEnable() method.
Removed isActive() method; use isShown().
Removed float.position() method; use bubble.refreshPosition().
Removed trigger() method; use emit().
Added getListeners() method.
Added require() method.
Added destroy() method.

Events

Removed beforeValidate event.

Removed validated event; use success.

validation.on('success', function () {...});

Removed afterValidate event.

ch.Custom

The ch.Custom API has been redesigned to create and manipulate multiple custom validations instance with the same trigger. Now, you should give a name to your custom validations.

Old

$('#element').custom(function (value) {
    return value === 'Something';
}, 'This is a custom Validation!');

New

$('#element').custom('some-name', function (value) { 
    return value === 'Something';
}, 'This is a custom Validation!');

ch.AutoComplete

Options

Removed url.
Removed content.
Removed suggestions.
Removed jsonpCallback.
Removed points option; use side and align.

Example

Old

var ac = $('.example').autoComplete({
    'url': 'http://www.chico-ui.com.ar/suggest?q=',
    'jsonpCallback': 'autoComplete'
});

function autoComplete(data) {
        ac.suggest(data);
}

New

var ac = $('.example').autoComplete();

ac.on('type', function (userInput) {
    $.ajax({
        'url': 'http://www.chico-ui.com.ar/suggest?q=' + userInput + '&callback=ac.suggest',
        'dataType': 'jsonp',
        'cache': false,
        'global': true,
        'context': window,
        'jsonp': 'ac.suggest',
        'crossDomain': true
    });
});

Example with the MercadoLibre API

var mercadolibre = $('.autoComplete3').autoComplete();

var parseMLAPIResults = function (results) {
    var data = [];
    results[2].suggested_queries.forEach(function (e, i) {
        data.push(e.q);
    });

    mercadolibre.suggest(data);
}

mercadolibre.on('type', function (userInput) {
     $.ajax({
         'url': 'http://suggestgz.mlapps.com/sites/MLA/autosuggest?q='+ userInput +'&v=1&callback=parseMLAPIResults',
         'dataType': 'jsonp',
         'cache': false,
         'global': true,
         'context': window,
         'jsonp': 'parseMLAPIResults',
         'crossDomain': true
     });
});

Events

Added type

CSS

Messages boxes

To expand the messages boxes variety, now you have to include the icon by yourself and the CSS class name ch-box-icon to the container:

Example

Old

<div class="ch-box-error">Oops, something wrong happened</div>

New

<div class="ch-box-icon ch-box-error"><i class="ch-icon-remove-sign"></i>Oops, something wrong happened</div>

Upgrade Guide

Upgrading from 0.13.x to 1.0.0

Contents

Core (ch)

ch.support

ch.util

ch.Positioner

Methods

Example

Old

New

ch.Content

Parameters

Old

New

Events

ch.Viewport

Methods

Events

ch.Calendar

Options

Properties

Methods

Events

ch.Countdown

Properties

Methods

Events

ch.Datepicker

Old

New

Properties

Methods

Events

ch.Expandable

Old

New

Properties

Methods

Events

ch.Popover

Old way

New way

Options

Old

New

Properties

Methods

Events

ch.Dropdown

Options

Old

New

Properties

Methods

Events

ch.Carousel

Options

Old

New

Properties

Methods

Events

ch.Tabs

Properties

Methods

Events

ch.Menu

Properties

Methods

ch.Form

Options

Properties

Methods

Events

Old

New

Old events timeline

New events timeline

ch.Validation