scrollMay 2014 / PhreeBooksR36RC3
Author – Dave

PhreeForm is a very powerful tool to build Reports and Forms tailored for your business.

Form – Normally a single page of information e.g. an Invoice Form
Report – Reports can be many pages long, consisting of line after line of details. e.g. a Monthly Sales Report

One of the more powerful features of PhreeForm is the ability to add you own custom processing to manipulate data for display in Reports and Forms, to meet you needs. This is one of the more complicated but valuable features of PhreeBooks, as it requires both programming experience and knowledge of the database structure. I will attempt to clarify the procedure to add a new custom processing option to your companies PhreeForm ‘Processing’ options.

Background About PhreeForm:

PhreeForm uses a GUI to ‘define’ how to extract data from the database and render it in a user defined format.phreeform

TOOLS > Reports > New Form

LH icon -> ‘New Report
RH icon -> ‘New Form

NOTE: one of the most useful applications of the information contained in this HowTo is in modifying an existing Form or Report, to better suit the needs of your business. (Please remember to first make a copy of any Form or Report before it is modified)

This HowTo will not go into all the features of PhreeForm, but will focus just on the ‘reformatting’ of the data to get the desired output.

phreeform-processing

When configuring fields, you will notice an option for ‘Processing’ the data. The drop-down list is built from the currently installed and enabled modules. For example, The ‘Formatted Date’ processing, simply takes the native date format from the database (YYYY-MM-DD) and reformats it into your locale format (i.e. mm/dd/yyyy). The current set of processing functions has evolved from the generation of various reports as needed by the community.

Properly Inserting a Custom Processing Option Into PhreeBooks:

The proper way to insert a custom processing script is through the hook provided in PhreeForm that looks for a file in the folder

/modules/phreeform/custom/extra_phreeform.php

and includes it when building the drop-down ‘Processing’ choices and when processing the database information. The file must be in proper PHP syntax and contain the following information:

// Path: /modules/phreeform/custom/extra_phreeform.php - optional but helps remember where the file needs to be
$FormProcessing['key'] = 'Locale Text'; // This will add your custom processing to the drop-down
function pf_extra_process($strData, $Process) { // this function will be called when processing the data
  switch ($Process) {
    case 'key': // Do something with $strData, 'key' must match EXACTLY the 'key' value set in $FormProcessing
      return $answer;
    default: // Do nothing
  }
  return $strData; // No Process recognized, return original value
}

Coding Your Custom Processing:

Here’s the tricky part. To do this effectively, you must know what value you are expecting and how to process it. There are many ways to go here, usually digging into the code is the best place to start. I’ll show a couple of examples.

Example 1.    Adding a simple count

This Example adds a simple line count to replace the field data. In this case, it doesn’t matter what data is sent to be processed as it is discarded and replaced with a simple counter. Notice how the variable $My_line_count is declared global outside of the function. This allows for the memory of the current count for every time the function is called (for each line retrieved). This example will count the number of rows returned for given report/form. It will render differently for Reports than Forms. For Reports, the output will be the current line count for each row of the report. For Forms, the total count will be displayed for all field types EXCEPT tables, which will behave as a Report.

$My_line_count = 0;
$FormProcessing['my_count'] = 'Line Count';
// Extra form processing operations
function pf_extra_process($strData, $Process) {
  global $My_line_count;
  switch ($Process) {
    case "my_count":
      $My_line_count++;
      return $My_line_count;
    default: // Do nothing
  }
  return $strData; // No Process recognized, return original value
}

Example 2.   Returning the logged in username to place on a form

This example will replace the database field with the current username that is logged in when the form is generated. This will be useful if you want to see who’s account was used to generate an invoice for internal tracking purposes. The username is stored in a php $_SESSION variable so it can easily be pulled and replace whatever data has been sent. I typically use the record id as it’s small and typically always is part of the record fetched from the database.

$FormProcessing['username'] = 'Current User';
// Extra form processing operations
function pf_extra_process($strData, $Process) {
  switch ($Process) {
    case 'username':
      return $_SESSION['display_name']; // the Display Name from the users settings
    default: // Do nothing
  }
  return $strData; // No Process recognized, return original value
}

Putting Your Custom Processing Into Action:

Let’s see how we did.

  1. First upload your file to the server into the location stated above.
  2. go to Tools -> PhreeForm (Reports) -> and navigate to the Report/Form you want to customize.
  3. On the File tab, edit the field to apply the processing to. You can also add a new field if needed. The field views vary depending on what type you are editing, however, beside the types that use a database field, you should see a Processing drop-down selection.
  4. Click the drop-down and your ‘Locale Text’ should show up on the list.
  5. Select it and save the report.

Your new custom processing should work the next time you render that Report/Form.

Please post any queries or comments to the Forum