Add third-party libraries to an app

This tutorial explains how third-party code libraries work with BladeRunner, which ones come with BladeRunner as standard, and how to add additional libraries of your own.

BladeRunner Third-party Libraries

BladeRunner comes out-of-the-box, with a set of third-party libraries, including link:https://jquery.com/, link:https://knockoutjs.com/, link:https://momentjs.com/, etc., which the Caplin system uses to provide different aspects of its functionality. They may be used by all BladeRunner applications, and are located in the following directory: bladerunner/sdk/libs/javascript/thirdparty-libraries/<LIBRARY NAME>

For example, the jQuery library can be found in:

bladerunner/sdk/libs/javascript/thirdparty-libraries/jquery
This is not the place to add a new third-party library for your own app! The contents of the sdk directory will get replaced when the application is upgraded.

Application Third-party Libraries

Applications can include any third-party libraries they need (in addition to the ones BladeRunner uses in any case). Each application should include each additional third-party library within its own app folder:

apps/<APP NAME>/thirdparty-libraries/<LIBRARY NAME>/

Worked Example: Add 'amcharts' Library

Download the Third-party Library

Start by downloading the third-party library you want to use. For this example, we’ll be using amcharts, which you can download from https://www.amcharts.com/download/.

Set up an Application Structure

You’ll need to have an application set up in order to do this. For the purposes of the example, we will be using an app called my-app, which contains a single bladeset called my-bladeset. The amcharts library is for generating charts, so we’re calling our blade simplechart. The app will also have the usual default-aspect.

br 3pl 1

If you want to work through this example, set up a similar app structure and follow the steps given.

Paste the Library into the thirdparty-libraries Directory

In the apps/my-app/thirdparty-libraries/ directory, create a new folder called amcharts, and paste the amcharts library and resources into it, like so:

br 3pl 2

Modify the JavaScript in your Blade, to use the Third-party Library

Use the caplin.thirdparty() class to include the amcharts library, using the name of the folder that you created in the previous step ("amcharts"). This lets BladeRunner know that you are using third-party code, and where it is, so that your simplechart blade can use it.

Next, write a simple column chart, which writes to an element called 'chartdiv'. You can use the sample code below for this.

Save your JavaScript into the correct folder for JavaScript resources in your blade, as ExampleClass.js. This will be:

apps/my-app/my-bladeset/blades/simplechart/src/app/charts/simpechart/ExampleClass.js

caplin.thirdparty("amcharts");

app.charts.simplechart.ExampleClass = function()
{
    var chart;

    var chartData = [{
        country: "USA",
        visits: 4025
    }, {
        country: "China",
        visits: 1882
    }, {
        country: "Japan",
        visits: 1809
    }];

    AmCharts.ready(function () {
        // SERIAL CHART
        chart = new AmCharts.AmSerialChart();
        chart.dataProvider = chartData;
        chart.categoryField = "country";
        chart.startDuration = 1;

        // AXES
        // category
        var categoryAxis = chart.categoryAxis;
        categoryAxis.labelRotation = 90;
        categoryAxis.gridPosition = "start";

        // value
        // in case you don't want to change default settings of value axis,
        // you don't need to create it, as one value axis is created automatically.

        // GRAPH
        var graph = new AmCharts.AmGraph();
        graph.valueField = "visits";
        graph.balloonText = "[[category]]: [[value]]";
        graph.type = "column";
        graph.lineAlpha = 0;
        graph.fillAlphas = 0.8;
        chart.addGraph(graph);

        chart.write("chartdiv");
    });
}

Make Your default-aspect Construct this Blade

Users will access the application via the default-aspect, so you need to make the aspect construct the ExampleClass() function that you defined in ExampleClass.js. Insert the following code into: apps/my-app/default-aspect/src/app/App.js

app.App = function()
{
    app.charts.simplechart.ExampleClass();
};

Update the index.html File

Add the following line to the body of the index.html file in the default-aspect folder, to create the element to which the chart will be written.

<div id="chartdiv" style="width: 100%; height: 400px;"></div>

Load the Application!

Once complete, your app should use the functionality provided by amcharts, to produce a bar-chart, like this one:

br 3pl amchart

Managing Third-party Library Dependencies

If you find yourself needing to manage load-order dependencies for a third-party library’s JS files, or to define dependencies between two different third-party libraries, you can do so using a library.manifest file. See Thirdparty Library manifest file rules for more information.

You can view all the dependencies used by your application, by executing the following instruction in a command-line window: bladerunner app-dependencies <app-name>