Arrow "Client Side SDK - Alloy" Example

READme.md

Arrow 'Alloy SDK' example

This blog provides a clear example of implementing Arrow Client Side ‘Alloy’ SDK in your Appcelerator Alloy Mobile Application projects.

By the end of the example, you will be able to create a mobile/client applications that consumes data with no coding! I mean, literally: no looping through arrays, lists, or creating loops in loops (for array or arrays) to simply extract data from back-end data results and display them on your mobile (or client) application.

Isn’t this just brilliant?

This feature of Appcelerator Alloy is based on Backbone.js. You can learn more about it through

• Appcelerator documents
• [Appcelerator Blog] (https://www.appcelerator.com/blog/2016/05/alloy-data-binding-revisited/)
• [And my personal favourite @ CDNJS] (https://cdnjs.com/libraries/backbone.js/)

However, you don’t have to.
This is the perfect example for you to start building mobile apps that displays data from your Arrow Applications, in minutes, without going into the nitty-gritty of backbone.js.

This demo is suitable for anyone, who knows how to create Arrow Applications and generate Client SDKs.

OK, let’s create an Alloy Mobile Application that lists all of the Accounts under our Salesforce demo account.

Steps:

1. Assuming you have an Arrow Application created, tested and published (or running locally). My Arrow application is called MySF_Accounts.

2. All we need to do is to now is to generate the Client Side SDK.

• run the following command from your Arrow application folder

> appc generate

• Select Arrow SDK from options

? What type of component would you like to generate?
 Arrow Component
❯ Arrow SDK
 CLI Plugin

• Select Alloy (alloy) from options to generate SDK code compatible with our Alloy mobile app

 ? Which type of App SDK? (Use arrow keys)
❯ Alloy (alloy)
 Android (android)
 jQuery (jquery)
 NodeJS (nodejs)
 Objective-C (objc)
 Titanium (titanium)

• You will be prompted to name your SDK

? What should the name of the SDK be? (MySFAccounts) MySF_Accounts

Here, we need to name our SDK. If left blank, by default, it will take your Arrow application's name. I have named mine MySF_Accounts. I suggest you come up with better names to prevent any confusion :)

• Finally, you will be asked which directory the files should be generated in. I have saved mine in sdk.

? Generate files into which directory? (sdk)

3. Once the SDK generation is successful, you need to copy the Client SDK files to your Alloy mobile app project directory. 'README.md' file contains the necessary information on how to start using your client side SDK in your Alloy app.

• Copy Alloy Client Side SDK files from Arrow into your Alloy Mobile Application Directory as below:
     

4. We need to make few adjustments to ensure our Model, View and Controller are all connected.
   In this example, Model is Sf_Account.js, View is index.xml and Controller is index.js.

   index.js

---

1. Get Client Sie SDK to query the relevant model info from data source, Salesforce in this case.
   Add the following into your controller (replace SfAccount with your model name):

   Alloy.Collections.SfAccount.fetch();
   

2. Add the following function to convert the model to JSON object.

function transformFunction(model) {
return model.toJSON();
}

3. Finally, to prevent memory leaks, we need to call the destroy function as below:

function cleanup() {
   $.destroy();
  }

  __Final look at index.js (Controller)__

   ![Completed view of index.js](https://cloud.githubusercontent.com/assets/20290208/19110402/7056770e-8b45-11e6-8016-0ebaa7d6522a.png)  

index.xml

---

1. Let's start with the most basic list view. I am using a barebone Alloy ListView from [Appcelerator Documents] (http://docs.appcelerator.com/platform/latest/#!/guide/Alloy_ListView_Guide).
   Add the following code to your View. This is index.js in our example. ~~~
   ~~~

2. We now need to make our model, SfAccount.js, accessible from View, index.xml. Much like referencing js and css in HTML.
   Add following just before the <Window> tag

   <Collection src="SfAccount"/>
   

3. Add the following properties to ListSection to automatically loop through our collection of Salesforce Accounts and to convert the data to JSON.

     dataCollection="SfAccount" dataTransform="transformFunction"
   

4. Quickly add the event listener to Window tag to call our cleanup function to prevent memory leaks upon user closing the window.

   onClose="cleanup"
   

5. Finally, we need to tell our view which elements to display from the model. In this case, I will display the each account's Name and State. Just add the following as the title of ListItem

   title="{Name}, {BillingState}"
   

   Final look at our index.xml (View)

   

SfAccount.js

---

1. Since Arrow requires authentication (Basic by default), we need to add the **_authentication key_** into our model as well as **_domain_** and **_port_**. Basic configuration and authorization keys are available in the _READ.me_ file generated as part of your SDK.  

  <p align="center">
		<img src="https://cloud.githubusercontent.com/assets/20290208/19296215/be3a135a-9085-11e6-99d0-b653e3a6790c.png" alt="README.md file contains authentication keys" width="680" height="245"  />
	</p>

    Add following line into your model, straight after `require` line

 ~~~
 SDK.Authorization = 'YourArrowAPIKey'; (as per above)
 SDK.port = '8080';
  SDK.domain = 'http://localhost'; (if running locally)
 ~~~  

	If your Arrow application is published and running online, set your domain accordingly:

	![Arrow Application domain](https://cloud.githubusercontent.com/assets/20290208/19297280/069cc7f6-908f-11e6-8b88-b7c9c8704ef9.png)

 

Final Product

Now we know how to integrate Arrow SDKs into Alloy Mobile Applications to display data with basic copy-and-paste. This is already done for us.

Final Words

As you can see, we didn't put any effort in to create a basic native mobile application that lists the accounts we have in Salesforce. This could have been your database or any other data source.

You may want to add some style and further functionality to this mobile application to make it nicer looking and more functional.

Look forward to your comments.

index.js

$.index.open();

var args = $.args;

Alloy.Collections.SfAccount.fetch();

function transformFunction(model) {
    return model.toJSON();
}

function cleanup() {
    $.destroy();
}

index.xml

<Alloy>
	<Collection src="SfAccount"/>
	<Window onClose="cleanup">
		<ListView >
			<ListSection dataCollection="SfAccount" dataTransform="transformFunction">
				<ListItem  title="{Name}, {BillingState}"  />
			</ListSection>
		</ListView>
	</Window>
</Alloy>