Module Tutorial: User Polling / Rating: Backend Interface - Create a Poll

In order to let site editors add polls to their websites, they’re going to need to be able to create and view polls on their system. So the next step is to add a list of polls into the backend of the site and a way to create and edit polls. While Webiva doesn’t create these interfaces for you automatically, it does make them fairly quick to write with two library classes: active_table and admin_form. The former provides a quick way to create searchable, sortable, and paginated tables while the latter helps to build quick administration forms.

The existing management controllers inside of Webiva are generally not REST-fully built, but are built on the traditional :controller/:action:/:path interface. The advantage of this is that the system doesn’t need to keep track of a ton of routes for each of the management interfaces, but if you want to add a specific set of routes for your module to make it REST-ful, you can create a routes.rb file. See the documentation on routes.rb for more details.

Creating the controller

Let’s create a new file called manage_controller.rb. This will be our poll management controller. Put the following code into that file, to start stubbing out the functionality we need:

vendor/modules/poll_demo/app/controllers/poll_demo/manage_controller.rb

  class PollDemo::ManageController < ModuleController      

    component_info 'PollDemo'     
    permit :poll_demo_manage
  
    cms_admin_paths "content",
     "Poll Demo" =>  {:action => 'index'}
  
    def index
      cms_page_path ["Content"], "Poll Demo"
    end      
  end

You’ll notice a lot of similarities between this controller and PollDemo::AdminController, discussed in the first step of this tutorial. Both of them inherit from ModuleController and both have calls to component_info, permit and cms_admin_paths. In this case, we can just call component_info without any additional details, just to let this controller know what module we’re in. The call to permit is also slightly different as we want anyone with the :poll_demo_manage permission to be able to access this controller. The cms_admin_paths tells the system this controller is under the content tab and it currently only registers one page, ‘Poll Demo’. Finally, the index method just has a call to cms_page_path to let us know where in the system we are.

Let’s create a blank view file to show that our index method has something to render. First, you will need to create the directory:

$ mkdir vendor/modules/poll_demo/app/views/poll_demo/manage

Then, put some text in your new view:

vendor/modules/poll_demo/app/views/poll_demo/manage/index.html.erb:

   To Do!

Since we added some new paths, let’s restart rails so it’ll find the new controller and views:

   $ touch tmp/restart.txt

If you go to the URL http://yourwebsitehere.com/website/poll_demo/manage, you should see a blank page like the one below:

Adding a content model to the content page

Before we go further along in the management controller, we need to do a little housekeeping so that we can access the poll management interface from the content tab of the site.

Let’s edit the PollDemo::AdminController file again and add in the following lines around line 19 (the location actually doesn’t matter):

vendor/modules/poll_demo/app/controllers/poll_demo/admin_controller.rb

 content_model :polls

 def self.get_polls_info
   [ { :name => 'Poll Management', 
       :permission => :poll_demo_manage,
       :url => { :controller => 'poll_demo/manage' } 
    } ]
 end

What this does is tell the system that when it displays the content page, it should show a block named “Poll Management” to all users with the :poll_demo_manage permission. If you click on the content tab, you’ll see that new block that will take you directly to your controller.

Creating a new poll

Before we get in to the details of creating a table, let’s create the poll edit form to make it easier to add some data into the system. Let’s add an edit method into the ManageController after the index method:

vendor/modules/poll_demo/app/controllers/poll_demo/manage_controller.rb

    def edit
      @poll = PollDemoPoll.find_by_id(params[:path][0]) || PollDemoPoll.new
      cms_page_path ["Content","Poll Demo"], 
          @poll.new_record? ? "Create a Poll" : ["Edit %s",nil,@poll.name]
  
      if request.post? && params[:poll]
        if !params[:commit] 
          redirect_to :action => 'index'
        elsif @poll.update_attributes(params[:poll])
          flash[:notice] = 'Saved Poll'
          redirect_to :action => 'index'
        end
      end
    end

This edit method will handle both creating new polls and editing existing ones. The logic is relatively simple - look for a poll by ID, otherwise create a new PollDemoPoll object.

In the next line, we set the breadcrumbs and title of the page to either “Create a Poll” or “Edit Poll Name Here”. The latter part is worth reviewing. The system will automatically try to translate the text in the title, so instead of passing “Edit Poll Name Here”, we pass a translatable string combined with a “%s”, which will be replaced with a non-translatable value. The format of this array is:

     [ "Translatable String", URL destination, "Non Translatable String" ]

Since in this case we don’t need a URL, the second element of the array is blank. In situations where we want a dynamic value that isn’t in cms_admin_paths, we can pass an array instead of a just a string for each element of the breadcrumbs.

Going back to the edit method, the system then checks if this request is a post with the proper input parameters, and if so, it checks for a params[:commit] argument - this argument is the name of the submit button that is pressed when the user actually submits a form. If it doesn’t find this argument, that means the user pressed on the cancel button, so we should just redirect them back to the index action. If they did press submit, we need to try to save the model with the posted parameters and display a success message on the destination page if everything went fine.

The Poll Form

Now that we’ve got the logic for submitting a form, we’ll need to create a view that displays the form. Webiva has a special form_for called admin_form_for for creating administration forms with as little as effort as possible. (Who likes making forms, after all?) Create a new file called edit.html.erb and put the following form code in there:

vendor/modules/poll_demo/app/views/poll_demo/manage/edit.html.erb

  <div class='admin_content'>
    <% admin_form_for :poll, @poll do |f| -%>
      <%= f.text_field :name, :required => true %>
      <%= f.text_field :question, :required => true %>
      <%= f.text_area :answers_string, :rows => 8, :cols => 40, :required => true,
           :label => 'Answers',
           :description => 'Enter answers, one per line' %>
      <%= f.cancel_submit_buttons 'Cancel','Submit' %>
    <% end -%>
  </div>

admin_form_for will create a styled form with labels and error messages. However, since the form doesn’t actually know anything about the @poll object itself, we do need to tell it which fields are required; in our case, all of them are. (All this does is add an asterisk after the field name.) We can override the default label and add a helpful description by adding :label and :description options where appropriate. In this case, we’ve modified the default label on the :answers_string field and added a description.

Finally, there’s a custom field type called cancel_submit_buttons. This will create two buttons which we can label how we like, however the right button will be the default form action (submitted when a user presses enter in a form) and will be named “commit”, so that our form is submitted correctly based on how we set up our controller.

The last thing you’ll notice is that the entire form is wrapped in an .admin_content <div>. What this does is provide some spacing for the form away from the edges of the page. It’s not added by default because some forms will want to maximize screen real-estate, but most of the time, it’s a good idea (so our designer tells me).

If you restart Rails (you know the drill by now) and head to the /website/poll_demo/manage/edit URL, you should now be able to play with the form. Try submitting the form without the required elements filled in, and you’ll see the error message appear. We now need to connect our creation form to the index page.

Adding an action panel to index

Webiva provides a helper to add ‘call to action’ links at the top of the page, called action_panel. Let’s use it to add a link to our ‘Create a poll’ page. Open up your index.html.erb file and replace it with the following code:

vendor/modules/poll_demo/app/views/poll_demo/manage/index.html.erb

  <% action_panel do |p| -%>
    <%= p.link "Create a new Poll", :action => 'edit', :icon => 'add.gif' -%>
  <% end -%>
  
  <hr/>
  
  <div class='admin_content'>
    Table will go here...    
  </div>

You’ll see that the code creates an action panel and adds a link using the panel builder passed to the block. Action panel links work similarly to link_to calls, except they accept a couple of extra options. You can pass the :icon option to specify an image that goes along with the link. These images are provided by the administration theme - take a look at the /public/themes/standard/images/icons/actions directory for the images that are available.

We can now play around with the interface a little bit, trying out the form and redirect logic. Of course, we don’t yet see any polls that are created, so let’s work on that administration table in the next step.