bah-ea
This application was generated with the Slush-MarkLogic-Node generator, and uses the following components:
- AngularJS
- Gulp
- node.js: very thin layer, hosting the Angular code and proxying MarkLogic REST API requests
- Roxy Deployer: bootstrap MarkLogic databases, application servers, etc; scaffolding for MarkLogic REST API service extensions
Install Required Dependencies
To deploy and run the application you need:
- node.js v0.10+
- npm v2+: Built-in package manager for node (comes with node)
- gulp: Javascript task automation (
npm install -g gulp
) - Bower: A package manager for front-end libraries (
npm install -g bower
) - Git - Roxy depends on this version control system
- Ruby v1.9.3+ - Roxy depends on Ruby in order to run server configuration scripts
Note: the node
command has been renamed to nodejs
. Some dependencies still point to node
, which is out of our control.
You may need to manually alias those commands, or install the node-legacy
package.
Microsoft Windows users should also read the Additional Microsoft Windows Requirements.
Quick Start (for the Impatient)
On Mac or Linux:
npm install
bower install
gulp init-local
./ml local install
./ml local mlcp -options_file import-sample-data.options
On Windows:
npm install
bower install
gulp init-local
ml.bat local install
ml.bat local mlcp -options_file import-sample-data.options
Prepare your Application
Go to the generated application directory:
cd <app-name>
The generator installs NodeJS and JavaScript dependencies automatically, but if shared among colleagues, they likely need to run the following commands manually:
npm install
bower install
The generator also creates a local.json
and a deploy/local.properties
, but
those are usually gitignored. Check if they exist. If they do, check the settings,
most importantly the port settings to make sure they list available ports. If
those files don't exist, then use the following command to create them:
gulp init-local
Note: you can use gulp init-dev
and gulp init-prod
to setup properties for
the dev and prod environments.
Note: the deploy properties allow tweaking the MarkLogic side of the application
in great detail. Look inside deploy/build.properties
or the documentation of
the Roxy deployer to learn more about this.
Note: consider editing 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
.
Deploy your Application
Run the following Roxy commands to deploy the application to the chosen MarkLogic installation. It will create and configure databases, REST servers, users, and roles for you, and deploy the back-end application code.
./ml local bootstrap
./ml local deploy modules
./ml local deploy content
Or on Windows:
ml.bat local bootstrap
ml.bat local deploy modules
ml.bat local deploy content
Launch your Application
To launch the middle-tier, and open a browser tab automatically, you only need to run:
gulp serve-local
Note: this will also watch the ui/
folder for changes, compile them, and reload the
browser fully automatically.
Note: to get more debug logging from Express, run with:
DEBUG=http,mail,express:* gulp serve-local
Note: it is possible to override settings on the command-line:
gulp serve-local --ml-host=<your-host> --ml-http-port=8234 --app-port=9234 --nosync
Note: --nosync
will cause no extra browsersync reload proxy to get launched at 3000,
and no browser tab will be opened automatically. In addition you have --verbose
, and
--ignoreErrors
(for gulp build
). A few more flags are documented at the top of
gulpfile.js
.
Loading Sample Data
Four sample documents are included in the data/ea folder. You will load these using mlcp. To check if Roxy's link to mlcp has been correctly specified, run
./ml local mlcp
Roxy will print the following message if it cannot find MLCP:
ERROR: MLCP not found or mis-configured, please check the mlcp-home setting.
Roxy looks for /usr/local/mlcp/
(or \usr\local\mlcp\
) by default. It can be
convenient to just install MLCP there, or create a symlink from /usr/local/mlcp
to where MLCP is installed. Alternatively, edit your deploy/local.properties
, and
append a mlcp-home=/path/to/your/mlcp/
to the end of it. Repeating above command
should show MLCP usage, not an ERROR.
Once MLCP works correctly, you can run:
./ml local mlcp -options_file import-sample-reference-data.options
Or on Windows:
ml.bat local mlcp -options_file import-sample-reference-data.options
This command will load in the binary information from the data/ea directory and put them in MarkLogic.
Note: the detail controller, the part that handles showing your data, can not only handle JSON, but also XML, Binary, and Text data out of the box.
Loading concepts
The concepts that have been defined are all in the ea/ea.ttl file, which is in Turtle format. New concepts, relationships and instances can all be configured here. To load them, it's easiest to first delete any existing triples, and then reload them via mlcp. The way this is cofigured, all the triples go into the "triples" collection.
To delete them, execute xdmp.collectionDelete("triples")
in Query Console, which can be accessed at http://52.41.245.255:8000. Create a new Javascript query, and use the above function to delete all the documents in the "triples" collection. Note that in Javascript, any function that updates a document needs to be prefaced with declareUpdate() at the top of the module. See https://developer.marklogic.com/learn/sjs/concepts for more information and examples.
To insert new concepts as triples, call:
./ml local mlcp -options_file import-ea-ttl.options
After running that command, all of your new triples will be available.
Updating links from concepts
In the demo, we're using the https://github.com/Templarian/ui.bootstrap.contextMenu library to support the right click functionality when you click on a node in vis.js. I haven't yet figured out the magic sauce for how to get this library to support a dynamic call to get the supporting documents based on which node you select (all of the backend support for this is in place--just can't get the darn library to display it). So I've hardcoded links for now, which should work for a demo as long as you show the correct one.
To update these links, go to ui/app/search/search.controller.js and look at line 184. Changes to this should be reflected immediately. But if that's not working, restart the front-end.
Search landing page
All of the UI code is in the ui directory. This template uses Angular JS (I believe version 1), so if you're familiar with that, you shouldnn't have an issue locating where to change the look and feel. The specifics of the detail page are in the ui/app/detail/detail.html document. The landing page is at ui/app/landing/landing.html. So if you dig around there and use your browser development tools, you should find what you need.
Deployment on Server
At some point you might want to deploy and run this as a service on some (demo) server. For details on that see INSTALL.mdown.
Next Steps
Documentation about the slush generator is provided on the Generator Wiki. It covers amongst others:
-
Project folder structure, which describes the project directory as produces by the generator.
-
Explaining the stack, which gives a brief description of the overall architecture.
-
Core Tools and Components, which allows you to learn more about the various tools and components used by or for the application.
-
Production Deployments, which helps you understand best practices when deploying to a production environment
Last but not least, the landing page of the out of the box application provides many more links.