Sencha Cmd Metadata
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.
The metadata tracked by the Sencha Cmd compiler has a variety of uses, some of which we will examine in this guide. To support these uses, the compiler can export and format this metadata in several different ways, which we will cover here as well.
The following guides are recommended reading before proceeding further:
metaOne of the major new dimensions provided by the compiler is its ability to export metadata
in various formats. This feature is used to produce the ext.js "bootstrap" file that
contains various classes and a block of metadata about all of the files in the
framework.
There are several forms of metadata that the compiler can export using the meta command:
Note. This process is handled automatically for applications generated by Sencha Cmd. If you are not using Sencha Cmd generated application, this section describes how to achieve the same results manually.
The primary use for the meta command is to create your own "bootstrap" file. This file
gives the framework the same level of awareness of your application code that it has of
the framework code itself.
The simplest way to manage your bootstrap file is to store it alongside your markup file.
If that won't work for you, read on to see how to manage relative paths. If you have your
markup file in a source folder in your classpath, you need to tell the compiler to ignore
the bootstrap file. Do this using the -ignore switch:
sencha compile -classpath=sdk/src,app -ignore bootstrap.js \
...
requiresThe end of "ext-debug.js" contains these two function calls:
Ext.ClassManager.addNameAlternateMappings({
"Ext.draw.engine.ImageExporter": [],
"Ext.layout.component.Auto": [],
...
});
Ext.ClassManager.addNameAliasMappings({
"Ext.draw.engine.ImageExporter": [],
"Ext.layout.component.Auto": [
"layout.autocomponent"
],
...
});
It is the presence of these two pieces of metadata that allow wildcards to be used in
requires statements. That is:
Ext.define('MyApp.App', {
requires: [
'Ext.grid.*'
],
...
});
All that is required to use wildcards in your own code is to provide the same bootstrap data for your app.
This command will produce a file that does just that:
sencha compile -classpath=app \
meta -alias -out bootstrap.js and \
meta -alt -append -out bootstrap.js
The above command line tells the compiler to read in the source in the app folder and
generate two pieces of metadata. The second piece of metadata is written to the same
output file as the first, but using the -append option to append to the file and not
replace it.
Once you have the "bootstrap.js" file, change your page like so to add it to the
x-bootstrap section:
<html>
<head>
<!-- <x-compile> -->
<!-- <x-bootstrap> -->
<script src="../sdk/ext-dev.js" type="text/javascript"></script>
<script src="bootstrap.js" type="text/javascript"></script>
<!-- </x-bootstrap> -->
<script src="app/app.js" type="text/javascript"></script>
<!-- </x-compile> -->
</head>
<body></body>
</html>
The "bootstrap.js" file needs to be regenerated if you do any of the following:
This rebuild of the bootstrap data can be handled in a variety of ways, but the fundamental question is whether to keep these files in source control or require developers to generate them locally. Both approaches work and can be automated to some degree.
Note. For applications generated by Sencha Cmd, this is handled as part of the build
process of sencha app build. Alternatively, refreshing just the bootstrap instead of
performing a full build is accomplished by the sencha app refresh command.
In large applications it can be helpful to organize your namespace using multiple source
trees. In fact, Ext JS itself uses three source trees. This approach, however, has always
presented problems for the dynamic loader requiring loader paths to be configured by hand
to work around the issue. The compiler, however, has complete knowledge of class-to-file
relationships given all of the source in the classpath. And the meta command can export
that data for use in your application.
If you are already sold on the above to create a "bootstrap.js", this data can be added
by
adding one more meta command (of course, the classpath will contain multiple folders in
this case):
sencha compile -classpath=src1,src2,src3 \
meta -alias -out bootstrap.js and \
meta -alt -append -out bootstrap.js and \
meta -loader -append -out bootstrap.js
Now the "bootstrap.js" file solves both problems. With this approach, the following
things
will also require you to rebuild "bootstrap.js":
Note. This part is also handled automatically for applications generated by Sencha Cmd.
-base-pathFor many good reasons, paths need to be relative. Whenever you deal with relative paths,
however, you need to solve the problem of where those relative paths are based. In the
above examples we cheated a bit and placed the "bootstrap.js" file next to the markup
file. This leverages the fact that the meta command defaults the base folder to the
location of the output file.
When this is not the case, you need to tell the meta command the base for determining
relative paths. Let's say we want to move the "bootstrap.js" file in to the "build"
folder
(perhaps because we are not keeping it in source control). Since our page is in the
current
folder and our source is in the "app" folder, this will generate the proper relative
paths:
sencha compile -classpath=src1,src2,src3 \
meta -alias -out build/bootstrap.js and \
meta -alt -append -out build/bootstrap.js and \
meta -loader -append -base-path . -out build/bootstrap.js
Since the -alias and -alt modes do not deal in paths, the -base-path option is only
needed on the -loader use of the meta command.
By default, the meta command exports metadata in JSONP format using a function call
wrapper appropriate for the type of metadata requested. If a different function call is
desired or you want the data in JSON format, you can request this in the meta command.
In the example below, the aliases.json file will contain the alias data in JSON format.
You cannot use -append in this case because JSON format requires a single, top-level
object or array.
sencha compile -classpath=src1,src2,src3 \
meta -alias -json -out aliases.json
In this next example, we customize the JSONP wrapping by supplying the function to call:
sencha compile -classpath=src1,src2,src3 \
meta -alias -jsonp Foo.bar.doAliases -out aliases.js
This form can work with -append because it produces JavaScript code. The output of the
above looks roughly like this:
Foo.bar.doAliases(
// ... the JSON data ...
);
An occasionally useful form of metadata supported by the meta command is filename data.
That is, the list of a files in the proper, dependency order. In many ways this is the
same
as the other meta data forms in that this data can be exported in JSON or JSONP format,
and
can be combined using -append.
The first difference with -filenames is that the default format is text. To produce JSON
or JSONP, you must specify one of the -json or -jsonp options.
In the default mode of text, the filenames are written as lines of text, one filename per
line. The following command will create "filenames.txt":
sencha compile -classpath=src1,src2,src3 \
meta -filenames -out filenames.txt
Each line of the file can be decorated using the -tpl option. Because of the special
characters needed for this example, we use a response file to hold the template. We put
this in "template.txt", like this:
<script src="{0}" type="text/javascript"></script>
Then run the following command.
sencha compile -classpath=src1,src2,src3 \
meta -filenames -tpl @template.txt -out filenames.txt
We now have a chunk of markup that will "script-tag in" all of the files in their correct order.
For example:
<script src="ext/src/ShadowPool.js" type="text/javascript"></script>
<script src="ext/src/Shadow.js" type="text/javascript"></script>
The compiler normally reads metadata such as classes, namespaces and dependencies by parsing source code. In situations where this is hidden, for example, when obfuscating a library, the compiler will be unaware of any defined classes or their dependencies.
This form of metadata export can be used to provide the "symbols" for such libraries so that users can still compile their application using Sencha Cmd.
sencha compile -classpath=src1,src2,src3 \
meta -definitions -out symbols.js
The above creates a file that contains directives like this:
// @define Foo.bar.Thing
// @require Ext.panel.Panel
// @uses Ext.layout.container.HBox
These directives are recognized by the compiler and introduce the symbolic names needed for user code to compile. These symbols should be added to the obfuscated library file to ensure that the library code is concatenated in the right order.
Cmd | Terms of Use