What’s the problem?

Just implementing resource bundles to localize your application doesn’t quite cut it. You need to do things like work with localized dates in the browser (including formatting), numbers, currencies, and who knows what else to munge your data. It sure would be nice if there were a way to transparently make this happen in a message oriented way that does not require server side awareness for services, can you help me with this problem? sure.

Built in ‘ization’ support in Appcelerator

Globalization (G11N) and Localization (L10N) both get lumped into Internationalization (I18N) – how to deal with languages, time, data formats and everything else that goes on making it so that people in different places in the world can use your glorious application. Appcelerator localization helps you out with this on some really simple levels with the langid attribute:

  <span langid="account.number.title"></span>:<input type="text"></input>

This should arm you successfully with an ability to deal with things like simple messages and labeling in your application. Now if you want to blend in your data payload to render localized text, you can make use of appcelerator javascript functions Appcelerator.Localization.get and the more powerful but less documented Appcelerator.Localization.getWithFormat.

<script>
  var en_lang_bundle = {
	"invalidlogin.message": 
"Dear sir/madame, the username you provided '#{username}' does not exist:"
  }
  Appcelerator.Localization.addLanguageBundle("en",English",$H(en_lang_bundle));
</script>
<span on="l:invalidlogin.response then value[text]"></span>
<app:script on="r:invalidlogin.response then execute">
  var text = Appcelerator.Localization.getWithFormat('invalidlogin.message',
null,null,{username:'azuercher'});
  $MQ('l:invalidlogin.response',{text:text});
</app:script>

This is a nice way to use message indirection for munging messages, but really is quite messy and anything but transparent. There must be a better way!

Interceptors

A lesser known feature of Appcelerator is the concept of interceptors – client side behavior that you can have play in-between the delivery of queued messages to their recipients. In the case for client-2-server orchestration all server requests and their corresponding response messages are enqueued and subject to perversion by interceptors. You just have to know how to implement them. Lets say that whenever I send a CRUD request to the server called ‘r:createorder.request’ I want to add a new attribute called last_modified_utc which is a numerical representation of a utc date as a long. I can add that to the payload to the back end service completely transparently with the Appcelerator.Util.ServiceBroker.addInterceptor method – the method takes a callback to the following:

• interceptQueue – where requests from client to server are intercepted
• interceptSendToListener – where responses from server to client are intercepted

In the example below I

• add ‘last_modified_utc’ as a current utc long to r:createorder.request which is consumed by my back end service
• transform ‘last_modified_utc’ in the r:createorder.response from utc to a localized string in the browser

<app:script>
	var interceptor = {
	    interceptQueue: function(msg, callback, messageType, scope) {
			if (messageType=='remote:createorder.request') {
				msg.data.last_modified_utc = new Date().getTime();
			}
	        return true;
	    },
	    interceptDispatch: function (requestid, type, data, datatype) {
	        return true;
	    },
	    interceptSendToListener: function (listener, messageType, data, datatype) {
			if (messageType=='createorder.response') {
				date = new Date(data.last_modified_utc);
				data.last_modified = date.toString();
			}
	        return true;
	    }
	};
	Appcelerator.Util.ServiceBroker.addInterceptor(interceptor);
	$MQ('r:createorder.request',{hi:'there'});
</app:script>

Obviously, you can take this a step further and then add interceptors that munge your data conditionally based on the current locale defined in Appcelerator.Localization. The benefit here is that this data transformation happens at a layer outside of my normal pub/sub for messages in Appcelerator – the normal pattern is to either replace or add attributes in the payload.

wrap up

Although not a shrink wrapped solution for I18N in all its glory, its not hard to implement interceptors to do so. Beyond I18N, a lot of other aspects for your messages can be mutated in the browser non-intrusively. Although the key demonstration here is data transformation, you would potentially add other horizontal services into your application.

this article cross-posted at http://blog.zuerchtech.com/2008/10/13/using-appcelerator-interceptors-for-i18n-l10n-g11n

ShareThis

Deep-linking is important. It’s what makes the web so … webby. Usability guru Jakob Nielsen tells us that Deep Linking is Good Linking, and hypertext pioneer Doug Engelbart encourages us to make “Every Object Addressable.”

With the old-web, deep-linking was easy because everything was a page and every page had a URL. In the new RIA web however, a complex web app can fit into a single page, and without some careful programming, we lose the ability to bookmark or share objects and places inside the app.

To get deep-linking in an RIA, we need to store the link info in the hash part of the URL. For example, the Google Docreader team has documented their scheme for deep-linking into ajax-ified documentation. Deep-linking to Flash content with SWFAddress also takes advantage of the hash component of a URL.

In Appcelerator, a convenient way to provide deep-linkable addresses (as well as sane forward-backward button support) is to use Appcelerator Routes to map the hash part of a URL onto an Appcelerator message. Routes have a similar syntax to Ruby on Rails routes, but are entirely client-side.

An example routes definition:

routes({
    '#home' :                  'r:get.home.request',
    '#cat/:id' :               'r:get.animal.request[type=cat,id=#{id}]',
    '#dog/:id' :               'r:get.animal.request[type=dog,id=#{id}]',
    '#yaps/:fromid/:toid' :    'r:get.messages.request[dogid=#{fromid},catid=#{toid}]',
    '#hisses/:fromid/:toid' :  'r:get.messages.request[catid=#{fromid},dogid=#{toid}]',
});

Now, when someone navigates to http://yourapp.com/pets#dog/fido, the message r:get.animal.request[type=dog,id=fido] will be fired on page load. Inside your UI code, you can react to the response of this message to switch the active section of your app:

<div on="r:get.animal.response[type=dog] then show and bind[dog_info] else hide" style="display: none">
  My Cat Friends:
  < app:iterator on="r:get.animal.request[type=dog] then execute" property="dog_info.cat_friends">
    <a href="#cat/#{cat_id}">#{name}</a> (<a href="#yaps/#{my_id}/#{cat_id}">Our messages</a>)<br/>
  < /app:iterator>
  <!-- more UI for viewing a dog -->
</div>
<div on="r:get.animal.response[type=cat] then show and bind[cat_info] else hide" style="display: none">
  <!-- UI for viewing a cat -->
</div>
<div>
  <!-- another section of the app -->
</div>

So, when http://yourapp.com/pets#dog/fido loads, a remote message will be fired, a response (hopefully containing some friends) will return, the iterator will be executed, and links will be generated. If Fido has a cat friend named Milo, we’d get HTML generated (client-side), like this:

    <a href="#cat/milo">Milo</a> (<a href="#yaps/fido/milo">Our messages</a>)

Both of those links will fire an Appcelerator message when clicked, as well as changing the hash component of the URL (which is what makes forward/backward usable). Because we’ve set up an else-clause for the dog-ui section (r:get.animal.request[type=dog] then show and bind[dog_info] else hide), if the user clicks the #cat/milo link, the currect section will hide, and the cat-ui section will be shown.

So, with a few lines of declarative javascript, we’ve been able to retain all the webby goodness of deep-linking, and also reap the benefits of Appcelerator’s transparent client/server messaging and client-side templating. Cool, huh?

ShareThis

The intent of this message is to provide a little clarification to those wanting to write their own Appcelerator backend (Service Broker). Appcelerator Service (server side) and Message (client side) Brokers use a simple, standard JSON protocol to send and respond to messages. Data is posted to the server via an Ajax request and the Service Broker first parses the request to find messages, which are mapped to some service handler, function, or method via the type (name) of the message. Next the Service Broker delegates the message to the handler to finish its computation and returns the result using the same protocol definition. More detail on the protocol definition is available here, but the basic structure goes something like this:

{
    "timestamp": 1214008045871, 
    "version": "1.0", 
    "messages": 
    [
        {
          "type": "app.test.message.request", 
          "scope": "appcelerator", 
          "version": "1.0", 
          "data": {"message": "Hello,world"}
         }
     ]
}

where messages is an array of messages. Each message is defined as follows:

{
    "type": "app.test.message.request", 
    "scope": "appcelerator", 
    "version": "1.0", 
    "data": {"message": "Hello,world"}
}

where type is the name of the message, scope describes which elements on the client will receive the message, and data is a JSON object containing the data payload of the message.

Astute readers might have gathered that the request/response procedure is synchronous. This decision was made after trying both polling and synchronous methods. Synchronous behavior was chosen for its efficiency and because it did not adversely impact the user experience on the client.

One final note: It’s important to set the content type in the http response to “application/json” so the client knows how to parse the incoming messages.

ShareThis

One of the undocumented features of the Appcelerator WebSDK is the built-in support of transparent PNG images for IE6. A simple Google search will show you many, many different Javascript code snippets that you can put in your app to apply the PNG transparency filter on your images. But we thought we could provide this in our framework for you so you don’t have to worry about it.

The only problem has been that you couldn’t control exactly which images you want the filter to apply to. For example, if the filter applied to a div that had a background-image and a position, then potentially nothing inside that div would be clickable. And you also probably don’t want the extra processing on PNG images that don’t have any transparency to begin with.

So on the next released version of the WebSDK (2.1.3), we’ll have a .htc file that you can use in your CSS to control which images you want the PNG fix to apply to. For example you can do

.png 
{
   behavior: url(/images/iepngfix.htc);
}

to apply on all elements that have the class “png” or you can do

img, div 
{
   behavior: url(/images/iepngfix.htc);
}

to simply apply on all img and div elements.

Having these .htc files may not be the best thing in the world, but at least you can have control on where the PNG fix is applied.

ShareThis

Purpose

The Appcelerator framework allows for the extension of the build and deployment process so that you can add components and modify the behavior of your service implementations. It is quite powerful and not only restricted to services, plugins for example could span across to the modification of applications and the entire build and deployment process for that matter. For simplicity, this article will identify how to create a new component added to our java service for monitoring performance.

Install Appcelerator

I’ve assumed that you’ve successfully downloaded and installed Appcelerator from http://www.appcelerator.org/products. Once you’ve gone through the installer you can get the java service

1

  app install:service java

You may want to get an existing plugin (I needed the java:spring plugin to implement my plugin):

1

  app install:plugin java:spring

Plugin Creation

Lets assume that our plugin is going to be called java:perf, to create the plugin project:

1
2

  cd $HOME/workspace
  app create:plugin . java:perf

This will create a sub directory named java_perf, now you will want to create a proper license entry in your build.yml for example check out build.yml. You now have the opportunity to modify the entry points in your java_perf.rb. I personally wanted to setup my install script so that:

• it dynamically builds the jar when we add the plugin to a project
• modifies the spring.xml to include the bean entries for my component

All of this is in before_add_plugin(event) callback. If you want to see where this is called, check out add_plugin.rb. Once my coding is complete (added my source files to java_perf/src), I created the plugin distribution:

1

rake zip

Install the plugin

As you noticed, I haven’t covered debugging the plugin just yet, this is because I want to first set up the plugin for installation and then work with it in my install directory. Lets install it to the local machine:

1

app install:plugin java_perf.zip

Add the plugin to my project

I thought that I’d create a blank java project real quick

1
2

cd workspace
app create:project . myproject java

now we can add the spring plugin and our new java:perf plugin to our project

1
2
3

cd myproject
app add:plugin java:spring
app add:plugin java:perf

You can now directly modify the java_perf.rb file in your install directory

• windows: c:/Program Files/Appcelerator/releases/plugin/java_perf/1.0
• unix: /usr/local/Appcelerator/releases/plugin/java_perf/1.0
• mac os: /Library/Appcelerator/releases/plugin/java_perf/1.0

I suggest that you continue to modify the java_perf.rb this way to debug it and then finalize by copying back over to $HOME/workspace/java_perf

Next Steps

As a final parting you can release your new plugin so that others may be able to leverage it

1
2

cd $HOME/workspace/java_perf
app release java_perf.zip

-andrew

this article is cross posted at:
http://zuerchtech.com/2008/3/4/implementing-an-appcelerator-plugin

ShareThis

Purpose

If you are venturing to implement a Rich Internet Application (RIA) with Appcelerator, then there are features about the framework that I’m really geared up about that help you implement your solution effectively. When used together these items enable the agile creation of solutions in a shorter time that integrate nicely with services in an existing architecture and provide a richer user experience for clients.

Achieving Re-use

There are a bunch of ways to do this, personally I leverage app:content files judiciously. You can provide args in the definition of your content files so that you can use the same content file over again. Some things to keep in mind:

• reference the args as #{argname} in your element ids, any variables, and make sure that functions you call take this into account (possibly make them stateless)
• the order in which the content file is loaded to make sure that listeners are properly setup to respond to messages

here is an example app:content reference

1
2
3

<app:content lazy="false" on="mainstate[person] then show else hide" 
  args="{'prefix':'person'}">
</app:content>

here is the content.html file

1
2

<div id="#{prefix}header" ...
</div>

I know that this may be abstract, but the point is that you can use the arg “prefix” to reuse the file and provide alternative behavior based on it.

Mocking Services

You can mock out server side services extremely easily with the framework. This is extremely useful whether your goal is:

• Visual Use Cases: implementing a prototype that results in 100% useable application code
• Working offline: no need to run a web server at all, you can directly run off of a simple file

Once you have this in place, you have a well defined contract in place which makes knocking out the service implementation a snap.

No restart

If you are just working on your application (no service work), you can directly make changes to your application without requiring rebuilding and redeploying your application. In java I typically work directly in my tomcat deploy directory and have an ant task to pull the web files into my workspace. With our next version of the framework coming out, this will be even easier with our support for Jetty coming and the Ruby based command line tool. In the meantime, the following is useful in your java project:

1

ant pullweb

Make sure that you have your deploy.dir setup in your $HOME/.ant.properties for example:

1

deploy.dir=/Applications/apache-tomcat-6.0.14/webapps

With our Ruby implementation for example, this is even easier (running webbrick directly in your workspace).

Great Support for Model Objects

I’ve touched a bit on this in a previous post on JSON serialization with Appcelerator java services. To summarize the framework enables

• Hibernate persistence: ModelObjects can easily be used with our Hibernate integration
• JSON serialization: Serializing and deserialing complex objects is a snap

Slick support for forms

In case you haven’t looked, you dont need to include a form tag anywhere in the application: simply add a fieldset attribute to your input elements and put something like this

1
2
3
4

<input name="age" fieldset="save_person" type="text"/>
<input name="name" fieldset="save_person" type="text"/>
<input value="Create Person" fieldset="save_person"/>
  on="click then r:create.person.request" type="button"/>

This will create a message of type r:create.person.request with the payload being all your input elements with fieldset of “save_person” ex:

1

{'name':'jim','age':'35'}

To me, this is very eloquent solution to leveraging form input elements with a messaging architecture.

Easy to use UI widgets

I love some of the widgets that are at your fingertips. Some of the ones that i use the most

• app:panel: slick styling
• app:datatable: great way to show rows of data
• app:chart: fantastic visual effects to bring life to data

All these widgets have a very terse usage that is very intuitive. For example, using this set, I was able to knock out a realtime dashboard application in 3 evenings.

Service Platform Options

Pitching the right framework is something that varies from project to project. For example, possibly your client wants to leverage an existing java infrastructure and is sold on its robustness for scaling enterprise applications, while on the other side possibly you want to take advantage of using a Rails controller and ORM/Active Record implementation for rapid development. On the same level you also have the option for implementing services to customers that deliver in a .Net solution architecture. Many other platforms also exist (python, PHP) enabling the opportunity to plug into those services as well.

The app:get non-visual widget also makes pre-existing services accessible as well and since Messaging is at the heart of the implementation, plugging into an ESB or pure MOM framework is perfectly setup as well.

Wrap Up

In this article 7 key tips have been covered

• re-use
• mock services
• no restart
• model objects
• messaging & forms
• UI widgets
• platform options

Although there are more items that have not been covered here, these are the ones that appeal personally to me and have noticed a huge gain in doing much more with less effort.

this article cross-posted at http://blog.zuerchtech.com/2008/02/26/effectively-implementing-appcelerator-rias-and-services/

ShareThis

Purpose

The ability to debug applications is critical when things go sideways on you. I understand that for some of the developers out there learning a new framework can be challenging. Appcelerator provides developers with the tool-set to drastically reduce the amount of javascript code that they need to write and to be honest I think that the more you use the framework, the less you will need to debug applications as you familiarize yourself with the syntax.

Alerts

Prior to logging, alerts were the best way to display state during execution (showing you how old school I’ve been). Nonetheless, sometimes this is just easier since it blocks execution until you confirm. When you do this, you may want want to display objects. Lets take for example the following

1

alert(myobject);

You make get an alert that shows:

Well that isn’t very useful. If you want a nice string representation, use the following

1

alert(Object.toJSON(myobject));

Now you’ll get a nice JSON representation.

Logging

Safari and Firefox both provide you with the ability to view logging in the console. For firefox, you need to install firebug. If you are a safari user, you can use webkit (from the Debug menu, click “Show Javascript Console”). Both of which make available a console that displays log statements.

In firefox you can do the following in javascript

1

console.log("wassup");

I suggest however that you dont do that! Instead make use of the abstracted Logger

1

Logger.info("wassup");

This will not only show up in Firefox, but also in Safari’s console.

On another note, you can use the debug=1 parameter in your URL and you will see a ton of appcelerator messages (ex: http:localhos:8080/myapp?debug=1). I will caution you that it will almost look like spam given the amount of detail that is logged, but nonetheless its there if you want it.

You can also expand the Get and Post statements in firefox which will let you know what you have sent in your request and the JSON result that was returned from the server.

In-line Debugging

Lets say that you have an error in your app:script. Well in Firefox, you can take a look at the console and that will give you some pretty good feedback, however its going to be some cryptic text and you can’t step through it. You have 2 options that will enable you to step through the code:

• can make a call to a javascript function from your app:script (I normally define a project specific javascript file and put my functions in it)
• define a $MQL in your javascript file – app:script goes away

Here is scenario 1:

1
2
3

<app:script on="r:someevent.response then execute">
  Myapp.dosomething(this.data);
</app:script>

and the corresponding javascript

1
2
3
4
5

Myapp = Class.create();
Myapp.dosomething = function(data)
{
  //code here
}

For scenario 2: alternatively you could just define in your javascript file

1
2
3
4

$MQL('r:someevent.response',function(type,msg,datatype,from)
{
	//code here
});

The downside of this is that your implementation is not colocated in a single html file, but the upside is that you can debug it. Note that if you are not using content files, then you could alternatively define the above in a script element instead (a little cleaner), however if its a large app, then you really will want to decompose your app and use content files.

IE Specific Debugging

To be honest I’m not a huge IE fan, but it makes up an install base of 80% of the market. Chances are that pretty much everyone out there is using IE if you are building an application that appeals to the general public. To this end, Microsoft has made the .Net Developer Studio available for debugging your applications. The steps are pretty simple:

• install .Net Studio and create a project
• add your javascript files to your project
• start IE with your app’s url
• in Visual studio, select debug process and select your iexplorer.exe (sometimes it wont attach, but just keep trying and you should get there eventually)

For understanding styling, I suggest downloading the Internet Explorer Developer Toolbar. This will allow you to inspect individual elements (using the hover) and then setting styling attributes on your elements. This is much better than changing your html and reloading your page, especially for large applications.

Firefox (Firebug) Specific debugging

As with IE, you can use the firefox plugin to step through your code.

• load your app
• open firebug
• click script and select the html or javascript file and set your breakpoints

As with IE, using the Inspect module in firebug is very useful for styling your application.

Wrap Up

In this article we covered a bunch of ways that you can get down to the details in your application

• alerts (and displaying objects as strings)
• logging (appcelerator debug mode, custom log statements, ajax payloads)
• in line javascript debugging and styling

For many this may be an obvious repeat of the mechanisms that they currently use as web developers, but hopefully it will uncover some of the tactics that are used.

-andrew

this blog is cross posted at:
http://zuerchtech.com/2008/2/21/debugging-appcelerator-applications

ShareThis

Purpose

Once you have developed a functional application and are priming for a roll-out, it will be in your interest to tune your application and identify those touch-points which are candidates for tuning. I’ve preferred taking a quantitative approach to performance tuning so that you can compare metrics before and afterwards to identify improvement from a measurable perspective. To this end, it is possible to record statistics both client and server side (currently only for java services). Sometimes the culprit may be server side or client side and determining the area where performance bottlenecks exist is important which is why taking on a triangulation approach is important.

Client Side

Currently in the client, you can invoke the Appcelerator.Util.Performance component. To enable it, simply include logStats=1 in your url, for example: http://localhost:8080/myapp?logStats=1. The performance component by design will have no impact on your application unless you include this parameter. By default, the servicebroker will calculate the statistics for handling all message types both local and remote. The statistics will include the following:

• last – the last recorded time
• mean
• hits – aka count
• min
• max
• total – total time overall

These statistics will be logged to the console (available in Firefox with Firebug and in Safari with Webkit).

However, you do not need to have logging available to inspect the statistics (please see the section “Viewing Client Side statistics” below). In addition the component also allows for resetting all statistics to restart your recording.

Capturing your own statistics

If for some reason you want to capture statistics at a finer level, you can easily to this in javascript:

1
2
3

var stat = Appcelerator.Util.Performance.createStat();
//do some work
Appcelerator.Util.Performance.endStat(stat,"mystat","mycategory");

In this example we create a statistic called “mystat” that will be included in a category of “mycategory”. This is useful for filtering through your stats as well as being able to compare statistics side by side. For example, the service broker will automatically record the following categories:

• remote
• local

Viewing Client Side statistics

You may want to include the following content file in your application and make it visible when the logStats=1 parameter is included.

Here is the content source itself
clientperformance.html

Tuning Considerations

As you develop larger applications, it may be useful to consider the following tips:

• use lazy=true for app:content files. this will help to delay long initial load times for your applications
• if you do not lazily load your content files, consider postponing app:message invocations until they are needed
• consider using CSS selectors in the implementation of your app:iterator rather than re-firing messages for logic
• leverage the app:datacache to reduce the number of outgoing messages
• make use of pagination if rendering large datasets – the app:datatable allows for client side pagination for example

Wrap Up

We covered in this article

• how you can capture statistics for client side applications
• some performance tips in regards to client applications

In a later article we will identify how you can take this a step further to capture statistics on the server side as well with java services.This article has been cross posted on

ShareThis

Using Model Objects

The issue of serializing/transforming model objects is not new, heck I’ve been doing this for quite some time:

• rmi (ejb/corba)
• xml (jms, soap, etc..)
• json

JSON is not the only way to serialize objects for web2.0 applications, but its the most abundant and heavily used throughout our framework. Doing this is actually really easy to do with appcelerator IModelObejects. Our IModelObjects can easily be used along with hibernate for persistance, but lets leave that for later for now. When you define your Model classes, there are some very simple things to keep in mind:

• annotate your attributes with @MessageAttr
• have your class implement IModelObject

Here is a simple example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

public class User implements IModelObject, Serializable {
  private static final long serialVersionUID = 1L;
 
  @MessageAttr
  public String name;
 
  public void setUsername(String username) {
    this.username = username;
  }
 
 public void setPassword(String password) {
   this.password = password;
  }
 
  ...
}

Unit test it

Now to test the rendering of our object to JSON with a simple junit test…. As you can see, we leverage the Appcelerator framework to serialize our objects to JSON

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

public class ForumTest extends TestCase { 
 
public void testSimple() {
  User user = createUser();
  Message message = new Message();
  JSONMessageDataObject data = new JSONMessageDataObject();
  message.setData(data);
  message.getData().put("user", user);
  message.getData().put("count", 1);
  String messagestr = data.toDataString();
  assertEquals(messagestr,"\"user\":{\"password\":\"pwd\",\"threads\":0,\"fullName\"
  :\"antewew\",\"username\":\"azuercher\",\"state\":\"mystate\",\"email\":\"email\",
  \"posts\":0,\"id\":0},\"count\":1}");
}
 
private User createUser() {
  User user = new User();
  user.setEmail("email");
  user.setFullName("ante wew");
  user.setId(new Long(0));
  user.setPassword("pwd");
  user.setPosts(new Long(0));
  user.setState("mystate");
  user.setThreads(new Long(0));
  user.setUsername("azuercher");
  return user;
}
 
}

Dealing with recursion

Whats always a bit of a tangle is understanding how to deal with the recursive/circular relationship.
If you take a look at JSONObject you will see 2 overridden methods for createBean

1
2

public static JSONObject createBean(IModelObject object,MessageAttr parentAtt, String context,String[] parentSuppres,int level, int maxlevels)
public static JSONObject createBean(IModelObject object)

The latter is obviously a bit more simple, but the former is where the power is. In the MessageAttr annotation, you can provide the suppress attribute which is a comma separated list of aggregates (using bean.name notation to not serialize). This is used for attributes in your IModelObject implementation where the association is with another IModelObject. The following model is for a forum object model where the following aggregate hierarchy exists:

1
2
3

* Forum
** ForumThread
*** Post

In the snippet below, I’ve omitted the getter/setter methods for the aggregates for simplicity.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

public class User implements IModelObject, Serializable {
  @MessageAttr (suppress="user,thread.lastPost")
  public Post lastPost;
}
 
public class Post implements IModelObject, Serializable {
  @MessageAttr(suppress="lastPost,forum.lastPost")
  public Forumthread thread;
 
  @MessageAttr (suppress="lastPost")
  public User user;
}
 
public class Forumthread implements IModelObject, Serializable {
  @MessageAttr (suppress="lastPost")
  public Forum forum;
 
  @MessageAttr (suppress="thread,user.lastPost")
  public Post lastPost;
}
 
public class Forum implements IModelObject, Serializable {
  @MessageAttr (suppress="thread.forum,thread.lastPost,user.lastPost")
  public Post lastPost;
 
}

Rolling your own serialization

Assuming you know what your JSON string is going to look like, you can use our RawMessageDataList and RawMessageDataObject to serialze your objects. This is pretty useful if you already are rendering JSON in an existing framework and don’t want to have to transform to and back again. The snippet below shows with static strings just so that you get the idea:

1
2
3
4
5
6
7
8
9

IMessageDataList people = new RawMessageDataList(
"[{'name':'joe','age':22},{'name':'jane','age':33}]");
 
IMessageDataList dog = new RawMessageDataObject("{'breed':'doberman','weight':78}");
 
Message message = new Message();
message.setData(new JSONMessageDataObject());
message.getData().put("people", people);
message.getData().put("dog", dog);

Using Coarse Grained objects

This is probably the simplest/prettiest way to implement your services assuming that you aren’t interested in using fine grained classes that are associated with most of today’s persistence frameworks. Here is how you would create a single compound JSON object:

1
2
3
4
5

IMessageDataObject dog = MessageUtils.createMessageDataObject();
obj.put("breed","doberman");
obj.put("wieght",78);Message message = new Message();
message.setData(new JSONMessageDataObject());
message.getData().put("dog", dog);

and now with a collection:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

IMessageDataList<IMessageDataObject> people =
MessageUtils.createMessageDataObjectList();
 
IMessageDataObject joe = MessageUtils.createMessageDataObject();
joe.put("name","joe");
joe.put("age",22);
 
IMessageDataObject jane = MessageUtils.createMessageDataObject();
joe.put("name","jane");
joe.put("age",33);
 
people.put(joe);
people.put(jane);
 
Message message = new Message();
message.setData(new JSONMessageDataObject());
message.getData().put("people", people);

Summary

As you can see there are quite a bit of alternatives for you based on what your needs are to accommodate your service implementations. I’ve personally used all of the above as I’ve implemented:

• Model Objects: using hibernate for persistence
• Custom Serialization: for integrating with pre-rendered objects (commons-monitoring)
• Coarse Grained: in implementing a dashboard/event driven solution

cheers and enjoy,

-andrew

cross-posted @ http://zuerchtech.com/2008/2/8/json-serialization-with-appcelerator-java-services

ShareThis

Extending Appcelerator to support new widgets is actually pretty straight-forward. The first, and quite possibly most important, step is to create a name. The name must be unique to its namespace and, unless you want all your hard work to be ignored, be somewhat descriptive of what it does. If it’s a standard, general use widget, like a button, panel, or script block, it makes sense to put it in the app namespace. Specialized widgets, such as the widget to drop in google analytics, go in their own namespace. Staying within these conventions makes it simpler to include new widgets into the Appcelerator core. Other than convention, neither the name nor namespace will effect the functionality of the widget. For the stopwatch widget, we picked app:stopwatch. The rest of this article focuses on how we built it.

Once you’ve got a name, it’s time to create the directory structure for the widget. Navigate to the modules directory in the appcelerator source in your file-browser of choice, and create the following directory structure:

The directory should be called %namespace%_%widget% and needs to contain a file called %namespace%_%widget%.js. The directories css, images, and js aren’t required, you can omit them if your module does need any css, images nor depend on any javascript not contained within the widget. The stopwatch does not need any third party javascript or images, so we’re going to remove those directories.

You can write out all the boiler plate on your own, or you can do what we do and copy from a pre-existing widget. app:script is a good choice, since its implementation is relatively simple.
Lets take a look at the structure of the template:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

Appcelerator.Module.Stopwatch =
{
	getName: function()
	{
		return 'appcelerator stopwatch';
	},
	getDescription: function()
	{
		return 'stopwatch widget';
	},
	getVersion: function()
	{
		return 1.0;
	},
	getSpecVersion: function()
	{
		return 1.0;
	},
	getAuthor: function()
	{
		return 'My Name';
	},
	getModuleURL: function ()
	{
		return 'http://www.appcelerator.org';
	},
	isWidget: function ()
	{
		return true;
	},
	getWidgetName: function()
	{
		return 'app:stopwatch';
	},
	getAttributes: function()
	{
		//these attributes become part of the parameter map.
	},
	getActions: function()
	{
		//custom actions that this widget responds to go here
	},
	compileWidget: function(params)
	{
		//put code here if you need to add run-time code
	},
	buildWidget: function(element,parameters)
	{
		//this is where you build your widget’s html code.
 
		return {
			'position' : Appcelerator.Compiler.POSITION_REMOVE
		};
	}
};
 
Appcelerator.Core.registerModule('stopwatch',Appcelerator.Module.Panel);

Boring Functions
getName, getDescription, getVersion, getAuthor, and getModuleURL, are all for documentation. They do not effect the functionality of your widget.

getSpecVersion is the version for the module framework. For now, and the foreseeable future, it’s 1.0. This will be used in future versions of Appcelerator to provide backwards compatibility.

Again, in the future modules might be more than just widgets. The function isWidget should return true for widgets, so that the Appcelerator compiler does the right thing.

All of these functions are already correctly filled out in the stub above.

getAttributes: function()
this method returns the list of supported element attributes. The attributes defined in here will become the parameter keys in the parameter map passed into buildWidget and compileWidget. Each item in the list should be an object with the following properties:

The stopwatch has one optional parameter to control wether or not the buttons should be displayed. The complete code for this function in the stopwatch widget is:

1
2
3
4

getAttributes: function()
{
    return [{name: 'show_button', optional: true, description: "Set to false to hide button"}];
},

buildWidget: function(element, parameters)
This is where you define the presentation for your widget. Only presentation logic should reside in this function. Things like state and event listeners go in the compileWidget function described later.

The stopwatch widget replaces <app:stopwatch></app:stopwatch> with the text for the current time and, optionally, some buttons to control the widget. Therefore, we need to construct an html string.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

var html = [];
html.push('<div id="' + element.id + '" class="stopwatch">');
html.push('<table><tr>');
html.push('<td><h3 id="' + element.id + '_clock">00:00 <span>00</span></h3></td>');
if(parameters["show_button"] != "false") 
{
    html.push('<td class="stopwatch_start">')
    html.push('<app:button width="100" on="click then script[Appcelerator.Module.Stopwatch.start_stop(\'' 
            + element.id + '\')]">Start</app:button>');
    html.push('</td>');
    html.push('<td class="stopwatch_stop">');
    html.push('<app:button width="100" on="click then script[Appcelerator.Module.Stopwatch.start_stop(\'' 
            + element.id + '\')] and l:' + element.id + '_reset">Stop</app:button>');
    html.push('</td>');
    html.push('<td class="stopwatch_reset">');
    html.push('<app:button disabled="true" width="100" on="click then script[Appcelerator.Module.Stopwatch.clear_time(\''
            + element.id + '\')] and disable or l:' + element.id + '_reset then enable">Reset</app:button>');
    html.push('</td>');
}
html.push('</tr></table>');
html.push('</div>');

As you can see, this is pretty basic stuff. It’s just html. You’ll notice that we’ve used another widget app:button in this widget. This is completely valid and highly recommended. After all, it does not make sense to reinvent the wheel, if you don’t have to.

Also, notice that the buttons are controlled using on expressions. One drawback of using widgets inside other widgets is that they are not guaranteed to be loaded when compileWidget is called. Therefore, you cannot reliably add event listeners to widgets in compileWidget and you should use on expressions instead. In order to call functions within your module, you need to give the fully-qualified class name and surround the call in a script tag.

From this function, you need to return an object that looks like this:

1
2
3
4
5
6

return {
	'presentation' : html.join(' '),
	'position' : Appcelerator.Compiler.POSITION_REPLACE,
	'compile' : true,
	'wire' : true
};

What all this means:

Widgets aren’t required to have any presentation and could be completely non-visual. Therefore, the two most common values for position are Appcelerator.Compiler.POSITION_REMOVE, which removes this element from the DOM entirely (for non-visual widgets) and Appcelerator.Compiler.POSITION_REPLACE which removes the Appcelerator markup and substitutes what was defined in presentation.

compileWidget: function()
The stopwatch needs to store the state of its clocks and timer somewhere and the logical place is the class-level hash-map called stopwatches. In compileWidget, we create the entry for this particular stopwatch in the map:

1
2
3
4
5

compileWidget: function(params)
{
    var id = params['id'];
    Appcelerator.Module.Stopwatch.stopwatches.set(id, {'date': new Date(0), 'timer_id': null});
},

You could also assign event listeners to any html elements here as well, if you choose to use that approach instead of on events.

getActions: function()
This returns a list of functions that can serve as actions when the widget receives a message. The stopwatch allows you to start_stop, and clear_time. You might pause here and think that “toggle” and “reset” might be more logical names, but these are global actions available on all elements. Global action declarations take precedence over custom actions.

The code for this function is just:

1
2
3
4

getActions: function()
{
    return ['start_stop', 'clear_time'];  
},

Custom Actions
The get actions method allows you to define the custom actions that can be performed on the widget. To implement a custom action you need to implement a function with a particular signature:

start_stop: function(id,parameters,data,scope,version)

The full implementation of the start_stop function is:

1
2
3
4
5
6
7
8
9
10
11
12

start_stop: function(id,parameters,data,scope,version)
{
    var stopwatch = Appcelerator.Module.Stopwatch.stopwatches.get(id);
    if(stopwatch.timer_id != null)
    {
        Appcelerator.Module.Stopwatch.stop(id);
    } 
    else
    {
        Appcelerator.Module.Stopwatch.start(id);
    }
},

Responding to messages and events
There are a few ways you can do this, which you choose depends on your needs. The standard is to not do anything. Your widget will automatically respect the on attributed specified on it. For example:

<app:script on="l:toggle_me then start_stop"></app:script>

will call the function start_stop on the message l:toggle_me. No additional code was required.

However, this doesn’t always work, such as when an element internal to the widget needs to respect the on and not the widget itself. In this case, you need to over-ride the function dontParseOnAttributes like so:

1
2
3
4

dontParseOnAttributes: function()
{
    return true;
},

then manually add the contents of on to the required element in your buildWidget function. Also, remember to set wire to true.

Registering Module Resources
Every module has at least one resource that it will need to register (itself). To do this, you need to call

Appcelerator.Compiler.registerModule(moduleName, moduleClass)

outside of the class declaration for your module.
If you have third party javascript, you need to call:

Appcelerator.Core.registerModuleWithJS(moduleName,moduleClass,[list_of_files]);

instead. The javascript must be in the javascript directory under the module root.

If your module has any module-specific css, you will also need to call

Appcelerator.Compiler.loadModuleCSS(moduleName,cssFileName).

For this call to work, the file must be in the module’s css directory.

Since the stopwatch has css, but no javascript, you’ll find the following at the very bottom of app_stopwatch.js

1
2

Appcelerator.Core.registerModule('app:stopwatch', Appcelerator.Module.Stopwatch);
Appcelerator.Core.loadModuleCSS('app:stopwatch', 'stopwatch.css');

The Final Product
The stopwatch is now complete. You can see the full source code at https://svn.appcelerator.org/appcelerator_sdk/trunk/src/web/modules/app_stopwatch/.

The stopwatch widget is slated to be included in the Appcelerator 2.1 release. Once that release goes live, so to will the Web Units.

Any questions about this guide or building widgets should be directed towards our google group, appcelerator-platform-sdk@googlegroups.com.

ShareThis