Building Connect Applications
Eric Adams - Architect, Carbyn & Applications


So you want to build an app?


You have two options:

  • GUI Toolkit
  • Carbyn Connect

Both options have challenges



Carbyn Connect Apps


  • Self-hosted
  • JS APIs are at your disposal
  • ...and you are in an iframe


(More on that last part later.)

Carbyn Connect


  • HTML5 postMessage API for Communication
  • Contains a whitelist of allowed hosts
  • Establishes connection to the host asynchronously
  • Actually, all communication is async
  • ...because you are in an iframe

Using Carbyn Connect


// Set up a new intents handler
Carbyn.connect("app.registerIntent", [], doSomethingWithIntent);
// Get intents when launching an app
Carbyn.connect("app.getInitIntents", [], doSomethingWithInitIntents);

Parameters:
  • API Method
  • Arguments
  • Callback

Livin' la Vida Async



Enter Carbyn Context


  • Supports commonly used web and Carbyn APIs
  • Built upon jQuery Deferred Objects
  • Available as Bower components
  • Exposed as RequireJS Modules
  • Allows applications to run outside of Carbyn

Available APIs


  • Ajax (HTTP GET and POST)
  • Cache
  • Preferences
  • Tracking
  • Intents*
  • User Info**

* Partially available in web context

** Not available in web context

Ajax


  • Carbyn Proxy within Carbyn (can be cross-origin)
  • XMLHttpRequest in standalone/web (no cross-origin)
  • Prefers JSON responses, and will parse them for you
  • Async - uses Promises

Context.http.get("http://vm01.eadams.dev.opal.synacor.com/some/assets")
    .then(doSomethingWithResponse)
    .fail(doSomethingWithError);

Cache


  • Uses localStorage or ... localStorage
  • They are not the same context
  • Methods are chainable
  • They are both synchronous ... no Promises here

Context.cache
    .set('foo', 'bar')
    .set('bar', 'bat')
    .purge();

Preferences


  • Backed by a Datastore in Carbyn (uses ConfigManager)
  • Namespaced localStorage in standalone/web context
  • Async - uses Promises

Context.preferences.get('foo')
    .then(doSomethingWithValue)
    .fail(doSomethingWithNothing);

Tracking


  • Omniture tracking in Carbyn
  • Image tracking in standalone/web context
  • Async - uses Promises

Context.track('clickButton', {
    // arbitary params to track
    page: 'home',
    user: 'eadams',
    date: '2013-06-16'
});

Intents


  • Carbyn Intents API in Carbyn
  • Hashchange event and pub/sub combination in standalone/web context
  • Limited use outside of Carbyn with client-side apps
  • Async - uses Promises

Context.registerIntent('read')
    .then(doSomethingWithIntent);

User Info


  • Carbyn User Data
  • Noop/reject in standalone/web context
  • Async - uses Promises

Context.user.getUsername()
    .then(doSomethingWithUsername)
    .fail(doSomethingWithError);

Installing Carbyn Context


  • Prefers Bower for installation - http://bower.io/
  • Not opinionated about install location
  • Carbyn and Web Connectors are installed as dependencies
  • Configure your own application for hosting path and RequireJS
  • Repo location
git://git01.dev.synacor.com/repos/synacor-apps-libs-context

Now Back to Carbyn

(for a moment.)


git://git01.dev.synacor.com/repos/carbyn-apps
  • App Wrapper - See (Optimized Wrapper App)
  • Use appconfig.json for your self-hosted endpoint
  • Use info.json for other application metadata

What Happens Next?



App Hosting


Backbone Boilerplate


  • Backbone.JS / Require.JS  solution for client-side applications
  • Uses Grunt 0.4 for task management
  • CSS compilation/minification
  • Template Compilation
  • JS combination/minification
  • Unit tests (QUnit)
  • Easy to extend tasks

Using Iframes




Mobile Scrolling


  • iScroll, Sly are good options
  • Setup and maintenance are required
  • mobile-scroll.js
  • Options for scrollbars, events, etc.
  • Styles for rendering in a 3d layer
  • ...and most important

Local Support



(photo used without permission.)

Links


  • Some sites just don't like to be in an iframe
  • Use location.href
  • Fallback to window.open()

window.location.href = href;

// If the link did not load, open in a new window.
_.delay(function() {
    if (window.location.href !== ev.currentTarget.href) {
        window.open(href);
    }
}, 3000);

Cross-Origin Resource Sharing



// Example using express
app.all('/', function(req, res, next) {
    res.header("Access-Control-Allow-Origin", "*");
    res.header("Access-Control-Allow-Headers", "X-Requested-With");
    next();
});

In Conclusion


  • Carbyn Connect apps live on the web
  • Carbyn Context can give you a standalone dev or production deployment
  • There are tradeoffs to consider when using Carbyn Connect


Questions?
Made with Slides.com