Picker

Picker is a powerful component that allows you to create custom overlay pickers which looks like iOS native picker.

Picker could be used as inline component or as overlay. Overlay Picker will be automatically converted to Popover on tablets (iPad).

Create Picker Instance

Picker can be created and initialized only using JavaScript. We need to use related App's method:

myApp.picker(parameters) - initialize Picker with parameters

  • parameters - object - object with Picker parameters. Required.
  • Method returns initialized Picker instance

For example:

var myPicker = app.picker({
    input: '#picker-input'
    cols: [
       {
         values: ['Apple', 'Orange', 'Bananna']
       }
     ]
});   
myPicker.open(); // open Picker

Picker Parameters

Let's look on list of all available parameters:

Parameter Type Default Description
Common Picker Modal Component Parameters
container string or HTMLElement String with CSS selector or HTMLElement where to place generated Picker HTML. Use only for inline pickers
input string or HTMLElement String with CSS selector or HTMLElement with related input element
scrollToInput boolean true Scroll viewport (page-content) to input when picker opened
inputReadOnly boolean true Sets "readonly" attribute on specified input
convertToPopover boolean true Converts picker modal to Popover on large screens (on iPad)
onlyOnPopover boolean false Enable it and Picker will be always opened in Popover
cssClass string Additional CSS class name to be set on picker modal
closeByOutsideClick boolean true If enabled, picker will be closed by clicking outside of picker or related input element
toolbar boolean true Enables picker modal toolbar
toolbarCloseText string 'Done' Text for Done/Close toolbar button
toolbarTemplate string Toolbar HTML Template. By default it is HTML string with following template:
<div class="toolbar">
  <div class="toolbar-inner">
    <div class="left"></div>
    <div class="right">
      <a href="#" class="link close-picker">{{closeText}}</a>
    </div>
  </div>
</div> 
Specific Picker Parameters
rotateEffect boolean false Enables 3D rotate effect
momentumRatio number 7 Larger values produces more momentum when you release picker after fast touch and move
updateValuesOnMomentum boolean false Updates picker and input values during momentum
updateValuesOnTouchmove boolean true Updates picker and input values during touch move
value array Array with initial values. Each array item represents value of related column
formatValue function (p, values, displayValues) Function to format input value, should return new/formatted string value. values and displayValues are arrays where each item represents value/display value of related column
cols array Array with columns. Each array item represents object with column parameters
Callbacks
onChange function (p, values, displayValues) Callback function that will be executed when picker value changed. values and displayValues are arrays where each item represents value/display value of related column
onOpen function (p) Callback function that will be executed when picker is opened
onClose function (p) Callback function that will be executed when picker is closed

Column parameters

When we configure Picker we need to pass cols parameter. It is an array where each item is object with column parameters:

Parameter Type Default Description
values array Array with string columns values
displayValues array Array with string columns values that will be displayed in Picker. If not specified, it will display values from values parameter
cssClass string Additional CSS class name to be set on column HTML container
textAlign string Text alignment of column values, could be "left", "center" or "right"
width number Column width in px. Useful if you need to fix column widths in picker with dependent columns. By default, calculated automatically
divider boolean false Defines column that should be used as a visual divider, that doesn't have any values
content string Should be specified for divider-column (divider:true) with content of the column
Callbacks
onChange function (p, value, displayValue) Callback function that will be executed when column value changed. value and displayValue represent current column value and displayValue

Picker Methods & Properties

After we initialize Picker we have its initialized instance in variable (like myPicker variable in example above) with helpful methods and properties:

Properties
myPicker.params Object with passed initialization parameters
myPicker.value Array where each item represents current selected value for each column
myPicker.displayValue Array where each item represents current selected display value for each column
myPicker.opened true if Picker is currently opened
myPicker.inline true if Picker is inline Picker
myPicker.cols Array with specified Picker columns. Each column also has its own methods and properties (look below)
myPicker.container Dom7 instance with Picker HTML container
Methods
myPicker.setValue(values, duration) Set new picker value. values is array where each item represents value for each column. duration - transition duration in ms
myPicker.open() Open Picker
myPicker.close() Close Picker
myPicker.destroy() Destroy Picker instance and remove all events

Column Methods & Properties

Each column in myPicker.cols array also has its own useful methods and properties.

//Get first column
var col = myPicker.cols[0];
Properties
col.container Dom7 instance with column HTML container
col.items Dom7 instance with column items HTML elements
col.value Currently selected column value
col.displayValue Currently selected column display value
col.activeIndex Index number of currently selected/active item
Methods
col.setValue(value, duration) Set new value for current column. value is a new value, duration - transition duration in ms
col.replaceValues(values, displayValues) Replace column values and displayValues with new ones

Access to Picker's Instance

If you initialize Picker as inline Picker it is possible to access to Picker's instance from its HTML container

var myPicker = $$('.picker-inline')[0].f7Picker;

Examples

Picker With Single Value

<div class="content-block-title">Picker with single value</div>
<div class="list-block">
  <ul>
    <li>
      <div class="item-content">
        <div class="item-inner">
          <div class="item-input">
            <input type="text" placeholder="Your iOS device" readonly id="picker-device">
          </div>
        </div>
      </div>
    </li>
  </ul>
</div> 
var pickerDevice = myApp.picker({
    input: '#picker-device',
    cols: [
        {
            textAlign: 'center',
            values: ['iPhone 4', 'iPhone 4S', 'iPhone 5', 'iPhone 5S', 'iPhone 6', 'iPhone 6 Plus', 'iPad 2', 'iPad Retina', 'iPad Air', 'iPad mini', 'iPad mini 2', 'iPad mini 3']
        }
    ]
});

Two Values and 3D-Rotate Effect

<div class="content-block-title">2 values and 3d-rotate effect</div>
<div class="list-block">
  <ul>
    <li>
      <div class="item-content">
        <div class="item-inner">
          <div class="item-input">
            <input type="text" placeholder="Describe yourself" readonly id="picker-describe">
          </div>
        </div>
      </div>
    </li>
  </ul>
</div>  
var pickerDescribe = myApp.picker({
    input: '#picker-describe',
    rotateEffect: true,
    cols: [
        {
            textAlign: 'left',
            values: ('Super Lex Amazing Bat Iron Rocket Lex Cool Beautiful Wonderful Raining Happy Amazing Funny Cool Hot').split(' ')
        },
        {
            values: ('Man Luthor Woman Boy Girl Person Cutie Babe Raccoon').split(' ')
        },
    ]
});                

Dependent Values

<div class="content-block-title">Dependent values</div>
<div class="list-block">
 <ul>
   <li>
     <div class="item-content">
       <div class="item-inner">
         <div class="item-input">
           <input type="text" placeholder="Your car" readonly id="picker-dependent">
         </div>
       </div>
     </div>
   </li>
 </ul>
</div>
         
var carVendors = {
    Japanese : ['Honda', 'Lexus', 'Mazda', 'Nissan', 'Toyota'],
    German : ['Audi', 'BMW', 'Mercedes', 'Volkswagen', 'Volvo'],
    American : ['Cadillac', 'Chrysler', 'Dodge', 'Ford']
};
var pickerDependent = myApp.picker({
    input: '#picker-dependent',
    rotateEffect: true,
    formatValue: function (picker, values) {
        return values[1];
    },
    cols: [
        {
            textAlign: 'left',
            values: ['Japanese', 'German', 'American'],
            onChange: function (picker, country) {
                if(picker.cols[1].replaceValues){
                    picker.cols[1].replaceValues(carVendors[country]);
                }
            }
        },
        {
            values: carVendors.Japanese,
            width: 160,
        },
    ]
});

Custom toolbar

<div class="content-block-title">Custom toolbar</div>
<div class="list-block">
 <ul>
   <li>
     <div class="item-content">
       <div class="item-inner">
         <div class="item-input">
           <input type="text" placeholder="Describe yourself" readonly id="picker-custom-toolbar">
         </div>
       </div>
     </div>
   </li>
 </ul>
</div> 
var pickerCustomToolbar = myApp.picker({
    input: '#picker-custom-toolbar',
    rotateEffect: true,
    toolbarTemplate: 
        '<div class="toolbar">' +
            '<div class="toolbar-inner">' +
                '<div class="left">' +
                    '<a href="#" class="link toolbar-randomize-link">Randomize</a>' +
                '</div>' +
                '<div class="right">' +
                    '<a href="#" class="link close-picker">That\'s me</a>' +
                '</div>' +
            '</div>' +
        '</div>',
    cols: [
        {
            values: ['Mr', 'Ms'],
        },
        {
            textAlign: 'left',
            values: ('Super Lex Amazing Bat Iron Rocket Lex Cool Beautiful Wonderful Raining Happy Amazing Funny Cool Hot').split(' ')
        },
        {
            values: ('Man Luthor Woman Boy Girl Person Cutie Babe Raccoon').split(' ')
        },
    ],
    onOpen: function (picker) {
        picker.container.find('.toolbar-randomize-link').on('click', function () {
            var col0Values = picker.cols[0].values;
            var col0Random = col0Values[Math.floor(Math.random() * col0Values.length)];
 
            var col1Values = picker.cols[1].values;
            var col1Random = col1Values[Math.floor(Math.random() * col1Values.length)];
 
            var col2Values = picker.cols[2].values;
            var col2Random = col2Values[Math.floor(Math.random() * col2Values.length)];
 
            picker.setValue([col0Random, col1Random, col2Random]);
        });
    }
});          

Inline Picker / Date-time

<div class="content-block-title">Inline Picker / Date-time</div>
<div class="content-block">
 <div style="padding:0; margin-right:-15px; width:auto" class="content-block-inner">
   <div style="margin:0" class="list-block">
     <ul style="border-top:none">
       <li>
         <div class="item-content">
           <div class="item-inner">
             <div class="item-input">
               <input type="text" placeholder="Date Time" readonly id="picker-date">
             </div>
           </div>
         </div>
       </li>
     </ul>
   </div>
   <div id="picker-date-container"></div>
 </div>
</div>
var today = new Date();
 
var pickerInline = myApp.picker({
    input: '#picker-date',
    container: '#picker-date-container',
    toolbar: false,
    rotateEffect: true,
 
    value: [today.getMonth(), today.getDate(), today.getFullYear(), today.getHours(), (today.getMinutes() < 10 ? '0' + today.getMinutes() : today.getMinutes())],
 
    onChange: function (picker, values, displayValues) {
        var daysInMonth = new Date(picker.value[2], picker.value[0]*1 + 1, 0).getDate();
        if (values[1] > daysInMonth) {
            picker.cols[1].setValue(daysInMonth);
        }
    },
 
    formatValue: function (p, values, displayValues) {
        return displayValues[0] + ' ' + values[1] + ', ' + values[2] + ' ' + values[3] + ':' + values[4];
    },
 
    cols: [
        // Months
        {
            values: ('0 1 2 3 4 5 6 7 8 9 10 11').split(' '),
            displayValues: ('January February March April May June July August September October November December').split(' '),
            textAlign: 'left'
        },
        // Days
        {
            values: [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31],
        },
        // Years
        {
            values: (function () {
                var arr = [];
                for (var i = 1950; i <= 2030; i++) { arr.push(i); }
                return arr;
            })(),
        },
        // Space divider
        {
            divider: true,
            content: '  '
        },
        // Hours
        {
            values: (function () {
                var arr = [];
                for (var i = 0; i <= 23; i++) { arr.push(i); }
                return arr;
            })(),
        },
        // Divider
        {
            divider: true,
            content: ':'
        },
        // Minutes
        {
            values: (function () {
                var arr = [];
                for (var i = 0; i <= 59; i++) { arr.push(i < 10 ? '0' + i : i); }
                return arr;
            })(),
        }
    ]
});