Creating Modules

You can create, add, optimize, and debug modules in Adobe® Flash® Builder™. For information on writing module code, see Creating modular applications.

    Creating modules in Flash Builder

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

    Create modules in Flash Builder

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

    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.

      Because modules are runnable, they must be in the project’s source folder.

    3. Enter a filename for the module; for example, MyModule.

    4. Enter the Width, Height, and Layout properties for the module.

    5. Specify whether to optimize the module.

      If you optimize a module for an application, classes used by the application are excluded from the module. This can result in smaller download sizes for your SWF files. For more information, see Optimizing modules in Flash Builder.

      • Optimize for Application

        If you select this option, specify an application to optimize the module against.

      • Do Not Optimize

        If you select this option, all classes are included 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 because it has all of its dependencies compiled into it.

    6. Click Finish.

      Flash Builder adds a new MXML module file in your project.

    Compiling modules in Flash Builder

    In Flash 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 application, then when you run your application, Flash Builder compiles SWF files for all modules in the project. 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 Flash Builder to compile it, close Adobe Flash Player or the 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 Flash Builder compiles the modules at the same time as your application, regardless of their location. Modules 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. One way to do this is to compile all open projects in Flash Builder at one time.

    If you compile modules separately from the main application, 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 Flash Builder.

    The Flash 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

    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.

      Module projects can use the load-externs compiler option to remove overlapping dependencies.

    Using one project for each module has the following drawbacks:

    • Many projects uses more memory.

    • 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, manually apply the load-externs and link-report compiler options.

    Using one project for all modules

    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 Flash Builder

    1. Create a main project.

    2. Create a new project for your module or modules.

    3. From the context menu for the module’s project 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 Flash 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 Flash 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, use the Build Order dialog box. Changing the build order 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 Flash 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 is 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.

    Adding modules to your project

    In some cases, you use modules that are not in your main application’s project. You might have the module in a separate project so that you can use custom configuration options, or you might want to share the module across multiple applications. Add the module’s source code to your application’s source path and then add the module to the application’s module list before you can use it in your project.

    Add an already-compiled module to your project

    1. Select the main application in the Flex Package Explorer.

    2. Select Project > Properties > Flex Build Path to add the module’s source to the application project’s source path.

    3. Click the Add Folder button and browse to the module’s source path. Click OK to select the module. You must do this for each external module that you add to your application’s project.

    4. Click OK again to save your changes.

    5. Click Project > Properties > Flex Modules to add the module to the application’s module list. The Flex Modules dialog box lists all modules that have been added to the current project or that are in the current project. When you first create a project, this dialog box is empty.

    6. Click the Add button. The Add Module dialog box appears.

    7. Use the Browse button or enter the location of the module’s MXML file in the Source text box. All modules that are in the project’s source path are available to add by using this dialog box.

    8. Select one of the radio buttons under Module SWF Size to enable or disable module optimization. If you select Optimize for Application, Flash Builder compiles the module against the selected application and excludes all classes that are defined in the main application. These can include framework classes or custom classes. When you select this option, you cannot use the same module in another application, because the list of excluded classes might be different. For more information, see Optimizing modules in Flash Builder.

    9. Click OK to save your changes. Flash Builder adds the module to the list of available modules in your application’s project.

    Optimizing modules in Flash Builder

    In Flash Builder, you typically select a single application to optimize the module against when you first create the module or add it to a project. If you later decide to change the application that you optimize the module against, or if do not want to optimize the module, you can edit the module’s properties within the project. For more information, see Reducing module size.

    Optimize modules with Flash Builder

    This procedure assumes the module and application are in the same Flash Builder project. If the modules are in a separate project, manually add the load-externs and link-report compiler options.

    1. Right-click the application’s project in the Flex Package Explorer and select Properties. The project’s Properties dialog box appears.

    2. In the left pane, select Flex Modules.

    3. From the list of modules, select the module and then click the Edit button. The Edit Module dialog box appears.

    4. To remove optimization, select the Do Not Optimize radio button under Module SWF Size.

    5. To optimize the module for a different application, select the new application from the Optimize for Application pop-up menu.

    6. Click OK.

    To further optimize a module’s file size, you can remove debugging information. If you build a module in Flash Builder, debugging information is included in the module by default. By removing debugging information, you can further reduce the size of the module. For instructions on how to remove debugging information from modules, see Debugging modules in Flash Builder.

    Debugging modules in Flash Builder

    To debug modules and applications, you must include debug information in the SWF files when they are compiled. To do this in Flash Builder, just run the application, because debug information is included by default. On the command line, you set the debug compiler option to true. The default is true, but if you disabled it in a configuration file, you must be sure to override it.

    By default, Flash Builder builds a single SWF file that includes debug symbols, so both Run and Debug work when you execute an application that uses modules in Flash Builder. However, including debug symbols in a module’s SWF file makes the SWF file larger. To exclude debug symbols prior to deployment, you must disable debugging for the application’s modules. To do this, you export the release version of the modules by selecting Project > Export Release Build.

    To exclude debugging information from SWF files in Flash Builder, you can either set the debug option to false in the Additional Compiler Arguments text box, or you can output the SWF files by using the Export Release Build feature, which generates non-debug SWF files. This includes the modules, if those modules are in the current project.

    If you create a separate project for your modules, you can enable or disable debugging for the entire project, without changing the settings of your main application.

    When you want to debug a module, you must also debug the application that loads the module. The Flex debugger will not connect to an application that does not contain debug information, even if the modules that the application loads contain that information. In other words, you cannot exclude debug information from the application if you want to debug the module that the application loads.

    When you’re using modules in an AIR application, the module SWF must be located in the same directory as the main application SWF or one of its subdirectories.