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!

The final goal is to have an automated process to generate fresh static copy of the site and to upload it to the subversion repository. Although more advanced solutions exist (i.e. Capistrano), I used a 22 line Rake script for dradisframework.org. There are two tasks:-

• prepare: uses wget to generate a static copy of the site in the ./out/ directory.
• commit: commits the changes in the ./out/ directory to the subversion repository.

You would only need to synchronise your web server document root with the ./out/ directory of the subversion.

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

desc 'Prepare the static site in the ./out/ directory'
task :prepare  do
  Dir.mkdir('out') unless File.exist?('out')
  Dir.chdir('out') do
    `wget -m -nH http://localhost:3000`
  end
  `rsync -ruv --exclude=.svn/ --exclude=dispatch* --exclude=500.html --exclude=422.html public/ out/`
end
 
desc 'Prepare the static site and commit the changes to the svn repo.'
task :commit => :prepare do
  # Display the messages as they come, don't buffer
  STDOUT.sync = true
 
  # Subversion operations
  print "Adding the output directory (out/) to subversion... "
  `svn add --force out`
  puts "done."
  print "Commiting... "
  `svn commit out -m "New static site content #{DateTime.now().to_s}"`
  puts "done."
end

The only little trick here is the use of rsync in line 7. We want to make sure that everything we have in the ./public/ directory will also be in the static copy of the site. This includes flash videos, demos, full-size screenshots, etc. Using the --exclude parameter we prevent the copy of some files that won’t be required in the production environment.

Every time we want to generate a fresh copy of the site and send it to the subversion repository we will only need to run:-

rake commit

And now we are done for good, from a Rails application in our laptop to a static site in the web server in a couple of lines!

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.

• Make one of the components compulsory to install.
• We will look at a way to write our script in such a way that it can be reused for future releases of MyApplication.
• A few extra tips and tricks.

Making a component compulsory
At the end of Part 2 we added the components page to our installer. The component page gives the user the option to select which components he want to install. However, we want the installer not to give the user the option to not install MyApplication component but to make the installation of MyApplication when executing the script. We use the SectionSetFlags method to achieve this. SetSectionFlags allows you to set certain attributes of a section (component to be installed). We add the following code:

Function .onInit
  IntOp $0 ${SF_SELECTED} | ${SF_RO}
  SectionSetFlags ${SEC03} $0
FunctionEnd

• You will recall from Part 1 that the .onInit function is called on initiating the script.
• The SectionSetFlags method sets first 8 bits of the section’s flags. We are interested in the first bit (setting a sections and selected) and the fifth bit (setting a section as read only)
• To achieve this we use the SF_SELECTED and the SF_RO constants that are equal to 1 and 16 respectively.
• When we OR these to constants together we end up with a value of which the first and the fifth bit are set (line 2).
• In line 3 we use the SectionSetFlags method to apply the result of the OR to SEC03 which is our MyApplication component.
• The result is that the MyApplication component will be selected and read only on the components page of the installer.

Making our script usable for the future
I might happen that we want to release a new version of MyApplication that requires a new installer. The new version might have the same requirements but a few new files might be added that now needs to be added to the installer. If the install section of MyApplication gets very big (depending on the size of MyApplication) it can be a daunting task to review all the SetOutPath “$INSTDIR\my_folder” and File “application_files\myapplication.rb” type calls. It will be great if we can automate the creating of these calls.

I have created the following Ruby script that receives as commandline argument the folder in which MyApplication lives and the creates a text file that contains the instruction set that we need in the MyApplication section:

require 'fileutils'
include FileUtils::Verbose
 
def recursive_folder_dump(folder, install_file, uninstall_file, relative_path)
  cd(folder) {
    folders = []
    Dir.foreach('.\\') { |inner_file|
      if File.directory?(inner_file) && inner_file != '.' && inner_file != '..'
        folders << inner_file
      elsif inner_file != '.' && inner_file != '..'
        install_file.puts "File \"" + relative_path + inner_file + "\""
        uninstall_file.puts "Delete \"$INSTDIR\\" + relative_path + inner_file + "\""
      end
    }
    folders.each { |folder|
      install_file.puts "SetOutPath \"$INSTDIR\\" + relative_path + folder + "\""
      recursive_folder_dump(folder, install_file, uninstall_file, relative_path + folder + "\\")
      uninstall_file.puts "RMDir \"$INSTDIR\\" + relative_path + folder + "\""
    }
  }
end
 
if ARGV[1] == nil
  puts 'usage: ruby nsis_folder_dump.rb  '
  puts 'where:'
  puts ' - is the folder/file structure to be dumped'
  puts ' - will be used to create the output file names: _install.nsi and _uninstall.nsi'
  exit
end
 
if !File.exists?(ARGV[0])
  puts ARGV[0] + " is not an existing folder"
  exit
end
 
install_file = File.new(ARGV[1]+"_install.nsh",'w')
uninstall_file = File.new(ARGV[1]+"_uninstall.nsh",'w')
 
install_file.puts "SetOutPath \"$INSTDIR\\" + ARGV[0] + "\""
recursive_folder_dump(ARGV[0], install_file, uninstall_file, ARGV[0] + "\\")
uninstall_file.puts "RMDir \"$INSTDIR\\" + ARGV[0] + "\""
 
install_file.close

The above script will create two files. Depending on the commandline parameters they might be myapplication_install.nsh and myapplication_uninstall.nsh.

NSIS allows us to include these files in our script with the !include. We change the MyApplication install section to look like this:

Section "MyApplication" SEC03
  !include "myapplication_install.nsh"
SectionEnd

And we add the following to the top of our Uninstall section:

!include "myapplication_uninstall.nsh"

We can now keep our NSIS install script the same for all future releases of MyApplication and just generate new myapplication_install.nsh and myapplication_uninstall.nsh files.

A few more tips and tricks
MyApplication has a database the can be initialised by a rake task. We can run this rake task at the end of a successful installation. We achieve that with the following code:

!define MUI_FINISHPAGE_RUN_TEXT "Initialise the database"
!define MUI_FINISHPAGE_RUN "$0\bin\rake.bat"
!define MUI_FINISHPAGE_RUN_PARAMETERS "-f $\"$INSTDIR\server\Rakefile$\" db:migrate"

On uninstall files and folders can be removed by the Delete and RMDir methods. If you want to delete a whole folder recursively its contents you can use the /r directive:

RMDir /r "$INSTDIR\my_application"

And that brings us to the end of Part 3.

• Ruby (the target machine that our application is installed on requires Ruby)
• MyGem (our application is dependent on this fictitious gem)
• MyApplication (this is our application to be installed)

In this part we will look at how we will let the installer take care of the Ruby and MyGem components.

To start off, place the following at the top of your code:

!include LogicLib.nsh

This includes the LogicLib library and allow us to write more readable code by providing us some macros to write traditional logical structures for example IF and CASE structures

Ruby

Our application needs Ruby to be installed on the target machine. In the case that Ruby is not installed on the machine we want to relieve the user from having to install Ruby separately. Instead we want to install it for him.

In the example in Part one we replace the code:

Section "Ruby" SEC01
SectionEnd

with (we will go through this in detail):

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

Section "ruby" SEC01
  ; read the registry to check if there is not already a local installation of ruby
  readRegStr $0 HKLM "SOFTWARE\RubyInstaller" Path
  ${If} $0 != ''
    ; ruby installed
    MessageBox MB_OK 'Ruby is already installed on the system. The automated installation of Ruby will not proceed'
  ${Else}
    ; no ruby installer
    MessageBox MB_OK 'The ruby installer will now be downloaded and executed. This might take a few moments.'
    ; download and install ruby
    NSISdl::download /NOIEPROXY "http://rubyforge.org/frs/download.php/29263/ruby186-26.exe" "ruby186-26.exe"
    Pop $R0
    ${If} $R0 == 'success'
      ; ruby download successful
      StrCpy $0 ''
      ; rum the one click installer
      ExecWait '"ruby186-26.exe"' $0
      ${If} $0 == ''
        ; execution of one click installer failed
        MessageBox MB_OK "Ruby install failed. Please install Ruby manually"
      ${EndIf}
      ; delete the ruby one click installer
    ${Else}
      ; ruby download not successfull
      MessageBox MB_OK "Ruby download failed. Please download and install Ruby manually"
    ${EndIf}
    Delete "ruby186-26.exe"
  ${EndIf}
SectionEnd

Lets go through the code in detail

• We make the assumption that if Ruby is installed on the system that there will be a registry entry for the installation. We check for this registry entry with the readRegStr command (line 3).
• If we find an entry in the registry we prompt (MessageBox) this to the user and we do not proceed with the Ruby installation (line 6).
• If Ruby is not installed we notify the user that the installer will download the Ruby one-click installer and then proceed with the download (NSISdl::download, line 11)
• A successful download will place the success string on the stack. We Pop the top value from the stack and store in $0 (line 12).
• The installer inspects $0 and is the download was successful it proceeds to running the Ruby one-click installer (ExecWait, line 17)
• The return value of the one-click installer is inspected to determine a successful install. In the case of failure this is prompted to the user (lines 18-20).
• Towards the end of the script we handle the case of a failed download (lines 23-25).
• Finally the installer deletes the downloaded one-click installer (Delete, line 27)

MyGem

The installer needs to take care of the installation of our required gem, MyGem. To minimize the insteraction between the user and the installation process the installer installs the gem from a file in the installation package. This file contains the gem for local install.

Once again refering to the example in Part 1 one, we replace the code:

Section "MyGem" SEC02
SectionEnd

with:

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

Section "MyGem" SEC02
  SetOutPath "$INSTDIR\client"
  File "my_gem-x86-mswin32-60.gem"
  # check if ruby is installed and install the mygem gem locally if so
  readRegStr $0 HKLM "SOFTWARE\RubyInstaller" Path
  ${If} $0 != ''
    ; ruby installed
    StrCpy $1 ''
    ; install the mygem locally
    ExecWait '"$0\bin\gem.bat" install my_gem-x86-mswin32-60.gem' $1
    ${If} $1 == ''
      MessageBox MB_OK "Gem install failed. Please install the MyGem gem manually"
    ${EndIf}
  ${Else}
    ; ruby not installed
    MessageBox MB_OK "Ruby is not installed. Please install ruby and then run the installer again or install the MyGem gem manually"
  ${EndIf}
  Delete "my_gem-x86-mswin32-60.gem"
SectionEnd

By now you should be able to follow the code quite easily. I will just highlight to things:

• Yet again we have to check if Ruby is installed on the target machine (line 5).
• Note that you have to give the full path to the gem batch file when triggering the gem installation (line 10).

Choosing Components

You might what to give you users the option to choose the components that they want to install. The modern user interface makes it really easy for you.

Add the following to your script below !insertmacro MUI_PAGE_COMPONENTS:

!insertmacro MUI_PAGE_COMPONENTS

And at the end of all your section code add:

!insertmacro MUI_FUNCTION_DESCRIPTION_BEGIN
  !insertmacro MUI_DESCRIPTION_TEXT ${SEC01} "Installs ruby. The installer will download the ruby one click installer and execute. Alternatively you can install ruby manually."
  !insertmacro MUI_DESCRIPTION_TEXT ${SEC02} "Installs the MyGem gem. The gem requires ruby to be installed."
  !insertmacro MUI_DESCRIPTION_TEXT ${SEC03} "Installs the MyApplication."
!insertmacro MUI_FUNCTION_DESCRIPTION_END

I am going to leave it at that. In Part 3 we will look at you can make certain components compulsory, how we can write our script so that we can also use it for future releases of MyApplication and a few extra tips and tricks to clean up the script.

Happy coding!

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 />

I am using HM NIS editor and IDE for NSIS to make the task a little easier. To get out of the blocks a little quicker I used the HM NIS wizard to create a simple framework from where I will progress.

The wizard allows you to install different components (groups). These are typically different parts of your application and dependencies that needs to be installed. I created the following components:

• Ruby (this will download and install the Ruby one-click installer if ruby is not installed)
• MyGem (this will install the the required gems)
• MyApplication (this will install my application)

The wizard also lets you pick a GUI type. I picked modern. You can choose between modern, classic or none.

The script generated by the wizard will look something like the following (do not bother to read it all right now, I will go into detail for some parts of it):

; Script generated by the HM NIS Edit Script Wizard.
 
; HM NIS Edit Wizard helper defines
!define PRODUCT_NAME "My application"
!define PRODUCT_VERSION "1.0"
!define PRODUCT_PUBLISHER "My company, Inc."
!define PRODUCT_WEB_SITE "http://www.mycompany.com"
!define PRODUCT_UNINST_KEY "SoftwareMicrosoftWindowsCurrentVersionUninstall${PRODUCT_NAME}"
!define PRODUCT_UNINST_ROOT_KEY "HKLM"
 
; MUI 1.67 compatible ------
!include "MUI.nsh"
 
; MUI Settings
!define MUI_ABORTWARNING
!define MUI_ICON "${NSISDIR}ContribGraphicsIconsmodern-install.ico"
!define MUI_UNICON "${NSISDIR}ContribGraphicsIconsmodern-uninstall.ico"
 
; Welcome page
!insertmacro MUI_PAGE_WELCOME
; License page
!insertmacro MUI_PAGE_LICENSE "c:pathtolicenceYourSoftwareLicence.txt"
; Directory page
!insertmacro MUI_PAGE_DIRECTORY
; Instfiles page
!insertmacro MUI_PAGE_INSTFILES
; Finish page
!insertmacro MUI_PAGE_FINISH
 
; Uninstaller pages
!insertmacro MUI_UNPAGE_INSTFILES
 
; Language files
!insertmacro MUI_LANGUAGE "English"
 
; MUI end ------
 
Name "${PRODUCT_NAME} ${PRODUCT_VERSION}"
OutFile "Setup.exe"
InstallDir "$PROGRAMFILESMy application"
ShowInstDetails show
ShowUnInstDetails show
 
Section "Ruby" SEC01
SectionEnd
 
Section "MyGem" SEC02
SectionEnd
 
Section "MyApplication" SEC03
SectionEnd
 
Section -AdditionalIcons
  SetOutPath $INSTDIR 
  WriteIniStr "$INSTDIR${PRODUCT_NAME}.url" "InternetShortcut" "URL" "${PRODUCT_WEB_SITE}"
  CreateDirectory "$SMPROGRAMSMy application"
  CreateShortCut "$SMPROGRAMSMy applicationWebsite.lnk" "$INSTDIR${PRODUCT_NAME}.url"
  CreateShortCut "$SMPROGRAMSMy applicationUninstall.lnk" "$INSTDIRuninst.exe"
SectionEnd
 
Section -Post
  WriteUninstaller "$INSTDIRuninst.exe"
  WriteRegStr ${PRODUCT_UNINST_ROOT_KEY} "${PRODUCT_UNINST_KEY}" "DisplayName" "$(^Name)"
  WriteRegStr ${PRODUCT_UNINST_ROOT_KEY} "${PRODUCT_UNINST_KEY}" "UninstallString" "$INSTDIRuninst.exe"
  WriteRegStr ${PRODUCT_UNINST_ROOT_KEY} "${PRODUCT_UNINST_KEY}" "DisplayVersion" "${PRODUCT_VERSION}"
  WriteRegStr ${PRODUCT_UNINST_ROOT_KEY} "${PRODUCT_UNINST_KEY}" "URLInfoAbout" "${PRODUCT_WEB_SITE}"
  WriteRegStr ${PRODUCT_UNINST_ROOT_KEY} "${PRODUCT_UNINST_KEY}" "Publisher" "${PRODUCT_PUBLISHER}"
SectionEnd
 
Function un.onUninstSuccess
  HideWindow
  MessageBox MB_ICONINFORMATION|MB_OK "$(^Name) was successfully removed from your computer."
FunctionEnd
 
Function un.onInit
  MessageBox MB_ICONQUESTION|MB_YESNO|MB_DEFBUTTON2 "Are you sure you want to completely remove $(^Name) and all of its components?" IDYES +2
  Abort
FunctionEnd
 
Section Uninstall
  Delete "$INSTDIR${PRODUCT_NAME}.url"
  Delete "$INSTDIRuninst.exe"
 
  Delete "$SMPROGRAMSMy applicationUninstall.lnk"
  Delete "$SMPROGRAMSMy applicationWebsite.lnk"
 
  RMDir "$SMPROGRAMSMy application"
 
 
 
  DeleteRegKey ${PRODUCT_UNINST_ROOT_KEY} "${PRODUCT_UNINST_KEY}"
  SetAutoClose true
SectionEnd

The first thing to get you head around here is the general layout of a NSIS script and how this maps to the final installer. For a thorough read on this refer to section 2.3 Scripting structure in the NSIS User Manual. As a brief overview:

• Compiler commands
  The instructions that start with ! (exclamation mark) are compiler commands. These commands are executed on compile time.
• Installer attributes
  Close to the top of your script you will note a few installer attributes that are defined. For example:

  Name "${PRODUCT_NAME} ${PRODUCT_VERSION}"
  OutFile "Setup.exe"
  InstallDir "$PROGRAMFILESMy application"

  These attributes are used and referenced later in the installation process

• Installer pages
  A non silent installer consist of different pages. These pages will mostly be taken care of by the GUI interface that you picked. The predefined GUI pages that are used are specified by the !insertmacro directives. For example:

  !insertmacro MUI_PAGE_WELCOME

  specifies that the modern GUI’s welcome page should be inserted.

• Sections
  You will note that chunks of the script are wrapped by the Section and SectionEnd directives. These mostly correspond to different components of your application to be installed.
  In my example you will note sections for Ruby, MyGem and MyApplication. You will also notice some sections that start with un. These sections are called during uninstall.
  The code inside a section are executed on the machine that the installer is being run on. Sections are executed in the order as they appear in the code.
• Functions
  Functions are pieces of script code that are called either from within sections by using Call functionName or they are called at different points in the script execution as Callback functions. For example .onInit will be called when the installer is initiated.

When you defined your application’s different components in the wizard you were allowed to specify the different files that should be installed. These files are referenced in the install and uninstall sections. In the install sections you will note something similar to:

SetOutPath "$INSTDIRmy_folder"
File "application_filesmyapplication.rb"

The first line specifies that what follows after that line (File “application_files\myapplication.rb”) should be applied to the $INSTDIR\my_folder directory. It effectively changes the current directory path. The second line instructs the installer to copy the file located at application_files\myapplication.rb to the current path.

In the uninstall section you will note code that is similar to:

Delete "$INSTDIRmy_foldermyapplication.rb"
RMDir "$INSTDIRmy_folder"

It instructs the uninstaller to delete the file at $INSTDIR\my_folder\myapplication.rb and remove the folder $INSTDIR\my_folder.

I am going to leave it at that. In the next post I’ll describe how I install Ruby and the required gem on running the installer.

In the plugin test folder I created a lib and a fixtures folder. In the lib folder I created two files activerecord_connector.rb and activerecord_test.rb.

acticerecord_connector.rb:

require "rubygems"
require "active_record"
require 'active_record/fixtures'

conf = YAML::load(File.open(File.dirname(__FILE__) + '/../database.yml'))
ActiveRecord::Base.establish_connection(conf['sqlite3'])

This file is required to make a connection to the database that is configured by database.yml that I placed in the test folder.

database.yml:

sqlite3:
  database: ":memory:"
  adapter: sqlite3
  timeout: 500

This specifies a connection to a Sqlite database that is to be kept in memory. It means the database is just alive for the duration of our test - perfect.

activerecord_test.rb

require 'test/lib/activerecord_connector'
require 'test/fixtures/schema.rb'

class ActiverecordTest < Test::Unit::TestCase
  FIXTURES_PTH = File.join(File.dirname(__FILE__), '/../fixtures')
  dep = defined?(ActiveSupport::Dependencies) ? ActiveSupport::Dependencies : ::Dependencies
  dep.load_paths.unshift FIXTURES_PTH
end

The code in this file does the following:

• It requires activerecord_connector.
• Requires a schema.rb file for populating the database.
• Defines the ActiverecordTest class that define and store the path to your fixtures folder.

schema.rb:

ActiveRecord::Schema.define do
  create_table "users", :force => true do |t|
    t.string   "first_name"
    t.string   "last_name"
    t.integer "id"
  end
end

As you can see, this creates the users table in the database.

I created a User model that is stored in the fixtures folder.

user.rb

class User < ActiveRecord::Base
  #this class might be extended by your plugin
end

Also in the fixtures folder is a users.yml file to serve as test content in our database.

users.yml

david:
  id: 1
  first_name: Thomas
  last_name: Black

jamis:
  id: 2
  first_name: Peter
  last_name: Martin

Lastly we have our test file.

hot_plugin_test.rb

require 'test/unit'
require 'test/lib/activerecord_test'

class HotPluginTest < ActiverecordTest

  def setup
    Fixtures.create_fixtures(FIXTURES_PTH, 'users')
  end

  def test_users
    user = User.find(:first)
    assert_equal "Thomas", user.login, "not working!!"
  end
end

• HotPluginTest inherits from ActiveRecordTest.
• The setup method creates the content in our database from the users.yml file.

Now you can extend models that you place in the fixtures folder with your plugin and run tests against them in HotPluginTest.

As I said at the start, this is just a method of doing it - you might have some other ideas. I’ll be happy to hear about them. For another approach you might want to look at Plugin Test Helper.

Happy testing!

My credit to the following posts and plugin for leading to this solution:

• Rails Plugin Testing Guide
• Using ActiveRecord outside Rails
• will_paginate plugin that has a great test example

This is the first of a series of posts with small tips and tricks of ExtJS that will also address its integration with Ruby on Rails.

In this release we are going to create a ComboBox that loads its items from a remote location (potentially a rails REST endpoint).

I wanted to create this series when I started using ExtJS so it could be used as a step-by-step howto of ExtJS and rails, but as sometimes happens, I got carried away with the coding side of things leaving the post writing abandoned :(. That is the main reason why some core concepts of ExtJS development are not included here. The project site, documentation and samples can help with that. Here we are dealing with the real stuff, so lets get it on.

First the code: extjs-comboxml.tar.bz2. I have a local apache for debuging purposes and I uncompressed the ExtJS package in /var/www/ext-2.2/, then I created a test folder inside it. This code should work fine if you uncompress its contents in the test folder. If you have a different environment, adjust the locations of the script tags in the header of combo.html.

This is how it should look like:

So with ExtJS there are two ways of loading combo items from a remote location, it is a bit confusing because these two are called local and remote modes. The difference is that in local mode, the combo is relying on someone else to grab the information and in remote mode the combo itself will make the Ajax call.

No matter what mode we choose, we will need a data store for our items. Here is the code used in the example:

var categories = new Ext.data.Store({
        url: 'categories.xml',
        autoLoad: true, // required for the combo that does not use Ajax
        reader: new Ext.data.XmlReader(
                { record: 'category', id: 'id'},
                [ { name: 'name', type: 'string' } ]
              ),
        listeners: {
          load: function(records, options) {
            console.log( 'loaded ' + records.totalLength + ' records');
          },
          loadexception: function(proxy, options, response, error) {
            console.log('error loading records from server:');
            console.log("\tfile: "+error.fileName);
            console.log("\tline: "+error.lineNumber);
          }
        }
      });

The listeners in the code above are just for debuging purposes and can be removed safely. The only interesting bit is the autoLoad option, but we will come back to that later. For now it is enough to say that the Store above will read an XML document with this structure:

<?xml version="1.0" encoding="UTF-8"?>
<categories type="array">
<category>
<id type="integer">1</id>
<name>default category</name>
</category>
<category>
<id type="integer">2</id>
<name>security risk</name>
</category>
</categories>


The autoLoad config options determines if the data store will try to load the values from the provided url upon creation or if it will be necessary to call the load(). This is useful when we are working in local mode, let’s see the code for the first combo:

var comboLocal = new Ext.form.ComboBox({
  fieldLabel: 'Select a category',
  store: categories,
  mode: 'local',
  displayField: 'name',
  selectOnFocus: true,
  emptyText: 'No Ajax in the combo...'
});

Above we specified local this means that options for this combo will be loaded from the categories store. The data store is expected to be populated already, this can be done either by specifying the autoLoad option as described above or by calling the load().

If you rather have you combo performing the Ajax request, then the code you need to use is:

var comboRemote = new Ext.form.ComboBox({
  fieldLabel: 'Select a category',
  store: categories,
  displayField: 'name',
  triggerAction: 'all',
  selectOnFocus: true,
  emptyText: 'Options loaded using Ajax...'
});

There is no need to include mode: 'remote' because is the default behaviour, here the trick is to include the triggerAction: 'all', otherwise the Ajax request will never be executed.

So that was it, short and simple, stay tuned for the next one