Before reading this article please read the following articles.
- Introduction to Sencha Touch 2
- Hello World App using Sencha Touch 2
Introduction
In last article we have developed a sample "Hello World Application". In this article we will develop a sample form. From this sample form application you will get a clear understanding of controls provided by Sencha Touch 2, how to use those controls and so on. So let's start with the basic controls provided by Sencha Touch 2.
As we know, to get input from users we need some TextBoxes, DropDowns, CheckBox, RadioButtons, Sliders, Toggle Buttons and so on. We will see all those basic controls here in this article. In future articles we will go through some container controls, databound controls, toolbars and so on.
Here we will start first from how to create a control. As in the previous article we have seen the "Ext.create" statement we will make this much easier now by replacing "Ext.create" with simple "xtype". First we will create our sample form and then we will go through the properties, events, methods.
Step 1: Create a simple application as we created in the previous article. Add a reference to the Sencha library and css file. This time you need to replace only the css file with "sencha-touch.css" present in the downloaded SDK in the first article.
Step 2: Replace the code in app.js file with the following code:
Ext.application({
// requires download the required files i.e. dynamic loading
requires: ['Ext.form.*','Ext.field.*','Ext.Button','Ext.Toolbar'],
launch: function () {//Entry point
var formPanel = Ext.create("Ext.form.Panel", {
id: 'basicform', height: '100%', width: '100%',
items: [{//items of formpanel
xtype: 'fieldset', title: 'Personal Info', id: 'personalinfo',
instructions: 'Please enter the information above.',
items: [{//items of fieldset
xtype: 'textfield',
name: 'Name',
label: 'UserName',
id: 'name', //required to get value
listeners: {
keyup: function (field, e, eOpts) {//event
alert('Key Up');
}
}
},{
xtype: 'passwordfield',
name: 'password',
label: 'Password',
id: 'password'
},{
xtype: 'textfield',
name: 'disabled',
label: 'Disabled',
disabled: true,
id: 'disabled'
},{
xtype: 'emailfield',
name: 'email',
label: 'Email',
placeHolder: '[email protected]',
id: 'email'
},{
xtype: 'urlfield',
name: 'url',
label: 'Url',
placeHolder: 'http://krishnasaralanet.wordpress.com',
id: 'url'
},{
xtype: 'checkboxfield',
name: 'Check',
label: 'Check Me',
value: true,
id: 'check'
},{
xtype: 'spinnerfield',
name: 'spinner',
label: 'Spinner',
id: 'spinner'
},{
xtype: 'selectfield', //dropdown
name: 'Select',
label: 'Select One:',
valueField: 'value',
displayField: 'title',
id: 'select',
store: {//data bound control needs to pass store object
data: [{ value: '1', title: 'Master' },{ value: '2', title: 'Student' },{ value: '3', title: 'Instructor' },{ value: '4', title: 'Assistant' }]
}
},{
xtype: 'datepickerfield', //datepicker
name: 'date',
label: 'Start Date',
id: 'date',
value: new Date(),
picker: {
yearFrom: 1980
}
},{
xtype: 'textareafield', //area textbox
name: 'Desc',
id: 'desc',
label: 'Description',
maxRows: 10
},{
xtype: 'sliderfield',
name: 'height',
label: 'Height',
id: 'height'
},{
xtype: 'togglefield',
name: 'enable',
label: 'Security Mode',
id: 'toggle'
},{
xtype: 'radiofield',
name: 'team', //provide same name if you need group of radiobuttons
label: 'Red Team',
value: 'redteam'
},{
xtype: 'radiofield',
name: 'team', //provide same name if you need group of radiobuttons
label: 'Blue Team',
value: 'blueteam'
}]
},{
xtype: 'toolbar',
docked: 'bottom', //also available left,right,top
items: [{//items on toolbar
xtype: 'button', id: 'done', text: 'Save', align: 'left', ui: 'confirm',
handler: function () {
//this is traditional way to get controls and their values when we will see MVC with sencha we will make this lot easier
//instead of writting independent controls will fetch directly bunch of records
var record = {//create array
name: Ext.getCmp('name').getValue(), //use Ext.getCmp('ControlId') to get Control instance
password: Ext.getCmp('password').getValue(),
email: Ext.getCmp('email').getValue(),
url: Ext.getCmp('url').getValue(),
spinner: Ext.getCmp('spinner').getValue(),
select: Ext.getCmp('select').getValue(),
date: Ext.getCmp('date').getValue(),
desc: Ext.getCmp('desc').getValue(),
height: Ext.getCmp('height').getValue(),
toggle: Ext.getCmp('toggle').getValue()
}
Ext.Viewport.setMasked({//disabling ui
xtype: 'loadmask',
message: 'Saving...'
});
alert('Record Saved'); //perform ajax call to save record
Ext.Viewport.setMasked(false); //after the process enabling UI
}
},{
xtype: 'button', id: 'cancel', text: 'Cancel', align: 'right', ui: 'decline',
handler: function () {
alert('Cancel');
}
}]
}]
});
Ext.Viewport.add(formPanel);
}
});
In code snippet above, as usual we have started our application using "Ext.application". You can see below that we have added a new attribute, "requires", which is used to specify the required Sencha classes to be downloaded. Here if this statement is omitted then it will still work because we have already downloaded all the Sencha classes when we added the reference to the Sencha library. Creating an application using the Sencha library is not the way but for demo purposes we are doing this. Next in future articles we will see the senchaSDKTool to generate, build and pack our application in case we need this required attribute.
Next we have created our required entry point, in other words the "launch" function. In the launch function we have create a formpanel "Ext.create("Ext.form.Panel")" by extending the "Ext.form.Panel" class. For the formpanel we have attributes like id, height, width and items. In the items attribute we have created two main controls using "xtype", in other words fieldset and toolbar. Now here to create a fieldset we need not to write a statement like "Ext.create("Ext.form.Fieldset")". We simply omitted "Ext.create" using xtype. Here xtype is the tagprefix now onwords whenever you are creating a control simply use xtype. Next you will see we have added some items in fieldset as well. Fieldset is one of the container controls that includes child controls in it like TextBoxes, DorpDowns, email boxes, URL boxes and so on. In the following we will see the common controls and their config options, methods, and events.
TextBox:
xtype: 'textfield',
name: 'Name',
label: 'UserName',
id: 'name',
listeners: {
keyup: function (field, e, eOpts) {//event
alert('Key Up');
}
}
In the above snippet you can see we have created a TextBox using xtype as a textfield. Textfield has config options like name, id, label, height, width and so on. The same TextBox has common methods like setValue(), getValue() and so on as well has common events like focus(), keyup() and so on.
All the remaining controls like EmialField, UrlField has the same syntax except DropDown. We will see the DropDown below.
DropDown
As we already know dropdown is a databound control so here are some differences between normal TextBox creation and DropDown creation. To create a dropdown we can use the following code.
xtype: 'selectfield', //dropdown
name: 'Select',
label: 'Select One:',
valueField: 'value',
displayField: 'title',
id: 'select',
store: {//data bound control needs to pass store object
data: [
{ value: '1', title: 'Master' },
{ value: '2', title: 'Student' },
{ value: '3', title: 'Instructor' },
{ value: '4', title: 'Assistant' }
]}
In the above snippet we have created a simple dropdown control using xtype as "selectfield". Here are some differences between normal Textfields and DropDowns. We have added three new attributes to selectfield, in other words valueField, displayField and store. As an ASP.Net developer we all are binding some datasource to our DropDown. Here store is nothing but the datasource for selectfield and as usual valueField and displayField are as in ASP.Net DropDown.
I hope you are clear about the controls used to create a basic form. Now we will look to the toolbar control that is the second item for "Ext.form.Panel" after "fieldset".
Toolbar
As a Windows application developer we all know about toolbars. Generally we use toolbars for common button menus and so on. Here is the same use of a toolbar for buttons.
xtype: 'toolbar',
docked: 'bottom', //also available left,right,top
items: [{//items on toolbar
}]
You can create a toolbar by using xtype as a "toolbar" toolbar with common config options like id, name, docked, items and so on. You can override the default toolbar color blue as you require by providing cls config that is nothing but the css class name. Here we have created a toolbar with two buttons, one for saving records and the second for canceling the operation.
items: [{
xtype: 'button', id: 'done', text: 'Save', ui: 'confirm',
handler: function () {
var record = {
name: Ext.getCmp('name').getValue(),
password: Ext.getCmp('password').getValue(),
email: Ext.getCmp('email').getValue(),
url: Ext.getCmp('url').getValue(),
spinner: Ext.getCmp('spinner').getValue(),
select: Ext.getCmp('select').getValue(),
date: Ext.getCmp('date').getValue(),
desc: Ext.getCmp('desc').getValue(),
height: Ext.getCmp('height').getValue(),
toggle: Ext.getCmp('toggle').getValue()
}
Ext.Viewport.setMasked({
xtype: 'loadmask',
message: 'Saving...'
});
alert('Record Saved');
Ext.Viewport.setMasked(false);
}
},
{
xtype: 'button', id: 'cancel', text: 'Cancel', ui: 'decline',
handler: function () {
lert('Cancel');
}
}
]
In above snippet you can see we have simply added two buttons, in other words save and cancel. The buttons have a common config options like id, text, cls and so on. For the buttons here we have created handler functions that will be called when the button is clicked. In this handler function we are writing code to get the values for the above TextBoxes, DropDown, emailfields and so on.
To get a control instance Sencha Touch provides the "Ext.getCmp('ControlId')" function. Once you have the control instance you call the methods of a specific control, like for TextBoxes we call getValue() to get the value from the TextBox.
Conclusion
Here I'm ending this explanation. For more about controls and their config options see docs.sencha.com. In the next article we will see about container controls.