Skip to content

Latest commit

 

History

History
313 lines (291 loc) · 8.01 KB

README.md

File metadata and controls

313 lines (291 loc) · 8.01 KB
Raw

devDependency Status [Flattr this git repo](https://flattr.com/submit/auto?user_id=nolimits4web&url=https://github.com/nolimits4web/framework7-keypad/&title=Framework7 Keypad&language=JavaScript&tags=github&category=software)

Framework7 Keypad

Keypad plugin extends Framework7 with additional custom keyboards. By default it comes with predefined Numpad and Calculator keyboards, but it also can be used to create custom keyboards with custom buttons.

Keypad Instance

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

myApp.keypad(parameters)

Where parameters - object - object with Keypad parameters. Required This method returns initialized Keypad instance

For example

var myKeypad = myApp.keypad({
    input: '#demo-numpad-limited',
    valueMaxLength: 2,
    dotButton: false
});

Keypad 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 Keypad HTML. Use only for inline keypad
input string or HTMLElement String with CSS selector or HTMLElement with related input element
scrollToInput boolean true Scroll viewport (page-content) to input when keypad opened
openOnInput boolean true Automatically open keypad if HTMLElement is a input.
inputReadOnly boolean true Sets "readonly" attribute on specified input
convertToPopover boolean true Converts keypad modal to Popover on large screens (on iPad)
onlyOnPopover boolean false Enable it and Keypad will be always opened in Popover
cssClass string Additional CSS class name to be set on keypad modal
toolbar boolean true Enables keypad 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>

    </code></pre>
  </td>
</tr>
<tr>
  <th colspan="4">Specific Picker Parameters</th>
</tr>
<tr>
  <td>value</td>
  <td>string</td>
  <td></td>
  <td>Initial Keypad value</td>
</tr>
<tr>
  <td>formatValue</td>
  <td>function (p, value)</td>
  <td></td>
  <td>
    Function to format input value, should return new/formatted string value. <b>value</b>
    is the current keypad value
  </td>
</tr>
<tr>
  <td>type</td>
  <td>string</td>
  <td>'numbad'</td>
  <td>Keypad type, could be 'numpad', 'calculator' or 'custom'</td>
</tr>
<tr>
  <td>valueMaxLength</td>
  <td>number</td>
  <td>null</td>
  <td>Limit value by selected number of characters</td>
</tr>
<tr>
  <td>dotButton</td>
  <td>boolean</td>
  <td>true</td>
  <td>Only for 'numpad' type. Show or hide "dot" button</td>
</tr>
<tr>
  <td>dotCharacter</td>
  <td>string</td>
  <td>'.'</td>
  <td>Dot character symbol. Only for 'numpad' and 'calculator' types</td>
</tr>
<tr>
  <td>buttons</td>
  <td>array</td>
  <td></td>
  <td>
    <p>Array with keypad buttons, by default it is predefined for numpad and calculator, but can be used for custom keypad.</p>
    <p>Each button should be presented as object with the following properties:</p>
    <ul>
        <li><i>html</i> - <b>string</b> - button inner HTML</li>
        <li><i>value</i> - <b>string/number</b> - button value</li>
        <li><i>cssClass</i> - <b>string</b> - additional CSS class on button</li>
        <li><i>dark</i> - <b>boolean</b> - defines "dark" color button</li>
        <li><i>onClick</i> - <b>function (p, button)</b> - callback function that will be executed when you click on button</li>
    </ul>
    <p>As a reference look at source code to see how buttons defined for Numpad and Calculator</p>
    <p>For example:</p>
    <pre><code>



...
buttons: [
{
html:'1',
value: 1,
onClick: function () {
console.log('Button 1 clicked')
}
},
{
html:'A',
value: 'a',
},
...
]


    </code></pre>
  </td>
</tr>


<tr>
  <th colspan="4">Callbacks</th>
</tr>
<tr>
  <td>onChange</td>
  <td>function (p, value)</td>
  <td></td>
  <td>
    Callback function that will be executed when keypad value changed.
  </td>
</tr>
<tr>
  <td>onOpen</td>
  <td>function (p)</td>
  <td></td>
  <td>
    Callback function that will be executed when picker is opened
  </td>
</tr>
<tr>
  <td>onClose</td>
  <td>function (p)</td>
  <td></td>
  <td>
    Callback function that will be executed when picker is closed
  </td>
</tr>

Keypad Methods & Properties

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

Properties
myKeypad.params Object with passed initialization parameters
myKeypad.value Current keypad value
myKeypad.opened true if Keypad is currently opened
myKeypad.inline true if Keypad is inline Keypad
myKeypad.container Dom7 instance with Keypad HTML container
Methods
myKeypad.setValue(value) Set new keypad value.
myKeypad.open() Open Keypad
myKeypad.close() Close Keypad
myKeypad.destroy() Destroy Keypad instance and remove all events

Automatic initialization

Such predefined Numpad and Calculator keypads could be initialized automatically. Just use usual inputs but with special type attribute:

<input type="numpad">
<input type="calculator">

Access to Keypad's Instance

If you initialize Keypad as inline Keypad or using automatic initialization, it is still possible to access to Keypad's instance from its HTML container:

var myKeypad = $$('.keypad-inline')[0].f7Keypad;