Voxel Enhanced Action List Widget
The {CODICTS} Voxel Enhanced Action List Widget plugin extends the Voxel theme’s built-in Action List Elementor widget by adding the ability to save post relationships directly from frontend preview cards and single post pages. It injects a new action type — “Save post relationships” — into Voxel’s action list widget, allowing users to add or remove post relations without navigating away from the current page.
The plugin operates in two distinct modes: a Popup Mode that opens a searchable popup where users can browse and toggle related posts, and a Quick Action Mode that provides a simple one-click toggle button for profile-only relationships.
Installation & Activation
Start by downloading the plugin from the Downloads page on your dashboard on the CoDicts website.
After downloading, install and activate the plugin in WordPress by navigating to “Plugins” > “Add New” > “Upload Plugin” and selecting the downloaded zip file. Click “Install Now” and then “Activate”.
On activation, the plugin automatically detects your Voxel theme version and copies the appropriate template files into your child theme. The enhanced Action List widget is immediately available in Elementor.
Key Features
| Feature | Description |
|---|---|
| New Action Type | Adds “{C} Save post relationships” to Voxel’s Action List widget in Elementor. |
| Popup Selector | Searchable popup with pagination for browsing and toggling related posts using checkboxes or radio buttons. |
| Quick Profile Toggle | One-click add/remove button for profile-only relationships — no popup needed. |
| Multi & Single Selection | Checkboxes for “Has Many” / “Belongs to Many” relationships, radio buttons for “Has One” / “Belongs to One.” |
| Search & Pagination | Real-time search with debounce and “Load more” pagination for large lists inside the popup. |
| Author Approval Support | Shows pending status indicator when author approval is required for the relationship. |
| Active State Styling | Configurable default and active state icons, text, and full per-item custom styling in Elementor. |
| Preview Card Support | Works on both single post pages and dynamically loaded preview cards. |
| Voxel 1.0 & 1.4+ Support | Separate template sets for both major Voxel versions, auto-detected on activation. |
How It Works
The plugin adds a new action type to Voxel’s Action List (Advanced List) Elementor widget. When a user clicks the action button on a listing, the plugin either opens a searchable popup or performs a quick one-click toggle — depending on the relationship configuration.
Two Modes of Operation
| Mode | When It Activates | Behavior |
|---|---|---|
| Popup Mode | The relationship field’s target post types include types other than just “profile” (e.g., Events, Places, Products). | Opens a searchable popup where users browse available posts, toggle checkboxes or radio buttons, and manage relationships. Supports search, pagination (18 items per page), and pending approval indicators. |
| Quick Action Mode | The relationship field’s target post types contain only “profile.” | A simple toggle button directly on the preview card or single page. Clicking immediately adds or removes the relationship via a single click — no popup. Works like a Follow/Bookmark button. |
The mode is detected automatically based on your relationship field configuration — no manual selection needed.
Pre-Setup — Understanding Voxel Post Relationships
Before configuring the plugin, ensure your Voxel post types have Post Relation fields set up in the Voxel type editor. Voxel supports four relationship types:
| Relation Type | Direction | Selection in Popup |
|---|---|---|
| Has One | Parent → Child | Radio button (single select) |
| Has Many | Parent → Children | Checkboxes (multi select) |
| Belongs to One | Child → Parent | Radio button (single select) |
| Belongs to Many | Child → Parents | Checkboxes (multi select) |
For example, an “Events” post type might have an attendees relation field (Has Many → Profile), while the “Profile” post type has a corresponding attended-events field (Belongs to Many → Events).
Setting Up the Save Post Relationships Action
Step 1: Ensure Relationship Fields Exist
In the Voxel type editor, verify that your post types have Post Relation fields configured. You’ll need to know the field keys for both sides of the relationship.
For example:
| Post Type | Field Key | Relation Type | Target |
|---|---|---|---|
| Events | attendees | Has Many | Profile |
| Profile | attended-events | Belongs to Many | Events |
Step 2: Add the Action List Widget in Elementor
1. Edit your Voxel template in Elementor (e.g., a preview card template or single post page template).
2. Add the “Actions (VX) ({C})” widget (Voxel 1.4+) or “Action list (VX) ({C})” widget (Voxel 1.0).
3. Add a new action item to the repeater.
4. Set “Choose action” to “{C} Save post relationships”.
Step 3: Configure the Action Settings
| Setting | Description | Example |
|---|---|---|
| Post Field Key | The key of the post-relation field on the current post’s listing type. | attendees |
| Profile Field Key | The key of the post-relation field on the user’s profile listing type. Used for Quick Action Mode. | attended-events |
Step 4: Configure Button Labels and Icons
Set the text and icons for both the default (inactive) and active states:
| State | Settings | Description |
|---|---|---|
| Default State | Text + Icon | What the button shows before the user has activated the relationship (e.g., “Attend” with a plus icon). |
| Active State | Text + Icon | What the button shows after the relationship is active (e.g., “Attending” with a check icon). |
You can also enable a tooltip that appears on hover, and apply custom per-item styling including colors, typography, borders, and icon styles for default, hover, and active states.
5. Save the Elementor template.
Popup Mode — How It Works
When the relationship field targets post types other than just “profile,” the plugin uses Popup Mode.
1. The user clicks the action button on a listing.
2. A popup opens with a searchable list of available posts.
3. The popup displays:
| Element | Description |
|---|---|
| Search input | Type to filter posts in real time (500ms debounce). Results update as you type. |
| Post list | Scrollable list showing each post’s avatar, title, and post type label. |
| Checkboxes or radio buttons | Checkboxes for multi-select relationships (Has Many / Belongs to Many). Radio buttons for single-select (Has One / Belongs to One). |
| Load more | Pagination button that loads the next batch (18 items per page). |
| Pending indicator | Shows next to items that are awaiting author approval (when approval is required). |
4. Click any post to toggle the relationship on or off. The change is saved immediately via AJAX.
Note: The popup requires the user to be logged in. Unauthenticated users are redirected to the login page when they click the action button.
Quick Action Mode — How It Works
When the relationship field targets only “profile” as its post type, the plugin automatically switches to Quick Action Mode.
1. The button renders on the preview card or single page with a default or active state — depending on whether the current user’s profile already has this relationship.
2. Clicking the button immediately toggles the relationship (adds or removes) via a single AJAX call. No popup opens.
3. The button visually toggles between its default and active state.
This works similarly to a Follow or Bookmark button — perfect for “I attended this event,” “Save to my list,” or “Add to favorites” actions.
How the active state is determined: The plugin checks the current user’s profile for the Profile Field Key. If the current post’s ID exists in that field’s values, the button is rendered in its active state on page load.
Example Setup — Event Attendance
1. Activate the plugin with the Voxel theme and a Voxel child theme active.
2. In the Voxel type editor, configure the relationship fields:
a. On the “Events” post type, add a Post Relation field with key attendees, type “Has Many,” targeting “Profile.”
b. On the “Profile” post type, add a Post Relation field with key attended-events, type “Belongs to Many,” targeting “Events.”
3. Edit the Events preview card template in Elementor.
4. Add the “Actions (VX) ({C})” widget. Add an action item and set the action type to “{C} Save post relationships.”
5. Set Post Field Key to attendees and Profile Field Key to attended-events.
6. Set the default state text to “Attend” (with a plus icon) and the active state text to “Attending ✓” (with a check icon).
7. Save the template.
8. Since the attendees field targets only “profile,” the plugin automatically uses Quick Action Mode. On each Event preview card, users see an “Attend” button. Clicking it instantly adds them as an attendee — the button toggles to “Attending ✓.” Clicking again removes them.
Example Setup — Linking Posts via Popup
1. In the Voxel type editor, on a “Products” post type, add a Post Relation field with key related-stores, type “Has Many,” targeting “Stores.”
2. Edit the Products single post page template in Elementor.
3. Add the “Actions (VX) ({C})” widget with a “{C} Save post relationships” action. Set Post Field Key to related-stores. Set the default text to “Link Stores.”
4. Save. Since the field targets “Stores” (not just “profile”), the plugin uses Popup Mode. Clicking “Link Stores” opens a searchable popup listing all available Stores. Users can search, browse with pagination, and toggle checkboxes to link or unlink stores from the product.
Voxel Version Compatibility
The plugin ships with two complete template sets and automatically installs the correct one based on your Voxel theme version:
| Voxel Version | Widget Name in Elementor | Action Label |
|---|---|---|
| Voxel < 1.4 | Action list (VX) ({C}) | Save post relationships |
| Voxel ≥ 1.4 | Actions (VX) ({C}) | {C} Save post relationships |
The core “Save post relationships” functionality is identical across both versions. The differences are only in inherited Voxel widget controls and naming conventions.
Note: When you update the Voxel theme to a new major version, deactivate and reactivate the plugin to ensure the correct template set is installed for your version.
Frequently Asked Questions
Does this require a child theme?
Yes. The plugin copies template files into the child theme to override the Voxel Action List widget. Without a child theme, the plugin cannot install its templates.
Does this work on preview cards?
Yes. The plugin works on both single post pages and preview cards. The JavaScript automatically reinitializes when Voxel updates the page content (e.g., after AJAX navigation or loading new cards), so dynamically loaded preview cards are fully supported.
How does the plugin decide between Popup Mode and Quick Action Mode?
It’s automatic. If the Post Field Key’s target post types contain only “profile”, Quick Action Mode is used (one-click toggle, no popup). If the field targets any other post types (or multiple types), Popup Mode is used (searchable popup with checkboxes/radio buttons).
Do users need to be logged in?
Yes. Both modes require authentication. In Popup Mode, unauthenticated users are redirected to the login page when they click the action button. In Quick Action Mode, the toggle only works for logged-in users with a Voxel profile.
What relationship types are supported?
All four Voxel relationship types: Has One (radio button), Has Many (checkboxes), Belongs to One (radio button), and Belongs to Many (checkboxes). Single-select types show radio buttons in the popup, while multi-select types show checkboxes.
Does it support author approval?
Yes. When a relationship field has “require author approval” set to “always” in the Voxel type editor, the popup shows a pending approval indicator next to items that are awaiting approval.
Can I customize the button appearance?
Yes. Each action item supports full Elementor styling — including custom typography, text colors, background colors, borders, icon sizes, and icon colors for default, hover, and active states. You can also set different text and icons for the default and active states.
Which Voxel versions are supported?
Both Voxel 1.0 and Voxel 1.4+. The plugin auto-detects your Voxel version on activation and installs the matching template set. If you upgrade Voxel to a new major version, deactivate and reactivate the plugin to switch templates.
Does the plugin create any database tables?
No. Relationships are stored in Voxel’s existing voxel_relations table using Voxel’s native field update methods. The plugin stores only a single option for template installation status.
What happens when the plugin is deactivated?
The template files are removed from the child theme, and Voxel’s original Action List widget is restored. Existing relationship data in the voxel_relations table is preserved. Reactivating the plugin reinstalls the templates and restores full functionality.
Troubleshooting
Widget Not Appearing in Elementor
| Cause | Solution |
|---|---|
| Templates not installed | Deactivate and reactivate the plugin to force-reinstall templates. Verify template files exist in your child theme at app/widgets/advanced-list.php and templates/widgets/advanced-list.php. |
| Plugin not activated | Go to Plugins → Installed Plugins and verify the plugin is active. |
| Voxel or child theme not active | Both the Voxel theme and a child theme must be active. |
“Save Post Relationships” Action Missing from Dropdown
| Cause | Solution |
|---|---|
| Template not copied correctly | The plugin overrides the entire advanced-list.php widget file. Deactivate and reactivate the plugin. Verify app/widgets/advanced-list.php exists in your child theme. |
| Wrong Voxel version templates | If you recently upgraded Voxel, the old templates may still be installed. Deactivate and reactivate the plugin to detect the new version and install matching templates. |
Popup Doesn’t Open When Clicking the Action
| Cause | Solution |
|---|---|
| JavaScript error | Check the browser console (F12 → Console) for errors. The JavaScript depends on Voxel’s core scripts and jQuery — ensure they are loading correctly. |
| User not logged in | The popup requires authentication. Unauthenticated users are redirected to the login page. |
| Scripts not loading | The plugin’s CSS and JS are only loaded when the relationship action template is rendered. Verify the action is properly configured in Elementor. |
Popup Shows “No Posts Found”
| Cause | Solution |
|---|---|
| No published posts | The target post types must have published posts. Check that listings of the target type exist and are published. |
| Author restriction | If the relationship field’s “allowed authors” is set to author-only, only the current post author’s posts appear. Change to “any” in the Voxel type editor if needed. |
| Current post excluded | The current post is always excluded from the popup results (by design, to prevent self-referencing). |
Quick Action Mode Not Working
| Cause | Solution |
|---|---|
| Field doesn’t target only “profile” | Quick Action Mode only activates when the Post Field Key’s target post types contain exactly one entry and that entry is “profile.” Verify your relation field configuration in the Voxel type editor. |
| User has no profile | The user must have a Voxel profile post for the toggle to work. Ensure the user has created their profile. |
| Wrong Profile Field Key | Verify the Profile Field Key matches the relation field key on the Profile post type. |
Relationships Not Persisting
| Cause | Solution |
|---|---|
| No edit permissions | The current user must have edit permissions on the post. The plugin checks Voxel’s is_editable_by_current_user(). If the post is authored by another user and the current user isn’t an admin, the action will fail. |
| Max count reached | The relationship field may have a maximum count limit set. Check the field configuration in the Voxel type editor. |
Active State Not Showing on Page Load
| Cause | Solution |
|---|---|
| Popup Mode limitation | In Popup Mode, the button doesn’t show an active state on the page — the active state is shown inside the popup on individual items. This is by design. |
| Quick Action — wrong Profile Field Key | In Quick Action Mode, the active state is determined by checking the user’s profile field. Verify the Profile Field Key is correct and the relationship data exists. |
Template Overwrite Warning
The following template files in your child theme are managed by this plugin and will be overwritten on reactivation and updates:
app/widgets/advanced-list.php
templates/widgets/advanced-list.php
templates/widgets/advanced-list/save-post-relationship-action.phpIf you’ve customized these files, back up your changes before updating the plugin or deactivating/reactivating it.
“Voxel Theme Not Detected” or “Child Theme Not Detected” Error
The Voxel theme and a child theme must both be installed and active. Go to Appearance → Themes to verify.
For further support, visit codicts.com or contact us at support@codicts.com.