CartThrob 9 documentation for ExpressionEngine commerce teams Visit CartThrob.com
Add-on docs
CartThrob.com

CartThrob Global Item Options Version 3.0.2

Overview

CartThrob Global Item Options lets you define reusable option groups (with optional price modifiers) and make them available across product entries.

Core behavior in current code:

  • Option groups are managed in add-on CP (groups, create-option-group, edit-option-group, delete-option-group).
  • Availability can be limited to selected CartThrob product channels.
  • Two fieldtypes let you override global behavior per entry: cartthrob_item_options_select (specific option values) and cartthrob_item_groups_select (specific option groups).
  • Price modifiers are injected through CartThrob extension hook cartthrob_get_all_price_modifiers.
  • No module template tags are exposed in mod.cartthrob_item_options.php.

Requirements

From live docs/release metadata:

  • ExpressionEngine 5+
  • CartThrob 5.4.5+
  • PHP 7.1+

Installation

  1. Upload cartthrob_item_options to /system/user/addons/.
  2. Install CartThrob Global Item Options from EE Add-on Manager.
  3. Confirm CartThrob product channels are configured.
  4. Configure add-on Settings and create at least one option group.
  5. Add fieldtypes to product channels if per-entry overrides are needed.

Upgrading

  1. Upload new add-on files over existing cartthrob_item_options folder.
  2. Run add-on update in EE Add-on Manager.
  3. Recheck channel settings and option groups.

Notes from updater:

  • 3.0.0 migration adds/normalizes settings/options schema (primary keys, typed serialized values, site scoping).
  • Channel-selection legacy values all/none are migrated to explicit channel IDs/empty list.

Start Here (10-Minute Setup)

  1. Open Add-ons > CartThrob Global Item Options > Settings.
  2. Select product channels where global item options should apply.
  3. Open Option Groups and click New.
  4. Set Label (descriptive group name) and Short Name (unique, safe key such as global_size).
  5. Add at least two option rows in the options grid: option_name, option_value, and optional price.
  6. Save.
  7. In product templates, output options with CartThrob core {exp:cartthrob:item_options} tag.

Common Tasks With Examples

1. Create a Global Size Group

  • Group label: Shirt Sizes
  • Short name: global_shirt_sizes
  • Rows:
  • Small, small, 0.00
  • Large, large, 2.00

2. Restrict Global Options to Specific Product Channels

  • In Settings, check only channels where options should apply.
  • Entries in unselected channels will not receive these modifiers.

3. Override by Entry With Fieldtypes

  • Add CartThrob Global Item Options Multi Select to product channel to whitelist specific option values.
  • Add CartThrob Global Item Groups Multi Select to product channel to whitelist specific groups.

4. Customize Option Data/Grid Behavior via Hooks

  • Use cartthrob_item_options_modify_option_data to alter row data before save.
  • Use cartthrob_item_options_modify_option_grid to alter CP grid rendering.

Control Panel Reference

Base route: addons/settings/cartthrob_item_options

Items:

  • Option Groups (with New button)
  • Settings
  • external Documentation

Settings

Route: settings

Form field:

  • global_item_options_channels (checkbox list)
  • list is limited to CartThrob product_channels

Behavior:

  • If no product channels are configured, CP shows an important alert and no settings form.
  • Saved under settings key global_item_options_channels for current site_id.

Option Groups List

Route: groups

Table columns:

  1. ID
  2. Label
  3. Short Name
  4. Manage (toolbar)

Manage actions:

  • Edit opens edit-option-group/{id}
  • Remove opens delete-option-group/{id}

Create/Edit Option Group

Routes:

  • create-option-group
  • edit-option-group/{id}

Fields:

  1. label (required)

- descriptive name shown in CP and labels map

  1. short_name (required)

- unique machine key used when adding modifiers to CartThrob

  1. data grid (required)

- columns: - option_name (descriptive) - option_value (value key) - price (optional modifier)

Save behavior:

  • Row data normalized into serialized array structure.
  • Hook cartthrob_item_options_modify_option_data can mutate row data before model save.
  • Hook cartthrob_item_options_modify_option_grid can mutate displayed grid object.

Delete Option Group

Route: delete-option-group/{id}

Behavior:

  • requires confirm = y to delete
  • on success, redirects back to groups with success alert

Fieldtypes and Template Output

cartthrob_item_options_select

Name: CartThrob Global Item Options Multi Select

Purpose:

  • lets entry editor choose specific option values to include for that entry

Source of choices:

  • all option rows from all global option groups
  • option label format in CP: {group_label}: {option_name}
  • submitted value is option_value

Storage:

  • stored as EE encoded multi-value field

Template output behavior (replace_tag):

  • single output: pipe-delimited string by default
  • supports limit
  • supports markup="ul"|"ol"
  • pair output provides variables:
  • {item}
  • {count}
  • supports backspace in pair mode

cartthrob_item_groups_select

Name: CartThrob Global Item Groups Multi Select

Purpose:

  • lets entry editor choose which global option groups apply to that entry

Source of choices:

  • global option groups (short_name => label)

Storage/output behavior:

  • same multi-value encode/decode pattern
  • same replace_tag parsing behavior and parameters as above (limit, markup, backspace, pair vars item/count)

Runtime Hooks and Behavior

Extension Hooks Registered by Updater

  • cartthrob_get_all_price_modifiers -> cartthrob_get_all_price_modifiers
  • cartthrob_add_settings_nav -> cartthrob_add_settings_nav

Modifier Assembly Logic

On cartthrob_get_all_price_modifiers($entry_id):

  1. Loads entry channel + fieldtype presence.
  2. Reads per-entry selected option values (if fieldtype exists).
  3. Reads per-entry selected groups (if fieldtype exists).
  4. Applies global channel restriction from settings.
  5. Loads all option groups, stores cart meta:

- global_item_options - item_option_labels map (short_name => group label) 6. Builds per-group option arrays and merges with existing modifier stack from prior extension calls.

Filtering behavior summary:

  • If entry-level selected option values exist, options are filtered by those values.
  • If entry-level selected groups exist, only those groups are included.
  • If no entry overrides exist, all global groups/options apply (subject to channel restriction).

Changelog

Version 3.0.2

Release December 13, 2021

  • addon.setup.php version marker is 3.0.2.

Version 3.0.1

Release March 17, 2021

Version 3.0.0

Release December 19, 2020

  • Upgraded for CartThrob 5.4.5+.
  • CP screens moved to EE shared form/styles.
  • Fieldtypes aligned to EE option/shared select views.
  • Settings/options schema updates and data migration support.
  • Added ItemOption and Setting models.