Roulette - globules-io/OGX.JS GitHub Wiki

Roulette is a component used to display a list in an infinite way like a casino slot machine cylinder where fruits and symbols are displayed.

Group of Roulettes used in REWIND_MODE to make a vehicle selector

Extends

 Uxi, Touch

Requires

 List, Templater

 {"selector:Roulette":{CONFIG}}  

 let config = {
      el:_SELECTOR_,
      enabled:true|false, //default to true
      list:_ARRAY_, //Required, an array of strings or objects
      value:_CURRENT_VALUE_ //Required, the value to display at start
      key:_STRING_, //Optional
      display:_DISPLAY_OBJECT_ //Optional,
      mode:_CONSTANT_ //Optional,
      name:_STRING_ //Optional,
      required:_BOOLEAN_, //Optional, defaults to false
 };

To create from an OML node, from an object extending Uxi

 let node = {};
 node["#myDiv:Roulette"] = config;
 OGX.OML.render(this, OML);   

You can also create a Roulette on the fly, at runtime, from an object extending Uxi

 let roulette = this.create('Roulette', config);

or independently

 let roulette = OGX.Object.create('Roulette', config);

In any case, you can either set the current value via the config object, or via the data-value attribute of your container element. The attribute will be converted to value via the OGX.Data.stringToVal method then removed from the element.

 <div id="roulette" data-value="myValue"></div>

Roulette supports multiple data modes. You can pass a simple array of strings, such as

 {...,
      list:['HOME', 'WORK']
 }

but you can also use objects. In this case, the default property to display for each object is the label property. While the value is the value property, such as

 {...,
      list:[{label:'My house', value:'home'}, {label:'Soul beater', value:'work'}]
 }

In this case, only the label is rendered in the default template. Now, if you wish to display other information than the label of an object, you can use a custom display object, like the one used in OGX.DynamicList.

Let's pretend our list of objects look like this, and that we want to use the description field instead,

  {...,
      list:[{description:'My house', value:'home', zip:'12345'}, {description:'Soul beater', value:'work', zip:'66666'}]
  }

We need to set the key to description in the config, such as

  {...,
      key:'description',
      list:[{description:'My house', value:'home', zip:'12345'}, {description:'Soul beater', value:'work', zip:'66666'}]
  }

Now if we wanted to display one that one field, we should use a display object to tell the component what to render and where to render it

Roulette offers two roll modes, MODE_REWIND and MODE_CLOSEST. These modes only affect when setting the value through the val method. The prev and next methods are unaffected.

MODE_REWIND will make the component roll up/rewind if the new set value is lower in index in the list, no matter how far down the list is. Whereas, in MODE_CLOSEST, the component would scroll down completely to reach the beginning of the list again and then down to the value.

Roulette can also be used in a form. Use the name property to automatically create a hidden field with the name property as name attribute.

If you want to use a Roulette within a form, and have the form validate the Roulette as well, set the required flag to true

 roulette.disable();
 roulette.enable();

Get the current value

 let value = roulette.val();

Set the current value

 roulette.val(_VALUE_, _TRIGGER_); //Triggers a boolean, defaults to false

Make the component loop x times before displaying (and setting) the new value (like a slot machine)

 roulette.loopval(_LOOPS_, _VAL_, _TRIGGER_);  //Triggers a boolean, defaults to false

Set and render

 roulette.setData(_LIST_);

Previous or next

 roulette.prev(_BOOLEAN_); //Defaults to false, set to true if you want to trigger a OGX.Roulette.CHANGE event
 roulette.next(_BOOLEAN_); //Defaults to false, set to true if you want to trigger a OGX.Roulette.CHANGE event

Get the whole object instead of the values

 roulette.item();

OGX.Roulette.CHANGE          

 roulette.destroy();

To create an infinite looping roulette that display numbers from 1 to 10 and display 5

 let config = {el:'#myDIV', list:[{label:'01', value:1}, {label:'02', value:2}, ...], value:5);
 let roulette = new OGX.Roulette(config);