Applications using Clutch are made using a combination of native code and HTML/CSS/JavaScript. The Clutch JavaScript library is designed to create content areas for your application using web technology that both looks and feels native.
To achieve this kind of performance and flexibility, we’ve built the core of the library on top of the best mobile JavaScript code we could find: Zepto, Backbone, and Underscore.
The first thing that Clutch does when it loads is set up some bookkeeping and set up a communication channel between your native code and your JavaScript code. Once that’s all finished, it calls the function you attach using Clutch.Core.init.
| Arguments: |
|
|---|
Keep in mind you should not start your rendering until after this function has been called. Here’s an example of how that could look in your code:
Clutch.Core.init(function() {
alert('Hello from Clutch!');
});
Once that is set up, you can go ahead and use any of Clutch’s resources–the communication channel, the UI helpers, and more.
But the real core of Clutch is really just the communication channel between the JavaScript that you write and the iOS code that you write.
| Arguments: |
|
|---|---|
| Returns: | Nothing |
As you can see, it’s simple and straightforward. As an example, if a user taps on a button and you want something to happen, you might write something like this:
Clutch.Core.callMethod('userTapped', {userId: 10});
In this example, we’re calling the userTapped method in your iOS code, and passing an NSDictionary whose key userId is set to 10. You can also pass a callback function, which might look something like this:
Clutch.Core.callMethod('getUsername', function(data) {
alert('Hello, ' + data.username);
});
To register a function on the JavaScript side that iOS can call, Clutch provides a registerMethod function.
| Arguments: |
|
|---|
Note
The function that you expose will always receive a single argument: an object of parameters passed from iOS.
Here’s how it might look if you were to expose an alertUser function which pops open an alert dialog with the given alert text:
function alertUser(params) {
alert(params.alertText);
}
Clutch.Core.registerMethod('alertUser', alertUser);
One thing we need to do all the time in building iOS apps is to wait for some data. Whenever we do that, we need to somehow indicate to the user that there’s something loading. Clutch provides an easy mechanism for showing and hiding loading screens.
| Arguments: |
|
|---|
Pops up the loading dialog with optional loading text.
Removes the loading dialog.
Clutch helps you present a UI to your users that looks and feels like it’s native. Here’s what’s provided:
| Arguments: |
|
|---|
This view is the core of all of the Clutch-provided UI constructs. It’s actually a subclass of Backbone.View, with a few added extras. Here are the added properties and functions:
The default template provided for all Clutch.UI.View subclasses is a simple underscore template that looks like <%= c.value %>.
The default render for all Clutch.UI.View subclasses renders the template but passes the view options as the c varible. It’s equivalent to this implementation:
$(this.el).html(this.template({c: this.options}));
| Arguments: |
|
|---|
This view creates a user interface that looks and acts like Cocoa’s UITableView.
You must extend this view to populate it with any data, and here are the parameters you can provide in your extension:
Required
The number of table sections that should be displayed.
| Arguments: |
|
|---|
Determines the number of cells to be rendered for the given section.
| Arguments: |
|
|---|
Returns the Clutch.UI.TableCell subclass that should render the requested table cell.
Optional
Determines the visual style of the table. Currently only supports 'normal' and 'grouped'.
Returns the Clutch.UI.TableHeader subclass that should render into the table’s header area.
Returns tje Clutch.UI.TableFooter subclass that should render into the table’s footer area.
| Arguments: |
|
|---|
Returns a Clutch.UI.SectionHeader subclass that should render into the given table section’s header area.
| Arguments: |
|
|---|
Returns a Clutch.UI.SectionHeader subclass that should render into the given table section’s footer area.
| Arguments: |
|
|---|
A Clutch.UI.View subclass for rendering table headers.
| Arguments: |
|
|---|
A Clutch.UI.View subclass for rendering table footers.
| Arguments: |
|
|---|
A Clutch.UI.View subclass for rendering table section headers.
| Arguments: |
|
|---|
A Clutch.UI.View subclass for rendering table section footers.
| Arguments: |
|
|---|
In that options object, here are the expected and optional parameters:
Required
The value that should be displayed in the cell.
Optional
Determines which accessory to display for the cell. Should be one of Clutch.UI.Accessories.
An optional function which will receive an event whenever this table cell is tapped by the end user.
Note
If you subclass Clutch.UI.TableCell, then you can set the multiline attribute to true and it will be able to display more than one line of content.
var MultiLineCell = Clutch.UI.TableCell.extend({
multiline: true
});
Here’s an example of how you could use this JavaScript library to create a table which has some cells and a few headers.
// Let's create a simple table by subclassing Clutch.UI.Table
var SimpleTable = Clutch.UI.Table.extend({
// Our table should have two sections
numSections: 2,
// We want it to display in the "grouped" style which looks cooler
style: 'grouped',
numCells: function(section) {
// Each section has 4 cells
return 4;
},
sectionHeader: function(section) {
// The section header just displays its own index
return new Clutch.UI.TableSectionHeader(
{value: 'Section ' + section + ' Header'}
);
},
sectionFooter: function(section) {
// The first section doesn't have a footer
if(section === 0) {
return null;
}
// The second section does have a footer though
return new Clutch.UI.TableSectionFooter(
{value: 'Section ' + section + ' Footer'}
);
},
cell: function(section, row) {
var value = 'Section ' + section + ' Cell ' + row;
return new Clutch.UI.TableCell({
value: value,
accessory: Clutch.UI.Accessories.DisclosureButton,
tap: function(e) {
// Call the "tapped" method on iOS, and pass
// the text value of the cell as an argument.
Clutch.Core.callMethod('tapped', {value: value});
}
});
}
});
// Remember to wait for this event before rendering out our table.
Clutch.Core.init(function() {
// Instantiate our new table
var table = new SimpleTable();
// Render the table
$('body').append(table.render().el);
});