Composer allows users to add other Composer projects as sub-projects to an existing Composer project giving them access to any xObject in the sub-project.  This feature does away with the need to import desired xObjects from one project into another project, which creates an additional copy of the xObject source.  Additional copies of xObjects can cause code maintenance problems.  With a sub-project a user can re-use a xObject in multiple projects without creating multiple copies of the original source xObject.

When a project is added as a sub-project, its xObjects appear with the main projects xObjects in the Navigation and Detail panes of Composer as shown below.  

ActionExamples is a sub-project of the TutorialBegin project.

Notice that each xObject name from a sub-project is prefixed with the name of the sub-project allowing you to distinguish, which xObjects belong to which project.  This naming convention also groups xObjects of one project together in the detail pane lists for quick scanning.  In addition, for convenience in locating main project xObjects, you can remove sub-project xObjects from the Detail pane display using the menu bar selection of View | Filter xObjects as shown below.

Below are the steps to add a sub-project to a project:

.        Choose Configuration from the Tools menu.

.        Select the Sub-Projects tab.

.        Click the plus-sign icon to add a sub-project.  In the browse window choose any .spf file that was created by Composer that you want to be your sub-project.  You can repeat this step as many times as you wish to add as many sub-projects as you wish.

.        Click OK to close the dialog.  Your sub-project's xObjects will appear in your Composer Project.

Before Composer had sub-projects the only way to reuse code/objects between projects was by importing each xObject you wanted to use from one project to another.  The biggest problem of importing a xObject into a project is that the original object's XML file(s) are copied into the current project. This leaves you with two copies of the XML file of the xObject, one for each project.  This can cause code maintenance problems.  The problem being that any changes to the original xObject will need to be made in all copies of that object that have been imported to other projects.  With subprojects this is no longer the case.  When you include a sub-project within your current project, no new copies of the sub-project's XML files are made. All the sub-projects files are stored in one place thus simplifying code maintenance.  This also makes it easy to create a repository project to store code that you wish to reuse in multiple projects.

A project can have any number of sub-projects.  Having said that it is important to point out that a project containing one or more sub-projects cannot serve as a sub-project itself.  For example, if the TutorialBegin project contains a sub-project named ActionExamples. A third project called DOMMethods could not use TutorialBegin as a sub-project.  If you try to add a sub-project to your current project, and that sub-project contains its own sub-projects, you will get a warning message:

Composer checks to see if newly added sub-projects contain other sub-projects and will prevent the use of such sub-projects.

Only certain xObjects and variables are shared between a project and a sub-project and there are rules associated will this sharing.

• xObjects: A main project can access a sub-project's components (and other xObjects), but the sub-project cannot access the main project's objects.

• Project variables: Project variables defined in a main project cannot be used by a component in a sub-project.   The reverse is true as well; a project variable defined in a sub-project cannot be used by a component in a main project.

• ECMAScript variables and functions: A main project can use a custom script function from a sub-project; however, a sub-project may not use a custom script function from a main project.  The example below shows a sub-project custom script function being used in a main project:

 One item to keep in mind is deployment.  When a Composer Project is deployed the jar file created during the deployment contains all the xObjects for the project.  When a Composer project with a sub-project is deployed the jar created during deployment contains all the xObjects for the main project as well as all the xObjects from the sub-project even if only a few of the sub-project's xObjects are actually used in the main project.  It is a good idea to keep this deployment characteristic of sub-projects in mind when you are deciding how to setup your sub-projects. 

Sub-projects are a good repository of information that is to be used in multiple projects.  Deciding how to setup your project(s) that will be used as sub-project(s) is ultimately a personal preference.   However, here is a suggestion.  Create one sub-project for each Resource type in a project.  For instance, create a sub-project that contains all the Connection resources used in all your projects.  Create another project for all the Code Tables and Code Table Maps that will be needed for the projects.  If one of these Resources gets too large on its own then perhaps divide the Resource into multiple sub-projects.  For example, if you have several code tables and placing them in one sub-project is getting unmanageable, then divide the code tables into two subcategories and place one subcategory in one sub-project and the rest in another.  This is one way we suggest to organize projects that will be used as sub-projects.  This takes into account the fact that the entire sub-project used in a main project is incorporated in the deployment jar.  Separating the sup-projects in to smaller pieces makes them more manageable and also they take up less room on deployment.

Sub-Projects are a valuable new feature in Composer.  They allow for easy code maintenance.  They also simplify the reuse of code between projects.