search

miguelcobain / ember-cli-selectize

An Ember and Selectize integration, packaged as an Ember-cli addon.
MIT License
151 stars 80 forks source link

readme

Ember-cli-selectize Build Status Ember Observer Score

NOTE: consider using ember-power-select

An Ember and Selectize integration, packaged as an Ember-cli addon. Check Selectize and Ember-cli!

Demo

Check (old demo): http://miguelcobain.github.io/ember-selectize

Installation

ember install ember-cli-selectize

Usage

This addon provides an ember-selectize component. Its usage should be very similar to Ember.Select, but with additional features.

{{ember-selectize
  content=controller.items
  optionValuePath="content.id"
  optionLabelPath="content.name"
  selection=model.item
  placeholder="Select an item" }}

Properties

Property Description
content Array containing all the options to select from
selection Ember-selectize will set this property to the selection that was made. Usually some property on a model, for example. If multiple is true, then it should be an array.
value Ember-selectize will set this property to the *value of the selection* that was made. It is not currently supported in multiple selection mode.
optionValuePath Selectize requires a unique hash for each option available. Set this to a path to such a property on your options. Prefix with content.. Example: content.id
optionLabelPath Set this to a path where selectize can get a label for display. Computed properties are many times useful for this. If Ember-selectize detects a "falsy" value, it will use an empty string. Example: content.name
plugins Set this to a comma delimited list of selectize plugins to override the default plugin selection (currently remove_button). Note, not all plugins have been tested to work with ember-cli-selectize, YMMV. Example: restore_on_backspace,drag_drop
placeholder or prompt Set any of these to display a text when there is no choice made. Example "Please select an option"
disabled If true disables changes in selectize
multiple If true ember-selectize will enter multiple mode. selection is an array of options.
sortField Pass a string of a property to sort by. You can also pass an array of objects [{ field: 'someProperty', direction: 'asc' }, {/*...*/}]. See selectize usage for details. Example: "name"
sortDirection If sortField is a string, specify the direction. Example: "asc" or "desc". This is ignored if sortField is an array (you can specify direction inside that array).
searchField If searchField is a string, it specifies what field should be searched on. It also accepts an array to search on multiple fields, e.g., ['label', 'value']. Defaults to 'label'.
filter This property will have the text that the user entered to filter options. Useful for searching options in server from a large set.
loading When true ember-selectize adds a loading class to selectize wrapper. Just like selectize does. Then you can customize. Useful with async relationships or "finds" in Ember-Data: loading=types.isPending.
optionFunction, itemFunction, optionCreateFunction, optgroupHeaderFunction, optgroupFunction Will be called on the component with two parameters data and escape. escape is a function to escape text. These functions are expected to build the desired html and return it as a string or DOM elements. These functions take precedence over their Component counterparts.
optionComponent, itemComponent, optionCreateComponent, optgroupHeaderComponent and optgroupComponent Render using components! Functions (see above) take precedence over components, so if you do strange things like setting optionFunction and optionComponent, the latter will be ignored. Inside your component and template data will contain the data for the current item being rendered. An example component could be Hi, {{data.firstname}}!
required If true adds required attribute

ember-selectize also supports selectize's general options, excluding options and items (equivalent to content and selection respectively).

Actions

Ember is moving towards a paradigm that encourages the use of actions. With this in mind, ember selectize provides a set of actions. The goal is to not use two way data bindings, that is, you pass the data to your components, but the components send actions up to let you (and only you) change the data. Here are the actions the ember selectize supports:

Action Description
create-item Sent when the user creates a tag. The text is sent as a parameter.
update-filter Sent when the user types in the input element (functional equivalent of observing filter property)
select-item / select-value Sent when the user selects an item (functional equivalent of observing selection property). The selected object is sent as a parameter. When the user deselects the option, parameter is null. `select-value` is identical, but gets the selected value passed in.
add-item / add-value sent when the user selects an item in multiple mode. The added object is sent as a parameter. `add-value` is identical, but gets the added value passed in.
remove-item / remove-value Sent when the user deselects an item in multiple mode. The removed object is sent as a parameter. `remove-value` is identical, but gets the removed value passed in.
on-focus Sent when the control gains focus.
on-blur Sent when the control loses focus.
on-init Sent once the control is completely initialized.
score Overrides the default score() method if a cutom one is passed as an option to the component.

Ember selectize supports both APIs.

More info:

We will folow Ember Select's approach, which is really flexible:

Option Groups

Ember-selectize supports two flavors of option grouping.

#1 optionGroupPath

Set optionGroupPath to a path for a property to group for. Example:

[
  {
    id: 1,
    category: 'Nature',
    title: 'This title will appear on select'
  },
  {
    id: 2,
    category: 'Nature',
    title: 'This title will appear on select'
  },
  {
    id: 3,
    category: 'Another category',
    title: 'This title will appear on select'
  },
  //...
]

optionGroupPath would be "content.category", which would group items according to that property automatically.

like

{{ember-selectize optionGroupPath="content.category"}}

#2 groupedContent

If you prefer you can group your items yourself and pass them to ember selectize. Just set the property groupedContent to an array with the following format:

[
  {
    label: 'Nature',
    content: [
      {
        id: 1,
        title: 'This title will appear on select'
      },
      {
        id: 2,
        title: 'This title will appear on select'
      }
    ]
  },
  {
    label: 'Another category',
    content: [
      //...
    ]
  },
//...
]

and in your template

{{ember-selectize groupedContent=someArray}}

Theme customization

You can customize which theme to use in your Brocfile.

//your-app/Brocfile.js

var EmberApp = require('ember-cli/lib/broccoli/ember-app');

var app = new EmberApp({
  'ember-cli-selectize': {
    //valid values are `default`, `bootstrap2`, `bootstrap3` or false
    'theme': 'bootstrap3'
  }
});

module.exports = app.toTree();

If you want to use the default theme, you don't need to specify any option. If you don't want to include any css at all for some reason, simply assign false or any "falsy" value to the theme option.

Running

Running Tests

Building

For more information on using ember-cli, visit https://ember-cli.com/.