Tutorial: How to Build an App
Welcome!
If you are here, you probably already know that MarkLogic is a powerful, multi-model, NoSQL database with ACID transactions and top-grade security.
You can use it to build all kinds of applications: [TODO:examples] - and more that we have not yet imagined. You might be the first to create a new kind of application.
All that power and flexibility is amazing, but it can be daunting when you sit down to write your first MarkLogic-backed app. By working through this tutorial, you will quickly and without much effort build your first web app backed by MarkLogic, using this DEMO app generator, which is what we at MarkLogic use as a starting point for most of the demos we build. [TODO: examples of public Slush-generated demos]
Along the way, we'll try to point out key MarkLogic features and some general best practices.
Keep in mind that the particular tech stack used here (AngularJS, NodeJS, etc) is 100% arbitrary. You can use your preferred tools to build a Web application backed by MarkLogic. This app communicates with MarkLogic using the MarkLogic REST API. As long as you can make http requests, you can build an app against MarkLogic. (We even have another version of this demo app generator that sets up a Java middle tier, instead of NodeJS.)
Let's get started.
To follow along with this tutorial, you need to make certain choices when you generate your app, so read this whole section first.
TODO: something about working on the command line
Work through the steps detailed in the Getting Started section of the README, with the following additions:
-
In this tutorial, we will assume that when you "Run the generator", you ran the following it from your home directory and gave it the name
slush-marklogic-node-tutorial:cd ~ slush marklogic-node slush-marklogic-node-tutorial
So, this tutorial will assume your generated source code lives in
~/slush-marklogic-node. If you generate the application in a different directory or give it a different name, simply modify the provided steps accordingly. -
When you "Run the generator", choose the default options and make your admin password 'admin'. Your console should look like this:
(If you need or really want to, you can of course enter something different, but just make the necessary changes to the steps ahead.)
When you navigate to localhost:3000, you will see the landing page for your newly generated DEMO application:
TODO: call out features of landing page - Angular application
Click on 'Search' in the top navigation bar. Since you haven't logged in and the search page is protected by the application's loginService, the Angular router will redirect you to a login page. For now, let's use the admin:admin user.
(NOTE: There is an application-specific user that has been created for you too. You can see and potentially change that user's password in the deploy/build.properties files of your generated source code. Role-based security is a major feature of MarkLogic. Later, you can experiment with using it to control which sets of documents different users have access to, for example. [TODO: maybe we should start using app-specific user?])
Once you login, you will see a Search page, with a search bar - but no search results yet since we don't have any data!
STOP! Before we go any further, you need to check this new project into version control. Otherwise, you won't be able to tell your changes apart from the work done by the generator - and you won't be able to back out mistakes. In this tutorial, we will use git. So, enter the following into the command line:
cd ~/slush-marklogic-node-tutorial # Or wherever your source code lives
git init
git add .
git commit -am "Initial slush-marklogic-node generated demo app"You can then optionally create a remote repository and push this code there as a backup, or to share with colleagues.
TODO: describe the work that has been done and introduce some related general concepts
TODO: describe the generated project folder structure
We've got a database all set up, but no data!
Run the command in the Sample Data section of the README to load 3000 JSON documents about 3000 people.
TODO: describe how that works, mlcp, etc - mostly linking to other background
Once you've done that, refresh localhost:3000/search. You should now see search results and facets on eye color and data collection:
TODO: call out facet; call out search; call out detail page; similar docs?; other stuff that comes out of the box
TODO: something about text editors / IDEs - referencing section on landing page, which we might actually migrate to the Wiki
TODO: walk through some other facet based on the 'Add a facet' recipe.
TODO: create recipe
TODO: create recipe