Update (2009-04-09): Checkout the new import/export plugin generators at dradis community forums.

Generate the plugin skeleton

$ ./script/generate plugin my_export
      create  vendor/plugins/my_export/lib
      create  vendor/plugins/my_export/tasks
      create  vendor/plugins/my_export/test
      create  vendor/plugins/my_export/README
      create  vendor/plugins/my_export/MIT-LICENSE
      create  vendor/plugins/my_export/Rakefile
      create  vendor/plugins/my_export/init.rb
      create  vendor/plugins/my_export/install.rb
      create  vendor/plugins/my_export/uninstall.rb
      create  vendor/plugins/my_export/lib/my_export.rb
      create  vendor/plugins/my_export/tasks/my_export_tasks.rake
      create  vendor/plugins/my_export/test/my_export_test.rb

Edit vendor/plugins/my_export/init.rb to include the main plugin library:

# Include hook code here
require 'my_export'

In the main library (vendor/plugins/my_export/lib/my_export.rb), define a module (choose a name, ideally it should match the plugin name):

# MyExport
module MyExport
end

This is all you really need to get it started. Now you have to put your code in the right place so the framework finds it (and creates an entry for you in the export menu).

Hooking into the framework

At the end of the day an export plugin provides a number of Rails actions. These are methods that will be invoked through the URL, for instance:-

/export/to_pdf
/export/to_xml
/export/to_excel
...

Each export plugin can define several actions. If more than one action is defined a nested submenu will be appended to the export menu with all the defined actions.

In order for the framework to find your actions, they have to be defined in a certain way, they have to be defined inside the Actions module (we are still editing the same file):-

# MyExport
module MyExport
  module Actions
    # first action
    def to_myformat(params={})
      # your action code goes here
    end
 
    # second action
    # [...]
  end
end

And that’s it, nice and easy, you can define as many actions as you like in you Actions module.

Finally, in order to make everything work together you need to include your module in the main repository of export plugins (Plugins::Export):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# MyExport
module MyExport
  module Actions
    # first action
    def to_myformat(params={})
      # your action code goes here
    end
    # [...]
  end
end
 
module Plugins
  module Export
    include MyExport
  end
end

Remember to restart you dradis server. Your export menu should have an entry for your newly created plugin. And now is the time to be creative about what you implement!

In this post I’ll be looking at what an extension is, how it fits into the dradis framework and how to write your own extensions.

You are welcome to jump ahead to the How do I write my own extension? if that is the only part that you are interested in.

What is an extension?

In a nutshell – A dradis extension is an addition to the collection of functions offered by the dradis client side. The possibilities of what an extension can be are almost endless. From a logical perspective it will be a function that enhances the usability of the application within the context of the user.

Currently the functionality that is offered by an extension is triggered from the command line console on the client side. To see what are all the commands offered by your currently installed extensions type help in the command line console of the dradis client. You might see something similar to:

List of registered commands
---------------------------
help:	shows the help of all the commands available
reload:	reload the modules from the filesystem
quit:	exits the application
add:	add elements to the project
fact:	shows a random Chuck Norris fact
encode:	Encodes a string using various differnet encoding schemes
lookup:	Basically greps a file, useful for lookup tables
decode:	Decodes a string into the specified encoding type
export:	export the knowledge base to a local file
ls:	lists entries under the directory specified as argument
import:	import external resources to dradis

Some of those commands are hard coded into the console functionality but the majority are commands offered by your installed extensions. For example the fact command is offered to you by the chucknorris extension and the ls command is offered by the filesystem extension.

Extensions can also communicate to other parts of the application. In the majority of cases this will be communication to the data storage. For example the add command allows you to add data to the data storage and the export command allows you to export the data storage to a local file.

Where do extensions fit into the dradis framework?

Extension fact list:

• As mentioned previously, extensions are found on the client side of the dradis framework.
• When looking at the code they can be found in the client/extensions folder.
• An extension provides one or more commands that can be called from the client command line console.
• Executing one of these commands in the console triggers a call to a method in the extension code (Executing fact in the console triggers the fact method in the chucknorris.rb file).
• The return value of the extension method is printed to the console interface (The return value of the fact method is a Chuck Norris fact that is printed to the console interface).
• The extension communicates to the rest of the application through calls to service providers (I’ll define a service provider shortly).
• An extension can be one of two types: simple or namespace (Definition of these will follow).

What is a service provider?
A service provider is an interface to a certain part of the application. It can be seen as a functionality presented through an API.
Lets look at an example: The dradis client side is modeled on a Model-View-Controller architecture. The extension code has access to an instance of the Controller (@controller). The extension does not have direct access to the Model (the Model is the access layer to the data storage). Calls to the Model is made through the data-storage service provider (client/core/service_providers/data_storage.rb. The data-storage service provider has a set of methods (an API) through which you can:

• add a node – @controller.request_service(:model_add_node, …)
• add a category – @controller.request_service(:model_add_category, …)
• get the contents of a node – @controller.request_service(:model_find_node, …)
• etc.

Have a look in the client/core/service_providers folder for all the currently available service providers.

What is a simple extension and a namespace extension?
A simple extension provides one or more commands that are grouped only by them being members of the extension. A command of a simple extension can be the only command in the current dradis client instance to have the name of that command. It is triggered in the command line console by: command parameters. The chucknorris extension is a simple extension and offers the fact command. No other simple extension can have a command called fact.

A namespace extension places its commands in a namespace. One namespace may contain commands with the same name as simple commands or commands in other namespaces. If we want to add a fact command that gives random Bruce Schneier facts then we can create the bruceschneier namespace and place a fact command in it that will not interfere with our Chuck Norris fact command. Namespace commands are called from the commandline in the format: namespace command parameter. The export extension is an example of a namespace extension.

How do I write my own extension?

Let’s have a look at the basic structure of a simple extension. Following is a simplified version of the chucknorris extension:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

module Extensions
  class Chucknorris < Extensions::Simple
    #----------------------------------------------------- Dispatcher implementation
    INFO = {
      :commands => {
        'fact' => {
          :desc => 'shows a random Chuck Norris fact',
          :syntax => [ ]
        }
      }
    }
 
    #----------------------------------------------------- commands implementation
    def fact(*args)
      # here we implement the magic that gets the new fact and returns it
    end
  end
end

• line 1 – To implement our extension we need to extend the Extensions module
• line 2 – We define our class to inherit from the Extensions::Simple class
• lines 4-11 – The INFO hash defines all the commands in our extension for the use of the command launcher. In the case of the example above it defines the presence of the fact command with its description and its syntax. In this case there is no syntax defined as the command does not take any parameters.
• lines 14-16 – This is the method implementation of the command that was defined in the INFO hash.

Now lets look at a slightly more complex namespace extension. The example is the add extension that hosts the node and category commands. The syntax for the two command are respectively:

add node  <parent id> <label>

and

add category <name>

This is the code for the extension:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

module Extensions
  class Add < Extensions::Namespace
    #----------------------------------------------------- private methods
    private
    #----------------------------------------------------- Dispatcher implementation
    INFO = {
      :namespace => 'add',
      :description => 'add elements to the project',
      :commands => {
        'node' => {
          :desc => 'Adds a node to the node tree.',
          :syntax => [
 
          {
            :required => true,
            :label => 'parent_id',
            :desc => 'The id of parent to the new node. Use 0 if it is to be a root node.',
            :regexp => /^\d*$/
          },
          {
            :required => true,
            :label => 'label',
            :desc => 'The label/name of the new node.',
            :regexp => /^\w[\w\s]*$/
          }
          ]
        },
        'category' => {
          :desc => 'Adds a note category.',
          :syntax => [
          {
            :required => true,
            :label => 'name',
            :desc => 'name of the new category',
            :regexp => /^\w[\w\s]*$/
          }
          ]
        }
      }
    }
 
    # Implements the add node fucntionality. See the above for allowed parameters
    def node(*args)
      # the parent_id needs to be an integer or a nil value
      args[1] = args[1] == '0' ? nil : args[1].to_i
      # call the service provider to add a node with the specified parameters
      @controller.request_service(:model_add_node, args[1], nil, args[2])
      return "Added node: #{args[2]}"
    end
 
    # Implements the add category fucntionality. See the above for allowed parameters
    def category(*args)
      # call the service provider to add a node with the specified parameters
      @controller.request_service(:model_add_category, args[1])
      return "Added category: #{args[1]}"
    end
  end
end

I’ll highlight the important and new bits of code:

• line 2 – Different that in the previous example we define this extension to inherit from the Extensions::Namespace class
• line 7 – In the INFO hash we define the namespace add. The contents associated with the add hash key defines the commands in the namespace.
• lines 9-38 – Here we define our commads in a very similar fashion as in the previous example. We have added the complexity of each command accepting some parameters. This is defined by the array assigned to the syntax key
• line 14 – States that the parameter is compulsary
• line 15 – This is the displayed name of the parameter
• line 16 – Defines the description of the command that will be printed in the help display of the command
• line 17 – Specifies the regular expression by which the parameter will be validated by the command launcher
• lines 42-55 – This is the implementation of the commands as defined in the INFO hash
• line 44 – The args array contains the parameters that was passed. args[0] is the command, node in this case. args[1] contains the parent_id and args[2] contains the label
• line 46 – This is an example of a call to a service provider in this case it calls a method in the data-storage service provider. (See the architecture section for a full discussion on this)
• line 47 – The return value will be displayed in the command line console.

As a last bit of advice:

• Name your extension file, class and if applicable namespace the same name
• If you add something new to the data storage you might find that you can not reference the newly added record immediately. The reason is that you have to wait for the local cache of the data storage to be refreshed. You can force a refresh with a @controller.request_service(:model_knowledge_refresh) call.

That should leave you with a good understanding of dradis extensions.

As always – Happy dradis coding!

It is not the final solution, and it is not integrated with the web interface, but hopefully it will give you an idea of how easy is to get your own exporting modules for dradis.

The Template

So the first step was to use Word to generate a template we could use for our export plug-in. I just created a simple empty document that looked like this:-

Save your template as an XML document (you can get mine here: template.xml). The template contains these sections:-

• Issue title
• Date of discovery
• Issue description
• Mitigation recommendations
• Additional information

What our plug-in is going to do is to walk through the notes in the repository and repeat this template for each one. In order for the code to find the different sections, you have to edit the XML file an add some id attributes to the tags associated with the sections. For instance:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

<!-- Note Section -->
<wx:sub-section>
  <w:p wsp:rsidR="005F557A" wsp:rsidRDefault="00C27C1C" wsp:rsidP="00C27C1C">
    <w:pPr>
      <w:pStyle w:val="Heading1"/>
    </w:pPr>
    <w:r><w:t id="vulntitle">Directory Listings</w:t></w:r>
  </w:p>
  <w:p wsp:rsidR="00C27C1C" wsp:rsidRPr="00C27C1C" wsp:rsidRDefault="00C27C1C" wsp:rsidP="00C27C1C">
    <w:pPr>
      <w:jc w:val="right"/>
      <w:rPr>
        <w:rFonts w:ascii="Arial" w:h-ansi="Arial" w:cs="Arial"/>
        <wx:font wx:val="Arial"/>
        <w:sz w:val="16"/>
        <w:sz-cs w:val="16"/>
      </w:rPr>
    </w:pPr>
    <w:r wsp:rsidRPr="00C27C1C">
      <w:rPr><w:rFonts w:ascii="Arial" w:h-ansi="Arial" w:cs="Arial"/><wx:font wx:val="Arial"/><w:sz w:val="16"/><w:sz-cs w:val="16"/></w:rPr>
      <w:t id="vulncreated">2009-02-10 00:07 GMT</w:t>
    </w:r>
  </w:p>
 
  <wx:sub-section id="vulndesc">
    <w:p wsp:rsidR="00C27C1C" wsp:rsidRDefault="00C27C1C" wsp:rsidP="00C27C1C">
      <w:pPr><w:pStyle w:val="Heading2"/></w:pPr>
      <w:r><w:t>Description</w:t></w:r>
    </w:p>
  </wx:sub-section>
 
  <wx:sub-section id="vulnrec">
    <w:p wsp:rsidR="00C27C1C" wsp:rsidRDefault="00C27C1C" wsp:rsidP="00C27C1C">
      <w:pPr><w:pStyle w:val="Heading2"/></w:pPr>
      <w:r><w:t>Recommendation</w:t></w:r>
    </w:p>
  </wx:sub-section>
 
  <wx:sub-section id="vulnextra">
    <w:p wsp:rsidR="00C27C1C" wsp:rsidRDefault="00C27C1C" wsp:rsidP="00C27C1C">
      <w:pPr><w:pStyle w:val="Heading2"/></w:pPr>
      <w:r><w:t>Additional Information</w:t></w:r>
    </w:p>
  </wx:sub-section>
</wx:sub-section>
 
<!-- /Note Section -->

• Issue title: <w:t id="vulntitle"> (line 7)
• Date of discovery: <w:t id="vulncreated"> (line 21)
• Issue description: <wx:sub-section id="vulndesc"> (line 25)
• Mitigation recommendations: <wx:sub-section id="vulnrec"> (line 32)
• Additional information: <wx:sub-section id="vulnextra"> (line 39)

For the issue title and the date of discovery we will be modifying the text of the XML node. For the description, recommendation and additional information we will be attaching child nodes to the one tagged.

The Code-fu

We are already thinking on ways of mapping your template sections with you repository fields, but for the time being most of the information is extracted from the the Note text. So the structure of our notes would be:-

Title:
Whatever is the title of the issue

Descripton:
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea
commodo consequat.

Duis aute irure dolor in reprehenderit in voluptate velit esse cillum
dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Recommendation:
Sed ut perspiciatis unde omnis iste natus error sit voluptatem
accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab
illo inventore veritatis et quasi architecto beatae vitae dicta sunt
explicabo.

Additional stuff:
- this and that
- blah blah

The code will take the Note text, then apply a regular expression to find the different sections and extract the fields used in the template:-

1
2
3
4
5
6

  Note.find(:all).each do |n|
    #... more stuff here
    puts "processing Note #{n.id}"
    fields = n.text.split(/.+?:\n.*?/).collect do |field| field.strip end
    #... more stuff here
  end

The code will be smart enough to detect if the Additional stuff section is present or not, this is done by simply counting the number of extracted fields.

The XML Documents

For To process XML we will be using REXML:

1
2
3
4
5
6
7
8
9
10

begin
  doc = REXML::Document.new(File.new('./vendor/plugins/word_export/template.xml','r'))
rescue REXML::ParseException => e # re-raise exception
  raise Exception.new(e)
end
 
vulns = []
body = REXML::XPath.first(doc, '//w:body')
vuln_template = REXML::Document.new( doc.root.clone.to_s )
vuln_template.root.add body.children[3]

First we need to load the template, then in lines 8-10 we locate the section of the code we will be repeating for each Note. and store a copy of the full section in vuln_template.

Using REXML there are two ways of copying an XML node, one is with element.clone() (that will create a copy of the node, but not of its children) and the other is creating a new document: Document.new( element.to_s ) (that will create a swallow copy). Ideally I would have created a new Document with the subsection that contains the template for the Note, however, Word defines a number of XML namespaces at the begining of the document, and REXML complains if we try to create a document without the right namespaces (this would be a simple: Document.new(body.children[3].to_s)).

So instead we need to create a new document that contains the Word namespaces, and then include the Note template we want to use. We do this by cloning the root node of the original document and then attaching the desired structure of the Note.

Also note in line 7 we are initialising an array of vulnerabilities. We will be looping through our notes and filling in the template with the information contained in the Note text and storing the vulnerability in this array. Afterwards, we will attach all the vulnerabilities to the w:body of our document.

Filling in the template

So for each Note we need to create a new XML section that will be stored in the vulns array. This is done by duplicating the vuln_template and filling it with content from the Note.

v = REXML::Document.new(vuln_template.to_s)

The rest of the code is standard XML processing. For the Title and Date fields, just assign the text of the node:

1
2
3
4

#title
title = REXML::XPath.first(v, "//w:t[@id='vulntitle']") 
title.delete_attribute('id')
title.text = fields[1]

For the Description, Recommendation and Additional information sections, we create a new XML paragraph for each paragraph in the original text:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

description = REXML::XPath.first(v, "//wx:sub-section[@id='vulndesc']")
description.delete_attribute('id')
fields[2].split("\n\n").each do |paragraph|
  par = REXML::Element.new('w:t')
  par.text = paragraph
  r = REXML::Element.new('w:r')
  r.elements << par
  chunk = REXML::Element.new('w:p')
  chunk.attributes['wsp:rsidR']='00C27C1C' 
  chunk.attributes['wsp:rsidRDefault']='00C27C1C'
  chunk.attributes['wsp:rsidP']='00C27C1C'
  chunk.elements << r
  description.elements << chunk 
end

Attaching the Vulnerabilities to the Document

Finally we need to attach all the vulnerabilities to the body of the main document. This is done with the following code:-

vulns.each do |v|
  body.insert_before('//w:sectPr', v.root.children[0])  
end

Note that we are not adding the root element, but its first child. This is because the root element is w:wordDocument tag that contains the namespace declarations as already discussed.

And the last thing that is left is to write the document in our output report.xml file:

doc.write(File.new('report.xml','w'), -1, true)

Get the Plug-in

The plugin is already in the repository (in server/trunk/vendor/plugins/), but if you have dradis already in your box you can get it by going to the server folder and executing:

ruby script\plugin install http://dradis.svn.sourceforge.net/svnroot/dradis/server/trunk/vendor/plugins/word_export/

And to run it:

rake export:word

Just remember that you need your notes to formatted as the plugin expects. You can download a sample development.sqlite3.

The old site consisted of 20 static pages or so, which was nice and easy but a real pain to maintain or restructure. So we thought that letting Rails do the heavy lifting for us would be a good idea, but we did not want to set up a Rail environment in the server…

What we finally did is use Rails as a tool to create a static site that we could .tar.gz and upload to the server. As a starting point we used a post in www.chuckvose.com and this is how we completed it to fit our needs.

Follow up (2009-03-23): do not miss how to integrate your rails-static site with Rake and Subversion in the second article of this series: Use Rails to Create a Static Site: Rake and Subversion.

The Controller

We just need one action in our main controller (PagesController):

class PagesController < ApplicationController
  layout 'main'
  def index
    @page = params.fetch(:id, 'index')
    expanded_page = "#{RAILS_ROOT}/app/views/pages/#{@page}.html.erb"
    exists = File.exists?( File.expand_path(expanded_page))
    if exists
      render :action => @page
    else
      render :text => "#{expanded_page} doesn't exist"
    end
  end
end

We fetch the :id parameter from the request that contains the name of the requested page (or index by default), then we try to locate the corresponding file (in /app/views/pages/) and if found we render the action. Rendering the action with no action code in the controller will just render it’s ERB template which is exactly what we want.

We also added a couple of routes in /config/routes.rb so every time a something.html was requested, the PagesController would be invoked:

map.root :controller => 'pages'
map.connect ':id.html', :controller => 'pages', :action => 'index'

The Layout and the Pages

The layout we used was quite simple. The most interesting bits follow.

First, we want each page to be able to set their own HTML title. This is accomplished by including the following code in the layout:-

<head>
  <title><%= yield :title %></title>
</head>

Then pages must include this line to set the contents of the :title variable:-

<% content_for :title do %>Announcements - dradis<% end %>

Other than that, we used the standard @content_for_layout in the main section of the page. However, the site has two menus, one in the top and one in the right hand side. This exposes a new challenge because we need to create the structure of the page in a way that is simple enough to maintain and add new content in the future. We had to code some Rails helpers to aid us in this.

The Helpers

The Top Menu

The Top menu bar consists only of the main sections of the site. In the layout we call the Helper straight away passing the current page (see The Controller above):

<div class="bar">
<ul>
  <%= barmenu(@page); %>
</ul>
</div>

The code of the helper in this instance is quite simple. The only intelligence we are adding is a check to see if the current page is one of the items in the menu, if it is, we add the CSS active class to the list item.

  def barmenu(page)
    items = ['download', 'demo', 'screenshots', 'documentation' ]
    items.collect do |i|
      active = ''
      label = i.capitalize
      if (page == i)
        active = ' class="active"'
      else
        label = "<a href=\"#{i}.html\">#{i.capitalize}</a>"
      end
      "<li#{active}>#{label}</li>"
    end
  end

Right Hand Side Navigation

The navigation menu in the right side was a bit trickier. We had our pages organised in three different sections: using dradis, developing dradis and support from.

Each section contains a number of items, some of the items have our content, some are links to external sites. In addition to this it would be useful if we could nest subsections as shown in the screenshot of the right.

So we had to figure out a way of representing the structure of the menu. Probably the neatest solution would have been to create an HTML page that contained a series of nested ul and li elements and then make the helper parse that structure assign the active CSS class to the right element and display it. Or maybe using a fancy JavaScript trick to locate the active item and assign the CSS class. However, as often happens we needed a solution, and it had to be fast, so we opted for having the structure loaded in a ruby array with one Hash per section:

$sections = [
  { ... }, # using dradis
  {
    :title => 'developing dradis',
    :pages => [
      {
        :title => 'info. for developers',
        :url => 'developers.html',
        :pages => [ :extensions ]
      },
      :roadmap,
      {
        :title => :bug_tracker,
        :url => 'http://sourceforge.net/tracker/?atid=1010917&group_id=209736&func=browse'
      },
      {
        :title => :feature_requests,
        :url => 'http://sourceforge.net/tracker/?atid=1010920&group_id=209736&func=browse'
      },
      {
        :title => :subversion,
        :url => 'http://sourceforge.net/svn/?group_id=209736'
      }
    ]
  },
  { ... } # support from
]

Each of the three section Hashes has a :title and a :pages attribute. The latter is an array containing the information of the pages associated with the parent section. The elements of the array can be either Symbols or new Hashes that describe the different pages.

We use a Symbol if the content of the page is provided by the site such as in the :roadmap case whose contents are in /app/views/pages/roadmap.html.erb and the link displayed in the menu would be “roadmap”. In more complex cases (i.e. we want a custom title for the link or a section that contains subsections) we use a Hash.

When a Hash is used at least a :title and a :url elements must be provided. Optionally a :pages element can be used to nest sections inside sections. The format of this :pages value is again an array as the one used in the top level section. So there you have your recursion!

The helper in this case is a bit more complex. First, the call in the layout, nothing fancy here:

<div>
  <%= rightmenu(@page) %>
</div>

The rightmenu() helper code:

def rightmenu(page)
  $sections.collect do |section|
    "<h3>#{section[:title]}:</h3>" + sectionmenu(:page => page, :section => section)
  end
end

Each main section is enclosed in h3 tags and then sectionmenu (a helper-to-the-helper method ) is invoked for each section. There are some tricks going on in the following piece of code, have a look and we will nail it down later:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

  def sectionmenu(options = {})
    current_page = options[:page]
    section = options[:section]
    level = options.fetch(:level, 0)
    css = options.fetch(:css, ['right_articles'])
    css |= ["submenu#{level}"] if (level > 0)
 
    section[:pages].collect do |page|
      # If the last item was the active one, clear the flag
      css.delete('active') if css.include?('active')
      title = ''
      url = ''
      complex = false
 
      # simple page (Symbol) vs. complex page (Hash)
      if (page.class == Hash)
        complex = true
        title = page[:title].to_s.gsub(/_/,' ')
        url = page[:url]
      else
        title = page.to_s.gsub(/_/,' ')
        url = page.to_s + '.html'
      end
 
      # active vs. inactive
      if (current_page + '.html' == url)
        css << 'active'
      else
        title = "<a href=\"#{url}\">#{title}</a>"
      end
 
      # subsections
      # tradeoff: calculate the sub section,
      # if it doesn't contain the "active" page, don't use it
      subsection = ''
      if (complex && page.key?(:pages))
        subsection =  sectionmenu(
            :page => current_page,
            :section => page,
            :level => level + 1
        )
 
        found = !(/active/ =~ subsection).nil?
        if ( !found && !css.include?('active') )
          subsection = ''
        end
      end
 
      "<div class=\"#{css.join(' ')}\">#{title}</div>" + subsection
    end.join
 
  end

In lines 2 to 6 we initialise the properties for this section. Then for each page in the section we apply the loop in 8 to 51. Due to the way the data is structured in the $sections variable, this code can be used to recursively crawl the tree of sections and subsections.

For each page in the section:

• we initialise the internal variables (9 to 13). If the page is a Hash we extract the title and URL for the link from it’s elements, if it is a Symbol we infer the title and link from the symbol name.
• Then we check if the current page in the iteration is the active one (26 to 30). If it is, we add a CSS attribute to the item, if it is not, then we add a hyper-link to it (it would not make sense to have a link to the page if you are already in it).
• Finally in 36 to 47 we check if there is a :pages element in the Hash and if there is one, we make a recursive call to render the subsection.

Two things need to be said about the above piece of code. First, each subsection will be assigned a CSS class in accordance to it’s level: submenu1, submenu2, etc. This will allow us to style the different subsections appropriately. And second, because there is no easy way of knowing if the active belongs to one of the sub sections of the current section we make the recursive call, and then see if we have found the active page. If we have not, we discard the subsection altogether. We want this behaviour of not displaying a subsection in the menu unless the user is already in that section and this was the easiest way of implementing it.

The Bread Crumbs

The bread crumbs help our users to know where they are in the site (see picture in the right sid). We need to have a flexible helper that would display the path the user has followed to get into the page they are at the moment. Below is the code of the layout, just above the main content and with a check to verify that we are not in the main page:

<div class="left">
  <% if @page != 'index' %>
  <div id="breadcrums">
    <ul>
      <%= breadcrumsmenu(:page => @page) %>
    </ul>
  </div>
  <% end %>
  <%= @content_for_layout %>
</div>

And again, this helper will use the $sections as discussed above.

  def breadcrumsmenu(options={})
    crums = []
    $sections.each do |section|
      options[:section] = section
      crums = breadcrums(options)
      break if (crums.size >1)
    end
    this_page = crums.pop
    (crums.collect do |c| "<li><a href=\"#{c[:url]}\">#{c[:title]}</a>&lt/li&gt"  end).join + "<li>#{this_page[:title]}</li>"
  end

Again a similar tradeoff here, we cycle through all the sections trying to find the active page. We use the breadcrums helper-to-the-helper function to find out if the page is in the given section and then we render the bread crumbs. I realise that the two helper-to-the-helper functions are quite similar (cycle through a section trying to locate the active page), and possibly we could refactor both into a single function that does thing. But then again, once it worked, we did not have too much spare time to look into it, so we may improve it in the future, but this is the solution we came up with at that point. The code of breadcrums() is very similar in structure to the code in sectionmenu() but this time, it returns an array of pages that will lead us to the active one:

  def breadcrums(options={})
    current_page = options[:page]
    section = options[:section]
    crums = options.fetch( :crums, [ {:title => 'home', :url => '/'} ])
 
    section[:pages].each do |page|
      title = ''
      url = ''
      complex = false
      found = false
 
      if (page.class == Hash)
        complex = true
        title = page[:title].to_s.gsub(/_/,' ')
        url = page[:url]
      else
        title = page.to_s.gsub(/_/,' ')
        url = page.to_s + '.html'
      end
 
      if (current_page + '.html' == url)
        found = true
        crums << { :title => title, :url => url }
      end
 
      if (!found && complex && page.key?(:pages))
        subsectioncrums = breadcrums(
          :page => current_page,
          :section => page,
          :crums => [{:title => title, :url => url}]
        )
        if (subsectioncrums.size > 1)
          crums += subsectioncrums
        end
      end
 
      break if (crums.size > 1)
    end
    return crums
  end

Finishing Touch

Finally, to generate the static pages that we could compress and upload to the server, some good old wget magic was used:

<br />
wget -m -nH http://localhost:3000/<br />