Architect 2 Sencha Docs

Build Ext JS Forms in Architect

This guide shows how to build a simple Ext JS form in Architect and attach an event handler for form submission. It also gives detailed descriptions of all the containers and field components available for building forms, provides several common examples of creating form field layouts, and walks through populating a ComboBox's dropdown list from a data store.

For similar information regarding forms in Sencha Touch, see Building Sencha Touch Forms in Architect.

Building a simple form

Almost all forms consist of the same basic parts: a Form Panel containing one or more form fields and (at least) a submit button with an event handler to validate and submit the form. As a quick demonstration of this common case, let's build one of the simplest forms possible: a login form.

Add and configure views

Start a new Ext JS project and set its URL Prefix in Project Settings. See Build Your First Desktop App and Build Your First Mobile App for details. Find the Form Panel component in the Toolbox and double-click it, or drag it to the Canvas, to add it to your project. Double-click the title bar of the panel on the Canvas, and change it to Login.

Drag a Text Field from the Toolbox onto the form panel. Double-click its label and change it to User Name. In Config, set the value of the name property to username.

Drag another Text Field from the Toolbox onto the form panel. Double-click its label and change it to Password. In Config, set the value of the name property to password, and set its inputType to password to make it behave like a password field.

To mark both fields as required, select each one and uncheck the allowBlank property in Config.

Next, drag a Toolbar component from the Toolbox onto the form panel. Select the Toolbar in the Inspector; you can also select it in the Canvas, but selecting it in the Inspector means you can be sure you have selected the right component. In the Canvas, click the Toolbar's Flyout Config button and set Dock In Parent to bottom. Drag a Button onto the toolbar and double-click change its label to Login. To align the button to the right, select the Toolbar and in Config set its pack property to end.

Add behavior

The final step is to add logic so the form does what we want when the user submits it. Select the Login button and find its Events item in Config. Click the add button ("+") to create a new event, and choose click from the list of events. Notice there is now a click event in the Inspector as a child of the button. Double-click the click event to open the code editor for the event. Insert the following code in the editor:

if (this.getForm().isValid()) {    
    this.getForm().submit({
        url: 'login.php',
        success: function(form, action) {
            Ext.Msg.alert('Login Successful!');
        },
        failure: function(form, action) {
            Ext.Msg.alert('Login Failed!');
        }
    });
}

This code checks that the underlying form is valid -- that both fields are filled in as required after we unchecked the allowBlank property. If they are, then the form is submitted to the server-side script at the URL login.php. The contents of that server-side script are beyond the scope of this tutorial, but the above code shows how to handle both success and failure responses. It uses a simple alert message but you would write whatever logic you want.

Let's try the simple form. Save and preview the project in a browser. Click the Login button without entering any values and see that the fields are highlighted as invalid. Fill in values and submit again and, assuming the login.php script does not exist, you will see the failure message.

Form components

Next let's explore all the container and field types you can use to build more complex forms than the example just described. The name of each is linked to its corresponding API documentation.

Containers

Ext JS provides specialized containers for forms and grouping of form fields:

  • Form Panel. The main outermost container for every form. It supports all the features of Panel but exposes an underlying form object (accessible via the getForm() method) that adds special functionality for loading and submitting form field data.

  • FieldContainer. Allows any child components and displays a label next to or above the container body so it aligns with other field labels.

  • FieldSet. Renders as an HTML <fieldset> element and allows collapsing of its contents.

  • Checkbox Group. A group of multiple checkboxes that are aggregated upon form submit into a single submit parameter.

  • Radio Group. A group of multiple radio buttons that are aggregated upon form submit into a single submit parameter.

Fields

The following form field components appear under the Form Fields group in the Toolbox. You usually set the name config for each field added to a form; that name is used as the name of the field's parameter when the form is submitted. All fields also enable a fieldLabel that can be aligned beside or above the field via the labelAlign config or hidden via the hideLabel config.

  • Checkbox. A single checkbox field.

  • ComboBox. A text field that displays possible value options in a drop-down list. The list's contents can be loaded from any data store and can be filtered/searched as the user types. ComboBox is covered in more detail below.

  • Date Field. A date-typed text field with a trigger button to enable selecting a date from a popup calendar widget.

  • Display Field. A field that displays its value as read-only plain text rather than an input field.

  • File Upload. A file upload field.

  • Hidden Field. A hidden input field.

  • HTML Editor. A rich HTML editor field with a toolbar of buttons to control formatting.

  • Label. A standalone field label. You typically don't need to use this; just set the fieldLabel config of a field component instead.

  • Multi Slider. A draggable slider field with multiple slider thumbs.

  • Number Field. A text field that allows only numeric values, and optionally displays spinner buttons to increment/decrement the value.

  • Radio. A single radio button field.

  • Slider. A draggable slider field.

  • Text Area. A multiline text area field.

  • Text Field. A single-line text field.

  • Time Field. A text field that allows time values, with a drop-down list for time selection .

  • Trigger Field. A text field with a trigger button next to it.

Controlling form layouts

By default any fields you add to a Form Panel are stacked vertically and expanded to the full width of the form. This is by no means the only layout; you have full control over how your fields are sized and arranged because a Form Panel, like any other Ext JS container, supports changing its internal layout and also nesting of sub-containers. See Layouts for an introduction.

Let's take a look at some common examples of laying out forms.

Changing the width of form fields

Children of a Form Panel by default are rendered stacked vertically and expand to the full width of the form; this is because the default layout of Form Panel is anchor and its children are given a default of anchor:'100%'. If you want the form to expand but not to the full width you can change its anchor config to a different value. For instance anchor: '-100' expands the form to 100 pixels from the right-hand edge. Or, if you want the field to be a fixed width, clear its anchor config by clicking the "x" button next to it in Config and setting its width config to the value you want.

Grouping fields with FieldSets

FieldSets are the most common way of arranging related fields into groups visually, and they make forms easy to use.

Create a Form Panel and add a FieldSet into it, then add multiple other fields into the FieldSet. Change the FieldSet's legend (title) by double-clicking it and typing in a new name.

FieldSets can be made collapsible by checking the collapsible config. Make a FieldSet collapsed by default by checking the collapsed config.

Just like Form Panel, a FieldSet is automatically configured with a layout of anchor; you can change the layout as you wish, or control the widths of its child field as described above.

Groups of radio buttons or checkboxes

The Checkbox Group and Radio Group are specialized containers for grouping checkboxes or radio buttons.

Create a Form Panel and add a Radio Group to it. Change the main label of the group to Favorite Color and change the box labels of the two default radio fields to Red and Green. Add a third Radio field into the group, check its hideLabel config to hide the main label, and change its box label to Blue.

To connect the three radio buttons so they only allow one to be checked at a time, set the name config of all three to the same value.

Uncheck the allowBlank config of the radio group to require the user to check one of the radio buttons. If no buttons are checked, then the form's validation will fail and the group will be highlighted as invalid in the same way as single fields.

Notice that the radio buttons are arranged horizontally by default. You can arrange them into vertical columns by changing the columns config. For instance, set columns: 1 to create a single column.

Arranging fields in multiple columns

For a form with a large number of fields, it’s possible to arrange them in more than one column to minimize scrolling. To do this, use nested Containers within the Form Panel. Either a particular section or the entire form can be laid out in multiple columns, depending on the relationship between the form fields.

For example, create a Form Panel and change its layout to hbox. Add two Container instances into it. Notice that the containers are arranged side-by-side and each one takes half the available space because flex is set to 1 by default.

Change the layout of each container to anchor. Add multiple form fields to each container. Now you have two columns of fields. You can add space between the column containers by setting their margins configs.

Aligning fields horizontally

In some cases a group of related fields in a form need to be aligned on one line, instead of in multiple columns, say for a multipart name field.

For example, create a Form Panel and add a FieldSet to it. Change the FieldSet's layout to hbox and its HBox align config to top.

Now add a Text Field into the FieldSet, change its label to First, set its labelAlign config to top, and give it a name of firstname. Right-click the field and select Duplicate and change the resulting second field's label to MI and its name to middleinitial. Duplicate the second field and change the resulting third field's label to Last and its name to `lastname.

You now have three horizontally arranged, equally-sized fields. Let's refine the layout. Select the First field and change its flex to 2. Select the MI field, remove its flex value, set its width to 30, and set margins to 0 10 to give it right and left margins of 10 pixels. Select the Last field and set its flex to 3.

Populating a ComboBox

The ComboBox field is one of the most useful form field types, because it helps the user easily select values from a drop-down selection list. The items listed in a ComboBox's drop-down list are defined using a data store. You will want to familiarize yourself with Sotres and Models before continuing.

The simplest way to set up a Store for a ComboBox is to create a local Array Store, as follows:

Create a new Array Store by clicking the "+" button at the top of the Project Inspector and selecting Array Store. Select the newly created MyArrayStore in the Inspector and change its userClassName config to Colors. Define a single Field for the store by clicking the "+" button next to the Fields item in Config; give the Field a name of text.

For this example we'll just add static local data into the store directly; in a real application you might want to fetch the data from a remote URL using an Ajax proxy, but for local data let's change the store's proxy to a local memory proxy by right-clicking the proxy and selecting Transform-->Ext.data.proxy.Memory.

Let's add some static array data to the store, by inserting the following as the value of the Store's data config:

[{text:'Red'}, {text:'Green'}, {text:'Blue'}, {text:'Yellow'}, {text:'Purple'}]

Finally let's create our ComboBox field and attach it to the store. Create a Form Panel, add a ComboBox to it, and set the ComboBox label to Color. Select the ComboBox and in Config select the Colors store for the store config. Since the data is local, set the queryMode config to local. (The default value of remote would be used if your data was queried from a remote URL.)

Now if you save and preview your project your ComboBox presents the colors from the store as options in its drop-down selection list, and typing in the field filters the options automatically.