Deploying MLJS - adamfowleruk/mljs GitHub Wiki

MLJS was originally designed to execute within a Node.JS server environment. Since this first version (0.2 and 0.4) in Dec 2012 and Feb 2013 I have added (in 0.6 in Apr 13) in-browser execution support too.

Installation

The rest of this document describes how MLJS can be deployed. For installation instructions please see the tutorials list on github.io.

Node.JS execution

MLDB was originally developed as an event driven REST server wrapper for Node.JS applications. The idea being I wanted to create a server process to act as a Jabber IM client bot. As a user of IM I befriended this bot and sent it messages to execute searches and receive the results in an IM message.

I then extended this to act as an alerting gateway and provide a HTTP server to a HTML5 + WebSockets app. The Node.JS server provided lightweight business level (find me manual documents) REST functions for the HTML5 app, and used MLJS internally to execute the relevant database functions (search).

To use MLJS within a Node.JS app you can just use npm to install it - npm install mljs. Then just require 'mljs' and create a connection and execute functions. All are non blocking, following Node.JS best practice and conventions.

Sensible defaults are used such that a default install of MarkLogic V6+ should work instantly with your Node.JS application with no configuration options set in the MLJS connection - defaults in MLJS are for a default install.

In browser execution

The core mljs.js file detects whether it is running in a browser (with a window.* object) or NodeJS. If in a browser, it attempts to detect the presence of any communication wrapper libraries. Firstly XmlHttpRequest 2, then jQuery, then Prototype.js, and then falls back to the browser's own XmlHttpRequest object support.

This is handled transparently except if the mljs-.js file isn't included in a script include tag, you will see a fatal error message in the JavaScript console. I may include these in the core mldb.js file in the future.

Automated browser installation

Download the mljsme.sh file from the main folder of the MLJS GitHub repository. Add this to your path (windows) or set up an alias called mljsme (*nix BASH .bash_profile). Now open a terminal and cd to your Roxy or REST custom app folder.

Type mljsme with no parameters to install in the Roxy app located in $PWD/src. Alternatively provide a -d /some/folder parameter to install in the Roxy src folder within the specified parent folder.

Manual browser installation

To install MLJS in the browser, just copy the mljs.js file (and supporting JS files) and CSS files (if using widgets) in to your MarkLogic REST server's modules database. For an easier time, download Roxy and create a 'hybrid' roxy and REST server app. Edit the config.xqy file to set this new app up. Running ml bootstrap local will create a REST server instance. Then running ml deploy local modules will install the Roxy code and your MLDB code to the REST server ready for testing. Easy!

Alternatively you can use a WebDav server in MarkLogic to upload your HTML files and the mljs.js and css files to your MarkLogic REST server, if you don't intend on using Roxy. (boo, boring!)

You now just need to include those in your webpage using script and link rel tags. Then just execute a page setup function (using a JavaScript enclosure like a good little coder!) that creates the MLJS db connection, and instantiates any widgets as required. (Check out the searchpage widget for a search app in two lines of code!)