Themer Guide

Flex allows you to theme your own app interfaces with your own html markup. You can create your own music controls, song displays, app content views, cart features, and more. It is entirely possible for you to create totally new and custom interfaces for your flex app without any advanced javascript programming knowledge.

Fundamental Theming Principle

Flex operates at the core using the Model View ViewModel (MVVM) architecture. This means that there is a convenient separation between the html markup that you create, and the back-end programming that powers the framework. For a themer, this means that it's easy to write just html & css to achieve any desired look or layout, and then let flex populate your created layout with real data and interactive features.

How It Works

Flex utilizes Knockout.js as the core library which actually binds internal application data and features to the created html structures. Therefore, all of the binding options, features, and syntax that are described in this documentation are also well documented on the knockoutjs.com website.

Here is a quick example of how it works in practice:

<div class="your-cart-totals">
  Total Items: <span data-bind="text: cart().items.length">0</span>
  Total Price: <span data-bind="text: cart().total">$0.00</span>
</div>
In the example above, you have some basic html code which can be themed and placed anywhere on your webpage. You'll notice that we added a special html attribute called "data-bind" to some of the <span> tags. This attribute is what tells flex to step in and do some processing. The value of the "data-bind" attribute in this example tells flex to update the text contents of those <span> elements with the appropriate cart data. Even more, whenever the cart is updated, the new cart values will also be updated in those <span> elements automatically.

Here is another example:

<div class="cart-buttons">
  <a class="view-cart" href="#" data-bind="click: cart.show">View Cart</a>
  <a class="checkout-now" href="#" data-bind="click: cart.checkout">Checkout Now</a>
</div>
In the example above, we use the "data-bind" attribute to tell flex to show the shopping cart when the "View Cart" link is clicked, and to begin the checkout process when the "Checkout Now" link is clicked. There are many more data points and interfaces that you can tie into with the "data-bind" attribute on your own. Those interfaces are listed at the bottom of this page.

Security Implications

Although the "data-bind" attribute tells flex (or fundamentally, knockout.js) how to bind data with your html, flex waits for you to specifically tell it to do so before actually pulling the trigger. This is to protect sites that are using the flex framework and that also accept and display user submitted html from being exploited.

Note: If you accept and display user submitted html, you need to make sure you filter out the "data-bind" attribute from submitted html to be sure that a malicious user cannot tap into it.

So in order for the "data-bind" attribute to actually do anything for you, you need to specifically tell flex to process it. You can do this with a jQuery selector; and target every element individually, or many elements at once.

So building on the examples shown above, we are going to add a small bit of javascript to the end of our example that shows how to turn flex "on" for the html elements with the "data-bind" attribute.

<div class="your-cart-totals bbflex-bind">
  Total Items: <span data-bind="text: cart().items.length">0</span>
  Total Price: <span data-bind="text: cart().total">$0.00</span>
</div>

<div class="cart-buttons bbflex-bind">
  <a class="view-cart" href="#" data-bind="click: cart.show()">View Cart</a>
  <a class="checkout-now" href="#" data-bind="click: cart.checkout()">Checkout Now</a>
</div>

<!-- This javascript is needed to actually make the bindings happen! -->
<script type="text/javascript">
  flexloader.execute(function($) {
    $(".bbflex-bind").bbflex('applyBindings');
  });
</script>

You'll notice that we added a new class "bbflex-bind" to some of our container elements. We just used this class to make it easy for us to select them at the same time with a single jQuery selector. The .bbflex('applyBindings') jQuery method is what actually causes flex to process all of the "data-bind" attributes within those selected elements.

It's also important to note that the jQuery command is wrapped in a function and executed with the flexloader.execute() method. We do this to ensure that the $ variable is referenced to the correct instance of jQuery, and that the flex app is loaded before the commands are issued.

Getting Started

In order to start building your own compelling interfaces for features in your flex app, you'll want to browse through the different interfaces and properties that are available to you via flex bindings:

flexloader.execute(function($) { $(".selections").bbflex('applyBindings'); });

All of the following application interfaces are part of the model which is bound via the jquery bbflex binding method demonstrated above. Click one to learn more: