Version 1

Initially I built a prototype in the big plastic box. It went with the temperature sensor, LED display, power override button and two independently commutated pairs of sockets. It worked off of and old iPad power adapter. Here how it looks inside and outside:

As you can see, it was pretty complicated inside. Built on Android Nano V3 328. Included power-independent RTC and used the 4-relay commutation module.

Practice showed all that wasn't quite reliable and useful. Thermometer with one of the commutated power sockets were intended for heating circle, but then I discovered that my heating is already regulated and maintains the temperature. So that's unnecessary.

What's left was the timer module for the lighting. I didn't need the screen too as it's always inside the aquarium stand and no one sees it anyway. Here is where the story of the Timer v2 begins.

Version 2

It didn't happen immediately after I decided to rebuild my first iteration. Over the while I've got excited about ESP8266 and figured that might be a great choice for the next gen timer. It is small, working on 3.3v, allows to connect to my local network to check status and make remote switching if necessary; all in one small body.

Here's the schematics of what I came up with:

220V power comes through J1 and is converted into 5V that is used to feed WeMos D1 Mini and switch the relay module. Since WeMos D1 Mini operates 3.3v, we need to use a NPN transistor as a simple switch. Traditional choice is 2N2222 with a 1kOm resistor in the base circuit to limit the current. We also need a D1 diode to cut out reverse current in the relay circuit. That's all schematically.

The casing was designed in Sketch Up and 3D-printed in three iterations, all due to small errors in measurements. I used PETG plastic as the material and it worked very nicely. Here's the model and the result:

Everything mounts without screws. It's so nice to be able to print stuff in whatever dimensions you need!

Software

Finally, here's the software running on the board:

Sources on BitBucket

Schematics

Things to notice here is power regulator 1117-33 that converts 5V of Arduino board into stable 3.3V for ESP8266. We could probably use 3.3V Arduino output, but I read it's not powerful enough for when the module is transmitting. Also I wired Arduino D11 to RXD of ESP8266 through voltage divider, so that 5V is also converted to 3.3V range. Logic level converters can be used here, but I have none handy, so divider be it.

Software

My module was initially in 115200 baud mode. When you don't know that it may cause a lot of confusion. Arduino I have isn't quick enough to do any useful work and catch up, so I had to find a way to switch module to a lower baud rate.

The module speaks AT-commands, and there are dangerous sequences that can brick your module that I won't write here to save everyone from trouble. Here's a pretty good one instead:

AT+UART_DEF=57600,8,1,0,0

It switches UART into 57600 baud mode with 8 bits, 1 stop bit, 0 for parity and 0 for flow control.

Here's the small program that lets you talk to the module in Serial Monitor tool.

#include <SoftwareSerial.h>

SoftwareSerial wifi(10, 11); // RX, TX

void setup() {  
  Serial.begin(115200);
  while (!Serial) { }

//  wifi.begin(115200);
//  wifi.println("AT+UART_DEF=57600,8,1,0,0\r\n");

  wifi.begin(57600);
  wifi.println("AT+GMR\r\n");
}

void loop() {  
  if (wifi.available()) Serial.write(wifi.read());
  if (Serial.available()) wifi.write(Serial.read());
}

Resources

• KIA1117 Datasheet
• ESP8266 Quick Start Guide
• Wiki article on ESP8266

Fading in

alpha='if(lt(t,t1),0,(t-t1)/t2)'

• t1 - start time (in seconds),
• t2 - length (in seconds).

Fading out

alpha='if(lt(t,t1),1,(t2-(t-t1))/t2)'

• t1 - start time (in seconds),
• t2 - length (in seconds).

Fading in and out

alpha='if(lt(t,t1),0,if(lt(t,t1+t2),(t-t1)/t2,if(lt(t,t1+t2+t3),1,if(lt(t,t1+t2+t3+t4),(t4-(t-t1-t2-t3))/t4,0))))'

• t1 - fade in start time (in seconds),
• t2 - fade in length (in seconds),
• t3 - time to keep fully opaque (in seconds),
• t4 - fade out length (in seconds).

If you happen to know a better way or shorter expressions, please let me know.

Let's assume that we want the CLI interface to look like this:

myscript <key> [-v <value>] [-l]

Here we have:

• required option
• two optional keys, one of which with required parameter

There's a very handy tool -- getopt -- which handles filtering and parsing command line options. Here's how we'll use it to define optional keys:

TEMP=`getopt lv: $@`

Here we set that we want to recognize only two options: l without arguments and v with one argument. Then we put whatever the script received as parameters as $@. The getopt command will set return status to 0 if parsing was successful and will return something else otherwise. We need to check if it's fine and continue, or show the usage information and exit if not:

usage() {
  echo "USAGE: myscript <key> [-v <value>] [-l]"
  exit 1
}

if [ $? != 0 ]; then usage; fi

In case of success we move on. The result of getopt will be saved into the TEMP var. The way getopt works is it puts the recognized options first, then places -- and finishes the string by listing everything it didn't understand.

Here are some examples to illustrate:

$ getopt lv: -l
-l --

$ getopt lv: -v test
-v test --

$ getopt lv: -v test -l
-v test -l --

$ getopt lv: -v test -l xyz
-v test -l -- xyz

However, if you specify an unknown option, it will return the status code 1 and output an error like this:

$ getopt lv: -v test -a
getopt: illegal option -- a
 -v test --

Let's parse this output. First lets put the TEMP into $@ while respecting any possible quotations.

eval set -- $TEMP

Next, let's go through the $@ item by item and see what we encounter.

for i
do
  case "$i"
  in
    -l)
      echo "Found -l option"
      shift;;

    -v)
      echo "Found -v option with parameter '$2'"
      shift 2;;

    --)
      shift;
      break;
  esac
done

As you can see, it all is pretty easy to grasp. Two things to notice:

for i
do
done

is basically equivalent to:

for i in "$@"
do
done

And the second is that after eval set -- $TEMP we have everything in our TEMP var assigned to $@ and the first nine arguments to $1 through $9. So first argument is in $1. When we iterate over the $@, we pick the first item, find the matching branch in case statement, act on it, then shift whatever number of arguments we consumed out of $@ and run another cycle. The exit condition is finding -- (in which case we also shift it out, in case we need the remainder).

Now that you know what this shift command does, let's recall that we wanted to have the required first argument. Here's the piece we should put at the very beginning after the usage function definition.

if [ $# -lt 1 ]; then usage; fi
key=$1
shift 1

It checks if we have enough arguments, picks the first one and shifts it out in preparation to optional arguments parsing.

Here's the full version of the script:

usage() {
  echo "USAGE: myscript <key> [-v <value>] [-l]"
  exit 1
}

if [ $# -lt 1 ]; then usage; fi
key=$1
shift 1

TEMP=`getopt lv: $@`
if [ $? != 0 ]; then usage; fi

setting=0

for i
do
  case "$i"
  in
    -l)
      echo "Found -l option"
      shift;;

    -v)
      echo "Setting value of '$key' to '$2'"
      setting=1
      shift 2;;

    --)
      shift;
      break;
  esac
done

if [ $setting -eq 0 ]; then
  echo "Reading value of '$key'"
fi

Go ahead and try it:

$ ./myscript
$ ./myscript test
$ ./myscript test -v value
$ ./myscript test -l

Here is how my Dockerfile looks:

# Dockerfile
FROM trenpixster/elixir:1.3.0

# Install AWS client (optional)
RUN apt-get update
RUN apt-get install -y awscli

RUN adduser --quiet deploy
WORKDIR /home/deploy

# Copy the app
COPY . app
RUN chown -R deploy:deploy app
WORKDIR app

USER deploy
ENV MIX_ENV prod

# This is to make sure it doesn't ask for Hex and Rebar
RUN mix local.hex --force
RUN mix local.rebar --force

# Build the release
RUN mkdir -p priv/static
RUN mix do deps.get, phoenix.digest
RUN touch config/prod.exs

# Prepare data directory
RUN mkdir -p /home/deploy/data/mnesia

EXPOSE 8080
EXPOSE 8443
VOLUME /home/deploy/data
ENTRYPOINT ["mix", "do", "compile,", "phoenix.server"]

Let's go section by section and I explain what's going on.

Base image. To create a runable Docker image I pick either official Elixir image (elixir) or the one by trenpixter (trenpixter/elixir). The last one tends to be very slightly ahead of the official.

# Dockerfile
FROM trenpixster/elixir:1.3.0

APT packages. If you need any system packages, you can install them as you usually would. Here I install AWS CLI package that I use to store backups to AWS S3.

# Install AWS client (optional)
RUN apt-get update
RUN apt-get install -y awscli

User setup. You obviously need a user that will run the app. Traditionally, I call it deploy, but it can be anything.

RUN adduser --quiet deploy
WORKDIR /home/deploy

Placing sources. Now the fun part begins. We need to get sources of the app into the box. I don't use any git repositories or anything for this, just copy sources from my working folder into the image.

# Copy the app
COPY . app
RUN chown -R deploy:deploy app
WORKDIR app

There are some files and directories that I don't want to be copied over and so I put them in a .dockerignore file that sits in the root of my local project tree:

# .dockerignore
.git
Dockerfile*
d-build
_build
deps
rel
Mnesia*
test

This one is typical, so you can grab it and add your own lines as necessary. Moving on.

Building the release. Now that the environment and sources are all ready we switch the user to the one that will be running the app and set the environment variable to production:

USER deploy
ENV MIX_ENV prod

This little hack is to make sure the building phase doesn't ask to install / update Hex and Rebar interactively. You certainly can't answer that.

# This is to make sure it doesn't ask for Hex and Rebar
RUN mix local.hex --force
RUN mix local.rebar --force

Finally, we create a directory for assets, fetch dependencies and build the app as part of the Phoenix static assets digesting.

# Build the release
RUN mkdir -p priv/static
RUN mix do deps.get, phoenix.digest
RUN touch config/prod.exs

The last line in the block above deserves some explanation. In this particular app I pass env variables to the app during the container launch. These vars customize behavior of the app and are part of the app configuration. If I don't touch the script, it won't be reconsidered during the app start and the app won't pick up new var values.

Launch configuration. In this app I use Mnesia database and as logic suggests, its data should be stored outside the box to survive the restarts and crashes. For this purpose I create a directory inside the user home /home/deploy/data that I then expose to the Docker environment as VOLUME. This volume will be mounted during the container start to a location in the host environment. Either default location Docker chooses for you, or your specific one.

Finally, I tell to expose two ports and specify the entry point that will be run when the container with this image launches -- mix do compile, phoenix.server:

# Prepare data directory
RUN mkdir -p /home/deploy/data/mnesia

EXPOSE 8080
EXPOSE 8443
VOLUME /home/deploy/data
ENTRYPOINT ["mix", "do", "compile,", "phoenix.server"]

Running the image

Here's how I run the image:

docker run --name myapp \
  -td \
  --restart=unless-stopped \
  -p 80:8080 \
  -p 443:8443 \
  -v /home/alg/volumes/myapp:/home/deploy/data \
  -e APP_VAR="1234" \
  image

• I tell Docker to run this container with the name myapp.
• It should be a detached TTY (we obviously want it to run in background).
• It should be restarted upon crashes until explicitly stopped.
• I bind ports 8080 and 8443 that this container provides to my host's 80 and 443, so that whatever app runs in it is exposed to the outside.
• The volume /home/deploy/data that was defined in the Docker file is bound to the host's directory /home/alg/volumns/myapp.
• I pass an environment var APP_VAR to the container. This var is used in the app.
• And finally, here's the name of the image we built with that Dockerfile above.

Have fun!

• Don't use custom schemes. Links with custom schemes are no longer clickable in SMS, Chrome and Gmail on Android.
• Use http / https schemes with your app domains. If your domains have "well-known" asset link files, your app is offered as the default handler. (Verification pending)

Quick start -- Android

• Register intent-filter for your activity. Here we tell that this app can handle HTTP and HTTPS links to my.domain.com with paths starting with /app.

<android>  
  <manifest>
    <application>
      <activity ...>
        <intent-filter>
          <action android:name="android.intent.action.MAIN"/>
          <category android:name="android.intent.category.LAUNCHER"/>
        </intent-filter>
        <intent-filter>
          <action android:name="android.intent.action.VIEW"/>
          <category android:name="android.intent.category.DEFAULT"/>
          <category android:name="android.intent.category.BROWSABLE"/>
          <data android:scheme="https" />
          <data android:scheme="http" />
          <data android:host="my.domain.com" />
          <data android:pathPrefix="/app"/>
        </intent-filter>
      </activity>
    </application>
  </manifest>
</android>  

• Put the app links verification file to the web server at my.domain.com/.well-known/assetlinks.json. This is only necessary if you want your app offered for that domain name links handling by default. If you can live with it just being offered along with Chrome or other browsers, that's fine to leave it out.

{ relation: [ "delegate_permission/common.handle_all_urls" ],
  target: {
    namespace: "android_app",
    package_name: "com.noizeramp.myapp",
    sha256_cert_fingerprints: [
      "14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"
    ] }
}

You get fingerprint from $ keytool -list -v -keystore my-release-key.keystore

• Add in-app handling of the event (Titanium version).

Ti.App.Android.launchIntent.getData()  

Quick start -- iOS

• Register entitlements. Put the details into the MyApp.entitlements file:

<?xml version="1.0" encoding="UTF-8"?>  
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">  
<plist version="1.0">  
<dict>  
  <key>com.apple.developer.associated-domains</key>
  <array>
    <string>applinks:my.domain.com</string>
  </array>
</dict>  
</plist>  

• Put the app links verification file to the web server. Here we tell that we allow the app with this appID to handle paths starting with /app on this domain. The app links verification file should be placed at my.domain.com/apple-app-site-association or my.domain.com/.well-known/apple-app-site-association.

applinks: {  
  apps: [],
  details: [
    { appID: "675aasd9f8.com.noizeramp.myapp",
      paths: [ "/app/*" ] }
  ]
}

• Add in-app handling (Titanium version).

if (OS_IOS) {  
  Ti.App.iOS.addEventListener('continueactivity', function(e){
    // This is important hack for 5.2.x (until 5.4.0). This createUserActivity
    // call that is never exectured is needed for the compiler to know we are
    // interested in continueactivity event.
    if (e.activityType === "never-executed") {
      Ti.App.iOS.createUserActivity();
    }

    if (e.activityType === "NSUserActivityTypeBrowsingWeb"){
      onOpen(e.webpageURL);
    }
  });
}

Links of interest

• iOS

  • https://developer.apple.com/library/ios/documentation/General/Conceptual/AppSearch/UniversalLinks.html
  • Appcelerator Titanium SDK 5.2.0 broke continueactivity event delivery, and so we need a hack. The fix is to be delivered in SDK 5.4.0. Related issue -- https://jira.appcelerator.org/browse/TIMOB-20220

• Android

  • https://developer.android.com/training/app-links/index.html
  • https://developer.android.com/guide/topics/manifest/intent-filter-element.html
  • https://developer.android.com/guide/topics/manifest/data-element.html

<!-- demo.xml -->  
<Page navigatingTo="navigatingTo">  
  <StackLayout orientation="vertical">
    <TextField text="{{ filter }}" hint="Enter filter"/>
    <ListView items="{{ items }}" />
  </StackLayout>
</Page>  

This is a very basic page with a ListView component that is supposed to list string values and a TextField that we'll use for filtering purposes.

// demo.js
var DemoModel = require("./demo-model");

exports.navigatingTo = function(e) {  
  var page = e.object;
  page.bindingContext = new DemoModel();
};

In the controller we create an instance of the model (see below) and bind it to a pange.

// demo-model.js
var Observable = require("data/observable").Observable;  
var _ = require("lodash");

module.exports = function() {  
  var model = new Observable();

  model.allItems = [ "Jack", "John", "Mark", "Ashley" ];
  model.items    = _refilter();
  model.filter   = "";

  function _refilter() {
    var items = model.allItems;
    var filter = model.filter.trim();

    if (filter) {
      var regexp = new RegExp(filter, 'i');
      items = _.filter(items, function(i) {
        return i.match(regexp);
      });
    }

    return items;
  }

  model.on(Observable.propertyChangeEvent, function(e) {
    if (e.propertyName === "filter") model.set("items", _refilter());
  });

  return model;
};

Our model is an instance of Observable. In allItems we hold the original list, items property is what we actually render, and filter holds current filter string. The only function -- _refilter -- creates a new list out of the original basing on the current filter value. We call it initially, and every time the filter property changes.

Simple enough.

From Model to View

Let's take this simple XML template consisting of just one field.

<!-- demo.xml -->  
<Page loaded="loaded">  
  <Label text="{{ name }}" />
</Page>  

It has a page with the loaded event handler bound to the co-named method of the controller and a single label with the text bound to the property of the page context named name.

// demo.js

var model = { name: "NativeScript };

exports.loaded = function(e) {  
  var page = e.object;
  page.bindingContext = model;
};

This is a really simple controller. The loaded method is called when the XML page is loaded. The single argument is an event object. The object property points to the source of event -- this page. The most important part here is the assignment of the model to page.bindingContext. This is how you pass the context to the XML view. This is how you tell what the name is in your template. Easy.

From View to Model

Now that we know how to display data from controller in the view, let's pass the data back.

<!-- demo2.xml -->  
<Page loaded="loaded">  
  <StackLayout orientation="vertical">
    <TextField text="{{ firstName }}" />
    <Button text="Save" tap="save" />
  </StackLayout>
</Page>  

Slightly more complex template with two components arranged vertically. The text field linked to the firstName context (model) property and the button that calls exported save method on tap.

// demo2.js
var model = { firstName: "Mark" };

exports.loaded = function(e) {  
  var page = e.object;
  page.bindingContext = model;
};

exports.save = function(e) {  
  alert(model.firstName);
};

Here the save handler is of interest. We don't look up the view and don't query its text property. Instead, we pick the current value from the model. NativeScript keeps the property in the model in sync with the view. When you change it in code, the view updates. When the user types something new in the view, the model in memory changes (and property change events are fired).

From Controller to Controller (forward)

Now it's turn to understand how do you pass data from one controller to the next. Let's assume that we have two pages -- an index list of items and the details view.

<!-- index.xml -->  
<Page loaded="loaded">  
  <ListView items="{{ items }}" itemTap="onItemSelected">
    ...
  </ListView>
</Page>  

We'll use a list view to display items. I don't go into the details of the view implementation. All you need to know is that the list view calls itemTap handler every time you tap on an item in the list.

// index.js

exports.loaded = function(e) {  
  var page = e.object;

  var items = [
    { id: 1, name: "Apples" },
    { id: 2, name: "Grapes" }
  ];

  page.bindingContext = {
    items: items
  };
};

exports.onItemSelected = function(e) {  
  var itemView = e.object;

  // Item is going to be one of the items from the list
  // that we bound to the list view:
  // { id: 1, name: "Apples" }, or
  // { id: 2, name: "Grapes" }
  var item = itemView.bindingContext;

  Frame.topmost().navigate({
    moduleName: './details',
    context: item
  });
};

We setup items list as an array of items with some data. When the list view is rendered, every item view in the list is assigned its own bindingContext (just like the one we assign to the page in the loaded handler.) It's done automatically by the list view component.

When an item is tapped, ListView calls a method bound to itemTap property and passes the item view in the object property of the event. This view has the item it renders in the binding context. In our case it is one of two hashes (with names "Apples" or "Grapes").

We take the item from the bindingContext and pass it on to the details view as that view context. Look how elegantly have we passed the tapped item to the details controller. You an pass any data to controllers this way.

// details.js

exports.loaded = function(e) {  
  var page = e.object;

  // Get the context passed to this controller by the previous one:
  // In our case: { id: x, name: y }
  var item = page.navigationContext;

  page.bindingContext = item;
};

The details controller is very simple. It takes the context that we sent to it (tapped item) and assigns it to the binding context of the page, so that the view could access the id and name properties. You aren't limited to this, of course. For example, you could use item.id to load more data.

Sending data back from Controller to the parent Controller

Sometimes we need to return some results from the controller. For example, when you select an avatar from a gallery, or a country from a list in a separate controller and then bring the selection back to the previous screen. How do we pass the results back?

The answer lies in the context again.

// first.js

var model = {};

exports.navigatingTo = function(e) {  
  if (e.isBackNavigation) {
    // returning from the second.js
    alert(model.result);
  } else {
    // entering this controller initially
  }
};

export.onGotoSecond = function() {  
  Frame.topmost().navigate({
    moduleName: './second',
    context: model
  });
};

Instead of the loaded handler we use navigatingTo handler that is called earlier, before the page is loaded, and contains the isBackNavigation flag that is set to TRUE when we are returning from the later controller back to this one.

It's not important when the onGotoSecond is called. It can be a button touch or some other event. When we navigate to the second screen we pass our model as the context and expect to see the result in it. This trick works since in JavaScript data is passed by references, not values. For us it means that whatever changes the second controller makes to the model we pass to it, the first controller "sees."

// second.js

var model = null;

exports.loaded = function(e) {  
  var page = e.object;
  model = page.navigationContext;
};

exports.onSubmit = function() {  
  model.result = "the result of this screen";
  Frame.topmost().goBack();
};

Here in the second controller, we save navigation context into own model variable, and upon the onSubmit event, set the result property of it to something useful. When going back, we get into the e.isBackNavigation === true branch of the first controller's navigatingTo handler and can work on the results.

Hope this intro to practical data binding patterns was helpful.

This morning I submitted my own docset for NativeScript 1.7.1. It's been accepted later today and can be found in Preferences -> Downloads -> User Contributed. Search for "NativeScript".

I'm planning on adding How-to's and guides from the official documentation site in it in the upcoming release.

Let's start with the list of bits we'll need for a successful sync:

• ContentProvider. Even if you don't use content providers, you'll need one, or the whole thing will crash on you.

• Authenticator and a binding service. Sync framework uses authenticators to manage user account tokens. Even if you don't need user account to access global app data, you need an authenticator. Let it be a no-op empty thing.

• Sync adapter and a binding service. This is the heart of it. Every time the sync is needed, the onPerform method is called.

You may have noticed that:

• We need binding services for authenticator and sync adapter. The services are the entry points for the sync framework and other apps (if you choose to allow that).

• We still need an account for an account-independent sync. If you look at other apps, like Shazam that require similar syncs, you'll notice they have a "Sync" account hardwired in Settings -> Accounts -> <App name>

Next, let's look at the steps. There's a great class by Google that you can follow to get your basic setup ready. Here's what you will do:

• Create a no-op content provider
• Create a no-op authenticator and its binding service, declare it in the manifest
• Create an empty sync adapter with its binding service, declare it in the manifest

A couple of things that puzzled me at this point:

• Account type (as seen in xml/authenticator.xml, xml/syncadapter.xml and MainActivity) is the identifier of the sync account. You tie together sync adapter with authenticator and account with it.

• Authority (as seen in xml/syncadapter.xml and provider definition in manifest). This is a link between the content provider and the rest of the world. At the very least, every sync adapter is linked to a specific content provider through the authority identifier.

Creating user account

In Google class it is shown how the sync account is added through the AccountManager. What's missing is the explanation of how to deal with the edge cases.

• During every app start, when you setup sync account, you need to check if the account with your account type is already present. If it is, you just use that account, and not even attempt adding a new one. Here's the bit of code:

AccountManager accountManager = AccountManager.get(this);  
Account[] accounts = accountManager.getAccountsByType(ACCOUNT_TYPE_GLOBAL);  
if (accounts.length > 0) {  
    globalSyncAccount = accounts[0];
} else {
    Account newAccount = new Account(ACCOUNT_GLOBAL, ACCOUNT_TYPE_GLOBAL);
    ...
    // add new account and init (see below)
}

• When you are adding an account, you may want to configure it on the spot. Sync framework operates on per-account basis, which means that you need to configure an account if you want to enable periodic updates etc. Here's how it's done:

if (accountManager.addAccountExplicitly(newAccount, null, null)) {  
    // registered new account, save it
    globalSyncAccount = newAccount;

    // Configure automatic account updates
    ContentResolver.setIsSyncable(globalSyncAccount, AUTHORITY_GLOBAL, 1);
    ContentResolver.setSyncAutomatically(globalSyncAccount, AUTHORITY_GLOBAL, true);
    ContentResolver.addPeriodicSync(globalSyncAccount, AUTHORITY_GLOBAL, Bundle.EMPTY, 60 * 60);
} else {
    // failed to register
    globalSyncAccount = null;
}

Forcing sync on app start

Basically, you don't do this. Following the traditional approach deeply ingrained in my mind, I tried to make it work and succeeded, but somewhere along the way I've got an understanding that in most cases this is completely unnecessary. The reason for that is periodic updates. You can configure your global data account to be updated (roughly) once an hour or once a day (depending on how frequently your data changes) and the system will perform the updates even when the app isn't running. Which means that you literally have the most recent data whenever your app starts.

To get laser-precise with updates, you can use GCM to get an invisible to user notifications when the backend changes data. Your app will be able to seamlessly update itself in the background in the most energy-friendly fashion (sync framework keeps an eye on when it's the best time to run syncs, batches them and does the rest to save energy).

If you still absolutely need to update on launch, go ahead and send a manual sync request. Just note that in some cases, you may encounter that your syncs run twice in a row. The exact nature of this effect is still unclear, but it looks like happening if you request a sync from the Application.onCreate() method. Moving it to main activity's onCreate() solved the problem (watch out for orientation changes which trigger this method -- you don't want to send a sync request every time the user turns their device).

What's next?

Next I'll be working on integrating user-specific syncs. This will get much more curious since it's a two-way street.

The goal

In this post we are going to build a very simple chat app with multiple rooms. Anyone with the link will be able to connect and say something. We won't be storing the history of messages for the case of simplicity.

If you are lost, or just want to skip over some hoops, the source of the app we build here is available at Github.

Preparations

This walkthrough will require Elixir 1.0.2+ as a dependency for Phoenix Framework. Please install it before you start.

Get the latest Phoenix Framework.

$ git clone https://github.com/phoenixframework/phoenix.git && cd phoenix && git checkout v0.6.2 && mix do deps.get, compile

Create a new phoenix app. This creates a new app that is configured to use Phoenix Framework. You don't need the phoenix folder that was checked out of the repo in the previous step.

$ mix phoenix.new chatex ~/tmp/chatex

Compile and launch your app skeleton.

$ cd ~/tmp/chatex
$ mix do deps.get, compile
$ mix phoenix.start

You should see the root page at http://localhost:4000/ now.

Layouts and assets

When we created a Phoenix app, the mix task initialized directory structure for us:

• config folder is for your config files
• lib is for standalone library code
• Static files go into the priv directory (much like public in Rails)
• test folder has familiar to Rails developers structure for tests
• web folder contains your web application code (much list app in Rails)

Throw in jquery-2.1.1.min.js and bootstrap.min.js (3.3.1) into priv/static/js and bootstrap.min.css into priv/static/css.

Update the layout web/templates/layout/application.html.eex to include our new assets and clean up a bit. Here's what I got:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <meta name="description" content="">
    <meta name="author" content="">

    <title>Chatex</title>
    <link rel="stylesheet" href="/css/bootstrap.min.css">
  </head>

  <body>
    <div class="container">
      <%= @inner %>
    </div>

    <script type="text/javascript" src="/js/jquery-2.1.1.min.js"></script>
    <script type="text/javascript" src="/js/bootstrap.min.js"></script>
  </body>
</html>

If you are familiar with Rails layouts, you should be at home with the notion of inserting generated pages inside the broader layout file. Here we have <%= @inner %> marking the place where the generated page content goes.

Routing

Open the web/router.ex file. What you see shouldn't be terribly hard to comprehend. You can read more on routes in officinal Routing guide. Let's just define three routes.

scope "/", Chatex do
  pipe_through :browser
  get "/",    RoomsController, :show
  get "/:id", RoomsController, :show
  post "/message/:room_id", MessagesController, :create, as: :new_message
end

Controllers

Let's add Chatex.RoomsController:

defmodule Chatex.RoomsController do
  use Phoenix.Controller

  @default_room "Lobby"

  @doc "shows a specific room with room_id specified"
  def show(conn, %{ "id" => room_id }) do
    conn |> render_room room_id
  end

  @doc "shows a default room -- Lobby"
  def show(conn, _params) do
    conn |> render_room @default_room
  end


  # renders the room with given ID
  defp render_room(conn, room_id) do
    conn |> render :show, room_id: room_id
  end

end

We add two show clauses -- one for the default room and one for the room with ID.

You can read more about controllers in the official controllers guide.

With that out of the way, let's move to views. We will get back to controllers when sending actual messages.

Views

Views are slightly different from what we've seen in Rails. They consist of two parts -- presenter module and templates. Read more on views in the official views guide and templates guide.

For now we'll create an empty view module web/views/rooms_view.ex:

defmodule Chatex.RoomsView do
  use Chatex.View
end

And then create the template for the show action:

<div class="row">
  <div class="col-sm-4">
    <h2>Rooms</h2>
    <ul id="rooms">
      <li><a href="<%= Chatex.Router.Helpers.lobby_path(:show) %>">Lobby</a></li>
      <li><a href="<%= Chatex.Router.Helpers.room_path(:show, "Help") %>">Help</a></li>
    </ul>
  </div>
  <div class="col-sm-8">
    <h1><%= @room_id %></h1>
    <div id="chatbox"></div>

    <div id="chatline">
      <form class="form" action="<%= Chatex.Router.Helpers.new_message_path(:create, @room_id) %>">
        <input type="hidden" name="room_id" id="room_id" value="<%= @room_id %>">
        <div class="form-group">
          <div class="row">
            <div class="col-sm-4">
              <input type="text" name="user" id="user" placholder="User name" class="form-control"/>
            </div>
            <div class="col-sm-7">
              <input type="text" name="body" id="body" placholder="Message" class="form-control"/>
            </div>
            <div class="col-sm-1">
              <input type="submit" class="btn btn-default" value="Say" />
            </div>
          </div>
        </div>
      </form>
    </div>
  </div>
</div>

If you restart your app at this point, you should be able to change pages by clicking on the Lobby and Help in the sidebar.

Channels

We will need some interactivity in the app. Phoenix Framework comes with built-in WebSockets and PubSup support, which are super fun to work with.

First, we define the channel in the routes and mount it on the /ws path:

defmodule Chatex.Router do
  use Phoenix.Router
  use Phoenix.Router.Socket, mount: "/ws"

  channel "messages", Chatex.MessagesChannel

  # ...
end

Second, let's create the web/channel/messages_channel.ex that will be talking to the WebSockets clients:

defmodule Chatex.MessagesChannel do
  use Phoenix.Channel

  @doc "Called when the user connects to the room."
  def join(socket, _room_id, _message) do
    { :ok, socket }
  end

  @doc "Called when the user disconnects."
  def leave(socket, _message) do
    socket
  end

end

This is a bare bones channel that does literally nothing. It accepts connections to any rooms and does nothing when a user leaves.

On the client side, we need to create a JavaScript file priv/static/js/room.js and include it in the layout file along with /js/phoenix.js after jQuery and Bootstrap.

$(function() {
  // new message form submission handler
  var form = $("form");
  form.on("submit", function(e) {
    e.preventDefault();

    var url  = form.attr('action'),
        body = $("#body"),
        user = $("#user");

    $.post(url, { message: { user: user.val(), body: body.val() } }, function(data) {
      body.val('').focus();
    });
  });

  // connection to the channel
  var socket = new Phoenix.Socket("/ws");
  socket.join("messages", $("#room_id").val(), {}, function(channel) {
    channel.on("new:message", function(data) {
      var div = $("<div class='alert alert-info'></div>").text(data.user + " said: " + data.body);
      $("#chatbox").append(div);
    });
  });
});

Here we listen for form submissions and then sending message[user] and message[body] to the MessagesController#create. We also connect to the room topic via WebSocket and listen for new messages to display.

Now let's create MessagesController that will broadcast our message to the members of the same room.

defmodule Chatex.MessagesController do
  use Phoenix.Controller

  plug :action

  @doc "Broadcasts a message to the members of the #room_id."
  def create(conn, %{ "room_id" => room_id, "message" => %{ "user" => user, "body" => body } }) do
    Phoenix.Channel.broadcast "messages", room_id, "new:message", %{ user: user, body: body }
    conn |> text "ok" 
  end

end

The controller handles the POST request to create a message in a certain room by broadcasting it to all users in the "messages" channel listening to topic with the ID of the room.

Try restarting the app, opening several browsers windows (some in the same room, some in different) and test how messages are delivered.

Testing

In this demo app I completely ignored the testing aspect of development for the sake of time and space. Testing deserves a separate series of posts. It's vast territory.

Exercises to consider

• Try using phoenix_haml instead of Eex
• Think about how could you list the history of 10 last entered rooms in the sidebar instead of static links
• Do you think you can create a separate channel that will send :new_room messages whenever someone enters a new room and then update the sidebar list of rooms dynamically?
• How about treating rooms as hashtags (#lobby), and broadcast messages to listeners of all hashtags found in a message ("#lobby and #help users, hello!")?
• Can you sanitize room id so that it allows only alphanumerics and dashes?

Conclusion

We haven't even scratched the surface of what's possible in Elixir and Phoenix Framework, but I hope you've got an idea of how simple it is to build interactive web apps with them.

The general idea is that it's not a request-response infrastructure, like Rails. Your application gears are always spinning. You can have long running processes with progress reported, lengthy calculations, real-time games, dynamic interfaces and much more. All of this sits on the base of reliable multi-core-ready foundation with supervisors, processes, self-recovery and native tools for distribution, scaling and monitoring.

Have fun! Any comments or questions are welcome.

#!/bin/zsh

typeset -a pids

tidy()  
{
    for pid in $pids
    do
        kill $pid

    done
}

trap tidy INT

(fswatch -e '#' lib test web | xargs -I anything -R 1 -L 1 -t mix test)&
pids=($!)

(fswatch -0 src/coffee | xargs -0 -n 1 -I _ sh -c "cat src/coffee/* | coffee --compile --stdio > priv/static/js/application.js")&
pids+=$!

wait

The original is by Dave Thomas and was posted in an Elixir user group thread.

We define a function that will terminate our background tasks on INT signal, then start two watchers and add their PIDs to the list. Finally, we wait.

Now to the fswatch command syntax. (Mac OS X users can install this tool with brew install fswatch.) The tool is pretty handy. It watches for changes in the given file / directory and sends notifications. In the first example, we just watch for notifications in code directories and run mix test for each noticed change. In the second, we watch for changes in src/coffee and then run the CoffeeScript compiler along with concatenation of the files.

Easy, bare bones and plenty of opportunities. Explore.

Storing HTML in YAML fields in a pretty way has never been as easy.

info: >  
  <h1>Page title</h1>

  <p>Some paragraph text.</p>

NOTE: You'll still need to tell Rails it's safe HTML.

Arrays and hashes

This is useful when you keep the list of options. For example, for the <select> tags.

options:  
  "yes": "Yes"
  "no":  "No"
  maybe: Maybe

NOTE: YAML interprets "yes" as true and "no" as false case-insensitively, that's why we need to put them in quotes

And this is how you'd use them in Rails:

= select_tag :field, options_for_select(I18n.t('options').invert)

NOTE: We need to invert the Hash so that keys and values land where Rails expects them.

If you don't care about key-value mapping, options can be stored as:

options: [ "Yes", "No", "Maybe" ]  

or

options:  
  - "Yes"
  - "No"
  - Maybe

NOTE: Quotes again.

Using this version in Rails is as easy, no inversion though:

= select_tag :field, options_for_select(I18n.t('options'))

I figure some of my friends might be interested in the tools I use currently, so here's the short rundown:

Release management - exrm

Fantastic tool for building releases ready for the deployment. Prepares a versioned nicely packed archive with all dependencies and start / stop / restart / remote_console scripts.

JSON handling - jsex

Sweet little library for encoding, decoding and jumping through all sorts of hoops with JSON.

Websockets - sockjs-erlang

Although there's great variety of web servers in Erlang Kingdom, I chose this one for my own needs for its simplicity. It sits on top of Cowboy and provides a very nice interface, so you focus on the task not on the Websocket handling chores.

UUID - uuid

Tiny library for all sorts of UUID generation.

HTTP client - httpoison

As with web servers, and basically everything else, there are plenty of options, but the one I stuck with is Httpoison. Being based on HTTPotion, it's an excellent piece of software that makes running HTTP requests async or not a breeze.

These are basically the essentials I spent time finding. Hope it saves a bit of time for some of you.

SELECT
  (SELECT COUNT(*)
   FROM table 
   WHERE group_id = X AND completed = 1) as completed,

  (SELECT COUNT(*)
   FROM table
   WHERE group_id = X) as total

FROM table
WHERE group_id = X
GROUP BY group_id

As you might understand the intention is to count all records in the group and those with completed flag set. This solution gives me creeps.

Here's how I would write the same:

SELECT
  COUNT(NULLIF(completed, 0)) as completed,
  COUNT(*) as total
FROM table
WHERE group_id = X

Now pick your DB book and go read what NULLIF function is, and do me a favor. No more crazy subselects, ok?