Docs Help

Terms, Icons, and Labels

Many classes have shortcut names used when creating (instantiating) a class with a configuration object. The shortcut name is referred to as an alias (or xtype if the class extends Ext.Component). The alias/xtype is listed next to the class name of applicable classes for quick reference.

Access Levels

Framework classes or their members may be specified as private or protected. Else, the class / member is public. Public, protected, and private are access descriptors used to convey how and when the class or class member should be used.

Member Types

Member Syntax

Below is an example class member that we can disect to show the syntax of a class member (the lookupComponent method as viewed from the Ext.button.Button class in this case).

lookupComponent ( item ) : Ext.Component
protected

Called when a raw config object is added to this container either during initialization of the items config, or when new items are added), or {@link #insert inserted.

This method converts the passed object into an instanced child component.

This may be overridden in subclasses when special processing needs to be applied to child creation.

Parameters

item :  Object

The config object being added.

Returns
Ext.Component

The component to be added.

Let's look at each part of the member row:

Member Flags

The API documentation uses a number of flags to further commnicate the class member's function and intent. The label may be represented by a text label, an abbreviation, or an icon.

Class Icons

- Indicates a framework class

- A singleton framework class. *See the singleton flag for more information

- A component-type framework class (any class within the Ext JS framework that extends Ext.Component)

- Indicates that the class, member, or guide is new in the currently viewed version

Member Icons

- Indicates a class member of type config

- Indicates a class member of type property

- Indicates a class member of type method

- Indicates a class member of type event

- Indicates a class member of type theme variable

- Indicates a class member of type theme mixin

- Indicates that the class, member, or guide is new in the currently viewed version

Class Member Quick-Nav Menu

Just below the class name on an API doc page is a row of buttons corresponding to the types of members owned by the current class. Each button shows a count of members by type (this count is updated as filters are applied). Clicking the button will navigate you to that member section. Hovering over the member-type button will reveal a popup menu of all members of that type for quick navigation.

Getter and Setter Methods

Getting and setter methods that correlate to a class config option will show up in the methods section as well as in the configs section of both the API doc and the member-type menus just beneath the config they work with. The getter and setter method documentation will be found in the config row for easy reference.

History Bar

Your page history is kept in localstorage and displayed (using the available real estate) just below the top title bar. By default, the only search results shown are the pages matching the product / version you're currently viewing. You can expand what is displayed by clicking on the button on the right-hand side of the history bar and choosing the "All" radio option. This will show all recent pages in the history bar for all products / versions.

Within the history config menu you will also see a listing of your recent page visits. The results are filtered by the "Current Product / Version" and "All" radio options. Clicking on the button will clear the history bar as well as the history kept in local storage.

If "All" is selected in the history config menu the checkbox option for "Show product details in the history bar" will be enabled. When checked, the product/version for each historic page will show alongside the page name in the history bar. Hovering the cursor over the page names in the history bar will also show the product/version as a tooltip.

Search and Filters

Both API docs and guides can be searched for using the search field at the top of the page.

On API doc pages there is also a filter input field that filters the member rows using the filter string. In addition to filtering by string you can filter the class members by access level, inheritance, and read only. This is done using the checkboxes at the top of the page.

The checkbox at the bottom of the API class navigation tree filters the class list to include or exclude private classes.

Clicking on an empty search field will show your last 10 searches for quick navigation.

API Doc Class Metadata

Each API doc page (with the exception of Javascript primitives pages) has a menu view of metadata relating to that class. This metadata view will have one or more of the following:

Expanding and Collapsing Examples and Class Members

Runnable examples (Fiddles) are expanded on a page by default. You can collapse and expand example code blocks individually using the arrow on the top-left of the code block. You can also toggle the collapse state of all examples using the toggle button on the top-right of the page. The toggle-all state will be remembered between page loads.

Class members are collapsed on a page by default. You can expand and collapse members using the arrow icon on the left of the member row or globally using the expand / collapse all toggle button top-right.

Desktop -vs- Mobile View

Viewing the docs on narrower screens or browsers will result in a view optimized for a smaller form factor. The primary differences between the desktop and "mobile" view are:

Viewing the Class Source

The class source can be viewed by clicking on the class name at the top of an API doc page. The source for class members can be viewed by clicking on the "view source" link on the right-hand side of the member row.

Architect 4.1


top

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 drop-down list from a data store.

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.

  • Field Container 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.

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

Form 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 Group A group of multiple checkboxes that are aggregated upon form submit into a single submit parameter.

  • 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 Field 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 Field 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.

  • Radio Group A field container with a specialized layout for arranging Ext.form.field.Radio controls into columns, and provides convenience for Ext.form.field.Radio methods for getting, setting, and validating the group of radio buttons as a whole.

  • Slider A draggable slider field.

  • TextArea A multi-line 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 is 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 multi-part 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 Stores 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.

Architect 4.1