Old Release

This documentation relates to an old version of VIVO, version 1.7.x. Looking for another version? See all documentation.

 

Tips and techniques to help in the process of customization.

Overview

This page describes some tools and techniques that can help customizing your VIVO user interface.

Use the Developer Panel

Many of these techniques involve The Developer Panel, which is described in the VIVO Programmer's Notes section of the wiki.

You can change settings on The Developer Panel interactively, while VIVO is running, or you can use a developer.properties file in your VIVO home directory.

A typical developer.properties file
developer.enabled=true
developer.permitAnonymousControl=true
developer.defeatFreemarkerCache=true

When any feature of The Developer Panel is active, you will see this indicator in the header of your VIVO pages:

This is to remind you that developer options may slow down your VIVO, and should not be used in production.

Iterate your code more quickly

Reduce the VIVO build time

A full rebuild of VIVO may be necessary if you are changing the Java source code, or the contents of RDF files. However, if you are only making changes to the Freemarker templates, you can run the build script like this:

ant deploy -skiptests=true

By choosing ant deploy instead of ant all or ant clean deploy, you are selecting an incremental build which will not re-compile all of the Java classes, or copy all of the unchanged files. By setting the option -skiptests=true, you are choosing not to run the unit tests. This is reasonable because the unit tests to not apply to the Freemarker templates.

After making your changes to the templates, you should perform a full build with unit tests.

ant all

Don't restart VIVO until you need to

VIVO will detect changes to the templates without requiring a restart. However, you will probably want to defeat the Freemarker cache (see below).

Also, VIVO will serve the latest version of CSS, JavaScript, or image files. For these files, however, you may need to clear the cache in your browser. Instructions for doing this will differ, depending on which browser you are using. If you don't know how to reset the cache in your browser, you may want to consult this web site: http://clearyourcache.com/, or just search the web for "clear browser cache".

If you change any other types of files, you will need to restart VIVO after running the build script.

Defeat the Freemarker cache

As mentioned above, VIVO will detect changes to Freemarker templates. By default, however, VIVO will not detect the changes immediately. The Freemarker framework caches the templates that it uses, and won't even look to see if a template has changed until 1 minute after it was last read from disk. In a production system, of course, that makes the accessing much more efficient. When you are making frequent changes, it's an annoyance.

Use The Developer Panel to defeat the Freemarker cache.

Customizing listViewConfigs

Ted Lawless has written an open-source Python script to assist with viewing the output of a listViewConfig without having to rebuild the entire Vivo app.

Also, you can skip the unit tests when building VIVO, as shown in Reduce the VIVO build time. Unit tests do not apply to listViewConfigs.

Reveal what VIVO is doing

Insert template delimiters in the HTML

It's not always clear which template has created a particular piece of your HTML page. Templates include other templates, templates are invoked in custom list views, short views, etc. You can use The Developer Panel to insert comments in the HTML that tell you where each template begins and ends.

For example, this section of a page was produced mostly by the identity.ftl template. The languageSelector.ftl template is included, but does not generate any HTML. The next section is produced by the menu.ftl template, and so on.

...
    
    <body >
            <!-- FM_BEGIN identity.ftl -->

<header id="branding" role="banner">

  <h1 class="vivo-logo"><a title="VIVO | connect share discover" href="/vivo">
    <span class="displace">VIVO</span>
  </a></h1>

  <nav role="navigation">
    <ul id="header-nav" role="list">
<!-- FM_BEGIN languageSelector.ftl -->
<!-- FM_END languageSelector.ftl -->
        <li role="listitem"><a href="/vivo/browse" title="Index">Index</a></li>
        <li role="listitem"><a href="/vivo/siteAdmin" title="Site Admin">Site Admin</a></li>
        <li>
          <ul class="dropdown">
            <li id="user-menu"><a href="#" title="user">Jim</a>
              <ul class="sub_menu">
                <li role="listitem"><a href="/vivo/accounts/myAccount" title="My account">My account</a></li>
                <li role="listitem"><a href="/vivo/logout" title="Log out">Log out</a></li>
              </ul>
            </li>
          </ul>
        </li>
      </ul>
    </nav><!-- FM_END identity.ftl -->
            <!-- FM_BEGIN menu.ftl -->
</header>

...

 

Improve your SPARQL Queries

Ted Lawless and Steve McCauley at Brown point out these resources for learning SPARQL:

But not all SPARQL techniques are efficient in practice. Brown has open-sourced their VIVO customization, where you can see some aspects of SPARQL that has worked for them:

https://github.com/Brown-University-Library/vivo/tree/master/productMods/config

This includes constructing local display properties against which they select.

 
  • No labels