Loading TOC...
Application Builder Developer's Guide (PDF)

Application Builder Developer's Guide — Chapter 1

Application Builder Quick Start

This chapter gets you started using Application Builder, a browser-based application that quickly creates fully functional search and analytics applications. These generated applications can, if needed, be customized and extended. This chapter includes the following sections:

Overview of Application Builder

Using Application Builder requires no coding on your part. Its user interface is easy to use, while its search applications can have many high-end search features such as a search box with Google-style search grammar, search suggestions, faceted navigation, and results visualization widgets. It scales for huge database sizes while maintaining its speed.

The generated application uses the Search API and can be used as is or customized with your own code.You can define many aspects of an application, such as:

  • Facets
  • Details appearing on the search result page
  • Content display control via item rendering
  • Visualization widgets for search results

Typically, building an application is an iterative process. To begin, you must have a representative content set loaded in a database with any needed indexes already set up. If your content is not complete or not completely indexed, you can still generate an application and modify it as you modify your content.

In this chapter, you use Application Builder to generate a sample application based on data about the Oscar awards. For details, see Building the Oscars Sample Application and Using the Oscars Sample Application.

Setting Up and Starting Application Services

Application Builder is bundled with MarkLogic Server Application Services. On a fresh installation of MarkLogic 6, Application Builder is preconfigured and ready to use. For an upgrade installation, your existing application data remains intact although some renaming of your Application database and App Server may occur during the installation process. This section describes the following scenarios:

Clean Installation

When you install MarkLogic Server for the first time, the installation process does the following:

  • Creates an HTTP App Server named App-Services on port 8000 for Application Services
  • Creates a database named App-Services to store the Application Builder application documents

For a complete description of installing MarkLogic Server, see Installing MarkLogic Server in the Installation Guide.

Upgrade Installation

Doing an upgrade installation of MarkLogic Server varies slightly depending on your previous installation. For details on the Application Services portion of a 4.1 or 4.2 to MarkLogic 6, see Prerequisites for Application Services Portion of the Upgrade in Installation Guide.

  • When upgrading from 4.1 to 5, if the previous installation had Application Builder configured, the upgrade installation does the following:
    • Renames the App-Builder App Server to App-Services
    • Creates a forest and database, named App-Services while keeping your application data intact.

      When using Application Builder for the first time after an upgrade, a prompt asks you to confirm moving your existing projects and data from your old App-Builder database into the new App-Services database. Click OK to do so. You can then delete the old App-Builder database and forest.

  • When upgrading from 4.2 to 5, your data and applications are immediately available without additional actions on your part. The App-Services App Server runs on port 8000.

Starting Application Services

To start Application Services, open a browser and go to your server's port 8000. For example, if your browser runs on the same machine as MarkLogic Server, open the following URL:


When MarkLogic Server prompts you for a username and password, enter them for a user with either the admin or app-builder role.

For details on these roles, see Predefined Roles for Application Builder.

Building the Oscars Sample Application

Application Builder includes a template to build a sample application based on Oscar awards data from Wikipedia. To build this application, go through the Application Builder wizard as follows:

  1. Start Application Builder by going to the following URL (If MarkLogic Server is installed on a different host or your App Server uses a different port, substitute those values):
  2. On the Application Builder Applications screen, click New Example Application.

  3. The New Example Application screen appears.
    1. Enter a name for the application, in this case Oscars.
    2. Select New Database and enter a database name, in this case Oscars.
    3. Click Create Application.

  4. Application Builder creates an Oscars App Server, forest, and database and then displays the Search tab page.

  1. On the Search page, you can accept the default search constraints and facets or change the settings.
  2. Click the next button at the upper right to go to the Assemble tab page.
  3. On the Assemble page, you can accept the defaults widgets and layout or change the settings.

  1. Click the next button at the upper right to go to the Results tab page.
  2. On the Results page, you can accept the defaults for the contents of an individual search result or change the settings.

  1. Click the next button to move to the Sort tab page.
    1. The Sort tab page displays.

  1. On the Sort page, you can accept the default search results ordering(s) or change the settings.
  2. Click the next button to go to the Content page.
    1. In the Content tab page, you can control how the application renders content as XHTML for web browsers.

  1. Click the next button to move to the Apperance tab page.
    1. On the Appearance page, you can specify your application's title and overall look and feel.

  1. Click the next button to go to the Deploy tab page.
    1. The Deploy page appears.

  1. On the Deploy page, select New App Server. (You can only select Existing App Server if an App Server is already configured for this application.) Accept the default values or provide the App Server with a name and port number.
  2. Click the Deploy button and confirm.
    1. Application Builder creates and configures the new App Server and opens a new window where it launches the new application. This may take a short while. When Application Builder prompts you to log in, enter a username and password and click OK.

      For details about controlling access to your new application, see Controlling Access to Application Builder and to Generated Applications.

      When you deploy an application, it appears in a new browser window using a URL whose hostname is what is stored in the MarkLogic Server configuration files (the result of an xdmp:host-name call). If you are running on a laptop computer that is changing networks, the hostname might not be available on your network, resulting in a 404 or similar error when the application launches (because it is trying to access a server name unavailable on your current network). Substituting localhost for the hostname in the URL should fix this.

    2. You can test the Oscars application by entering search terms or clicking on the browse links to narrow the diplayed results.

Loading the Complete Set of Oscars Data

Initally, Application Builder only loads a few sample data files for use by the Oscars application. To load the full 20 MB content set, use the following steps:

  1. In the Information Studio Flows section of the Application Services page, click New Flow.

    The Flow Editor appears.

  2. Click Change Collector at the bottom of the Collect section:

  3. In the Select A Collector window, select Oscars Example Data Loader:

  4. In the Configure Settings window, select Done. Do not make any changes in this window.
  5. The Collect section of the Flow now shows that the Oscars Example Data Loader is configured and the URL from which it will download the data.
  6. In the Load section, select oscars as the Destination Database and click Document Settings:

  7. In the Document Settings window, change the URI Structure Configuration to:

    Click Done.

  8. Click Start Loading to load the content into the database.

    The data downloads automatically over your Internet connection, while a spinning icon appears until the load is complete. When done, you will see different count values and additional facet values.

    While downloading the sample page, do not navigate away from it or close the browser window until the spinning icon disappears and the page reloads, otherwise the download might be interrupted.

Using the Oscars Sample Application

The Oscars sample application enables you to search, browse, and display articles about Oscar award winners from the last nine decades. It is uses the Search API's standard features, including query text parsing, faceted navigation, snippetting, and many more. For details about the Search API, see Search API: Understanding and Using in the Search Developer's Guide.

While you can learn about the application by playing with it, this section highlights some of its main features, including:

Keyword Searching, Search Suggestions, and Parsing

You can enter keywords into the search box and press return to search the database. For example, a search for raymond shows snippets for the first 10 of 37 results.

As you type search terms, the application suggests your possible full search. For example, as you type Ingrid Bergman, you might see something like the following:

Because the application uses the Search API, you can use standard search grammar such as combining multiple terms with AND semantics, treating double-quoted phrases as phrases, and so on. For information about the search grammar for the Search API, see Search API: Understanding and Using in the Search Developer's Guide.

You can also search using constraints. For example, the following query text finds everything about the actor Dustin Hoffman:

actor:"Dustin Hoffman"

This is not a standard full-text search, but is a constraint showing all the documents matching where an particular value in the source XML, <actor>, has the content Dustin Hoffman. You can combine the constraint with other terms to further narrow the results:

buck actor:"Dustin Hoffman"

When you click on any links in the user interface, notice that the query text in the search box shows the current query.

Browsing with Facets

The left side of the application shows facets used to browse through the content. When you click on a facet, it narrows the overall search results to those results in the facet's category, while keeping the existing categories or search terms active.

For example, if you first click on the Award:Best Director browse link, then on the Decade:1970s link, and then on the Winners:True link, your results are all of the 1970s winners of the Best Director award.

Each of the browse facets has a count of how many of its results match your current query.

Search Result Page

The search result page shows a link with a text summary of the content, highlighted snippets of the content matching your search, and other information about the search match. Clicking the result link takes you to the content details.

Displaying Content Details

The content details page includes the complete content for the search result. The rendering is based on the configuration specified on Application Builder's Content Display page. The page's style is based on the skin you chose and on any custom CSS entered on the Appearance page.

Using Application Builder to Modify the Oscars Sample Application

This section describes how to add a year facet to the Oscars application. With the year facet, you can first drill down on results with the decade facet, then drill down further using the year facet. The year facet uses the same index as the decade facet.

To create a year facet, do the following:

  1. Start Application Builder (for example, open http://localhost:8000/appservices in a browser).
  2. On the Application Builder Applications page, click the application name that you used for your Oscars sample application (in this case, Oscars).
  3. Click the Search tab. At the bottom of the Search page, click Add New:

  4. In the New Constraint dialog, Click Range.
    1. In the New Constraint dialog, enter year for the Name and select year for the Source Index.

    2. Click Create Range Constraint. Application Builder creates the constraint.

  5. In the application name menu, click Deploy Now from the Oscars pull-down menu:

  6. Application Builder compiles and deploys the new application code to your App Server's modules database. During deployment, the following appears in a new window:

When Application Builder is done, the newly modified application replaces the status page, including the new year facet. Test the facet by doing a search, selecting a decade, and then selecting a year to find the results for a single year from that decade.

The year facet in this example is available at all times, whether or not you have clicked on the decade facet. To only display the year facet after selecting a decade, you need to add additional display logic. The Oscars example application is not set up to do hierarchical logic, but you can modify it to do so. For details on modifying the application, see Extending Applications Built With Application Builder.

« Table of contents
Next chapter »