Navigation Framework (for the MITAA site)

Currently on isda-cs2 there is a Web Project called NavigationFrameworkTest which has a draft version of the navigation framework running on it.  Here's a link to a preview of the site index page in my sandbox: http://jcalz.navtest.www--sandbox.18-92-1-223.ip.alfrescodemo.net:8180/sitetree.jsp

How the Navigation Framework works:

There is a "navigation.jar" file which must live in the /WEB-INF/lib directory of the webapp.  It defines a JSP tag library which can be used to get navigation/breadcrumb/sitetree information.  This library causes the webapp to crawl its structure constantly in the background (in a low priority thread).  The webapp periodically updates a global "SiteTree" object representing all the navigation information about the site.  

For Content Authors:

The web application automatically generates navigation information for your web project.  If you do not tell it to do something differently, it will generate default titles for the sections and pages in your site.  By default, every folder (except /META-INF and /WEB-INF) in the site will be a Section whose title is the same as the name of the folder.  Also, every file in the site with an "html-like" extension (one of "jsp", "jspf", "jspx", "htm", "html", "xht", "xhtm", "xhtml", "sht", "shtm", or "shtml") will be a Page whose title is the same as the name of the file without the extension.  In some cases this default behavior will be what you want.  In other cases, you will want to alter the default behavior by controlling the navigation information yourself:

You may control the navigation information on a per-folder level in your Alfresco Web Project via the web form named "Navigation Information".  This web form manages a file in the current folder called "navigation.xml".  If you have just created a new folder and you want to control its navigation information, you must choose Create > Create Web Content:

 
Then you should create content via the "Navigation Information" web form as shown below:

If you have already created the navigation.xml file for a folder and you want to alter it, you can do so by clicking the edit (pencil) icon on the navigation.xml file:

The form for editing/creating the navigation.xml file is shown below:

There are three types of fields to be filled out.

The first is the Section Title.  The current folder corresponds to a Section in the site tree.  If you want the title of this Section to be something other than the name of the folder, enter it here.

The next type of field is a list of Links.  A Link consists of a Url and a Title.  You may enter as many Links as you'd like.  These will generally end up as Pages under the current section, in the order they appear in this web form.  There are several ways you can use Links to alter the default page naming behavior.

• To change the title of a Page which is already included in the current Section: type the url for the page (either the full root-relative url e.g.,"/foo/bar/baz.html" or just the file name e.g., "baz.html") in the Url field and a new title in the Title field.
• To add a Page which is not currently included in the current Section, because it is has a non-html-like file extension:  type the url for the page (either the full root-relative url for the page, e.g., "/foo/bar/baz.txt", or just the file name e.g., "baz.txt") into the Url field and the desired title in the Title field.
• To add a Page which is not currently included in the current Section, because you want to cross-link it from somewhere else in the site:  type the full root-relative url for the page, e.g., "/other/folder/thing.html", into the Url field and the desired title in the Title field.
• To add a Page which is not currently included int he current Section, because it is a link to an external web page: type the absolute url for this page, e.g., "http://web.mit.edu/", into the Url field and the desired title in the Title field.
• To change the order of a Page or a Section which is already included in the current Section: enter its url (root-relative or file name) into the Url field and the desired title in the Title field, and change the order of the Link by clicking the up or down arrow buttons in the form. 

  Note

  Note that any Links that are explicitly included in the navigation.xml file will come first in the listing for the current Section, before any Sections or Pages which are automatically included by default.  If you want fine-tuned control over the order of all the Sections and Pages within the current Section, you will need to create Links for all of them.

(Does that make sense?  Maybe that was too complicated, but the upshot is this: the Link fields specify the Pages that appear in the current Section.)

Finally, there is a list of Ignore Urls.  These are the urls of files or subfolders that you don't want to be included under the current Section.  Remember that by default, all folders and most html-like files are included in the site tree.  This is a way to turn that behavior off for particular folders and files.  There are two ways you can use Ignore Urls:

• To ignore a file so that it is not included as a Page: enter its file name e.g., "index-old.html", into the Url field.
• To ignore a folder so that it is not included as a child Section: enter the folder name (ideally ending with a slash) e.g., "junk/", into the Url field.

That's all there is to it for content authors. 

For Webapp Developers:

Webapp developers will primarily deal with the navigation framework JSP tags and the beans they expose. 

As mentioned above, the navigation.jar file must live in the /WEB-INF/lib directory of the webapp.  The navigation framework tag library is referenced by the symbolic url "http://web.mit.edu/ist/isda/tags/navigation".  In your JSP file, you should declare the tag library like this:

<%@taglib uri="http://web.mit.edu/ist/isda/tags/navigation" prefix="nav" %>

Navigation objects and properties

This section details the various object beans which can be exposed through the tags in the tag library.  Unless stated otherwise, these objects are in the edu.mit.isda.navigation package.  Also, all properties of these objects are read-only.  You cannot alter them in any way within a JSP.

SiteTree

This is an object representing the site tree.  There is really only one important property here: homeSection, which corresponds to the topmost url (usually "/") in the site.

Properties

Page (and Section)

This is an object representing a page or a section within the site tree.   The basic object is a Page, which has a title and a URL.  A Section is a special type of Page, which contains subpages.  If a Page is not a Section, it does not contain subpages.  (All Section objects are Pages, but not all Page objects are Sections.)   To ease JSP programming, you can just treat all Sections as Pages, and use the "isASection" and "subpages" properties to access section-specific behavior.

Properties

Tag descriptions

The following section describes the tags in the navigation tag library, as well as giving some example of how they are used in conjunction with the above bean properties.

<nav:setSiteTreeVar> 

 This <nav:setSiteTreeVar> action sets a scoped variable to the object representing the current site tree.  The site tree bean is useful for a JSP which generates a Site Index or Site Map page.  Once you have set a variable to the site tree bean, you can walk through it with the <nav:treeWalk> and <nav:subTreeWalk> tags.

It is not recommended to save the site tree to session or application scope for later use, as it will possibly be stale (if pages have been added or removed without restarting the webapp).  Instead, just use <nav:setSiteTreeVar> again when you need the most recent site tree.

Syntax

<nav:setSiteTreeVar [var="var"] [scope="page|request|session|application"] />

Attributes

Example

<nav:setSiteTreeVar var="theSiteTree" />
The Site Tree was last updated at <fmt:formatDate value="${theSiteTree.lastUpdated}" pattern="h:mm:ss a" />

And a possible output for this example:

<nav:treeWalk> and <nav:subtreeWalk>

The <nav:treeWalk> and <nav:subtreeWalk> actions allow you to recursively walk through the site tree (or any tree structure). The idea is that the body of the <nav:treeWalk> tag is performed for every branch of the tree. The body of the <nav:treeWalk> tag must contain the <nav:subtreeWalk> tag, which indicates where to include the sub-branches in the tree walk. It's much easier to look at an example than to explain what I mean.

Syntax

<nav:treeWalk [root="theRootObject"] [var="currentNodeObjectVar"] [depth="currentDepthVar"] >
  ...
  <nav:subtreeWalk subroot="subNodeObject" />
  ...
</nav:treeWalk>

Attributes

Example

The following example performs a fairly simple walk through the site tree, producing a set of nested bulleted lists representing all the sections/pages and subpages/subsections in the site. 

<nav:setSiteTreeVar var="theSiteTree" />
<ul><li>
  <nav:treeWalk root="${theSiteTree.homeSection}" var="page">
     <a href="${page.url}" ><c:out value="${page.title}" /></a>:<br/>
       <ul><c:forEach items="${page.subpages}" var="subpage">
         <li><nav:subtreeWalk subroot="${subpage}" /></li>
       </c:forEach></ul>
  </nav:treeWalk>
</li></ul>

And a possible output for this example:

<nav:setBreadcrumbVar> 

 This <nav:setBreadcrumbVar> action sets a scoped variable to an object representing the breadcrumb for a particular target url in the site.   In this case, the breadcrumb object is a list of the target's ancestor pages, starting from the home page of the site and ending at the target page.  This is useful for a JSP which generates a breadcrumb for the current page.   Once you have set a variable to a breadcrumb object, you can iterate through it within a <c:forEach> tag.

It is not recommended to save the breadcrumb to session or application scope for later use, as it will possibly be stale (if pages have been added or removed without restarting the webapp).  Instead, just use <nav:setBreadcrumbVar> again when you need the most recent breadcrumb.

Syntax

<nav:setBreadcrumbVar [url="targetUrl"] [var="var"] [scope="page|request|session|application"] />

Attributes

Example

The following example gets and displays a breadcrumb for the currently requested page, since the "url" attribute is not set. 

<nav:setBreadcrumbVar var="breadcrumb" />
<c:forEach var="page" items="${breadcrumb}" varStatus="status">
<c:if test="${not status.first}">&gt;</c:if><a href="${page.url}" ><c:out value="${page.title}" /></a>
</c:forEach>

And a possible output for this example:

<nav:setPageVar> 

 This <nav:setPageVar> action sets a scoped variable to an object representing the navigation information for a particular target url in the site.   This is useful for a JSP which needs to know, for example, the list of links for the current page or section.  

It is not recommended to save the page object to session or application scope for later use, as it will possibly be stale (if pages have been added or removed without restarting the webapp).  Instead, just use <nav:setPageVar> again when you need the most recent page object.

Syntax

<nav:setPageVar [url="targetUrl"] [var="var"] [scope="page|request|session|application"] />

Attributes

Example

The following example displays a bulleted list of all links underneath the currently requested page, since the "url" attribute is not set. 

<nav:setPageVar var="page"/>
<c:forEach var="subpage" items="${page.subpages}" >
&bull; <a href="${subpage.url}" ><c:out value="${subpage.title}" /></a><br/>
</c:forEach>

And a possible output for this example:

The end (for now)