String Interpolation

Appcelerator uses Ruby-style string interpolation in several different contexts. A typical use-case for interpolated variables is within an app:iterator:

<app:iterator on="l:data.message then execute" property="pets">
  #{name}, #{age}<html:br/>
</app:iterator>
<app:script>
  $MQ('l:data.message', {pets: [
    {name: 'Fluffy', age: 2},
    {name: 'Patchy', age: 6},
    {name: 'Scaly',  age: 12},
    {name: 'Itchy',  age: 4},
  ]});
</app:script>

In this case, the variables #{petName} and #{petAge} are replaced by text from the item in rows that is being iterated over.

When you have nested iterators, the outermost iterator will interpolate its variables before the inner iterators are executed. This can be confusing if you are used to variable shadowing in traditional languages. The solution to this problem is to give different names to the variables in your inner and outer iterators.

For example, in the following example, we’ve used #{ownerName} and #{petName} rather than the ambiguous variable name #{name} (which would have caused all the pets to take their owners’ names).

<app:iterator on="l:data.message then execute" property="people">
  <html:div>
    #{ownerName}:
    <app:iterator items="#{pets}">
      #{petName}, #{petAge}<html:br/>
    </app:iterator>
  </html:div>
</app:iterator>

Other uses of interpolation

String interpolation is also used in the following contexts:

• In the app:http widget, the uri attribute of the uri tag is interpolated with data from the message payload:

  <app:http on="l:get.pictures then get">
    <uri method="get" uri="http://api.fluttr.com/#{user}/photos/#{year}/#{month}/#{day}/feed.xml" response="l:get.pictures.response"></uri>
  </app:http>
  <app:script>
    $MQ('l:get.pictures', {
      year:  2008,
      month: '06',
      day:   16,
      user:  'bluebird'
    });
  </app:script>

• The app:content widget provides an attribute args which will be used to replace any variables in the content file.

• The app:pagination widget allows string interpolation in the attributes prevText, nextText, resultsString, and totalsString.

• The app:widget allows string interpolation in its body, based on parameters passed to the widget:

  <app:widget name="app:kitten" required_params="name,age">
    #{name}: Meow, I'm #{age} months old.<html:br/>
  </app:widget>
  
  <app:kitten name="Mewley" age="2"></app:kitten>
  <app:kitten name="Grumbly" age="2"></app:kitten>

Interpolating JavaScript expressions

The SDK supports using JavaScript expressions such as #{firstName.capitalize()} of expressions. This is very useful for doing formatting and localization of dates.

Using interpolation in your own widgets

If you are creating a widget and provide a way for users to replace template variables with data, you can use the Appcelerator.Compiler.compileTemplate to build a templating function:

var variableScope = {firstName: 'Sam', lastName: 'Steinheim'};
var text = "My name is #{firstName} #{lastName}";
var templateFunc = Appcelerator.Compiler.compileTemplate(text);
templateFunc(variableScope); // yields "My name is Sam Steinheim"

The template variable above can be reused with different variable scopes. The app:iterator, for example, compiles a single template and calls it repeatedly for each row of data.