Adobe Flex 3 Help

Creating modules in Flex Builder

The following steps describe how to create a new module in Flex Builder. After you create a new module, you can compile it.

Create modules in Flex Builder

  1. In Flex Builder, select File > New > MXML Module. The New MXML Module dialog box appears.

    New MXML Module dialog box.

  2. Select a parent directory for the module. You typically store modules in the same directory as the main application so that relative paths to shared resources are the same.
  3. Enter a filename for the module; for example, MyModule.
  4. Enter the Width, Height, and Layout properties for the module.
  5. (Optional) Select the Optimize for Application radio button to excludes from the module classes that are used by the application. (This can result in smaller download sizes for your SWF files.) From the pop-up menu, select the application that will be used to optimize this module. For more information, see Optimizing modules in Flex Builder.

    Select Do not Optimize to include all classes in the module, whether or not they are defined in the main application. This can improve the performance of the incremental compilation. In addition, you can load the module into any application, not just the application that you select here, because it has all of its dependencies compiled into it.

  6. Click Finish. Flex Builder adds a new MXML module file in your project.

    The following example shows the default contents of this new application:

    <?xml version="1.0" encoding="utf-8"?>
<mx:Module xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute" width="400" height="300">
</mx:Module>

Compiling modules in Flex Builder

In Flex Builder, you can either run the module as if it were an application or you can build the module's project. If the modules are in the same project as your Flex application, then when you run your application, Flex Builder compiles the modules' SWF files for you. The SWF files are then loaded into the application at run time.

You cannot run the module-based SWF file as a stand-alone Flash application or load it into a browser window. It must be loaded by an application as a module. If you run the module in Flex Builder to compile it, you should close Adobe Flash Player or browser window and ignore any errors. Modules should not be requested by the Player or through a browser directly.

The module SWF files and main application SWF file are typically in the same directory, although Flex Builder compiles the modules at the same time as your application, regardless of their location (they can be in the same directory as the application or in subdirectories).

You can also create a separate Flex or ActionScript project for each module or for groups of modules. This gives you greater control over how modules are compiled because each project can have different compiler options than the application or other modules. It also lets you compile the module's project or projects without compiling the application. However, this approach requires that you manually compile each module before compiling the application, unless you compile all open projects in Flex Builder at one time.

If you compile modules separately from the main application, you must be sure to include or exclude debugging information, based on whether you want to debug your application and modules. For more information, see Debugging modules in Flex Builder.

The Flex Builder workflow is designed around associating modules with a single application. If you want to use modules across multiple applications, consider encapsulating the code in a library component or class and including that in a simple module for each application. Modules are not intended to be used for cross-application code reuse; that is for libraries.

Using multiple projects for modules

When you set up your project's architecture, you can decide to include modules in your application's project, create a separate project for each module, or create a separate project for all modules.

Using one project for each module has the following benefits:

  • Module projects can be located anywhere in the workspace.
  • Module projects can have their own compiler settings, such as a custom library path.

Using one project for each module has the following drawbacks:

  • Having many projects uses more memory.
  • Having many projects in a single workspace can make the workspace crowded.
  • By default, when you compile the application, not all module projects are compiled even if they have changed.
  • To optimize your module's file size, you must manually apply the load-externs and link-report compiler options.

A related approach is to use a single project for all modules, while keeping the application in its own separate project. This has some of the drawbacks of using a single project for both the application and the modules, but it has many of the same benefits as using a separate project for each module.

Using one project for all modules has the following benefits:

  • The module project can be located anywhere in the workspace.
  • You can compile just the modules or just the application, without having to recompile both at the same time.
  • The module project can use the load-externs compiler option to remove overlapping dependencies.

Using one module project for all modules has the following drawbacks:

  • All of the modules in the module project must use the same compiler settings, such as the library path.
  • By default, when you compile the application, the module project is not compiled even if the module project has changed.
  • To optimize your module's file size, you must manually apply the load-externs and link-report compiler options.

Creating projects for modules

When creating a separate project for modules, you change the module project's output folder to a directory that is used by the application. You also suppress the generation of wrapper files.

Create a separate project for modules in Flex Builder

  1. Create a main project.
  2. Create a new project for your module or modules.
  3. Right click the module's project and select Properties. The Properties dialog box appears.
  4. Select the Flex Build Path option.
  5. Change the Output Folder to point to the MainProject modules directory. For example, change it to the following:
    ${DOCUMENTS}\MainProject\assets

    This redirects the output of your module's compilation to your application project's (MainProject) assets directory. In your main application, you can point the ModuleLoader url property to the SWF files in the assets directory. The value of this property is relative to the output folder.

  6. Click OK to save your changes.
  7. Open the project properties again and select the Flex Compiler option.
  8. Deselect the Generate HTML Wrapper File option. This prevents the module's project from generating the HTML wrapper files. You typically use these files only for the application. For modules, they are not necessary.
  9. Click OK to apply the changes.

Compiling projects for modules

Compiling multiple projects in Flex Builder is a common operation. First you choose the order in which you want the projects to be compiled and then you compile all projects at the same time.

Compile all projects at the same time in Flex Builder

 From the main menu, select Project > Build All.

Flex builds all projects in the workspace. The application files are added to each project's output folder. If you haven't already chosen to save files automatically before a build begins, you are prompted to save the files.

If you want to change the build order, you use the Build Order dialog box. This is not always necessary. Projects that use modules need to be compiled only by the time the main project application runs, not as it is compiled. In most cases, the default build order is adequate.

However, if you want to eliminate overlapping dependencies, you might need to change the build order so that the main application is compiled first. At that time, you use the link-report compiler option to generate the linker report. When you compile the modules, you use the load-externs compiler option to use the linker report that was just generated by the shell application. For more information on reducing module size, see Optimizing modules in Flex Builder.

Change the build order of the projects

  1. Open the Preferences dialog and select General > Workspace > Build Order.

    The Build Order dialog box appears.

  2. Deselect the Use Default Build Order checkbox.
  3. Use the Up and Down buttons to reorder the projects in the Project Build Order list. You can also use the Remove Project button to remove projects that are not part of your main application or that are not modules used by the application. The removed project will still be built, but only after all the projects in the build order list are built.
  4. Click OK.
  5. Modify the build order as needed and then click OK.

If you create dependencies between separate projects in the workspace, the compiler automatically determines the order in which the projects are built, so these dependencies are resolved properly.

When you use a separate project for each module, you can compile a single module at a time. This can save time over compiling all projects at once, or over compiling a single project that contains all module and application files.

Compile a single module's project

  1. Right-click the module's MXML file in the module's project.
  2. Select Run Application. The Player or browser window tries to run the module after it is compiled. You can close the Player or browser window and ignore any error messages that appear at run time. Modules are not meant to be run in the Player or in a browser directly.