Development - Zenbu 1 (for EE2)

Development documentation

In its simplest form, Zenbu natively displays the contents of a custom field stored in the exp_channel_data table. For customized display of custom field data, Zenbu already supports a number of custom fieldtypes, but third-party developers can add their own customized support for their fieldtype.

Zenbu first looks for Zenbu functions in the third-party’s fieldtype file (ft.field.php). If Zenbu functions are not found, Zenbu looks for fieldtype support files corresponding to a fieldtype in the zenbu/fieldtypes folder. As a final fallback, if Zenbu functions are still not found, the content of the data stored in exp_channel_data is displayed. (Note: The first two steps were reversed before v1.5.5)

Fieldtype framework functions
Hooks

zenbu_display

Set up display in entry result cell

zenbu_display($entry_id, $channel_id, $data, $table_data, $field_id, $settings, $rules, $upload_prefs, $installed_addons)

Parameters

$entry_id: (int) The entry ID of this single result entry
$channel_id: (int) The channel ID associated to this single result entry
$data: (array) Raw data as found in database cell in exp_channel_data
$table_data: (array) Data array usually retrieved from other table than exp_channel_data
$field_id: (int) The ID of this field
$settings: (array) The settings array, containing saved field order, display, extra options etc settings
$rules: (array) An array of entry filtering rules
$upload_prefs: (array) An array of upload preferences (optional)
$installed_addons: (array) An array of installed addons and their version numbers (optional)
$fieldtypes: (array) Fieldtype of available fieldtypes: id, name, etc (optional)

Return

$output: (string) The HTML used to display data

zenbu_get_table_data

Retrieve data stored in other database tables based on results from Zenbu’s entry list.

Instead of many small queries, this function can be used to carry out a single query of data to be later processed by the zenbu_display() method.

zenbu_get_table_data($entry_ids, $field_ids, $channel_id, $output_upload_prefs, $settings, $rel_array)

Parameters

$entry_ids: (array) An array of entry IDs from Zenbu’s entry listing results
$field_ids: (array) An array of field IDs tied to/associated with result entries
$channel_id: (int) The ID of the channel in which Zenbu searched entries (0 = “All channels”)
$output_upload_prefs: (array) An array of upload preferences
$settings: (array) The settings array, containing saved field order, display, extra options etc settings (optional)
$rel_array: (array) A simple array useful when using related entry-type fields (optional)

Return

$output: (array) An array of data (typically broken down by entry_id then field_id)

zenbu_result_query

Extra queries to be integrated into main entry result query

zenbu_result_query($rules, $field_id, $fieldtypes, $already_queried, $installed_addons)

Parameters

$rules: (int) An array of entry filtering rules
$field_id: (array) The ID of this field
$fieldtypes: (array) $fieldtype data
$already_queried: (bool) Used to avoid using a FROM statement for the same field twice
$installed_addons: (array) An array of installed addons and their version numbers (optional)

Return

Void. A query to be integrated with entry results should be mentioned. Should be in CI Active Record format (eg. $this->EE->db->…)

zenbu_field_extra_settings

Set up display for this fieldtype in “display settings”

zenbu_field_extra_settings($table_col, $channel_id, $extra_options)

Parameters

$table_col: (string) A Zenbu table column name to be used for settings and input field labels
$channel_id: (int) The channel ID for this field
$extra_options: (array) The Zenbu field settings, used to retieve pre-saved data

Return

$output: (array) An array with option names as key, and field settings to display (in HTML) as values.

Hooks

zenbu_filter_by_status

Enables the addition of extra queries when filtering entries by status

if ($this->EE->extensions->active_hook('zenbu_filter_by_status') === TRUE)
{
    $where = $this->EE->extensions->call('zenbu_filter_by_status', $channel_id, $status, $rule, $where);
    if ($this->EE->extensions->end_script === TRUE) return;
}

Parameters

$channel_id: (int) The currently selected channel_id
$status: (string) The currently selected status
$rule: (array) The current entry filter rule array
$where: (string) The partial query string

Return

$where: (string) The modified query string

zenbu_entry_query_end

Any last words? Enables adding additional Active Record patterns/commands before committing the completed Active Record query

if ($this->EE->extensions->active_hook('zenbu_entry_query_end') === TRUE)
{
    $this->EE->extensions->call('zenbu_entry_query_end');
    if ($this->EE->extensions->end_script === TRUE) return;
}

Parameters

None

Return

Void

zenbu_after_save_search

Enables the addition of extra code after the “Save this search” link

if ($this->EE->extensions->active_hook('zenbu_after_save_search') === TRUE)
{
    $vars_other['extra_options_right_save'] = $this->EE->extensions->call('zenbu_after_save_search');
    if ($this->EE->extensions->end_script === TRUE) return;
} else {
    $vars_other['extra_options_right_save'] = '';
}

Parameters

None

Return

$vars_other[‘extra_options_right_save’] (string) The output HTML

zenbu_modify_data_array

Modifies the data array containing most of Zenbu’s settings and output data. This data is used for the result view

if ($this->EE->extensions->active_hook('zenbu_modify_data_array') === TRUE)
{
    $vars = $this->EE->extensions->call('zenbu_modify_data_array', $vars);
    if ($this->EE->extensions->end_script === TRUE) return;
}

Parameters

$vars (array) The data array before modification

Return

$vars (array) The modified data array

zenbu_modify_channel_data

Modifies the channel array, used for the Zenbu channel dropdown, for example

if ($this->EE->extensions->active_hook('zenbu_modify_channel_data') === TRUE)
{
    $output = $this->EE->extensions->call('zenbu_modify_channel_data', $output);
    if ($this->EE->extensions->end_script === TRUE) return;
}

Parameters

$output (array) The channel array before modification

Return

$output (array) An array containing channel-related data

zenbu_modify_column_headers

Modifies the labels for each visible column in Zenbu.

if ($this->EE->extensions->active_hook('zenbu_modify_column_headers') === TRUE)
{
    $column_headers = $this->EE->extensions->call('zenbu_modify_column_headers', $column_headers);
    if ($this->EE->extensions->end_script === TRUE) return;
}

Parameters

$column_headers (array) The column header titles

Return

$column_headers (array) The modified column header array

zenbu_modify_title_display

Modifies the display of the “title” column in the entry listing

if ($this->EE->extensions->active_hook('zenbu_modify_title_display') === TRUE)
{
    $output['entry'][$row['entry_id']]['title'] = $this->EE->extensions->call('zenbu_modify_title_display', $output['entry'][$row['entry_id']]['title'], $entry_array, $row);
    if ($this->EE->extensions->end_script === TRUE) return;
}

Parameters

$output[‘entry’][$row[‘entry_id’]][‘title’]: (string) The output string to be displayed in the Zenbu column
$entry_array: (array) An array containing all the entry_ids of the entry listing results
$row: (int) An array of row data for the current entry

Return

$output[‘entry’][$row[‘entry_id’]][‘title’]: (string) The final output to be displayed in the Zenbu column

zenbu_modify_status_display

Modifies the display of the “status” column in the entry listings

if ($this->EE->extensions->active_hook('zenbu_modify_status_display') === TRUE)
{
    $output['entry'][$row['entry_id']]['status'] = $this->EE->extensions->call('zenbu_modify_status_display', $output['entry'][$row['entry_id']]['status'], $entry_array, $row, $output_status);
    if ($this->EE->extensions->end_script === TRUE) return;
}

Parameters

$output[‘entry’][$row[‘entry_id’]][‘status’]: (string) The output string to be displayed in the Zenbu column
$entry_array: (array) An array containing all the entry_ids of the entry listing results
$row: (int) An array of row data for the current entry
$statuses: (array) An array containing all entry status data

Return

$output[‘entry’][$row[‘entry_id’]][‘status’]: (string) The final output to be displayed in the Zenbu column

zenbu_modify_category_display

Modifies the display of the “category” column in the entry listing.

if ($this->EE->extensions->active_hook('zenbu_modify_category_display') === TRUE)
{
    $output['entry'][$row['entry_id']]['categories'] = $this->EE->extensions->call('zenbu_modify_category_display', $output['entry'][$row['entry_id']]['categories'], $entry_array, $row, $category_list);
    if ($this->EE->extensions->end_script === TRUE) return;
}

Parameters

$output (string) The output string to be displayed in the Zenbu column
$entry_array (array) An array containing all the entry_ids of the entry listing results
$row (int) An array of row data for the current entry
**$category_list (array) A multi-dimensional array of cat_id/cat_name, for each entry_id

Return

$output (string) The final output to be displayed in the Zenbu column

zenbu_modify_field_cell_data

Modify custom field cell data before output & display in Zenbu.

if ($this->EE->extensions->active_hook('zenbu_modify_field_cell_data') === TRUE)
{
    $info_data                      = $field_ids;
    $info_data['entry_id']          = $row['entry_id'];
    $info_data['current_field_id']  = $field_id;

    $field_data = $this->EE->extensions->call('zenbu_modify_field_cell_data', $field_data, $info_data);
    if ($this->EE->extensions->end_script === TRUE) return;
}

Parameters

$field_data (string) The current data to be displayed in the Zenbu column cell
$info_data (array) An array of the current entry_id, field_id, and an array of field information (ids, fieldtype, name…)

Return

$field_data (string) The modified data to be displayed in the Zenbu column cell

zenbu_modify_standard_cell_data

Modifies the display of standard entry data columns in the entry listing.

if ($this->EE->extensions->active_hook('zenbu_modify_standard_cell_data') === TRUE)
{
    $output['entry'][$row['entry_id']] = $this->EE->extensions->call('zenbu_modify_standard_cell_data', $output['entry'][$row['entry_id']], $entry_array, $row);
    if ($this->EE->extensions->end_script === TRUE) return;
}

Parameters

$output (string) The output string to be displayed in the Zenbu column
$entry_array (array) An array containing all the entry_ids of the entry listing results
$row (int) An array of row data for the current entry

Return

$output (string) The final output to be displayed in the Zenbu column

zenbu_add_column

Adds another standard setting row in the Display Settings section.

if ($this->EE->extensions->active_hook('zenbu_add_column') === TRUE)
{
    $hook_fields_and_labels = $this->EE->extensions->call('zenbu_add_column');
    if ($this->EE->extensions->end_script === TRUE) return;
    ... /* See source for the rest */
}

Parameters

None

Return

$hook_fields_and_labels (array) An array containing row data. The $hook_fields_and_labels array must have the following keys along with their values:
- column: Computer-readable used as identifier for settings, prefixed with show_. Keep it unique! For example, show_my_column
- label: Human-readable label used in the Display settings row.

Example

$hook_fields_and_labels[] = array(
    'column'    => 'show_my_column',
    'label'     => ee()->lang->line('show_my_column'),
);

return $hook_fields_and_labels;

zenbu_entry_cell_data

Add data to display in the custom/third-party entry row cell

if ($this->EE->extensions->active_hook('zenbu_entry_cell_data') === TRUE)
{
    $ext_result_array = $this->EE->extensions->call('zenbu_entry_cell_data', $row['entry_id'], $entry_array, $row['channel_id']);
    if ($this->EE->extensions->end_script === TRUE) return;
}

Parameters

$row[‘entry_id’] (int) The current Entry ID
$entry_array (array) An array of all entries found by Zenbu
$channel_id (int) The current channel ID for the entry

Return

$output (array) An array of data used by Zenbu. The key must match the computer-readable identifier, minus the show_ part. For example, if the column is show_my_column, then return $output["my_column"]

Example

$output["my_column"] = "Hello World";

return $output;

zenbu_custom_order_sort

Adds custom sorting to Zenbu results

if ($this->EE->extensions->active_hook('zenbu_custom_order_sort') === TRUE)
{
    $this->EE->extensions->call('zenbu_custom_order_sort', $sort);
    if ($this->EE->extensions->end_script === TRUE) return;
}

Parameters

$sort (string) The sort order (asc or desc)

Return

Void: Build your order_by() Active Record statements in the extension

Development - Zenbu 1 (for EE2)

Development documentation

Fieldtype framework functions

zenbu_display

Parameters

Return

zenbu_get_table_data

Parameters

Return

zenbu_result_query

Parameters

Return

zenbu_field_extra_settings

Parameters

Return

Hooks

Miscellaneous

Modifying existing fields

Adding columns to Zenbu

zenbu_filter_by_status

Parameters

Return

zenbu_entry_query_end

Parameters

Return

zenbu_after_save_search

Parameters

Return

zenbu_modify_data_array

Parameters

Return

zenbu_modify_channel_data

Parameters

Return

zenbu_modify_column_headers

Parameters

Return

zenbu_modify_title_display

Parameters

Return

zenbu_modify_status_display

Parameters

Return

zenbu_modify_category_display

Parameters

Return

zenbu_modify_field_cell_data

Parameters

Return

zenbu_modify_standard_cell_data

Parameters

Return

zenbu_add_column

Parameters

Return

Example

zenbu_entry_cell_data

Parameters

Return

Example

zenbu_custom_order_sort

Parameters

Return

Zenbu Studio