NestList - globules-io/OGX.JS GitHub Wiki

NestList is a component that generates nests (one per item) that can shrink or expend. It is also scope sensitive, meaning that it can display different containers based on its current scope (see scoping at the bottom).

Stack

Extends

 Uxi

Requires

 Templater

OML

 {"selector:NestList":{CONFIG}}

Create

NestList can also be created on the fly, at runtime

 let config = {
      el:_SELECTOR_ //requited, the HTML element where to instantiate this component
      scope:_ARRAY_ //optional, defaults to ['public']  
      list:_ARRAY_ //Array of items to display, depends on mode,
      map:_OBJECT_ //An optional map of properties (title, scope)
      order:_ARRAY_ //Optional, the preferred order of nests
 };

From an Object extending Uxi

 let list = this.create('NestList', config);

Independently

 let list = OGX.Object.create('NestList', config);

Data Format

Simple HTML content

NestList expects as data, an array of objects following this format.

 {title:_STRING_, scope:_ARRAY_, open:_BOOL_}

Ordering

NestList support order preference. Despite the fact that you can declare your data as a List and then sort it the way you want before you pass it to NestList, that order might become broken by adding/removing items to the NestList. So to make sure some nests always appear at the same position, you can enforce that positioning. For instance, if your data looks like this

 [
      {title:'NestA', body:'Some stuff', ...},
      {title:'NestB', body:'Some other stuff', ...}
 ]

but you want your NestList to always display NestsB on top, you can set the order flag in the config to

 {..., order:['NestB'], ...}

So even if you manipulate the list and remove NestB (which makes NestA the top one), then re-add by code a new NestB, that nest will always be on top. The nests that aren't defined in the order flag are added to the bottom of the list.

Enable/Disable

 list.enable();
 list.disable();

Get/Set

 list.val(_ARRAY_); //Set/Retrieve list of nests
 list.addNest(_CONFIG_, _NODE_, _INDEX_); //Add a nest given a config object, an OML node with default selector and optional index  
 list.removeNest(_NEST_TITLE_);
 list.replaceItem(_NEST_TITLE_, _NEW_OBJECT_)
 list.removeItem(_NEST_TITLE_); //Remove a nest and destroy its content
 list.updateItemHeight(_NEST_TITLE_); //Recompute the internal height of nest    
 list.scope(_ARRAY_); //set the current scope    
 list.updateHeight(_INDEX_); //Recalculate the height of a nested item given index

Events

 OGX.NestList.OPEN     //Triggered when the user opens an item
 OGX.NestList.CLOSE    //Triggered when the user closes an item
 OGX.NestList.READY,   //Triggered when the component has rendered

Destroy

 list.destroy();

Scoping

The component can display different containers based on scopes. To use scoping, you must set the current scope of the component in its config

 scope:['admin', 'finance']

meaning the component will display all containers that match the admin OR finance scope. If a node or container does not possess any of the scope, it won't display. You can of course update the scope of the component on the fly using setScope

Example

Here is an example of a configuration for the component.

 let config = {
      el:'#mydiv', 
      scope:['admin', 'finance'],
      list:[
           {title:'Permissions', body:'some html', scope:['admin'], open:false},
           {title:'Details', body:'some html', scope:['admin', 'hr'], open:true},
           {title:'Profile', body:'some html', scope:['admin', 'hr'], open:true}, 
           {title:'Rate', body:'some html', scope:['admin', 'finance'], open:true},              
           {title:'Stats', body:'some html', scope:['admin', 'hr'], open:true}, 
           {title:'Notes', body:'some html', scope:['admoin', 'hr'], open:false}
      ]
  }

  let list = this.create('NestList', config);