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

Application Builder Developer's Guide — Chapter 4

Extending Applications Built With Application Builder

Application Builder generates search applications by using defined templates. This chapter describes how to extend and modify the generated applications and contains the following sections:

Viewing the Generated Code

When you deploy an application, Application Builder deploys the application's code to an App Server's modules database. The App Server is specified on Application Builder's Deploy page. To view the code, look in the modules database in the /application/ directory. Use any method you care to look at documents in a database, such as setting up a WebDAV server to the modules database. The entire application is there, including all images, libraries, and other components.

The easiest way to display the application page in your browser and use the ‘View Page Source' feature to view the HTML source and navigate to the stylesheet and JavaScript files.

Do not update files in any of these directories. Otherwise, the next time you make changes to your application in App Builder, changes you made to these modules will be overwritten. Instead, modify the files described in The Custom Directory.

The basic files and directories in the / directory are shown below:

File Description
index.html File that defines the default HTML page for the application. This is what loads in the browser when the user loads the application.
application/app.xsl File that defines the XSLT used to render all pages in the application, except result pages. .
application/app-content.xsl File that defines the XSLT stylesheet used to render the content page described in Content Page.
application/app.css File that defines the CSS specified in the Customize field on the Appearance page.
application/app.js File that is the instantiation of the widget library for all the widgets on the page.
application/skin.css File that defines the CSS specific to the chosen skin (dawn/dusk)
application/skin.js File that applies a highcharts global theme object to the page, according to the selected skin.
application/constraint Directory containing the XQuery extension needed for map widgets.
application/css Directory containing the CSS definitions that define the layout for the application theme.
application/custom Directory containing all the files that can be used to extend and modify the application.
application/images Directory containing images used by the application.
application/lib Directory containing the library JavaScript files for the widgets and visualizations.
application/skins Directory containing the Dusk and Dawn skins defined in the Appearance page.

The Custom Directory

Use the files in the /application/custom directory to override the generated application files and preserve your changes when the application is redeployed by Application Builder.

The files in the /application/custom directory are shown below:

File Description
app.xsl Contains the XSLT used to render all pages in the application, except result pages. This file overrides the generated /index.html file. For an example, see Customizing the Footer.
content.xsl Contains the XSLT used to render result pages. This file overrides the XSLT stylesheet used to render the content page described in Content Page. For an example, see Customizing the Results Page.
rewrite.xml Contains URIs for additional content. This file extends the MarkLogic/Modules/MarkLogic/rest-api/endpoints/config.xqy file. The URI of the new content must begin with /content/.
app.js JavaScripts added to this file extend (but do not override) the JavaScript generated by Application Builder. For an example, see Adding Custom JavaScript.
app.css Styles added to this file override and extend the styles generated by Application Builder. For an example, see Customizing the Content Display.
app-config.js JavaScripts added to this file extend the configuration of your application and widget. For an example, see Adding Custom JavaScript.

Customizing Applications Generated by Application Builder

This section describes how to customize an Application Builder generated application using Application Builder, and contains the following parts:

Basic Design Pattern

Applications generated from Application Builder are designed to be extensible. The basic design pattern to modify a generated application is as follows:

  • Display the application page in your browser.
  • Use the browser ‘Display Page Source' feature to view the page source.
  • Locate the stylesheets, JavaScripts, or HTML to be modified in the page source.
  • Copy the code from the page source to the respective file in the custom directory. For example, if you want to change a style definition in the application/skin.css file, copy the definition to the custom/app.css file.
  • Modify the code in the custom file to override the code in the generated file.
  • Refresh the application page in your browser to see the results.

Accessing the Code in the Custom Directory

To modify a generated application, you must gain access to the files in the /application/custom directory in the application's modules database. One common way is to create a WebDAV App Server to the modules database, and then use it to access and modify the code. Many code development tools support WebDAV for editing. For details on WebDAV Servers, see WebDAV Servers in the Administrator's Guide.

If you are using oXygenXML, access the modules database through WebDAV.

Log in as a user with permissions for app-builder. Do not use WebDav logged in as the admin user, as this will create files readable only by admin.

Road Map for Application Page Objects

This section shows the basic objects that control the specific sections of the application pages. All of these can be modified in the custom files.

The objects below are common to the search and navigation page.

The content and sidebar portions of the search page are controlled by the following objects:

Customizing the Footer

To modify the footer in your generated application, find the footer definition in the /index.html file:

<div id="footer" class="footer">
  <p>
    <span class="copyright">
      © 2012, MarkLogic Corporation, All Rights Reserved.
    </span>
    <a href="/content/help">Oscar® Explorer Help</a>
    <span class="pipe"></span>
    <a href="/content/contact">Contact MarkLogic Corporation</a>
    <span class="pipe"></span>
    <a href="/content/terms">Terms of Use</a>
  </p>
</div>

For example, to change the copyright portion of the footer from that generated by Application Builder:

© 2012, MarkLogic Corporation, All Rights Reserved.

to:

© 2012, My Company, All Rights Reserved.

Add the following xsl:template element to the /custom/app.xsl file:

<xsl:template match="*:span[@class eq 'copyright']">
  <span class="copyright">
    © 2012, My Company, All Rights Reserved.
  </span> 
</xsl:template>

When you refresh your application page, it now uses the new footer, with the change persisting after redeploying the application in Application Builder.

Customizing the Content Display

To modify the content display in your generated application, locate the code in the application/app.css or application/skin.css file. For example, the following define the body background and the chiclet:

body {
  color: rgb(50,50,50);
  font-family: "Lucida Grande", Helvetica, Arial, sans-serif;
  background: blue;
}
#sidebar .chiclet {
  color: white;
  text-transform:capitalize;
  background: url('images/facet_green.png') left top repeat-x;
}

To change the body background to blue, the snippet text to green, and the chiclet text to yellow, add the following to the custom/app.css file:

body {
  color: green;
  font-family: "Lucida Grande", Helvetica, Arial, sans-serif;
  background: blue;
}
#sidebar .chiclet {
  color: yellow;
  text-transform:capitalize;
  background: url('../images/facet_green.png') left top repeat-x;
}

The relative pathname to the chiclet background URL must be modified to point to the images directory from the custom directory.

Customizing the Results Page

You can modify the look of the results page by adding XSLT to the content.xsl file. This overrides the XSLT stylesheet generated by Application Builder. For example, you want to change the links in the Oscars application to the Wikipedia pages from this:

to look like this:

You can add the following template to the content.xsl file:

  <xsl:template match="xhtml:a">
    <xsl:choose>
      <xsl:when test="starts-with(@href, 'http://example.com/')">
      </xsl:when>
      <xsl:otherwise>
        <span style="text-decoration: underline;">
          <xsl:apply-templates/>
        </span>
        <a href="{@href}" title="External link"> Link</a>
      </xsl:otherwise>
    </xsl:choose>
  </xsl:template>

Adding Custom JavaScript

The following are simple examples of modifying the behavior of existing JavaScript and adding new JavaScript to an application.

For example, you want to disable to widget-2 widget (In the sample Oscars applicaiton, this is the pie chart widget, by default) from refreshing the snippets displayed in the results panel. To do this, you can add the following JavaScript code to the custom/app.js file to disable the widget's selection behavior from updating other charts / results:

$('#widget-2').unbind('selection');

An example of adding new JavaScript is as follows. The first line writes a new empty widget container into the top of the page. It then creates a widget on that container which renders the total number of results along with the total number of pages of results:

$('#content').before('<div id="totalCount" class="widget"></div>');
var widget = ML.createWidget($('#totalCount'), function (data) {
   $('#totalCount').html(data.total + " results found<br />" +    Math.ceil(data.total / 10) + " Total pages of results");
});

When you refresh the search page in your browser, the following should appear in the upper-left portion of the page:

You can modify the widgets and other objects created by means of the JavaScript generated by Application Builder by editing the custom/app-config.js file. The custom/app-config.js file contains a number of commented examples that make use of the .extend utility to merge a new configuration into an existing configuration.

For example, one of the examples shows how to change the title of the pie chart widget:

// example of changing title for pie chart
//$.extend( pie_config_2, {title: "People Title"})

To enable this modification, simply remove the comment:

$.extend( pie_config_2, {title: "People Title"})

And observe the results in your deployed application.

Making Further Modifications to the Application

As described in Viewing the Generated Code, the generated application consists of HTML, XSLT, JavaScript, and CSS code that you can modify in any way you want. The example modifications shown in this chapter are simply an introduction that you can use as a starting point for making more substantial modifications.

Removing Modifications to an Application

You can remove all of the modifications to an application in the /application/custom directory by redeploying the application to another App Server.

For example, to redeploy an existing application to new server CleanApp, navigate to the Deploy page, select New App Server, enter the new name and port, and click the Deploy button:

« Previous chapter