Contributing

Contributions are more than welcome. Together we can make this a solid library and hopefully a friendlier web.

Read how to setup the project.

Bugs and Fixes

Each bug should be filed as a separate issue, and each fix should be in a separate pull request.

Pull Requests

Each new field should be submitted in a separate pull request, and please be sure to add the necessary tests. A good example is the dd_mm_yyyy field which can be found here which covers a wide range of formatting and validating scenarios.

It is important to maintain consistency with the other fields. For example, all date fields have an additional val method $('input.dd_mm_yyyy').formance('val_dd_mm_yyyy'); which returns a js Date object. So if you're contributing a new date field then it should adhere to such an api.

Creating A New Field

This example will walk you through creating a new field.

We'll start by writing tests for the new field to ensure we've thought about the expected behavior and edge cases. Create a file under test/fields/ called new_incredible_field.coffee. The code below is a good start, but be sure to add tests for each formatting and validating scenario.

In this example, our new incredible field adheres to the format 11 / 111. 2 digits, followed by a space a slash a space and 3 more digits.

assert = require('assert')
$ = require('jquery')
global.jQuery = $

require('../../lib/jquery.formance.js')

describe 'new_incredible_field.js', ->

    it 'should format the incredible field', ->
        # 52 is the normalized keyboard input representing the number 4
        # you can read more here http://api.jquery.com/event.which/
        # this simulates that the input field contained the value 2, 4 was entered, and the result is 24 / 
        format '2',    52,     '24 / ',     'append a / after the first two digits have been entered'
        ...

    it 'should validate the incredible field', ->
        validate '24 / 100',    yes,       'valid incredible input'
        validate '24 / ;;',    no,         'invalid incredible input'
        ...

# helper methods
format = (value, trigger, expected_value, message) ->
    $field = $('<input type=text>').formance('format_new_incredible_field')
                                   .val(value)
    e = $.Event('keypress')
    e.which = trigger
    $field.trigger(e)
    assert.equal $field.val(), expected_value, message

validate = (value, valid, message) ->
    $field = $('<input type=text>').val(value)
    assert.equal $date.formance('validate_new_incredible_field'), valid, messages

Now that we've written the tests, we can go ahead and create the field. Create the file new_incredible_field.coffee under src/zfields.

$ = jQuery

# subclass of the NumericFormanceField which is a subclass of the FormanceField
# there is also an AlphanumericFormanceField
class NewIncredibleField extends NumericFormanceField
    
    # restricts the length of the input field to 5 digits, all the formatting is stripped away
    restrict_field_callback: (e, $target, old_val, digit, new_val) =>
        return false if new_val.length > 5

    # this callback gets invoked every time the user enters a new digit
    format_field_callback: (e, $target, old_val, digit, new_val) =>        
        if /^\d{2}$/.test(new_val)  # if the 2nd digit was entered, lets append a /
            e.preventDefault()
            $target.val "#{new_val} / "

    # this callback gets invoked when the user is backspacing
    format_backspace_callback: (e, $target, val) =>
        if /\d[\s|\/]+$/.test(val) # deletes the a digit and /  
            e.preventDefault()
            $target.val val.replace(/\d[\s|\/]+$/, '') 
 
    # there is a format_paste_callback as well, which you should implement
    # take a look at FormanceField for more details

    # gets called when the input must be validated
    validate: () ->
        return /^\d{2}[\s|\/]*\d{3}$/.test( @field.val() )

# exposes the fields format and validate methods for the api
$.formance.fn.format_new_incredible_field = ->
    field = new NewIncredibleField this
    field.format()
    this
$.formance.fn.validate_new_incredible_field = ->
    field = new NewIncredibleField this
    field.validate()

Now we should run the tests to make sure our code works cake test. If it does, great you're almost ready to send a pull request. If not, time to put on your debugging hat.

• run cake build, then copy over the lib/jquery.formance.min.js to demo/js/.
• edit demo/formancejs.html to include your new field, it should be in alphabetical order
• increment the minor version (middle number) in package.json. This project adheres to semantic versioning.
• smile, and send that pull request you badass!