# Generator of Node.js Application Backed by MarkLogic

This is a [Slush](http://slushjs.github.io/) generator that produces a skeleton
[MarkLogic](http://www.marklogic.com/) application with the following
components:

- [AngularJS](https://angularjs.org/)
- [Gulp](http://gulpjs.com/)
- [node.js](http://nodejs.org/): very thin layer, hosting the Angular code and proxying MarkLogic REST API requests
- [Roxy Deployer](https://github.com/marklogic/roxy): bootstrap MarkLogic databases, application servers, etc; scaffolding for MarkLogic REST API service extensions

# Getting Started

Microsoft Windows users should read the [additional requirements documentation](WINDOWS.mdown)
## Install Required Dependencies

- [node.js](http://nodejs.org/download/)
- [npm](https://www.npmjs.com/): Built-in package manager for node (comes with
  node, but check to be sure you have latest version: `npm install -g npm`)
- [gulp](http://gulpjs.com/): Javascript task automation (`npm install -g
  gulp`)
- [Slush](http://slushjs.github.io/): Application generation tool (`npm install
  -g slush`) - only needed if you are generating the initial code
- [Bower](http://bower.io/): A package manager for front-end libraries (`npm
  install -g bower`)
- [Git](https://git-scm.com/) - Roxy depends on this version control system
- [Ruby](https://www.ruby-lang.org/en/documentation/installation/) - Roxy
  depends on Ruby in order to run server configuration scripts

## Install the generator

    npm install -g slush-marklogic-node

If you prefer to use the latest code under development:

    npm install -g git://github.com/marklogic/slush-marklogic-node.git

## Run the generator

Go to the directory where your new project will be created (the parent). Then:

    slush marklogic-node <app-name>

This will ask you several questions, with some intelligent defaults.

## Configure your application

Go to the generated application directory:

    cd {app-name}

Edit `deploy/build.properties` to set the -port properties to available ports
(defaults: 8040, 8041) and change other properties. The file itself documents
many of those properties. Others are described in the [documentation for the
Roxy deployer](https://github.com/marklogic/roxy). Then run the following Roxy
commands to configure your local MarkLogic database (typically, depending on
your configuration, it will create a database, associated forest(s), a REST
server, an app-user, and a role for that user).

    ./ml local bootstrap
    ./ml local deploy modules

On Windows, that would be:

    ml.bat local bootstrap
    ml.bat local deploy modules

Install additional dependencies using the bower package manager:

    bower install

Edit the `_loginMode` variable in `ui/app/login/login.service.js` to change the login mode of the application. The default is set to `full`. The other options are `top-right` or `modal`.

## Run your application

    gulp serve-local # this will watch the .less file for changes, compile them to .css, and run the node server

You can set some settings to match your setup in the Roxy properties files. For example:

    gulp serve-local --ml-host=<your-host> --ml-http-port=8234 --app-port=9234 --nosync

# Next Steps

Load some sample data, as described in the next section of this README.

The slush generation creates an entire project directory, described in
[Project folder structure](https://github.com/marklogic/slush-marklogic-node/wiki/Project-folder-structure).

[Explaining the
stack](https://github.com/marklogic/slush-marklogic-node/wiki/Explaining-the-stack)
gives a more complete description of the overall architecture.

Learn more about specific components of the generated application on the
[Components](https://github.com/marklogic/slush-marklogic-node/wiki/Components) page.

Learn about specific ways of customizing your app on the [Customization
Recipes](https://github.com/marklogic/slush-marklogic-node/wiki/Customization-recipes)
page.

# Data

## Sample Data

The application comes with 3000 JSON documents generated by json-generator.com.
You can load them with
(MLCP)[https://docs.marklogic.com/guide/ingestion/content-pump] like this:

**NOTE:** @sample-app-role in import-sample-data.options will change to your app's role
(Alternatively, you can discover that with `./ml local info`)

    ./ml local mlcp -options_file import-sample-data.options

Or on Windows:

    ml.bat local mlcp -options_file import-sample-data.options

## General Data Information

The application assumes that you're storing JSON data. This shows up in the
default format request for the MLRest service's `searchContext`, the
`detailController`'s (`detail-ctrl.js`) request to get a document, and in the
out-of-the-box detail view.

# Options

## Roxy

The generator defaults to using a 'rest'-type Roxy app and the 'master' branch
of Roxy. If you know what you're doing, and you want to do something different,
you can specify those options with this syntax:

    slush marklogic-node <appName> appType=mvc branch=dev

