Creating An Application Module

What Does An Application Module Do?

An application module is a way to encapsulate additional application functionality and customizations without needing to modify the host applications code.

Creating The Project

It is recommended you have the following base folder structure:

	+---mobile		
		+---argos-sdk
		+---products
			+---argos-saleslogix
			+---argos-gcrm
			\---<< other products and modules >>

You will want to create the base folder for your module inside of the products folder. The name of the folder should be prefixed with argos- as the primary build scripts currently require it to be. The folder structure inisde of the base folder is entirely up to you, though we use, and recommend, the following:

	+---products
		+---<< prefixed module name, i.e. argos-gcrm >>
			|	.gitignore	
			|	README.md	
			|	index-dev-<< module name >>.html
			|
			+---build
			|		release.cmd
			|		release.jsb2
			|
			+---configuration
			|	\---<< module name >>
			|			development.js
			|			production.js
			|
			+---content
			|	+---images
			|	\---css
			|			<< prefixed module name >>.css
			|
			\---src
				|	ApplicationModule.js
				|
				\---views

The rest of the guide will assume that you have used the folder structure above.

Creating The ApplicationModule Class

Open up the ...\src\ApplicationModule.js file. Before we can go any futher, we need to decide on the namespace that we will use for all classes inside of the module. In our own modules, we use Mobile.<< name >>, i.e. Mobile.GCRM or Mobile.SalesLogix. Once you have decided on a namespace, you can declare it in the file, like so:

	Ext.namespace('Mobile.Sample');

You will need to use the above namespace declaration at the top of all of your class files.

Next, you will need to declare the ApplicationModule class, like so:

	Ext.namespace('Mobile.Sample');

	Mobile.Sample.ApplicationModule = Ext.extend(Sage.Platform.Mobile.ApplicationModule, {
	
	});

Now we can move onto implementation.

Implementing The ApplicationModule Class

In most general terms, when we are implementing a module, we are looking to do two things: create new views and customize existing ones. The Sage.Platform.Mobile.ApplicationModule class provides hooks for us to do both of these things. We'll want to override the loadViews and loadCustomizations methods of the ApplicationModule class, like so:

	Mobile.Sample.ApplicationModule = Ext.extend(Sage.Platform.Mobile.ApplicationModule, {
		loadViews: function() {
			Mobile.Sample.ApplicationModule.superclass.loadViews.apply(this, arguments);
		},
		loadCustomizations: function() {
			Mobile.Sample.ApplicationModule.superclass.loadCustomizations.apply(this, arguments);
		}
	});

The superclass call in each of these is optional as the Sage.Platform.Mobile.ApplicationModule class has empty implementations for both functions. Creating and registering new views and customizations will be covered in other articles.

Setting Up The Build Script

In the ...\build folder, you'll see two files listed in the structure above: release.cmd and release.jsb2. The release.cmd file starts the build process with all the correct options; it is best to copy this file from another module. The release.jsb2 is the actual build project and is what we we need to create for our module. A basic build project for our sample module looks like so:

	{
		projectName: 'Sample Module',
		licenseText: '',
		deployDir: 'deploy/',
		pkgs: [{
			name: 'Sample Module',
			file: 'app/content/javascript/argos-sample.js',
			isDebug: true,
			fileIncludes: []
		}],
		resources: [{
			src: '../content/',
			dest: 'content',
			filters: ".*(\\.css|\\.jpg|\\.png|\\.gif)"
		},{
			src: '../configuration/sample',
			dest: 'configuration/sample',
			filters: ".*\\.js"
		}]
	}

Starting with that as our base, we need to add the ApplicationModule.js file that was created previously. You can do this by adding an item to the fileIncludes array property:

	fileIncludes: [{
        text: 'ApplicationModule.js',
        path: '../src/'
    }]	

The reason that we have to use a relative path for the path property is that all file includes are based off of the jsb2 file's path.

Creating Configuration

In the ...\configuration\sample folder, there are two files, development.js and production.js, which contain application configuration for development, and production, respectively. The format for both is the same, and they follow the same patterns as normal application, with one small difference; It is a best to have module configuration merge with application configuration. This can be accomplished with the following:

	Ext.namespace("Configuration.development");

	(function() {
		var merge = function(configuration, moduleConfiguration) {
			if (configuration)
			{
				if (configuration.modules && moduleConfiguration.modules)
					configuration.modules = configuration.modules.concat(moduleConfiguration.modules);

				if (configuration.connections && moduleConfiguration.connections)
					configuration.connections = Ext.apply(configuration.connections, moduleConfiguration.connections);
			}
		};

		merge(Configuration.development, {
			modules: [
				new Mobile.Sample.ApplicationModule()
			],
			connections: {
				
			}
		});
	})();

The function to merge configuration will be provided by the API in the near future. Notice that we add a new instance of our ApplicationModule to the modules list; This is how the application knows to load our module. In the connections property we can define any and all SData connections we need. The key used here to define the SData connections is the same that the views will need to have as their serviceName property, unless they will be using the default, applicaiton provided connecction.

Setting Up A Development Environment

Building And Deploying The Module