Development - Zenbu (for EE3)

Note: The developer documentation below applies for the EE2 version of Zenbu. Similar functions and hooks are available in EE3, but not fully documented yet.

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 (for EE3)

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