close

Filter

loading table of contents...

Studio Developer Manual / Version 2101

Table Of Contents

5.2 Ext JS with ActionScript and MXML

While the CoreMedia Studio code you see at runtime is all JavaScript, CoreMedia Studio is completely written in ActionScript and MXML, an XML format to describe components declaratively. CoreMedia calls this combination of tools and approach Ext AS (where obviously, "ActionScript" replaces the "JavaScript" in Ext JS. ActionScript and MXML are the languages originally used by Apache Flex (formerly Adobe Flex), but unlike Ext AS, Flex applications run in FlashPlayer or Adobe Air and use Flex components, not Ext JS. Still, Ext AS applications benefit from existing Flex tool support, for example offered by IntelliJ IDEA.

Ext AS is designed to provide a statically typed way to implement Ext JS applications. MXML is used to declaratively describe Ext UI components (or component trees). During the build process, MXML files are temporarily compiled to ActionScript 3, which in a second step are then compiled further to JavaScript. For localization, property files are provided as Flex ResourceBundles, so that you can access a localization key as in Flex and a Flex IDE will support you in doing so.

While it is possible to extend CoreMedia Studio with components written in JavaScript, it is recommended to use Ext AS. With the Jangaroo project, CoreMedia offers Open Source tools and libraries that provide complete support for this development approach. All public CoreMedia Studio APIs are available as ActionScript 3 ASDoc and source stubs, so that you can set up your IDE to provide code completion, validation, and documentation lookup.

This section states the rationale for using Ext AS, gives you a rough overview of the approach and tools, and contains references to the detailed online documentation, which is part of the Jangaroo Open Source project.

Ext AS: the Typed Version of Ext JS

In contrast to JavaScript and JSON, ActionScript and MXML are typed languages. While originally, typed languages were chosen to find errors early at compile time, the more important advantage today is that much better tools can be built to ease and speed up development. In a good IDE, errors and possible mistakes are detected as you type, and the IDE even makes suggestions as to what to type next, how to resolve errors, and lets you look up documentation easily. Using a typed language is important for the IDE to be able to derive what the code is referring to. With an untyped language, only limited IDE support is possible, and the IDE has use more or less imprecise heuristics, and will in many cases make ambiguous (or even erroneous) suggestions.

Source File Types and Compilers

CoreMedia Studio is an Ext AS application and as such uses four different kinds of source files:

  • MXML files to specify reusable UI components declaratively

  • Property files for localized texts and labels

  • ActionScript files for all other application code

  • JavaScript files for bootstrapping code and CKEditor extensions

Consequently, the Jangaroo build process invokes the Jangaroo compiler to translate all three non-JavaScript source file types to JavaScript and then proceeds to handle all JavaScript files. Internally, both MXML and Property files are intermediately translated to ActionScript and then reuse the ActionScript-to-JavaScript compiler.

Fitting into the Maven build process, the compiler is usually invoked through Maven, but there are also plugins for IntelliJ IDEA that extend IDEA's incremental build process and invoke the compiler directly, resulting in a much faster turnaround. Currently, CoreMedia strongly recommends using IntelliJ IDEA 2016.3.x for Jangaroo development for highest productivity.

Online Jangaroo Documentation

Since CoreMedia is not primarily a manufacturer of development tools, all these tools are released as Open Source under an Apache 2 license. Consequently, the tools are not documented here, but on the Jangaroo Website and in Jangaroo's Wiki. CoreMedia Studio uses Jangaroo version 4.

Since the CoreMedia workspace uses Maven, you can ignore all references to direct compiler command line interfaces or Ant. When starting with Jangaroo development, it is recommended to work through the documentation in the following order:

  1. Start with the Jangaroo Tutorial to get familiar with writing, building, and starting a Jangaroo application.

  2. Continue with Developing Jangaroo Applications with IntelliJ IDEA. This adds two aspects: on the one hand, the example project, like CoreMedia Studio, uses a multi-module setup, on the other hand, working with Jangaroo in IntelliJ IDEA is explained in detail. Please consider the multi-module example even if you use another IDE!

  3. In parallel, you can start getting acquainted with Ext JS (see Section 5.1, “Ext JS Primer”).

  4. Now you are ready to face Ext AS, including MXML, which is documented as Ext AS: Creating Ext JS Applications with ActionScript and MXML.

  5. Integrating Ext AS and especially MXML in IntelliJ IDEA requires some additional explanation; there is an IDEA plugin Jangaroo 4 that you're highly encouraged to install to get optimal Jangaroo support. All about Ext AS and IDEA is documented as Developing Ext AS Applications with IntelliJ IDEA.

If you have questions about any Jangaroo tool, please post in the Jangaroo user group. You can also write an email to info@jangaroo.net.

If the question or problem is Studio related, please contact CoreMedia support.

ActionScript Documentation

Being integrated in our ActionScript programming model, the documentation of all Ext JS components and public API components of CoreMedia Studio is accessible through the ASDoc (ActionScript Documentation) linked from the Studio's most recent release page, which is available at the CoreMedia download section or from our documentation site at http://documentation.coremedia.com.

In the ASDoc, each Ext AS component is represented by one ActionScript class. This class serves two purposes: It represents the type of an Ext Config object as well as the type of the resulting component or other object. Ext JS uses Config objects during construction of a UI component tree and sometimes to instantiate components, plugins or other objects in lazily. In Ext JS 6, with very few exceptions, properties configured via a Config object can be changed after the component has been created. While Ext JS uses set-methods for this, Ext AS makes modifying access to Config options transparent: independent of using a Config object or an instantiated component, you can use property assignment syntax: myPanel.title = "Studio"; is transparently converted to calling setTitle() when myPanel is a component instance, not a Config object. To declare new Config options, simply declare an ActionScript field and annotate it with [Bindable] to trigger this magic. Any fields declared in MXML inside <fx:Declarations> is automatically [Bindable].

For Ext JS components, the package of each class matches the official Ext JS documentation by Sencha, except that the top-level package is ext instead of Ext. The name, however, has been complemented to be meaningful without its containing package, because in ActionScript, classes are imported and the package usually is not mentioned when the class is used in code. To avoid frequent name clashes between classes with the same name from different packages, such classes are aliased. A full table with the mapping can be found in the Ext AS online documentation.

To support the Ext JS concept of xtype, a shorthand name for a component, Flex offers so-called component libraries. A component library aggregates several classes under a common namespace that can be used in MXML. The classes can be aliased to avoid name clashes. There is a component library for all Ext JS components, layouts, plugins, etc., and some component libraries for Studio objects:

  • module ext-as: namespace exml:ext.config;

  • module ui-components: namespace exml:com.coremedia.ui.config;

  • module editor-components: namespace exml:com.coremedia.cms.editor.sdk.config.

The exml: namespace prefix dates back to when Ext AS used a proprietary MXML variant called EXML (see glossary). The namespaces have been kept stable for backwards compatibility.

Configuring Components

Each configuration class defines the configuration attributes of that class. You can use instances of the configuration classes for configuring Ext JS components in a type-safe way, although it is still possible to write component configurations as a plain JSON object. The code fragments

Ext.create({
  xtype:
    "com.coremedia.cms.editor.sdk.config.stringPropertyField",
  itemId: "linktextEditor",
  propertyName: "linktext"
});

Example 5.3. Component instantiation using Ext JSON


and

Ext.create(StringPropertyField, {
  itemId: "linktextEditor",
  propertyName: "linktext"
});

Example 5.4. Component instantiation using typed wrapper


and

var stringPropertyFieldConfig:StringPropertyField =
  StringPropertyField({});
stringPropertyFieldConfig.itemId = "linktextEditor";
stringPropertyFieldConfig.propertyName = "linktext";
Ext.create(stringPropertyFieldConfig);

Example 5.5. Component instantiation using typed setters


are equivalent. While the first two code fragments are like you would create components in Ext JS, only the last variant actually uses the static type system and thus provides much better IDE support and allows safe refactoring. Note however that the most convenient (and thus recommended) way to write component configurations is to use MXML rather than ActionScript.

The last example shows how a configuration class itself can be initialized as a plain JavaScript object, while still allowing typed accesses later. Note that the type cast used for this pattern actually modifies the JavaScript object: It adds an xclass attribute with the fully-qualified name of the class and an xtype attribute (if the class represents a component and has an xtype) that is later used to instantiate the desired class.

When developing with MXML, you don't have to deal with the ActionScript code manually: The MXML compiler automatically generates code similar to the second variant shown above. In this case, the reduced type checking is offset by the checks at MXML level during development.

MXML files are described in more detail in the Jangaroo tools wiki. The namespaces to use in MXML files in the context of CoreMedia Studio are the component library namespaces mentioned above:

  • exml:com.coremedia.ui.config for the reusable components of the CoreMedia UI toolkit and

  • exml:com.coremedia.cms.editor.sdk.config for the actual CoreMedia Studio components.

Search Results

Table Of Contents
warning

Your Internet Explorer is no longer supported.

Please use Mozilla Firefox, Google Chrome, or Microsoft Edge.