-
Notifications
You must be signed in to change notification settings - Fork 6
Creating An Application Module
An application module is a way to encapsulate additional application functionality and customizations without needing to modify the host applications code.
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.
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, e.g.:
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.
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, e.g.:
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.
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 a sample module would look like:
{
projectName: 'Sample Module',
licenseText: '',
deployDir: 'deploy/',
pkgs: [{
name: 'Sample Module',
file: '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.
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.
In order to test your module, you'll need to create a development shell to run it in. The best way to do this is to copy the index-dev.html from the product for which your module is target, place it in the base folder, and rename it to index-dev-<< module name>>.html, i.e. index-dev-sample.html.
Next, the source files for the module must be referenced by the shell. It's best to place these immediately before the application is created and initialized, e.g.:
<!-- Argos Sample CSS -->
<link type="text/css" rel="stylesheet" href="../argos-sample/content/css/argos-sample.css" />
<!-- Argos Sample -->
<script type="text/javascript" src="../argos-sample/src/ApplicationModule.js"></script>
<!-- views would be referenced here -->
<!-- Argos Sample Configuration -->
<script type="text/javascript" src="../argos-sample/configuration/sample/development.js"></script>
<script type="text/javascript">
Ext.onReady(function() {
var application = new Mobile.SalesLogix.Application({environment: 'development'});
application.activate();
application.init();
application.run();
});
</script>The module configuration should always be referenced last as it will depend on other classes declared in the module's source.
Once the references are in there, this file must be either symlinked to, or copied to, the product's base folder. The .gitignore file for the product should be aware of these development shells, and they should not be included in any commits for the product.
To setup a symlink (recommended), you can do the following (from the product's folder):
Windows:
mklink index-dev-sample.html ..\argos-sample\index-dev-sample.html
Unix:
ln -s ../argos-sample/index-dev-sample.html index-dev-sample.html
If the product's development shell is updated, changes should be easily merged into your shell, or, if no merge is desired, the shell can be easily recreated.
First, save this (gist)[https://gist.github.com/815451] as build-module.cmd to the same folder where build-product.cmd and the argos-sdk reside. After this is done, you can build your module by executing the build-module.cmd script and passing in the module name as the argument, e.g.:
build-module sample
The output of the build will be in a folder named after the module inside of the deploy folder, i.e. ...\mobile\deploy\argos-sample.
In order to deploy your module, you'll need to copy the output of the build, to the folder where the product is deployed. The copy process may complain about existing folders; You'll want to allow it to copy into existing folders. After the copy process is complete, you'll need to add a few lines to both the index.html and the index-nocache.html files, right before the application is created and initialized, e.g.:
<link type="text/css" rel="stylesheet" href="content/css/argos-sample.css" />
<script type="text/javascript" src="content/javascript/argos-sample.js"></script>
<script type="text/javascript" src="configuration/sample/production.js"></script>
<script type="text/javascript">
Ext.onReady(function() {
var application = new Mobile.SalesLogix.Application();
application.activate();
application.init();
application.run();
});
</script>If the dynamic manifest, index.manifest.ashx is not being used, you must update the static manifest, index.manifest, and place the files into it.
A couple more things must be done if your module creates it's own SData connections. First, you'll need to add your SData endpoints to the NETWORK: section of the manifest files, index.manifest and template.manifest, e.g.:
NETWORK:
../sdata/
http://sample-server/sdata/
Next, if you're SData host is on another server, you'll need to enable Cross-Origin-Request-Sharing (CORS). You can find a document on how to set it up for IIS at: Setting-Up-CORS.