MyListing Private Gallery Field
The {CODICTS} MyListing Private Gallery Field plugin adds a new custom field type to MyListing that enables listing owners to upload images that are only fully visible to users with specific roles. Unauthorized users — including logged-out visitors — see a blurred version of the images instead, creating an exclusive, role-gated gallery experience on your directory site.
Requirements
Imagick required: The blur system depends on the Imagick PHP extension. Most managed WordPress hosts include it by default. Without Imagick, the plugin still protects privacy (images won’t be shown), but unauthorized users see broken image placeholders instead of attractive blurred previews.
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 copies its template files into your child theme. Navigate to any Listing Type editor to start adding the Private Gallery field and content block.
Key Features
| Feature | Description |
|---|---|
| Custom Field Type | Adds a “Private Gallery” field to the MyListing listing type editor for image uploads. |
| Custom Content Block | Adds a “Private Gallery” content block for displaying the gallery on single listing pages. |
| Role-Based Access Control | Full-resolution images are only visible to users with specified WordPress roles. Everyone else sees blurred versions. |
| Automatic Image Blurring | Blurred thumbnails are generated automatically using Imagick and cached on disk for fast loading. |
| Multiple Gallery Layouts | Choose from Carousel, Carousel with Preview, or Grid display styles. |
| Disable Interactions | Optionally prevent clicking, popup/lightbox, and hover interactions on blurred images. |
| Multi-Image Upload | Listing owners can upload multiple images with configurable file limits via AJAX uploads. |
| Blurred Image Caching | Blurred versions are generated once and cached — subsequent page loads serve the cached file instantly. |
| Automatic Cleanup | When original images are deleted, their cached blurred versions are automatically removed from disk. |
How It Works
The plugin operates through two components that work together — a field for uploading images and a content block for displaying them with role-based access control.
Setup Flow
1. An admin adds the “Private Gallery” field to a listing type’s form — this gives listing owners a file upload area when creating or editing listings.
2. The admin adds the “Private Gallery” content block to the listing type’s single page layout — this controls how the gallery is displayed to visitors.
3. On the content block, the admin selects which user roles can see the full-resolution images and chooses a gallery layout (carousel, carousel with preview, or grid).
Visitor Experience
When someone visits a listing page with a Private Gallery:
| Visitor Type | What They See |
|---|---|
| Not logged in | Blurred versions of all gallery images. |
| Logged in but without an allowed role | Blurred versions of all gallery images. |
| Logged in with an allowed role | Full-resolution original images with full gallery interaction. |
How blurring works: The first time an unauthorized user views a gallery image, the plugin uses Imagick to create a small (300×300px), heavily blurred version and saves it to disk. All future requests for that blurred image are served from the cache — no re-processing needed. When the original image is deleted, the cached blurred version is automatically cleaned up.
Adding the Private Gallery Field
The field controls the upload experience for listing owners when they create or edit a listing.
1. Edit a listing type in the MyListing admin.
2. Navigate to the Fields tab.
3. Look for the “{CODICTS} MyListing Private Gallery Field” quick-add button in the field sidebar, or manually add a field and select “Private Gallery” as the type.
4. Click to add the field, then configure its settings:
| Setting | Description |
|---|---|
| Label | The label shown above the upload area on the add/edit listing form. |
| Key | Unique field key used for data storage. The default is private-gallery. |
| Placeholder | Placeholder text for the upload input. |
| Description | Help text shown below the field. |
| Maximum number of uploads | Limit how many images a listing owner can upload. Leave empty for unlimited. |
| Required | Whether the field is mandatory when submitting a listing. |
| Show in Submit Form | Whether to display the field in the add/edit listing form. |
| Show in Admin | Whether to display the field in the WordPress admin editor. |
5. Save the listing type.
Supported Image Types
| Format | Extensions |
|---|---|
| JPEG | .jpg, .jpeg |
| PNG | .png |
| GIF | .gif |
| WebP | .webp |
Only image file types are accepted. Other file types are rejected during upload.
Adding the Private Gallery Content Block
The content block controls how the gallery is displayed on the single listing page and who can see the full images.
1. Edit the same listing type.
2. Navigate to the Single Page (or Profile) tab where you configure content blocks.
3. Add a new content block and select “Private Gallery” from the block list.
4. Configure the block settings:
| Setting | Description |
|---|---|
| Label | The section title displayed above the gallery on the listing page (e.g., “Exclusive Photos”). |
| Source Field | Select which Private Gallery field provides the images. Only fields of type “Private Gallery” appear here. |
| Gallery Type | The display layout for the gallery (see table below). |
| Allow access to user roles | Multi-select list of WordPress roles that can view the full-resolution images. Users with any of the selected roles see originals; everyone else sees blurred versions. |
| Disable actions | When enabled, prevents clicking to open the lightbox/popup and hovering interactions on blurred images. Only applies when images are blurred. |
5. Save the listing type.
Gallery Display Types
| Type | Description |
|---|---|
| Carousel | Horizontal scrolling image carousel. Images displayed at medium size. |
| Carousel with Preview | Carousel with a large preview image above the thumbnails. Images displayed at large size for higher quality. |
| Grid View | Responsive image grid layout. Images displayed at medium size. |
User Role Access Control
The “Allow access to user roles” setting is the core privacy mechanism. When a visitor views the listing page:
1. The block checks if the visitor is logged in.
2. If logged in, it checks whether the visitor has any role that matches the selected roles.
3. If there’s a match — original images are shown with full gallery interaction.
4. If there’s no match (or the visitor is logged out) — blurred versions are served instead.
Important: If no roles are selected in the “Allow access to user roles” setting, images will be blurred for everyone — including logged-in administrators — because no role can match an empty access list. Always select at least one role.
Example Setup
1. Activate the plugin with the MyListing theme and a child theme active. Verify Imagick is installed on your server.
2. Edit a listing type (e.g., “Real Estate” or “Profiles”).
3. On the Fields tab, click the “{CODICTS} MyListing Private Gallery Field” quick-add button. Configure the field with a label like “Exclusive Photos” and set a maximum of 10 uploads. Save.
4. On the Single Page tab, add a “Private Gallery” content block. Configure it:
a. Set the Label to “Exclusive Photos.”
b. Set the Source Field to the Private Gallery field you just created.
c. Set the Gallery Type to “Carousel with image preview.”
d. In Allow access to user roles, select the roles that should see full images — e.g., “Subscriber” and “Customer.”
e. Enable Disable actions to prevent unauthorized users from clicking or interacting with blurred images.
5. Save the listing type.
6. A listing owner creates a listing of this type and uploads photos via the “Exclusive Photos” field. The images are uploaded via AJAX with live preview.
7. When a logged-out visitor or a user without an allowed role views the listing, they see the “Exclusive Photos” section with blurred images and no click/hover interaction. This creates an incentive to register or upgrade.
8. When a user with the “Subscriber” or “Customer” role views the same listing, they see the full-resolution images in the carousel with full lightbox/popup interaction.
Frequently Asked Questions
Does this require a child theme?
Yes. The plugin copies template files into the child theme to register the Private Gallery field and content block with MyListing. Without a child theme, the plugin cannot function.
Does this require Imagick?
Imagick is strongly recommended. Without it, the plugin still protects image privacy (unauthorized users won’t see original images), but instead of blurred previews they’ll see broken image placeholders. Most managed WordPress hosts include Imagick by default.
Is there a settings page?
No. All configuration is done within the MyListing listing type editor — add the Private Gallery field to the form and the Private Gallery content block to the single page layout. Role access and gallery type are configured on the content block.
Which users see the full images?
Only logged-in users whose WordPress role matches one of the roles selected in the content block’s “Allow access to user roles” setting. Everyone else — including logged-out visitors and logged-in users with non-matching roles — sees blurred versions.
What happens if no roles are selected?
Images will be blurred for everyone, including administrators. Always select at least one role in the “Allow access to user roles” setting.
What image formats are supported?
JPEG (.jpg, .jpeg), PNG (.png), GIF (.gif), and WebP (.webp). Other file types are rejected during upload.
Can I limit how many images a listing owner can upload?
Yes. Set the “Maximum number of uploads” in the field settings within the listing type editor. Leave it empty for unlimited uploads.
What does “Disable actions” do?
When enabled on the content block, it prevents unauthorized users from clicking to open the lightbox/popup or hovering over blurred images. This only takes effect when images are blurred — users with allowed roles have full interaction. It adds an extra layer of protection beyond just blurring.
Are blurred images cached?
Yes. The first time a blurred version is needed, the plugin generates it and saves it to wp-content/uploads/codicts_private_gallery/. All subsequent requests serve the cached file instantly. When the original image is deleted, the cached blur is automatically cleaned up.
Can I manually clean up cached blurred images?
Yes. You can safely delete files in the wp-content/uploads/codicts_private_gallery/ directory. Blurred versions will be regenerated automatically the next time they’re needed.
Does the plugin create any database tables?
No. Image data is stored as post meta on the listing, blurred file paths are stored as attachment post meta, and a single options entry tracks the installed template version. No custom database tables are created.
What happens when the plugin is deactivated?
The template files are removed from the child theme and the Private Gallery field and block will no longer appear in the listing type editor. Existing gallery image data and cached blurred files remain on disk. Reactivating restores full functionality.
Troubleshooting
Images Not Being Blurred (Originals Shown to Everyone)
| Cause | Solution |
|---|---|
| No roles configured | Edit the listing type and check the Private Gallery content block’s “Allow access to user roles” setting. Select the roles that should see full images — if no roles are selected, the blur logic has no roles to check against. |
| Content block not added | The role-based access control is on the content block, not the field. Make sure you’ve added both the Private Gallery field (for uploads) and the Private Gallery content block (for display with access control) to the listing type. |
Broken/Missing Images for Unauthorized Users
| Cause | Solution |
|---|---|
| Imagick not installed | The blur system requires the Imagick PHP extension. Without it, blurred images return a # placeholder URL. Contact your hosting provider to install Imagick, or check with: <?php echo extension_loaded('imagick') ? 'Loaded' : 'Not loaded'; ?> |
| Cached blur file deleted externally | If a cached blurred file was deleted but the meta reference remains, the plugin will regenerate it. If this doesn’t happen, try re-saving the listing. |
Private Gallery Field Not Appearing in Listing Type Editor
| Cause | Solution |
|---|---|
| Templates not installed | Deactivate and reactivate the plugin to force-reinstall templates. Verify that templates/add-listing/form-fields/private-gallery-field.php exists in your child theme. |
| Plugin not activated | Go to Plugins → Installed Plugins and verify the plugin is active. |
| Quick-add button not visible | Refresh the page or navigate away and back to the Fields tab. The button is injected via JavaScript and requires the page to fully load. |
Gallery Images Not Uploading
| Cause | Solution |
|---|---|
| Server upload limit | Check your PHP configuration’s upload_max_filesize and post_max_size. Increase them if images exceed the limit. |
| Non-image file type | Only JPEG, PNG, GIF, and WebP files are accepted. Other file types are silently rejected. |
| Uploads directory not writable | Ensure wp-content/uploads/ is writable by the web server. |
“Too Many Files” Error
| Cause | Solution |
|---|---|
| File limit exceeded | The file limit is configured per-field in the listing type editor. Increase the “Maximum number of uploads” value, or leave it empty for unlimited uploads. |
Blurred Files Using Too Much Disk Space
| Cause | Solution |
|---|---|
| Accumulated cached blurs | Blurred images are stored in wp-content/uploads/codicts_private_gallery/. They are automatically cleaned up when the original attachment is deleted. You can also safely delete files in this directory manually — they will be regenerated on the next page view. |
Template Overwrite Warning
The following template files in your child theme are managed by this plugin and may be overwritten on reactivation:
templates/add-listing/form-fields/private-gallery-field.php
templates/single-listing/content-blocks/private-gallery-block.phpIf you’ve customized these files, back up your changes before deactivating/reactivating the plugin.
“MyListing Theme Not Detected” or “Child Theme Not Detected” Error
The MyListing 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.