XComponents

Create an AngularJS app with Cards and Lists using Bootcards

About XComponents

XComponents is a set of AngularJS directives that allow you to quickly create a basic app using cards and lists. It is build on top of the Bootcards UI framework to get a near-native look on iOS and Android.

These applications can be used with most modern PC and mobile browsers. For delivery through mobile app stores for Apple iOS and Android devices, XComponents uses Cordova. XComponents apps can support any back end that can provide a suitable REST API, including MongoDB, Microsoft SQL Server, PostgreSQL and IBM Domino 9.x with Domino Access Services.

XComponents follows some simplifying design principles:

  1. Card-based user interface
    User interfaces are built from a consistent set of high level objects - Cards and Lists These Cards and Lists are rendered by the framework in an optimized way for the device at hand. As a result, developers need to write much less user interface adaptation code.
  2. Integrates with Bootstrap
    With the XComponents, Card and List user interface objects are built with Bootstrap, using the Bootcards. Twitter Bootstrap is the most popular and widely used responsive web design framework.
    Use the responsive framework that you already know and love - Bootstrap.
  3. Support for online and offline modes
    With XComponents, developers can create apps that can work either online or offline. XComponents supports the LowlaDB mobile engine for offline-capable apps, and other local JSON datastores.
    Create your app once using XComponents and Javascript, then run it online or offline with the same front end source code.

Getting started

To get started with XComponents:

  • Install it using Bower: bower install xcomponents
  • Download the latest release from this repository - see link above (or clone it from git clone https://github.com/bootcards/xcomponents).

Check out the demo app or start a new app yourself.

Tutorial: an app and REST server in 6 simple steps

A tutorial on building a simple app that uses the XComponents and talks to a remote REST API powered by Strongloop Loopback.

1: Required software

Install NodeJS and Bower. Then install Strongloop Loopback in Node: npm install -g strongloop.

2: Setup the REST server

Create a new folder for you app. Using a terminal, go into the folder and enter slc loopback. This will setup the basic Loopback application.

We need to create a data model in Loopback: let's create a list of cars. Enter: slc loopback:model and enter Car as the model name. Accept all defaults until you get to "Properties". Create the following properties: 'make', 'type', 'color' and 'details'. Accept the defaults for every property. Leave the property name empty to stop creating properties.

Delete the file server/boot/root.js. That provides a default response for the root (/) route. We don't need that, because we're going to serve our own app: open server/middleware.json and replace the files property with:

"files": {
  "loopback#static": {
    "params": "$!../client"
  }
},

3: Install XComponents using Bower

Create a file called .bowerrc in the new folder and set its contents to:

{
  "directory": "client/bower_components/"
}
This will tell bower to install all dependencies into the client/bower_components folder.

Run bower install xcomponents#master --save to download XComponents and all its dependencies. This will retrieve the latest version.

4: JavaScript config file

Create a file called cars.js in the /client folder. This file contains app configuration settings. Set its contents to:

xcomponents.appVersion = '0.1';
xcomponents.menuOptions = [

    { label : 'Languages', isSecondary : true, icon : 'fa-globe' ,
      menuOptions : [
        { label : 'Dutch', url : 'contacts-accordion.html'},
        { label : 'English', url : 'contacts-accordion.html'}
      ]
    },
    { label : 'Help', isSecondary : true, icon : 'fa-question-circle'},
    
    { label : 'Dashboard', url : 'index.html', icon : 'fa-dashboard' },
    { label : 'Lists', url : 'lists.html', icon : 'fa-list',
      menuOptions : [
        { label : 'Cars', url : 'index.html', icon : 'fa-list-alt' }
      ]
    },
    
  ];

xcomponents.footerOptions = [
    { label : 'Cars', url : '/index.html', icon : 'fa-dashboard'}
  ]; 

xcomponents.models['car'] = {
  name : 'Car',
  fields : [
    { label : 'Make' , field: 'make', required: true},
    { label : 'Model' , field: 'model' },
    { label : 'Color', field : 'color', type : 'select', options : ['Blue', 'Yellow', 'Green'] },
    { field : 'details', type : 'multiline'}
  ]
};

5: Basic page with a list and card

Create a file called index.html in the /client folder. This will be our main app page:

<!doctype html>
<html>

<head>
  <title>XComponents</title>
  <meta name="viewport" content="width=device-width, initial-scale=1">

  <!--set the hidden class here, so everything is immediately hidden-->
  <style type="text/css">
    .hidden {
      display:none;
    }
  </style>
  
  <!-- polyfill for html imports & xcomponents resources -->
  <script type="text/javascript" src="/bower_components/xcomponents/dist/js/xc-base.js"></script>
  <script type="text/javascript" src="/bower_components/webcomponentsjs/HTMLImports.min.js"></script>
  <link rel="import" href="/bower_components/xcomponents/dist/includes/includes.html">
 
  <!-- xcomponents app config -->
  <script src="cars.js"></script> 
  
</head>

<body ng-controller="xcController" class="hidden">

  <xc-header title="View my cars"></xc-header>

  <xc-layout>

    <xc-list 
      list-width="5" 
      model-name="car"
      allow-add="true"
      order-by="make"
      order-reversed="false"
      url="/api/Cars/:id"
      summary-field="make"
      details-field="model"
      image-field="thumbnailUrl"
      image-placeholder-icon="car"
      autoload-first="true"
      type="categorised"
      group-by="make"
      infinite-scroll="true">

      <xc-form 
        url="/api/Cars/:id" 
        model-name="car"
        default-text="Select a car from the list"
        thumbnail-field="thumbnailUrl"
        thumbnail-show-with="name"></xc-form>

    </xc-list>

  </xc-layout>

  <xc-footer></xc-footer>

</body>

</html>

6: Start the server

Start the local server with slc run and view the result at http://localhost:3000.

The app will have a different look and feel on iOS, Android and Desktop and auto-adapts to the device size. Not only by changing the layout (responsive design), but also changing its behaviour: on tablets you get independent scrolling columns. On a smartphone a simple list/detail view with a back button.