Cape.Component - API Reference - Cape.JS: Documentation

Cape.Component - API Reference

checkedOn() - formData() - jsonFor() - mount() - paramsFor() - refresh() - root - unmount() - val() - valuesFor()

#checkedOn() 1.2

Usage

checkedOn(name)

This method returns:

true if the check box whose name is name is checked.
false if the check box whose name is name exists but is not checked.
undefined if the check box whose name is name does not exist.

Example

render: function(m) {
  m.form(function(m) {
    m.checkBox('done');
    m.button('Check', {
      onclick: function(e) {
        console.log(this.checkedOn('done'));
        return false;
      }
    })
  });
}

When the form has a name attribute, you should prepend its value and a dot to the name of check box.

Example

render: function(m) {
  m.formFor('task', function(m) {
    m.checkBox('done');
    m.button('Check', {
      onclick: function(e) {
        console.log(this.checkedOn('task.done'));
        return false;
      }
    })
  });
}

#formData()

Usage

formData()

This method returns a JavaScript object that represents the values of all form controls within the component.

The values are organized in hierarchical structure as explained following examples:

Example

If you have a component defined like this,

var Form = Cape.createComponentClass({
  render: function(m) {
    m.formFor('user', function(m) {
      m.textField('login_name');
      m.passwordField('password');
    });
  }
});

the formData() method of its instances returns an object like this:

{
  user: {
    login_name: 'john',
    password: 'p@ssw0rd'
  }
}

Example

If you have a component defined like this,

var Form = Cape.createComponentClass({
  render: function(m) {
    m.formFor('user', function(m) {
      m.textField('login_name');
      m.passwordField('password');
      for (var index = 0; index < 2; i++) {
        m.fieldsFor('addresses', { index: index }, function(m) {
          m.textField('country');
          m.textField('city');
        })
      }
    });
  }
});

the formData() method of its instances returns an object like this:

{
  user: {
    login_name: 'john',
    password: 'p@ssw0rd',
    addresses: {
      '0': {
        country: 'Japan',
        city: 'Tokyo'
      },
      '1': {
        country: 'USA',
        city: 'New York'
      }
    }
  }
}

#jsonFor() 1.1

Usage

jsonFor(formName)

Thid method returns a JSON string that represents the field values of a named form.

The values are organized in hierarchical structure as explained following examples:

Example

If you have a component defined like this,

var Form = Cape.createComponentClass({
  render: function(m) {
    m.formFor('user', function(m) {
      m.textField('login_name');
      m.passwordField('password');
    });
  }
});

the jsonFor() method of its instances returns a string like this:

{"user": { "login_name": "john", "password": "p@ssw0rd"}}

Example

If you have a component defined like this,

var Form = Cape.createComponentClass({
  render: function(m) {
    m.formFor('user', function(m) {
      m.textField('login_name');
      m.passwordField('password');
      for (var index = 0; index < 2; i++) {
        m.fieldsFor('addresses', { index: index }, function(m) {
          m.textField('country');
          m.textField('city');
        })
      }
    });
  }
});

the jsonFor() method of its instances returns a string like this:

{"user": {"login_name": "john", "password": "p@ssw0rd"}, "addresses": [{"country": "Japan", "city": "Tokyo" }, {"country": "USA", "city": "New York"}]}

#mount()

Usage

mount(id)

This method renders the component and inserts it within the element specified by id.

Example

<body>
<div id="main"></div>
<script>
var HelloWorld = Cape.createComponentClass({
  render: function(m) {
    m.p('Hello, World!')
  }
});
var component = new HelloWorld();
component.mount('main');
</script>
</body>

If the component has the init() method, the mount() calls it instead of rendering the component.

Example

var HelloWorld = Cape.createComponentClass({
  init: function() {
    this.name = 'World';
    this.refresh();
  },

  render: function(m) {
    m.p('Hello, ' + this.name + '!')
  }
});

Note that you should have to call the refresh() method at the end to render the component.

#paramsFor() 1.1

Thid method returns an object that represents the field values of a named form.

The returned object is organized in hierarchical structure so that you can pass it to the ajax() method of jQuery.

Example

Suppose that you have a component defined like this:

var Form = Cape.createComponentClass({
  render: function(m) {
    m.formFor('user', function(m) {
      m.textField('name');
      m.passwordField('password');
      m.btn('Sign in', { onclick: function(e) { this.save(); } });
    });
  },
  save: function() {
    $.ajax({
      url: '/sessions/',
      method: 'POST',
      data: this.paramsFor('user')
    }).done(function(data) {
      // Do something.
    });
  }
});

When you fill in name field with ‘john’ and password field with 1234 and click the ‘Sign in’ button, this.paramsFor('user') passes to the data option of the ajax() the following object:

{
  user: {
    name: "john",
    password: "1234"
  }
}

Note that jQuery converts this object to a query string like this:

user[name]=john&user[password]=1234

Example

Suppose that you have a component defined like this:

var Form = Cape.createComponentClass({
  init: function() {
    this.user_id = 123;
    this.setValues({
      user: {
        name: 'john',
        addresses: [
          { country: 'Japan', city: 'Tokyo' },
          { country: 'USA', city: 'New York' }
        ]
      }
    });
  },
  render: function(m) {
    m.formFor('user', function(m) {
      m.textField('name');
      for (var index = 0; index < 2; i++) {
        m.fieldsFor('addresses', { index: index }, function(m) {
          m.textField('country');
          m.textField('city');
        });
      }
      m.btn('Save', { onclick: function(e) { this.save(); } });
    });
  },
  save: function() {
    $.ajax({
      url: '/sessions/' + this.user_id,
      method: 'PATH',
      data: this.paramsFor('user')
    }).done(function(data) {
      // Do something.
    });
  }
});

When you change the value of name field from ‘john’ to ‘mike’ and click ‘Save’ button, this.paramsFor('user') passes to the data option of the ajax() the following object:

{
  user: {
    name: "mike",
    addresses: {
      '0': {
        country: "Japan",
        city: "Tokyo"
      },
      '1': {
        country: "USA",
        city: "New York"
      }
    }
  }
}

Note that jQuery converts this object to a query string like this:

user[name]=mike&user[addresses][0][country]=Japan&user[addresses][0][city]=Tokyo&user[addresses][1][country]=USA&user[addresses][1][city]=New+York

#refresh()

refresh()

This method rerenders the component by calling its render() method.

#root

This property refers to the HTML element which the component is mounted on.

Its data subproperty holds the values of data-* attributes of the root element.

Example

The following example shows “Hello, John!” on your browser.

<body>
<div id="main" data-name="John"></div>
<script>
var HelloMessage = Cape.createComponentClass({
  render: function(m) {
    m.p('Hello, ' + this.root.data.name + '!')
  }
});
var component = new HelloMessage();
component.mount('main');
</script>
</body>

#unmount()

Usage

unmount()

This method removes the component from the HTML document.

If the component has the beforeUnmount() method, it is called before the component is unmounted. If the component has the afterUnmount() method, it is called after the component has been unmounted.

#val()

Usage

val(name)
val(name, value)
val({ name1: value1, name2: value2, … })

Get or set the value of a form field.

When the number of arguments is one and that argument is a string, this method returns the value of the corresponding field.

Example

render: function(m) {
  m.formFor('user', function(m) {
    m.textField('family_name').sp()
      .textField('given_name');
    m.button('Check', {
      onclick: function(e) {
        console.log(this.val('user.family_name'));
        console.log(this.val('user.given_name'));
        return false;
      }
    })
  });
}

When the number of arguments is two, this method sets the value of a field whose name is corresponding to the first argument to the second argument and returns the original value of the field.

Example

render: function(m) {
  m.formFor('message', function(m) {
    m.textField('body');
    m.button('Send', {
      onclick: function(e) {
        var body = this.val('message.body', ''),
            self = this;
        $.post('/api/messages', { body: body }, function() {
          self.refresh();
        });
        return false;
      }
    });
  });
}

When the number of arguments is one and that argument is an object, this method sets the value of corresponding fields.

Example

render: function(m) {
  m.formFor('user', function(m) {
    m.textField('family_name').sp()
      .textField('given_name');
    m.button('Check', {
      onclick: function(e) {
        var self = this,
            data = self.formData();
        self.val({ user: { family_name: '', given_name: '' } });
        $.post('/api/users', data, function() {
          self.refresh();
        })
        return false;
      }
    });
  });
}

#valuesFor() 1.1

Thid method sets the field values of a named form by passing an object as the first argument.

The values of this object must be organized in hierarchical structure as explained following examples:

Example

If you render a component defined like this,

var Form = Cape.createComponentClass({
  init: function() {
    this.valuesFor({
      user: {
        login_name: 'john',
        gender: 'm'
      }
    });
    this.refresh();
  },
  render: function(m) {
    m.formFor('user', function(m) {
      m.textField('login_name');
      m.radioButton('gender', 'm');
      m.radioButton('gender', 'f');
    });
  }
});

you will see the only text field is filled with a string “john” and the first radio button is checked.

Example

If you render a component defined like this,

var Form = Cape.createComponentClass({
  init: function() {
    this.valuesFor({
      user: {
        login_name: 'john',
        addresses: [
          { country: 'Japan', city: 'Tokyo' },
          { country: 'USA', city: 'New York' }
        ]
      }
    });
    this.refresh();
  },
  render: function(m) {
    m.formFor('user', function(m) {
      m.textField('login_name');
      for (var index = 0; index < 2; i++) {
        m.fieldsFor('addresses', { index: index }, function(m) {
          m.textField('country');
          m.textField('city');
        })
      }
    });
  }
});

you will see the all text fields are filled in.