adding fields/#3398

Here is how to add fields to existing Streber objects so you can customise the content Streber is recording. Here is an example of adding a boolean field called onsite to the effort class. This information was a requirement of our PMS and allows you to track at where a particular effort was performed.

Add a field to the streber.effort table in MySQL:

   ALTER TABLE effort ADD COLUMN onsite TINYINT ... ;

To provide future upgrade you should also add this change to install/install.php like:

   ### update to v0.049
   if($db_version <0.049) {
       $update_queries[]="ALTER TABLE `{$db_table_prefix}effort` ADD `onsite` TINYINE ;";
   }

In db/class_effort.inc find the fields definition near the top of the file. At the base of the array, add your definition:

   new FieldBool(array('name'=>'onsite',
    'title'=>__('On Site'),
    'default'=>0,
    'view_in_forms'=>true,
   )),

Then open pages/effort.inc. Find thefirst function effortNew. At the base of the effortNew function locate where the $newEffort variable is being set. At this point all the fields are being added to the effort object. Add the new field, onsite, at the base of the array definiton:

 'onsite'=> 0

Although you could use "false" were are actually talking about a database-field here. So using the numbers 0 and 1 is a little bit more precise. And since you already provided a "default" value, you actually don't have to add this line add all.

The new field should now be visible and properly initialised in the new effort form. Now we add one further line of code to perform the same function for the edit form.

Move down to the effortEdit function. Toward the base of the function underneath all the other field initialisers add a basic one for the onsite field.

   $form->add($effort->fields['onsite']->getFormElement(&$effort));

You should now be able to view your new field in these forms and see the field being updated in your database.

To complete the modification you should add the field to be displayed in the listings for that object type. Open the file lists/list_effort.inc and in the ListBlock_efforts constructor add the new field to the function like so:

    $this->add_col(new ListBlockCol_onsite());

This will render the column using the ListBlockCol_onsite class. Further down this same file we define this class which controls how the field is rendered in the list.

Our class looks like this:

    class ListBlockCol_onsite extends ListBlockCol
    {
      public $key = 'onsite';
    
      public function __construct($args=NULL) {
        parent::__construct($args);
        $this->name= __('On Site?', 'column header');
      }
    
      function render_tr(&$obj, $style="") {
        $value = __('No');
        if ($obj->value) {
          $value = __('Yes');
        }
        print "<nowiki><td>$value </td></nowiki>";
      }
    }

There are two interessting points about this class.

1. All texts should always be put into a __() function. This will add the strings to the translation table. In case of 'Yes' and 'No' chances are good, that those words have already been translated. Because the current language is not known at parsing, what have to set the "name"-member in the constructor. To give the translator a hint to keep the translated text really short (we don't want huge columns), we add a context.
2. By setting the "key"-member you already provide the sort-feature for the list! The trade off is that streber would build an invalid sql-query if the "onsite"-field is not present in the "effort"-table. To add columns that don't have an excact match as table field, you must not provide a "key". (See list_tasks.inc -> assigments as an example).