Module Tutorial: User Polling / Rating: Creating the module

Modules in Webva live in the RAILS_ROOT/vendor/modules directory - they are essentially standard rails engines plugins the have a special structure to allow them to register themselves with Webiva and let the CMS know about additional functionality they can add.

The first step is to create module directory and basic scaffold for a module. Luckily there is a custom Webiva generator that handles this for us. We’re going to create a module call PollDemo. From the Rails root directory run the following command:

  $ ./script/generate webiva_module PollDemo

The generator should then run and the output should look similar to below:

  create  /vendor/modules/poll_demo
  create  /vendor/modules/poll_demo/init.rb
  create  /vendor/modules/poll_demo/app/controllers/poll_demo
  create  /vendor/modules/poll_demo/app/models
  create  /vendor/modules/poll_demo/app/views/poll_demo/admin
  create  /vendor/modules/poll_demo/app/controllers/poll_demo/admin_controller.rb
  create  /vendor/modules/poll_demo/app/views/poll_demo/admin/options.rhtml

Once the generator has run you’ll need to restart your rails server so that it can add the new module to it’s load path, so a quick (assumming a phusion install):

  $ touch tmp/restart.txt

should do the trick.

Jump into the backend in a development domain and go to Options -> Modules. You should see the PollDemo module there. Make sure the backgroundrb process has been started and then click ‘Active’ to activate the module. The initializing page should reload a couple of times and then you should be presented with the ‘Poll Demo Options’ page, which currently only displays a ‘Save’ button. We’ll get to the options page in a second so don’t click ‘Save’ yet.

What the generator has done for us is create the ‘poll_demo’ module directory in ./vendor/modules along with some other necessary directories. It has also created a module admin_controller.rb - this is an administrative (meta-)controller that defines module-level configuration and controls how the module interacts with Webiva. The webiva module system follows the rails convention. As such admin_controller.rb is located in ./vendor/modules/poll_demo/app/controllers/poll_demo/admin_controller.rb.

While not strictly necessary, it also defines an options method inside of admin_controller.rb which can be used to set some module-level options. Since admin_controller.rb is pretty dense with Webiva-specific functionality - let’s quickly go through the file line-by-line to cast some light on whats going on.

Let’s start with the top of the file:

 1
 2  class PollDemo::AdminController < ModuleController
 3
 4     component_info 'PollDemo', :description => 'PollDemo support', 
 5                     :access => :public
 6
 7     # Register a handler feature
 8     register_permission_category :poll_demo, "PollDemo" ,"Permissions related to PollDemo"
 9
 10    register_permissions :poll_demo, [ [ :manage, 'Manage Poll Demo', 'Manage PollDemo' ],
 11                                     [ :config, 'Configure Poll Demo', 'Configure PollDemo' ]
 12                                     ]
 13
 14    cms_admin_paths "options",
 15                     "PollDemo Options" => { :action => 'index' }
 16
 17    permit 'poll_demo_config'

The first thing you’ll notice - on line 2 - is the class definition. First of all it’s namespaced inside of the module “PollDemo”, secondly it doesn’t inherit from ApplicationController or from ActionController::Base. Rather it inherits from a class called ModuleController. This is the controller class you should use for any management interfaces that you create in Webiva. The controller class hierarcy in Webiva goes like this:

  ModuleController - Admin Controller in modules
  CmsController    - Admin Controllers in core system
  ApplicationController - Base Controller
  ActionController::Base  - Rails Base

While the RDoc for CmsController and ApplicationController will be helpful in seeing all the functionality that is available in ModuleController the only controller class that you will derive from for a standard administrative controller is ModuleController.

After the class name, there’s a number of class level declarations that register different functionality into Webiva. The first one - on line 4 - component_info, gives the system some information about the module itself, specifically a description and an access level. By setting the access level to public, the module will automatically appear in the list of modules in Options -> Modules. If we set the access level to :private we would need to first enable access to the module on the domain we’re using from System -> Domains -> < Click on domain name >

Next (line 8) we are going to register a permissions category - which is a separate tab that appears in Options -> Permissions. This method takes a permission prefix symbol, a human name for the permission category and a description. Here these have been auto-generated by the generator but it’s probably worth putting in something more descriptive in general.

Once the permission category is registered, we can register individual permissions for this module - the register_permission method takes a prefix symbol, (:poll_demo in our case) and an array of permissions, each an array consisting of [:permission_symbol, 'Permission Name', 'Permission Description']. By default the generator creates two permissions - :config: and :manage - which generally refer to permission to configure the module and manage it’s backend functionality.

Next up is the cms_admin_paths (line 14) command. This method defines the page paths that will be used in the controller. In our case the only page path is the ‘Poll Demo Options’ page. The first argument is the section that the controller is on (the module configuration page is under ‘options’ in this case), while the last argument is a hash with each element of the form:

     "Page Name" => { :url_for_argument => :value }

The :url_for_argument => :value hash is a hash that could be passed to url_for to generate a routing.

Finally line 17 contains a permit call which takes a permission string of who is allowed to access this controller. This string is a combination of a prefix and the :config permission that was defined above. What this means is that only editors with the ‘poll_demo_config’ permission will be allowed to edit the options for this module.

The remainder of the controller defines the options action which displays and updates any module level options as well as a class method for retrieving the options and the Options class itself. Because this class is nested inside of PollDemo::AdminController it’s actual name is PollDemo::AdminController::Options. It inherits from the HashModel class, which is a common class inside of Webiva for configuration options - it is stored in the database as a serialized hash which means that making changes to a HashModel doesn’t require any database changes.

The available options in a HashModel are set using the attributes class method. That method takes a hash with attributes of the form:

 :attribute_name_1 => "Default Value", :attribute_name_2 => "Default Value 2"

All attributes are assumed to be strings by default, but if you would like them to be typed as something differently, you can use a method like integer_options :attribute_name_1 to have them cast as integers when they are saved. See the RDoc for HashModel for more informations.

Let’s add a default configuration option called ‘default_poll_name’ that we’ll use later on. Update the definition of the Options hash model to:

  class Options < HashModel
     attributes :default_poll_name => 'Enter a Question Name'
     validates_presence_of :default_poll_name
  end

Now let’s update the options form itself. Open up the file: /vendor/modules/poll_demo/app/views/poll_demo/admin/options.rhtml and you’ll see just the skeleton of a form template. Let’s add in a text field on line 3 inside of the admin_form_for tag before the submit_tag:

 <%= f.text_field :default_poll_name %>

Now save the template and reload the “Poll Demo Options” page an you the option should appear. Go ahead an click ‘Save’ and you should be returned to the ‘Modules’ page with the “PollDemo” module now active.