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.
Ext Direct is a platform and language agnostic remote procedure call (RPC) protocol. Ext Direct allows for seamless communication between the client side of an Ext JS application and any server platform that conforms to the specification. Ext Direct is stateless and lightweight, supporting features like API discovery, call batching, and server to client events.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
Ext Direct is partially based on JSON (see http://www.json.org or RFC 4627 ), and utilizes HTML Form-based File Uploads ( RFC 1867, RFC 2388 ).
Server MAY support publishing its API to Clients via API discovery mechanism. If API discovery is supported the Server MUST respond to HTTP GET requests at preconfigured URI, returning a document with a correct content type for the browser to interpret this document as JavaScript code.
The Server API declaration MUST be valid JavaScript code that results in creation of a set of nested Objects assigned to a variable that can later be passed to Ext Direct initialization code in the Client application. It is RECOMMENDED that the code also conforms to stricter rules of JSON object syntax, for the benefit of non-JavaScript implementations that might try to parse the API declarations as JSON.
An example of API declaration code:
var Ext = Ext || {};
Ext.REMOTING_API = {
"id": "provider1",
"url": "ext/direct/router",
"type": "remoting",
"actions": {
"Album": [{
"name": "getAll",
"len": 0
}, {
"name": "add",
"params": ["name", "artist"],
"strict": false
}, {
"name": "delete",
"len": 1
}]
}
};
The JavaScript Object of the API declaration MUST contain the following mandatory properties:
url
- The Service URI for this API.type
- MUST be either remoting
for Remoting API, or polling
for Polling API.actions
- A JavaScript Object listing all Actions and Methods
available for a given Remoting API. MUST be omitted in Polling API
declarations.The API declaration MAY also contain the following OPTIONAL properties:
id
- The identifier for the Remoting API Provider. This is
useful when there are more than one API in use.namespace
- The Namespace for the given Remoting API.timeout
- The number of milliseconds to use as the timeout
for every Method invocation in this Remoting API.Any other properties are OPTIONAL.
Each Action within the actions
property of the API declaration is an
Array of Objects that represent Methods. Actions do not have properties
in themselves. Action names MAY be nested, i.e. an Action may contain
other Actions as well as Methods.
Method declaration MUST have the following properties:
name
- The name of this Method. MUST be unique within its Action.Each Method is fully qualified by Action and Method names concatenated with dot character (.), prefixed by optional Namespace:
[Namespace.]Foo.Bar.baz
Where Foo
is outer Action name, Bar
is inner Action name, and baz
is the Method name.
Method declaration MUST have one of the following mutually exclusive properties that describe the Method's calling convention:
len
- The number of arguments required for Ordered Methods. This
number MAY be 0 for Methods that do not accept arguments.params
- An array of parameters supported by a Named Method.
This array MAY be empty.formHandler
- A JavaScript Boolean value of true
indicates that
this Method accepts Form submits.Ordered Methods MUST always conform to their calling convention. When Remoting Method proxy function is called for an Ordered Method, it MUST be supplied with exactly the number of arguments required, in exactly the same order as required by the Method. If less than required number of arguments is passed, the Router MAY choose to return an Exception without invoking the actual Method.
Named Methods MAY use strict
property to control how the arguments
will be checked and passed to the Server when a Method is called:
strict
is set to true
, only arguments with names listed in the
params
array are sent to the Server; any other arguments are discarded.
This is the default behavior.strict
is set to false
, all arguments are passed to the Server.
The Router SHOULD pass all arguments to the actual Method.The Router MAY choose to return an Exception if some of the listed
parameters are missing, and omit invoking the actual Method. If the params
Array is empty and strict
property is set to false
, the Router MUST NOT
perform any argument checks and MUST pass all arguments to the invoked
Method.
An example of a Named Method with all optional parameters:
"actions": {
"TestAction": [{
"name": "named_no_strict",
"params": [],
"strict": false
}]
}
Method declaration MAY contain the optional metadata
property that
defines the type of Call Metadata accepted by the Method. If the metadata
property is not present in Method declaration, the Client MUST NOT send
call metadata to the Server for any invocation of that Method.
The metadata
property, if present, MUST be a JavaScript object with the
following properties:
len
- The number of arguments required for by-position Call Metadata.
This number MUST be greater than 0.params
- The Array of names of the supported for by-name Call Metadata.
This Array MAY be empty.strict
- JavaScript Boolean value that controls how Call Metadata
arguments are checked.When present, Call Metadata arguments MUST conform to their calling convention. Call Metadata calling convention MAY be different from the main Method arguments calling convention, e.g. an Ordered Method MAY accept by-name Call Metadata, or Named Method MAY accept by-position Call Metadata.
The argument checks are performed the same way as with main Method arguments.
Some examples of Method declarations accepting Call Metadata:
"actions": {
"TestAction": [{
"name": "meta1",
"len": 0,
"metadata": {
"len": 1
}
}, {
"name": "meta2",
"len": 1,
"metadata": {
"params": ["foo", "bar"],
"strict": false
}
}, {
"name": "meta3",
"params": [],
"strict": false,
"metadata": {
"len": 3
}
}, {
"name": "meta4",
"params": ["foo", "bar"],
"metadata": {
"params": ["baz", "qux"]
}
}]
}
Declaring Polling API is OPTIONAL. If the Server implements more than one Event Provider, it is RECOMMENDED to include Polling API declarations along with Remoting API declaration in the same JavaScript document.
An example of API declaration with one Remoting API and one Polling API:
var Ext = Ext || {};
Ext.REMOTING_API = {
"id": "provider1",
"type": "remoting",
"url": "ext/direct/router",
"actions": {
"User": [{
"name": "read",
"len": 1
}, {
"name": "create",
"params": ["id", "username"]
}]
}
};
Ext.POLLING_API = {
"id": "provider2",
"type": "polling",
"url": "ext/direct/events"
};
A remoting call is represented by sending a Request object, or multiple
Request objects, to a Server. Request(s) are encoded in JSON and are
sent as raw payload in a HTTP POST request to the Service URI advertised
as the url
in API Declaration. There MUST not be any other data present
in the HTTP POST, except valid JSON document containing one or more
Requests. Among HTTP headers for the POST request, there MUST be the
Content-Type header with the value of "application/json". The Client
MUST use UTF-8 character encoding for the Request document.
A Request is an Object with the following members:
type
– MUST be a string "rpc".tid
– The transaction id for this Request. MUST be an integer
number unique among the Requests in one batch.action
– The Action that the invoked Method belongs to. MUST be
specified.method
– The Remoting Method that is to be invoked. MUST be
specified.data
– A set of arguments to be passed to the called Remoting
Method. MUST be either null
for Methods that accept 0 (zero)
parameters, an Array for Ordered methods, or an Object for Named methods.metadata
- OPTIONAL set of meta-arguments to be made available
to the called Remoting Method, if provided by the Client. If no metadata
is associated with the call, this member MUST NOT be present in the
Request.A typical JSON encoded Request Object for an Ordered Method may look like this:
{"type":"rpc","tid":1,"action":"Foo","method":"bar","data":[42,"baz"]}
A typical JSON encoded Request object for a Named Method may look like this:
{"type":"rpc","tid":2,"action":"Foo","method":"qux","data":{"foo":"bar"}}
A typical JSON encoded Request object for an Ordered Method with by-name Call Metadata may look like this:
{"type":"rpc","tid":3,"action":"Foo","method":"fred","data":[0],
"metadata":{"borgle":"throbbe"}}
Remoting Requests MAY be batched, in which case the Requests MUST be
sent as an Array of Request Objects with unique tid
members:
[
{"type":"rpc","tid":3,"action":"Foo","method":"frob","data":["foo"]},
{"type":"rpc","tid":4,"action":"Foo","method":"blerg","data":["qux"]}
]
The Server MUST support Request batching, and SHOULD attempt to return call invocation Results or Exceptions in the same order.
A response to a Remoting call MUST contain either a Result, or an Exception for each Request. Responses are encoded in JSON and returned to the Client as raw HTTP response payload, with Content-Type header of "application/json" and character encoding of UTF-8.
If Requests were sent as a batch the Server MUST return the corresponding
Responses only after all Requests were processed by the Router, and the
Responses SHOULD follow the same order as the original Requests. For each
Response, the corresponding tid
member of the original Request MUST be
passed back unchanged by the Server.
A Result is an Object with the following members:
type
— MUST be a string "rpc".tid
— The transaction id for this Response. MUST be the same
as in the original Request.action
— The Action to which the invoked Method belongs to.
MUST be the same as in the original Request.method
— The name of the invoked Remoting Method. MUST be
the same as in the original Request.result
— The data returned by the Method. MUST be present
in the Response object, but MAY be null
for Methods that do not
return any data.A typical JSON encoded Array of Response objects may look like this:
[
{"type":"rpc","tid":1,"action":"Foo","method":"bar","result":0},
{"type":"rpc","tid":2,"action":"Foo","method":"baz","result":null}
]
An Exception is an Object with the following members:
type
— MUST be a string "exception".tid
— The transaction id for this Response. MUST be the same
as in the original Request.action
— The Action to which the invoked Method belongs to.
MUST be the same as in the original Request.method
— The name of the invoked Remoting Method. MUST be
the same as in the original Request.message
— The error message. MUST be present.where
— OPTIONAL description of where exactly the exception
was raised. MAY contain stack trace, or additional information.A typical JSON encoded Exception may look like this:
{
"type": "exception",
"tid": 3,
"action": "Foo",
"method": "frob",
"message": "Division by zero",
"where": "... stack trace here ..."
}
A remoting form invocation is represented by submitting an HTML form with HTTP POST request. The form content MUST conform to (HTML 4.01 specification)[5]. The Server MUST support both "application/x-www-form-urlencoded" and "multipart/form-data" content types for backwards compatibility. The Client MAY choose to implement only "multipart/form-data" encoding.
There MUST be only one Method invocation per submitted form. The Client MUST use form submission for each Method with Form Handler calling convention declared in Remoting API.
The form SHALL contain the following fields:
extType
- MUST be a string "rpc".extTID
- The transaction id for this Request. MUST be an integer
number unique among the Requests in one batch.extAction
- The Action that the invoked Method belongs to. MUST
be specified.extMethod
- The Remoting Method that is to be invoked. MUST be
specified.extUpload
- Stringified Boolean value ("true"
or "false"
)
indicating that file uploads are attached to this form submission.The form MAY contain the metadata
field if there is Call Metadata
associated with the given form submission.
The form MAY contain other fields in addition to the mandatory ones listed above. These additional fields MUST be passed to the invoked Method as Named arguments.
When the form is used to upload files, encoding type MUST be "multipart/form-data".
The Server MUST respond to the form submission with a JSON document containing a valid Response or Exception object as described in sections 4.2.1 and 4.2.2. The document MUST have content type of "application/json" and UTF-8 character encoding.
When the form request contained one or more file uploads, the Server MUST return a valid HTML document with correct content type for the browser to interpret this document as HTML. The document MUST have UTF-8 character encoding.
The HTML document MUST contain a valid JSON encoded Response or Exception
as described in sections 4.2.1 and 4.2.2, enclosed in HTML <textarea>
tags.
An example of a file upload response may look like this:
<!DOCTYPE html>
<html>
<head>
<title>File upload response</title>
</head>
<body>
<textarea>{JSON RESPONSE HERE}</textarea>
</body>
</html>
The Server MAY implement OPTIONAL event polling mechanism. Event polling is performed by periodically making HTTP GET requests to the Server. There MAY be more than one Event Provider per Server; in that case each Event Provider MUST have a separate Service URI.
An event poll request in its basic form is an HTTP GET request to the Service URI of the polled Event Provider. The Server MUST maintain a list of active Poll Handler methods for every Event Provider, and invoke each Poll Handler method every time a poll request is made. The Server MAY support passing arguments to Poll Handler methods via HTTP GET request URI but it is not required.
An event poll response MUST be a valid JSON document with a correct content type for the browser to interpret this document as JSON. The document MUST use UTF-8 character encoding.
The event poll response should contain an array of Event objects. This array MAY be empty if no Events are pending for the given request. The Server MUST NOT include Exception objects in the response array.
An event object MUST contain the following properties:
type
- MUST be a string "event".name
- Event name, MUST be a string.data
- Event data, SHOULD be any valid JSON data.An example of a typical Event object:
{
"type": "event",
"name": "progressupdate",
"data": {
"processId": 42,
"progress": 100
}
}
Ext Direct makes use of the following terms:
window
object
will be used.[Namespace.]Action.Method
.