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.
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.
Public classes and class members are available for use by any other class or application code and may be relied upon as a stable and persistent within major product versions. Public classes and members may safely be extended via a subclass.
Protected class members are stable public
members intended to be used by the
owning class or its subclasses. Protected members may safely be extended via a subclass.
Private classes and class members are used internally by the framework and are not intended to be used by application developers. Private classes and members may change or be omitted from the framework at any time without notice and should not be relied upon in application logic.
static
label next to the
method name. *See Static below.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).
Let's look at each part of the member row:
lookupComponent
in this example)( item )
in this example)Ext.Component
in this case). This may be omitted for methods that do not
return anything other than undefined
or may display as multiple possible values
separated by a forward slash /
signifying that what is returned may depend on the
results of the method call (i.e. a method may return a Component if a get method calls is
successful or false
if unsuccessful which would be displayed as
Ext.Component/Boolean
).PROTECTED
in
this example - see the Flags section below)Ext.container.Container
in this example). The source
class will be displayed as a blue link if the member originates from the current class
and gray if it is inherited from an ancestor or mixed-in class.view source
in the example)item : Object
in the example).undefined
a "Returns" section
will note the type of class or object returned and a description (Ext.Component
in the
example)Available since 3.4.0
- not pictured in
the example) just after the member descriptionDefaults to: false
)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.
classInstance.method1().method2().etc();
false
is returned from
an event handler- 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
- 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
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.
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.
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.
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.
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:
Ext.button.Button
class has an alternate class name of Ext.Button
). Alternate class
names are commonly maintained for backward compatibility.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.
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:
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.
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.
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.
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
.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
.
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.