Batch functions implementation
Batch functions are functions that are applied to a set of data. Examples of this are realiquoting in batch and updating in batch.
Contents |
Access point
Batch functions are accessed through the query tool action menu. To define new batch actions, create records in the table datamart_structure_functions. You'll need to provide the following information
- datamart_structure_id
- The datamart structure id. See table datamart_structures.
- label
- The label to display in the batch actions sub-menu.
- link
- The link to go to for the action.
- flag_active
- Whether this action is active or not.
Batch edit function
A batch edit allows to update many records at once. Developers should carefully select the available fields here as they don't all make sense. An example of a bad field would be participant first name. An example of a relevant field would be vital status.
Update form
The first time your function is reached, it will receive the data as sent by the query tool. It should hereby be Model => id => array of selected ids. You will need those ids later so its usually a good idea to put them into a single hidden field. As for any other form, you simply have to load a structure and set your options. Note that flag_batchedit will be used to display your structure.
Updating
Then the user will post the requested batch update. If you put your ids as a hidden field, you also have them. First, you'll need to validate the data. If non of your fields have the notEmpty validation flag, it's simple. You simply have to put the data into your model and call the validation on it. Here is an example from participants batch edit. <source lang=php> $this->Participant->set($this->data); if($this->Participant->validates()){ //save process } //error handling </source> If you have fields with the notEmpty validation flag but you don't want to honour that rule for that form, you'll have to remove the field fro the data array, but only if it's empty, because if it's not, this particular validation will work and you probably want to apply any other validation on that same field.
Then you are ready to update. Remember: You should only update fields that are not blank. So you have to remove blank fields from your updateAll call. A function was created for that: getUpdateAllValues. You simply give the data array you want to save and it returns the save array minus the blank fields. Here is an example from participants. <source lang=php> $ids = explode(",", $this->data[0]['ids']); $this->Participant->updateAll( AppController::getUpdateAllValues(array("Participant" => $this->data['Participant'])), array('Participant.id' => $ids) ); </source>
Redirection
Once the update is complete, you don't want your user to still have the batch edit screen. You also want to tell him that the update was successful. As always, to accomplish both you can make a call to atimFlash. In our example, we want to list the edited participants. We do it by using the search screen. Prior to redirecting the user, we need to give the system the search parameters. It's done through $_SESSION['ctrapp_core']['search']['criteria']. Here is the last part of our example. <source lang=php> $_SESSION['ctrapp_core']['search']['criteria'] = array("Participant.id" => $ids); $this->atimFlash('your data has been updated', '/clinicalannotation/Participants/search/'); </source>
