Recipe Customize Detail Pages

Recipe: Customize the Detail Pages

This recipe is based on the sample data included with this slush-marklogic-node DEMO app template. Before beginning, be sure that you have following the Getting Started steps and loaded the sample data.

Starting Point

After you start your application from the command-line at the root of your source code with:

gulp serve-local

navigate to localhost:3000/search and click on the first search result. It will look something like this:

There is a tool to view your data in both JSON and XML formats, and also some similar documents.

Using this recipe, you will be able to make a more user-friendly detail page with HTML markup that pulls values out of the document. Hopefully, you will also learn the concepts that will allow you to extend the ideas to whatever detail page you want to build in your own demos.

Step One: Find and View the detail.html Template

The demo application generated by slush-marklogic-node on your computer has a ui directory. All the AngularJS front-end, client-side code resides in this directory. Learning about Angular will be extremely helpful as you customize your own demo apps backed by MarkLogic, but no worries for now: We will provide enough Angular background to allow you to complete this recipe.

Within the ui directory, we are heading into the app folder. This directory houses all the Angular HTML templates and javascript that drives individual demo app pages. Particular pages or functions are grouped together inside the ui/app directory.

Navigate into ui/app/detail. In this recipe, we will only be changing files here.

Using your preferred text editor or IDE, open ui/app/detail/detail.html.

Note first that this file consists of a single overall <div> tag, with classes like row, detail, and col-sm-8. Those classes are defined by the Bootstrap 3 CSS library, which this demo app uses for styling.

If you are not used to Angular, line 3 may surprise you:

<uib-tabset type="pills">

This is an Angular directive, a central feature of the Angular 1 library. Basically, directives allow you to write markup that looks like HTML, but which transforms the element in some way. This particular directive is defined by the AngularUI Bootstrap library (you can tell because of the uib-* prefix). It does what you might expect: creates the tabs that let you switch between JSON and XML views of your document.

Down lower, you can see the markup for the 'Similar' documents panel.

Let's leave the existing markup alone for now. It can be helpful to have a full view of the existing document as you design your page, so you can see which values are available to you.

Step Two: Change the HTML Template

First, let's prove that we have the right file. Add some markup inside the second-level <div>, which defines the main column of the page, on a new line 3:

<h1>Hello World</h1>

Refresh the detail page and you should see your "Hello World" title at the top of the page. (By default, the gulp serve-local task that you ran watches for changes to your application files and reloads the browser using Browsersync, so it may have been refreshed for you!)

Step Three: Display Human-Readable Data from Your Document

If we look at our data, we see that there is a name field. That would make a much better title for the page.

But how do we get at the data?

It is being stored for us in the state of the Angular application. From the detail.html template, we can refer to it with the Javascript expression ctrl.doc.

Let's unpack that. For consistency, in all the generated templates, ctrl (short-hand for 'controller') refers to the stored state, or information, available to the template. Trust me for now. In the next step, we'll take a closer look at the controller that controls this state.

You can treat ctrl as a Javascript object with properties. In the detail.html context, one such property is doc, which has all the values of the current document.

So let's pull the person's name out of that data. Change your 'Hello World' title to the following:

<h1>{{ctrl.doc.name}}</h1>

Note the double curly-braces ({{}}). This is a signal to Angular, which processes all these templates, to evaluate the javascript inside. (This works for any arbitrary javascript expression, for example 1 + 1, which prints as '2'.)

Now you have the trick, and you can pull out additional elements. For example, try:

<p>You are welcome to discover more about {{ctrl.doc.name}}! A person with eyes of {{ctrl.doc.eyeColor}}, <span ng-if="ctrl.doc.gender === 'male'">his</span><span ng-if="ctrl.doc.gender === 'female'">her</span> favorite fruit is {{ctrl.doc.favoriteFruit}}. And <span ng-if="ctrl.doc.gender === 'male'">he</span><span ng-if="ctrl.doc.gender === 'female'">she</span> has a balance of {{ctrl.doc.balance}}.</p>

Note the use of ng-if. There is a long list of similar Angular directives that can assist you in customizing your templates. (Don't try to learn them all at once!)

Step Four: Introduce Some Business Logic

TODO: this is just a stub

(To introduce a bit of jargon, ctrl refers to an Angular scope.) ctrl is short-hand for 'controller', which is a handy reminder that this stored data is set in the relevant Angular controller.

The relevant controller for our detail.html is conveniently saved in the same ui/app/detail directory. Use that handy text editor again to open up ui/app/detail/detail.controller.js.