Building Faster with the JavaScript SDK

If you haven't deployed your first API on BrightWork, check out our Getting Started Guide. If you have, it's time to build a front-end that can consume your new endpoints. While it is very possible to follow the docs and create your own HTTP integration, we're going to look at how to use the BrightWork JavaScript SDK to get you building your application even faster. In this tutorial, we'll cover:

JavaScript Logo

Installing the BrightWork JavaScript SDK

To install the JavaScript SDK you can use Bower. If you've never worked with bower, you can check it out here. Once Bower is installed and setup, then run the command:

bower install --save bw-js-sdk

This will add the package to your bower components folder. You'll then need to include a script tag in the head of your index.html like this:

<script src="bower_components/bw-js-sdk/dist/index.js"></script>

You are now ready to initialize the SDK with your particular models. We'll be looking at the demo included with the SDK for this example.

Booting up the Demo

To boot up the demo photo app that is included with the SDK, navigate to the 'demo' folder in terminal. Once there, you can run:

npm install

followed by

bower install

You can then check out the demo by running:

grunt server

This should automatically open up the demo photo app in your web browser.

Photo App Demo Initial

Right now, the photo app is not connected to anything so if you look in your console you'll end up with an error like this:

SDK Error

To get the app working we'll need to first have a deployed Brightwork API. If you haven't done this yet, check out our Getting Started Guide. Once you have a deployed app, it's time to initialize the SDK.

Initializing the SDK

To initialize the SDK, you will need the API key and name of your deployed app. To get these, you can always navigate to your backend apps project folder and run:

bw list

Once you have the API key and name, you will need to include a call to initialize the BrightWork SDK like so:

BrightWork.initialize('YOUR_API_KEY', 'YOUR_APP_NAME').then(function(){  
  console.log('...SDK initialized');      
    ...
});

If you want to test out the demo, navigate to demo/public/js/main.js and add the necessary API Key and app name to the call to 'BrightWork.initialize'. (You will need to have created a photo app like the one in our Getting Started Guide).

SDK Initialized

Once the SDK is initialized, you will then be able to interact with your API using the built in methods included in the SDK. You can now post and delete albums to your API.

Photo App Demo Posts

Interacting with API Endpoints

Now that the SDK is initialized, your app has access to all your API models through bw.models.MODEL_NAME, so any interaction with albums can be done by bw.models.album. In the demo, after initialization, you can find a clear example that calls the 'find' method on the album model and returns all the albums currently stored on your back-end. The demo then uses jQuery to append the album.

bw.models.album.find().then(function(albums) {  
    $("#albumContent").append(renderTable({albums: albums}));
});

The demo also contains a good example of creating a new instance of your model to the back-end using 'create'. On submission of the form, a 'POST' call to the album model is made like so:

bw.models.album.create({name: $('#albumName').val()}).then(function(newAlbum) {  
    $('#albumName').val('');
  $("#albumContent").append(renderRow(newAlbum));
    });
});

When the call returns successfully, the album info and functionality is appended to the DOM.
You may have noticed one final example in the demo. There is a 'remove' function where we find a call to 'delete' and album like this:

bw.models.album.delete(id).then(function(deleted) {  
    $(".row-" + id).remove();
});

Once the HTTP 'DELETE' call returns successfully, the album element is removed from the DOM. Along with 'find', 'create', and 'delete', you can also use 'get' and 'save' to interact with your models. Check out the JavaScript SDK Docs for more info. This is only the beginning of what the SDK offers, you can also run complex queries.

Creating Queries

If we wanted to add the ability to query our albums, for example, to get all the albums that start with a certain letter, we could create another search input that takes a letter.

Photo App Demo By Letter

On submit we would build a query like this:

var query = BrightWork.query().startsWith('name', $('#letter').val());

bw.models.album.find(query).then(function(albums) {  
  $("#letter").val('');
  $("#albumByLetterContent").append(renderTable({albums: albums}));
});

The query is built with a call to the '.query' method. After calling the query method, we can chain any number of criteria like '.limit', '.descending', etc. For our example, we use '.startsWith' which takes a field and a string value as parameters. We pass in the submitted letter which returns all the albums that start with the given string. Those albums are then appended to our new Albums by Letter section.

To see all the query options, check out the JavaScript SDK Docs. We now have a full stack application built on BrightWork and hooked up with the BrightWork JavaScript SDK!