Many applications make use of columnar data that does not change very often. In such cases, the time and effort to incorporate this data into database tables and the overhead of looking up this data may not be justified. This model is used to implement a "table" using a php class to cache and retrieve the data. Since the entire table must be stored in memory, this technique should not be used to implement large data stores. Generally, you should restrict your php arrays to fewer than, say, 1000 data items. That is, the number of rows times the number of columns should not be be more than 1,000 or so. Keep in mind that this is not a strict rule in the sense that there are always exceptions. It really depends on how many rows of data your application needs to access for each request. If you only ever need one row for a given request, the overhead of loading an array with hundreds of items may not be justified. On the other hand, if your application generally needs to fetch lots of rows, this might be the most efficient method even when the table size is quite large.

Defining the Data

The first column of your php_array_data definition will be used as the key to access the data values. In most cases this will be assigned a unique value that will be used to identify the row. In some cases the data you wish to store in your array may not have a natural key value. In that case you can just leave the Row Index column empty and the data values will be stored using numeric keys starting at zero. If the Row Index you enter is non-blank and not unique, the data values for these rows will be stored as a multi-dimensional array.

The column names you define will be used to index into the second dimension in the table (or third dimension if the Row Index values are not unique). Suppose you are building a tarp manufacturing website and you want to store information about the different tarp materials you offer. Here is an example of what such a data table might look like:

Notice that column one contains a description of the material. This might be used in a drop-down select field to allow the user to choose the material they are interested in. The column headings in column 2 and 3 correspond to field names for the values that you want to return from the generated class.

Non-decimal numbers that are less than or equal to 9 digits will be defined as integers in the generated array. If you do not want this, you can enclose them in single quotes.

Generating get Methods

The generated classes offer generic methods for fetching the data. Nevertheless, you may want to have get methods that are specific to your columns. If you mark the option to generate get methods, the class will contain methods such as the following method used to retrieve material_width.

function get_material_width($row_index=null) { 
  if (!isset($row_index)) { 
    $row_index = $this->default_row_index; 
  } 
  return $this->data[$row_index]['material_width']; 
}

Notice that it is possible to set a default index value when using the get method. This is done by calling the set_default_row_index method.

Generating set Methods

In most cases, the data exposed by the generated classes is not intended to be changed by your application. Nevertheless, there may be times when you want to allow this. By marking the option to generate set methods, the generated php class will contain a set method for each column of data. Here is an example of such a method.

function set_weight($weight,$index1,$index2) {
	$this->data[$index1][$index2] = $weight;
}

Setting new values will only affect the copy of the class in memory. The original/saved class values will not be changed.

Including Empty Cells

This option controls whether cells that are left empty in the grid are to be included in the generated array data and, if so, what values these cells are to be assigned. By default the empty cells will be included with an empty string value. Alternatively, you can include these an assign them a value of 0 (zero), false or NULL. Chose the Exclude Empty Cells option if these values are not to be included in the generated array. Consider the following "sparse" array that is used to list alternative abbreviations for the Canadian province codes:

If we choose the option to exclude empty values, the generated array will appear as follows:

protected $data = array (
  'Newfoundland and Labrador' => 
  array (
    0 => 'nl',
    1 => 'newfoundland',
    2 => 'labrador',
    3 => 'newfoundland & labrador',
  ),
  'Prince Edward Island' => 
  array (
    0 => 'pei',
    1 => 'pe',
  ),
  'Nova Scotia' => 
  array (
    0 => 'ns',
  ),
  'New Brunswick' => 
  array (
    0 => 'nb',
  ),
  'Quebec' => 
  array (
    0 => 'que',
    1 => 'qc',
    2 => 'québec',
  ),
  'Ontario' => 
  array (
    0 => 'ont',
    1 => 'on',
  ),
  'Manitoba' => 
  array (
    0 => 'man',
    1 => 'mb',
  ),
  'Saskatchewan' => 
  array (
    0 => 'sask',
    1 => 'sk',
  ),
  'Alberta' => 
  array (
    0 => 'alta',
    1 => 'ab',
    2 => 'alb',
  ),
  'British Columbia' => 
  array (
    0 => 'bc',
  ),
  'Yukon' => 
  array (
    0 => 'yt',
  ),
  'Northwest Territories' => 
  array (
    0 => 'nwt',
    1 => 'nt',
  ),
  'Nunavut' => 
  array (
    0 => 'nvt',
    1 => 'nu',
  ),
);

Accessing Generated php_array_data Classes and Data

The data you define can be accessed programmatically in php. Here is an example of how we could access the php_array_data above named tarp_material using the site's create_object method. In this example we want to iterate through all of the values so we fetch all rows using the inherited get_data method:

$material = $this->site->create_object('tarp_material','',false,'array_data');
$all_material = $material->get_data();
foreach ($all_material as $key => $info) {
  $weight[$key] = $info['weight'];
  $width[$key] = $info['width'];
}

In the next example we don't utilize the create_object method and instead we need to require the class before instantiating it. In this example, we are requesting a specific row by passing the key that is defined in column 1 of the php_array_data specification. We use the inherited method get_row_data.

require_once SITE_CLASS_PATH.'array_data/tarp_material.php';
$material = new tarp_material();
$vinyl = $material->get_row_data('18 Oz Vinyl');
$width = $vinyl['material_width'];

This final example is similar to the one above except this assumes that the php_array_data class was generated to include get methods. In such a case we can use these methods to fetch the data rather than the more generic inherited methods illustrated above.

require_once SITE_CLASS_PATH.'array_data/tarp_material.php';
$material = new tarp_material();
$vinyl_width = $material->get_material_width('18 Oz Vinyl');

Entering Comments

Normally the values in the header row of the grid must be unique lower case strings that are suitable as PHP field names. It is also possible in begin the column header with two slash characters to indicate that the column will be used to enter comments and not actual data values. We show an example of this below in the last column: