Item lists

This page documents the way items are listed in the NorfelloCMMS OS.

Current system

Defining fields

The old way to define the list fields is something like this:

    @fields = [
                [_('ID'), :self],
                [_('Type'), :work_order_type_name],
                [_('State'), {:name => :state}.merge(@state_to_text)],
                [_('Description'), :short_description],
                [_('Priority'), {:name => :priority}.merge(@priority_to_text)],
                [_('Responsible worker'), :responsible_user],
                [_('Starting time'), :starting_time],
                [_('Deadline'), :deadline],
                [_('Asset'), :asset]
              ]

Each array inside the @fields array defines one column in the listing. The first item of those arrays defines the name of the column that will be shown in the header row. The second item defines the way the value for that column is retrieved from the actual item instance. The second item behaves differently according to the type of the item. attr_symbol refers to the actual value of the second item.

• Symbol - Try to get the value from an item's attribute called :attr_symbol
• Symbol - Try to get the value by calling the method :attr_symbol on the item
• Array - Try to get the value by calling the method attr_symbol.first on the item, using the rest of the array as arguments.
• Hash - Get the value_name from attr_symbol[:name], then get the initial_value from an item's attribute called :value_name and then transform this value with the hash attr_symbol[initial_value].
• If exception is raised or this point in the list is reached the value is set to '-'.

The actual value visible in the list depends on the class of the value. Strings are displayed like they should be but for example values of the class User, Asset or Attachment will generate links to a user, asset and attachment etc.

Defining the item actions

Actions for each list item are defined like this:

@actions = [ [_('Edit'), {:action=> 'edit', :image=>'16x16/edit'}] ]

Each entry in this array defines an action that can be taken on the particular item. Simple enough.

Defining the list action

List can have one action that can be performed to a multiple list items at once. By default this action is remove but this can be changed. Items are selected with check boxes and the action is performed with a submit button. There are also three helper buttons for selection all or none of the items and inverting the selection.

Improved system

The listing system outlined above will be improved by adding sorting and mass update functions (see #284, #290). This requires some changes to the way the lists are currently defined.

Defining the fields

For each field we need the following information:

• Name of the field (column header)
• Value of the field
• Is this column sortable

Defining the item actions

This doesn't have to be modified. One improvement would be to hide unauthorized actions though.

Defining the list actions

This will have to be changed so that there can more than one action and also the actions will be more complicated.

For each action we need the following information:

• Name of the action
  • Will be shown in the action selection drop-down menu.
• URL for the action {:controller => .., :action => ... etc}
  • Needed when performing the action.
• Additional fields

The additional fields information is needed for complicated actions like 'Assing the selected work orders to a user'. The fields would be used for selecting the target user in this case. The whole definition would be something like this:

 {:name => _('Assing'), 
  :url => {:action => 'assing_to_user'}, 
  :fields => [
               [_('Assing to user'), 'select_tag', 'user_id', user_options]
               [_('Comments), 'text_area_tag', 'comment']
             ] }

When selected this action would then be displayed like:

Perform action on selected items: [Assign [+]

   Assing to user: [ Smith, John (jsmith) [+]

   Comments:
             +------------------------------+
             | Some work for you            |
             |                              |
             |                              |
             |                              |
             |                              |
             |                              |
             +------------------------------+

   [Perform]

Clicking on the 'Perform' button would result in POST request to work_order/assing_to_user with the params looking like this (simplified):

params = { :item_ids => [1, 4, 9, 31], :user_id => 4, :comments => 'Some work for you' }

Full actions definition for work orders list could look something like this:

@actions =  [
                  { :name => _('Remove'), :url => {:action => 'remove'} },
                  { :name => _('Assing'), :url => {:action => 'update_states', :new_state => WorkOrder.ASSIGNED},
                    :fields => [ [_('Assing to user'), :select_tag, 'user_id', user_options],
                                 [_('Comments'), :text_area, 'comments'] ] },
                  { :name => _('Accept'), :url => {:action => 'update_states', :new_state => WorkOrder.ACCEPTED},
                    :fields => [ [_('Comments'), :text_area, 'comments'] ] },
                  { :name => _('Close'), :url => {:action => 'update_states', :new_state => WorkOrder.CLOSED},
                    :fields => [ [_('Comments'), :text_area, 'comments'] ] },
                  { :name => _('Reopen'), :url => {:action => 'update_states', :new_state => WorkOrder.NEW},
                    :fields => [ [_('Comments'), :text_area, 'comments'] ] },
                  { :name => _('Move'), :url => {:action => 'move'},
                    :fields => [ [_('Asset'), :select_tag, 'asset_id', asset_options] ] }
                ]