Consume SKY UX

SKY UX brings a consistent, cohesive experience to Blackbaud products, and you can use it to bring that same consistent experience to your own customizations and applications.

SKY UX supports Microsoft Edge and Internet Explorer 11 on Windows; the latest version of Firefox and Chrome on both Windows and Mac; the latest verion of Safari on Mac; the latest version of Mobile Safari on IOS; and the latest version of Chrome on Android.

CDN

You have several options to consume SKY UX. The first and easiest is to point your site to our CDN, which you can read about in our Getting started guide.

Package managers

If you wish to host SKY UX yourself, you can install it with Bower or NPM using the following commands:

bower install blackbaud-skyux

npm install blackbaud-skyux

Before you install with Bower or NPM, you must install Git.

If you install with Bower or NPM, you must include the same files indicated in the Getting started guide, but you point the URL to your own web server instead of the CDN. You may also use a hybrid approach where you load SKY UX with the CDN and fall back to a version hosted by your web server if the CDN is unavailable.

CDN with Fallback JS

Hosting static resources on a CDN offers many advantages. However, CDNs can become unavailable, so you need a fallback strategy to avoid a single point of failure for your application.

One option is to use the Fallback JS library to load SKY UX from a local version if the CDN fails. This fallback strategy allows you to take advantage of the CDN in the vast majority of cases but still keeps your app running properly if the CD fails.

  1. Import the Fallback JS library and incorporate it into your web application.

    You can load it via a CDN, but that defeats the purpose of the fallback strategy. Instead, download the library and host it with your web application.

    bower install fallback --save-dev
  2. Include Fallback JS on your page.

    For simplicity, this example adds Fallback JS directly to your page from its installed location, but you likely want to combine it and minify it into the files you already reference on your page that don't depend on the SKY UX library.

    <script src="/bower_components/fallback/fallback.min.js"></script>
  3. Import the SKY UX library and add SKY UX to your page.

    Download and host SKY UX on the same server that hosts Fallback JS and your web application. This is where Fallback JS loads SKY UX from if the CDN is unavailable.

    bower install blackbaud-skyux --save-dev
  4. Instead of adding script and link elements to load the SKY UX files, load them with the Fallback JS API:

    (function () {
        'use strict';
    
        fallback.load({
            // CSS
            sky_css: [
                'https://sky.blackbaudcdn.net/skyux/1.4.3/css/sky-bundle.css',
                '/bower_components/blackbaud-skyux/dist/css/sky-bundle.css'
            ],
            page_css: '/css/app.css',
    
            // JS
            angular: [
                'https://sky.blackbaudcdn.net/skyux/1.4.3/js/sky-bundle.min.js',
                '/bower_components/blackbaud-skyux/dist/js/sky-bundle.min.js'
            ],
            MYAPP_READY: '/js/app.min.js'
        }, {
            shim: {
                'MYAPP_READY': ['angular'],
                'page_css': ['sky_css']
            },
            callback: function (success, failed) {
                // See what succeeded and what failed.
            }
        });
    }());

    This is a decent amount of code, so let's look at what each piece of this code means. fallback.load() is called with two parameters. The first parameter is a dictionary of CSS and JS files to load on the page. The second parameter is some additional options.

    Load CSS

    The two CSS resources that the code loads are the SKY UX CSS file (aliased as sky_css) and your web application's CSS file (aliased as app_css). As you can see, the array of URLs that is specified for the sky_css property contains the CDN URL and the locally hosted URL. Fallback JS attempts to load these in the order they are specified. If the first fails, it loads the second. You can specify as many fallback URLs as you want, but this example just uses the CDN and the local URL.

    Load JavaScript

    We also load two JavaScript files: SKY UX's JS file and your web application's CSS file. Unlike the CSS resources that we alias with arbitrary names, each JavaScript alias must be an object that the JavaScript file adds to the global window object. Since the SKY UX bundle also loads AngularJS and AngularJS adds an angular object to window, we use angular as the alias. For the application's JS, we added the line window.MYAPP_READY = true; to the bottom of the application's JS code so that we can reference it here.

    Specify load order

    The second parameter passed to fallback.load() consists of a shim property that you can use to define the load order of the JavaScript and CSS files. Each property on the shim object is named after the corresponding resource's alias and is set to an array of other resources that must load before that resource loads. In this example, we state that our own app's JS and CSS depend on SKY UX's JS and CSS, ensuring that SKY UX loads before our app's resources load.

    CDN failures

    The option parameter's callback property can specify a function to call after all resources load. This callback accepts success and failed parameters, the latter of which can be used to determine which requests fail. Even though the fallback functionality should keep your app working properly when the CDN fails to load, you might want to know about failures so that you can include them in any instrumentation that you keep for your application.