Developing Jangaroo Applications with IntelliJ IDEA
This page documents how the Jangaroo IDEA plugins support developing JavaScript applications in ActionScript with Jangaroo 1 and 2. For Jangaroo 4 (used by CoreMedia LiveContext 3 and CMS 9), please refer to the Jangaroo-4-specific page. For additional information on how Ext AS / EXML development is supported, see Developing Ext AS Applications with IntelliJ IDEA. For general information on Jangaroo and IDEA, see Home.
All Jangaroo IDEA plugins add the following features:
- Adapted Maven import: IDEA can import Maven projects, but does not know about Jangaroo's Maven extensions. The Jangaroo plugins add support for dependencies between Jangaroo modules and automatically configure the Jangaroo compilers.
- Incremental compile: while you could just invoke Maven to compile your Jangaroo classes, IDEA offers much more elegant and faster compiler support. The plugins integrate the Jangaroo compiler into IDEA's incremental build process, so that only changed files are recompiled and redeployed. This results in a much faster turn-around.
- Deployment: A Jangaroo application aggregates scripts and other resources from all its modules. When building a multi-module project in IDEA, the Jangaroo IDEA plugins take care of all changed Jangaroo files being deployed into the Web application. Thus, the fast turn-around even works for multi-module projects.
- Jangaroo configuration UI: IDEA can be extended by so-called facets to let you edit module settings for new languages or tools. The Jangaroo plugins add such a facet for the ActionScript-to-JavaScript compiler. IDEA 10 and up supports artifacts that describe how a Web application is assembled. The plugins add a new packaging type that takes care of deploying Jangaroo resources.
The latest plugin Jangaroo 0.9 adds the following feature:
- Jangaroo SDK: supports the configuration of different versions of Jangaroo Tools, extending IDEA by a custom SDK type.
For Ext AS / EXML features added by the plugins, see Developing Ext AS Applications with IntelliJ IDEA.
Any Jangaroo plugin can be installed as usual using the IDEA plugin manager. Note that you need IDEA Ultimate Edition, because the Community Edition does not include AS3 support. Also, the bundled plugins "Maven Integration" and "Java EE Integration" must be activated for the Jangaroo plugin to be enabled. To chose the right plugin(s) to install, see section Plugins Overview. In the following, the usual case of installing Jangaroo 0.9 is described.
Invoke IDEA's plugin manager, either through the button on the top right of the welcome screen, or through "File | Settings | Plugins".
- IDEA 10: In the plugin manager, click on the "Available" tab and search for "Jangaroo".
- IDEA 11+: In the plugin manager, click on "Browse repositories..." and search for "Jangaroo".
Select "Jangaroo 0.9" and hit the "Download and Install" button. You will have to restart IDEA for the plugin to install (alas, it's not Eclipse).
Only after having installed the plugin, importing a Jangaroo Maven project ends with the expected result. (Without the plugin, IDEA does not import libraries correctly.)
This process always installs the latest version of the Jangaroo 0.9 IDEA plugin. Please check for updates regularly. When updating, do not forget to actually click the "Update Plugin" button or context menu, just selecting the plugin and clicking "OK" does not suffice.
To have a project to start with, we use a Jangaroo demo project available on GitHub. For the following steps, you need to have a git client installed and git enabled in IDEA. If you have neither, you can also download the project files as a zip and unpack to a local directory.
You can clone the project directly from IDEA, like follows. Select "Version Control | Checkout from Version Control | Git" (not "GitHub", since this only allows to do a local clone of your own GitHub repositories!).
In the opened dialog, enter git://github.com/CoreMedia/jangaroo-quickstart.git for "Git Repository URL", and specify the directory where you store your local projects as "Parent Directory". ("Directory Name" is automatically filled by IDEA, and "Origin Name" defaults to origin.) Press "Clone" and wait for IDEA to download the project.
Next, IDEA asks: "Would you like to create an IntelliJ IDEA project for the sources you have checked out to .../jangaroo-quickstart?" Answer "Yes". Continue with section "Importing a Jangaroo Maven Project".
Alternatively, download the project sources from GitHub:
- Open https://github.com/CoreMedia/jangaroo-quickstart
- Click "Downloads" button
- Click "Download .zip" button
- Save the file and unpack into a directory of your choice
Back in IDEA, select "File | New Project..." and follow instructions in the next section.
For importing a Jangaroo Maven Project, you have two options: either use IDEA's "New Project" wizard (either directly after checking out from version control or by selecting "File | New Project...", see previous section), or select "File | Open Project...". While the "New Project" wizard gives you more control over the import settings, the latter option is much faster, as it simply lets you chose the directory containing the pom.xml and opens the project without any further (stupid) questions.
If you like (stupid) questions, in the "New Project" wizard, select
- "Import project from external model", "Next >"
- "Maven", "Next >"
- Check that the "Root directory" points to your local project directory. If not, click "..." and select it.
- Check "Search for projects recursively" and "Import Maven projects automatically". If you have not used Maven from IDEA before, you may have to set "Environment settings...". Then, "Next >"
- The (only) Maven project
com.acme:my-joo:0.1-SNAPSHOT [my-joo]is already preselected. "Next >" - "Name" and "Project file location" can also be kept as-is. "Finish"
IDEA imports the project and updates its indexes.
Jangaroo's multi-module build process is based on Maven for managing dependencies and downloading the corresponding artifacts. Because IDEA's incremental build process could not easily be extended to support the Jangaroo extensions, you have to build via Maven once before building with IDEA. IDEA plus Jangaroo plugin do not support the full build process, but only what's necessary to update resources and debuggable JavaScripts after AS3 code changes in the project's modules. Thus, you also have to build via Maven if you use SNAPSHOT versions of external modules.
IDEA offers excellent Maven support. In a project imported from a Maven POM, you can browse the project, its modules, the Maven plugins and their goals in the "Maven Projects" window. To build the whole example project, select "my-joo > Lifecycle > install", then click the green 'play' button with the tooltip "Run Maven Build".
The Maven build process is started and you can watch its progress in the "Run" console window output. The output should end with BUILD SUCCESS.
You can now open the file jangaroo-quickstart/my-joo/my-joo-app/target/my-joo-app-0.1-SNAPSHOT/index.html in any browser and it runs the Jangaroo application (Enter your name and see a colorful greeting). Starting a Jangaroo application from the file system does not work for all application and in some cases makes debugging harder. For how to start a Web server (Jetty) via Maven and configure a corresponding IDEA run configuration is described in section "Debugging Applications".
After changing any source file, you can rebuild the whole project via Maven and reload the application in the browser. You may have to clear the browser cache to see your changes.
IDEA's Maven window even lets you run specific goals of the Jangaroo Maven plugin, which is in some cases much faster than running the whole build process. For example, you find the war-package goal of the my-app module in the "Maven Projects" window's tree under "my-joo-app > Plugins > jangaroo > jangaroo:war-package". You can run this goal just like the install goal by clicking the "Run Maven Build" button. For details on what the different Jangaroo Maven goals do, see Maven Build Process.
If you run some Maven goal(s) over and over again, it comes in handy that IDEA lets you store this call in a "Run Configuration". Just right-click the desired goal and chose "Create ''...". In the dialog that appears, you can do all kinds of Maven settings corresponding to command line options of the mvn tool, but for now, just confirm by clicking "OK". The new Run Configuration appears in drop down box in the center of the top toolbar. The green arrow next to it re-runs the currently selected Run Configuration, here, your Maven build, and can be invoked with the keyboard shortcut Shift+F10.
The IDEA Web Help contains extensive documentation of the Maven Projects Tool Window, which also covers creating Run Configurations.
Rebuilding the whole project on every change is quite cumbersome and takes too long. This is where IDEA's incremental build process comes in. It is invoked "Build | Make project" or by the keyboard shortcut Strg+F9. While on first invocation, an IDEA build run may not seem much faster than the Maven one, every following "Make Project" only compiles (and copies) files that have been changed, resulting in a lightning-fast turn-around!
There is one important thing: to be able to recompile and update single files, the incremental build process implemented by the Jangaroo Language IDEA plugin relies on Jangaroo's debug mode (see Maven Build Process and the Debugging Tutorial. In debug mode, every JavaScript file resulting from an ActionScript file is loaded into the browser separately. To activate debug mode, always make sure to add #joo.debug to the URL of your Jangaroo application. For the example project, assuming you use Windows and placed your project in C:\tmp, the debug-enabled URL would be
file:///C:/tmp/jangaroo-quickstart/my-joo/my-joo-app/target/my-joo-app-0.1-SNAPSHOT/index.html#joo.debug
In detail, the Jangaroo Language IDEA plugin adds support for two things that happen when you build via IDEA:
- For each changed
*.asfile under a source root of a module with a Jangaroo facet, Jangaroo's ActionScript-to-JavaScript compiler is invoked and creates or updates the corresponding JavaScript files in the module output directory configured in the Jangaroo Facet. - All changed resources of a Jangaroo module (this includes the output of the compiler from step one!) are updated in the Web application output directory.
The second step is not applicable for very simple Jangaroo projects that just consist of a single module that contains the Jangaroo code and the Web application, because there, the compiler generates JavaScript code directly into the Web output directory. But for multi-module projects (like the example project used here), code is generated into the module output directory first, and then copied into every Web application module that uses this module (just one in the example). See section "Inspecting and Changing Jangaroo Application Build Settings" for details.
The Jangaroo Language plugin adds a new facet to IDEA. IDEA uses facets to store module settings for a certain tool, for example there is a Web facet and a Flex facet. In the Jangaroo facet, the Jangaroo compiler settings can be inspected and changed. When importing from Maven (as described in the previous section), you usually do not have to care about facets, since they are created and configured by the Jangaroo Language IDEA plugin automatically.
However, if you want to check the settings or set up a Jangaroo project without Maven (which is not recommended, because it is much cumbersome work to download and unpack all needed libraries), you can find all facets in the "Project Structure" ("File | Project Structure", corresponding toolbar button, or Strg+Alt+Shift+S).
There are two views on the project's (Jangaroo) facets: One is opened by selecting "Modules" and clicking the + handle (first screen shot), the second by selecting "Facets" and clicking the + handle (second screen shot). Note that the my-joo-app module has a Jangaroo facet in addition to a Web facet, while the my-joo-lib module only has a Jangaroo facet. The IDEA Web Help provides more information on facets.
On the right-hand side, you can inspect the Jangaroo compiler settings this facet has stored for the corresponding module. These correspond to the command line switches of the ActionScript-to-JavaScript compiler. Most importantly, the "Output directory" can be checked and modified here.
Note that reimporting the Maven project from which these settings were imported overwrites your changes. Thus, the preferred way to change settings is to edit your pom.xml. IDEA provides very good assistance for editing a Maven POM: code completion (Strg-Space), documentation lookup (Strg-Q), error detection (red markers) and so on. IDEA will automatically do a Maven reimport when a pom.xml is changed, unless you did not check "Import Maven projects automatically". In that case, after editing a pom.xml, a yellow banner will appear, where you can click a link to reimport. Last resort is to click the yellow refresh button in the "Maven Projects" window ("Force Reimport All Maven Projects").
Similar to Jangaroo compiler settings, Jangaroo packaging settings are also imported from the Maven POM and can also be inspected and changed through IDEA's user interface.
Each Jangaroo module, i.e. each IDEA module with a Jangaroo facet, produces so-called "Jangaroo packaging output". This corresponds to the temporary module output documented on the Maven Build Process page. A Jangaroo application is a special IDEA module: it contains both a Web facet and a Jangaroo facet. Modules with a Web facet also produce packaging output.
Starting with version 10, IDEA has adopted Maven's notion of an artifact. An artifact is a file that contains the assembled module output. Again in the "Project Structure" dialog, IDEA shows a list of all the project's artifacts when selecting "Artifacts" on the left-hand side. For every Web module, IDEA automatically creates two artifacts: one of type "Web Application: Exploded" ("war exploded"), the other of type "Web Application: Archived" ("war"). The latter is nothing but a ZIP of the former one. When you select the exploded Web application artifact, IDEA shows you the "recipe" from which module packaging output the artifacts is assembled (see screen shot). So here you can see which resources and compilation results from Jangaroo library modules are copied into the Web application output.
One important control in this dialog is the check box labeled "Build on make". The Jangaroo Language IDEA plugin checks this option by default for every Jangaroo application module (i.e. a Web module that also has a Jangaroo facet). Otherwise, invoking "Make Project" (Strg-F9) after changing Jangaroo code in a library module would not have any effect on the deployed Web application!
When you have a complex project with more than one Jangaroo application module, it speeds up the development turn-around a bit if you uncheck "Build on make" for all but the application you are currently working on. Having multiple Jangaroo applications within one project sounds like a strange idea, but we have such a situation e.g. with integration test modules. Recall that Jangaroo library modules cannot be run on their own, but only as part of a Jangaroo application...
For more information on artifacts, see the IDEA Web Help page on artifacts.
IDEA comes with a Firefox plugin that allows to use IDEA's built-in debugger to connect to a JavaScript application running in Firefox. IDEA 10.5 adds a Chrome plugin for the same purpose. Since Jangaroo compiles ActionScript to very-similar-looking JavaScript, you can debug your Jangaroo application from inside IDEA!
Unfortunately, IDEA only allows setting breakpoints in files that are not excluded, and when (re)importing a project from Maven, all files under target are excluded in IDEA. Since Jangaroo generates JavaScript, the JavaScript files are located under target, namely at target/my-joo-app-0.1-SNAPSHOT/joo/classes. We need a trick to keep IDEA from excluding this directory. The trick is to manually remove the exclusion of target, then mark target/my-joo-app-0.1-SNAPSHOT/joo/classes as a source directory (blue folder, see screen shot TODO).
When reimporting the Maven project, IDEA excludes all folders under target but the my-joo-app-0.1-SNAPSHOT/joo/classes folder, so the generated JavaScript files are accessible now.
Next, let's create a JavaScript debug Run Configuration. From IDEA's main menu, select "Run | Edit Configurations". In the "Run/Debug Configuration" dialog which opens, click the yellow plus button ("Add New Configuration") and in the drop down menu, select "JavaScript Debug | Remote".
To be continued...