Free-Range App Utils (Frau)

[Deprecated] - Use frau-local-appresolver, frau-appconfig-builder instead.

Usage

Install free-range-app-utils as a dev dependency:

npm install --save-dev free-range-app-utils

Require the package:

var frau = require('free-range-app-utils');

Utilities

Local app resolver

A utility to host and resolve your app on your local instance.

var appresolver = frau.localAppResolver( appClass, options );
 
// Host an app resolver
appresolver.host();
 
// Get where the app content is hosted.  Needed when creating the appconfig.
var target = appresolver.getUrl();

Parameters:

• appClass (required) - The app class to resolve. If not specified, the appClass field from the package.json is used.
• options (optional) - An object containing:
  • dist - The directory containing the app files to serve. By default, the dist directory is used.
  • port - The port to listen on. By default, port 3000 is used, which is the port that the LMS expects it on.
  • hostname - The hostname (or IP) to listen on. By default, localhost is used. You should not need to change this.
  • configFile - The name of the app config file. By default, appconfig.json is used. You should not need to change this.

Build appconfig (UMD Apps)

A utility to create the appconfig file for free-range UMD apps.

// Returns a JSON object with the appconfig
var appConfig = frau.appConfigBuilder.umd.build( target, options );

gulp.task('appconfig', function(){
    // Returns a vinyl stream with the appconfig.  Convenience method for use with gulp.
    return frau.appConfigBuilder.umd.buildStream( target, options )
           .pipe(gulp.dest('dist'));
});

Parameters:

The build and buildStream functions take the same parameters:

• target (required) - The target url that the app will be served from.
• options (optional) - An object that contains the following:
  • id - The app's id. Defaults to the appId from package.json.
  • version - The app's version. Defaults to the version value from package.json.
  • description - The app's description. Defaults to description from package.json.

You should generally not need to provide options because the values can be obtained from the app's package.json file.

Note: If the app does not have a valid id, version, and description, you'll receive an error when you try and build the appconfig file.

Build appconfig (IFRAME Apps)

A utility to create the appconfig file for free-range apps that will be loaded into an iFrame.

// Returns a JSON object with the appconfig
var appConfig = frau.appConfigBuilder.iframe.build( target, options );

gulp.task('appconfig', function(){
    // Returns a vinyl stream with the appconfig.  Convenience method for use with gulp.
    return frau.appConfigBuilder.iframe.buildStream( target, options )
           .pipe( gulp.dest( 'dist' ) );
});

Parameters:

The build and buildStream functions take the same parameters:

• target (required) - The target url that the app will be served from.
• options (optional) - An object that contains the following:
  • id - The app's id. Defaults to the appId from package.json.
  • version - The app's version. Defaults to the version value from package.json.
  • description - The app's description. Defaults to description from package.json.

You should generally not need to provide options because the values can be obtained from the app's package.json file.

Note: If the app does not have a valid id, version, and description, you'll receive an error when you try and build the appconfig file.

Additional details for integrating iFramed free-range-apps can be found within the ifrau repository.

Build appconfig (HTML Apps)

A utility to create the appconfig file for free-range HTML apps.

// Returns a JSON object with the appconfig
var appConfig = frau.appConfigBuilder.html.build( options );

gulp.task('appconfig', function(){
    // Returns a vinyl stream with the appconfig.  Convenience method for use with gulp.
    return frau.appConfigBuilder.html.buildStream( options )
           .pipe( gulp.dest( 'dist' ) );
});

Parameters:

The build and buildStream functions take the same parameters:

• options (optional) - An object that contains the following:
  • id - The app's ID. Defaults to the name from package.json.
  • version - The app's version. Defaults to the version value from package.json.
  • description - The app's description. Defaults to the description from package.json.
  • defaultResource - The default resource to point to when the app is loaded. Defaults to appDefaultResource resource object in package.json.
  • additionalResources - An array of additional resource objects that the app makes accessible. Defaults to appAccessibleResources in package.json.

Resource objects contain the following properties:

• uri - The URI, relative to the application's root, at which the resource can be found.
• type - The type of resource (e.g. html).
• pageTemplate - The page template to use when the app is loaded.

You should generally not need to provide options because the values can be obtained from the app's package.json file..

Note: If the app does not have a valid id, version, and description, you'll receive an error when you try and build the appconfig file.

Tests

Run the tests locally:

• Install mocha: npm i -g mocha
• Run mocha: mocha

Contributing

Code Style

This repository is configured with EditorConfig rules and contributions should make use of them.