Creating A List View - Sage/argos-sdk GitHub Wiki

It is recommended that you read through the Creating An Application Module guide as we will be using it as our starting point.

The first step to creating a list view is to determine what resource, and what properties, to show. If you do not already know what data you want to see, one good way to find out is to explore the SData feeds directly.

First, we must create a file to contain the view's source. If you are using the folder structure outlined by the Creating An Application Module guide, we place all views inside of the ...\src\views folder, under a sub-folder for each resource, named the singular of the resource kind. For example, if the resource kind for the view is accounts we would place the source file for the view in the ...\src\views\account folder. For a list view, we name this file List.js, though you can change the name if you would like.

In the Creating An Application Module guide, we decided on a base namespace that would be used for all of our classes. For the views, we generally contain those within a unique namespace for each resource, i.e. Mobile.Sample.Account. Once you have decided on a namespace, you can declare it in the file, e.g.:

define('Mobile/Sample/Views/Account/List', ['Sage/Platform/Mobile/List'], function() {});

Next, you will need to declare the view class, e.g.:

define('Mobile/Sample/Views/Account/List', ['Sage/Platform/Mobile/List'], function() {

    return dojo.declare('Mobile.Sample.Views.Account.List', [Sage.Platform.Mobile.List], {

		id: 'account_list',
		icon: 'content/images/icons/sample.png',
		exposed: false,
		detailView: 'account_detail'	
	});
});

All list views should, either directly or indirectly, inherit from the platform class Sage.Platform.Mobile.List, which handles most of the work required to setup and use the view. Also, as you can see, we've defined some basic properties on the view's prototype, which are:

• id: The default id for the view, if none is passed as part of the options to the constructor. Each view instance must have a unique id.
• icon: The icon that the home view should display for this view. If the view is not exposed, this is not necessarily needed.
• exposed: True if the view should be exposed to the home view.
• detailView: The view to be shown when a user clicks on a row.

While the Sage.Platform.Mobile.List handles most of the interaction with SData, we do need to provide it some information, namely, the resource kind to query, the properties to select, and the order we want the results returned in. We do this by declaring some additional properties on the view's prototype:

define('Mobile/Sample/Views/Account/List', ['Sage/Platform/Mobile/List'], function() {

    return dojo.declare('Mobile.Sample.Views.Account.List', [Sage.Platform.Mobile.List], {
		id: 'account_list',
		icon: 'content/images/icons/sample.png',
		exposed: false,
		detailView: 'account_detail',

		resourceKind: 'accounts',	
		querySelect: [
			'Name',
			'Manager/Name'
		],
		queryOrderBy: 'Name asc'
	});
});

• resourceKind: The resource kind the view is responsible for and the default used for querying SData.
• querySelect: An array of properties to select from the resource.
• queryOrderBy: The order by expression.

For more information on these properties, please refer to the SData Specification.

Now that we've defined what we want to query SData for, we can now create a template to display the data. We can do this by overriding the contentTemplate for the view, e.g.:

define('Mobile/Sample/Views/Account/List', ['Sage/Platform/Mobile/List'], function() {

    return dojo.declare('Mobile.Sample.Views.Account.List', [Sage.Platform.Mobile.List], {
		contentTemplate: new Simplate([
			'<h3>{%: $.Name %}</h3>',
			'<h4>{%: $.Manager && $.Manager.Name %}</h4>'
		]),
		
		id: 'account_list',
		icon: 'content/images/icons/sample.png',
		exposed: false,
		detailView: 'account_detail',

		resourceKind: 'accounts',	
		querySelect: [
			'Name',
			'Manager/Name'
		],
		queryOrderBy: 'Name asc'
	});
});

The contentTemplate property is a a Simplate instance and is shared by all instances of the view unless a new template is passed as part of the options to the constructor. The template syntax is simple and is a mix of markup, tags, and javascript code. A quick summary of the parts used here:

• {%= ... %}: Output the result of the inner javascript.
• {%: ... %}: Output the HTML encoded result of the inner javascript.
• $: The data; in this case, it is the feed entry for the current row.
• $$: The data container; in this case, it is a reference to the view.

The last thing that must be done for the list view is to override the formatSearchQuery method to return a query that will be executed when a user invokes a search on the view. This can be accomplished by adding another property to the prototype, e.g.:

define('Mobile/Sample/Views/Account/List', ['Sage/Platform/Mobile/List'], function() {

    return dojo.declare('Mobile.Sample.Views.Account.List', [Sage.Platform.Mobile.List], {
		contentTemplate: new Simplate([
			'<h3>{%: $.Name %}</h3>',
			'<h4>{%: $.Manager && $.Manager.Name %}</h4>'
		]),
		
		id: 'account_list',
		icon: 'content/images/icons/sample.png',
		exposed: false,
		detailView: 'account_detail',

		resourceKind: 'accounts',	
		querySelect: [
			'Name',
			'Manager/Name'
		],
		queryOrderBy: 'Name asc',
		
		formatSearchQuery: function(query) {
			return String.format('Name like "${0}%"', query);
		}
	});
});

The query returned should be a valid SData query. You can read more about the query language in the SData Specification.

Before the view can be used, it must be registered with the application. This should be done in the loadViews method of your application module, e.g.:

define('Mobile/Sample/ApplicationModule', ['Sage/Platform/Mobile/ApplicationModule', ...], function() {
	return dojo.declare('Mobile.Sample.ApplicationModule', Sage.Platform.Mobile.ApplicationModule, {

		loadViews: function() {
			Mobile.Sample.ApplicationModule.superclass.loadViews.apply(this, arguments);
			
			this.registerView(new Mobile.Sample.Account.List());
			this.registerView(new Mobile.Sample.Account.List({
				id: 'account_related'
			}));
		}
	});
});

For list views, we generally register two view instances, with one of them being used for related lists from other entities; It is not required, however. The first instance we register, uses the ID we specified in the class declaration, account_list, though the second instance uses the ID we pass in the options to the constructor.

In order to test out the view in the development shell, a reference to the view's source and configuration in our sample must be added to the packages required before initializing the application, e.g.:

    <!-- Dojo -->
    <script type="text/javascript" src="../../argos-sdk/libraries/dojo/dojo/dojo.js" data-dojo-config="parseOnLoad:true, async:true"></script>
    <script type="text/javascript">
    require({
			baseUrl: "./",
            packages: [
			{ name: 'dojo', location: '../../argos-sdk/libraries/dojo/dojo' },
			{ name: 'dijit', location: '../../argos-sdk/libraries/dojo/dijit' },
			{ name: 'Sage/Platform/Mobile', location: '../../argos-sdk/src' },
			{ name: 'Mobile/SalesLogix', location: 'src' },
			{ name: 'Mobile/Sample', location: '../argos-sample/src' }, // Argos Sample
			{ name: 'configuration/sample', location: '../argos-sample/configuration' },
			{ name: 'localization/sample', location: '../argos-sample/localization' }
			]
     });
    </script>

Just like we did for the ApplicationModule.js in the Creating An Application Module guide, we have to add the new view to the fileIncludes section of the build script, e.g.:

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