Add listing image focal-point controls

[RabbiIslamRony]

PR Type

What kind of change does this PR introduce?

• Bugfix
• Security fix
• Improvement
• New Feature
• Refactoring (no functional changes, no api changes)
• Build related changes
• Text changes
• Other... Please describe:

Description

This PR adds listing-image focal-point controls to Directorist Core and keeps the editor preview compatible with the existing Fill, Fit, and Original Preview Image modes.

How to test the changes:

1. Open Directorist > Directory Builder > Add Listing Form, expand the Images field, and confirm Image Focal Point can enable or disable the editor.
2. From the frontend Add/Edit Listing form, upload or select a Preview image, set a non-centered focal point with drag, touch, keyboard, range, or preset controls, save the listing, and reopen it to confirm the coordinates persist.
3. Compare the editor with published archive cards in Fill, Fit, and Original modes using pixel and ratio sizing; also test Fit with blur and custom-color backgrounds.
4. Verify focal positioning on standard grid/list cards, Dashboard thumbnails, OpenStreetMap popups, Google Map popup markup, and the single-listing map popup.
5. Reorder or remove listing images and test Preview image, first Gallery image, default image, centered fallback, reset, desktop, and mobile behavior.

Any linked issues

No linked GitHub issue. Related support investigation: Directorist ticket #3199.

Checklist

• My code follows the WordPress coding standards

Summary

• Adds a frontend focal-point editor for the current listing Preview image.
• Keeps the editor preview aligned with Directorist's existing Fill, Fit, and Original image modes.
• Applies focal positioning to Core archive cards, Dashboard thumbnails, OpenStreetMap popups, Google Map popup markup, and single-listing map popups.
• Removes the destructive 150 × 150 single-listing popup pre-crop and lets the existing frame crop through CSS.
• Provides stable PHP, CSS, filter, and REST integration contracts for themes and extensions.

Product decision

• Keep the manual focal-point capability in Directorist Core rather than a separate extension.
• Keep the current release position-only with the existing x and y contract.
• Defer saved zoom until customer evidence justifies a Cover-only Core enhancement with image-quality and compatibility safeguards.

Compatibility

• Existing Preview Image option names and stored values remain unchanged.
• Listings without saved coordinates continue to use centered 50% 50% positioning.
• Fit mode keeps the full image visible and reproduces the configured blur or custom-color background.
• Original mode keeps its existing archive behavior while the editor uses the image's natural aspect ratio.
• Third-party templates remain opt-in through the documented helpers and neutral directorist-image-focal-point utility class.

Verification

• Cover, Fit, and Original editor previews were compared with published archive cards using pixel and ratio sizing.
• Fit mode was tested with blurred and custom-color backgrounds.
• Dashboard, OpenStreetMap, Google Map markup, single-listing map, preview/gallery/default fallbacks, reset, reopen, reorder, keyboard, disabled-state, desktop, and mobile flows were checked.
• PHP syntax, scoped PHPCS, focal-module ESLint, documentation Prettier, diff whitespace, and the legacy production build passed.
• The All Listings page rendered six cards without a PHP critical error after the final build.

Known local limitation

The configured Google Maps API project returns ApiProjectMapError locally, so the interactive Google popup could not be opened. The authenticated server-rendered popup markup, selected image fallback, focal utility class, and focal CSS variables were verified.

CI note

The repository's PHPCS workflow run stops in actions/checkout before dependencies are installed or PHPCS executes. The checkout action refuses to load a fork PR head inside the current pull_request_target workflow with its safe defaults. This is a base-workflow policy failure rather than a code-scan result. Scoped PHPCS, PHP syntax, JavaScript ESLint, diff whitespace, and the legacy production build passed locally.

Full product and compatibility document

View the complete Image Focal Point document

Directorist Image Focal Point

Status: Implemented in Directorist Core on codex/feature/image-focal-point
Document type: Product guide, use-case analysis, and packaging decision
Last reviewed: August 9, 2026

Executive decision

Keep the manual Image Focal Point capability in Directorist Core. Do not release it as a separate paid extension.

The feature controls how Directorist's existing preview image is cropped inside an existing listing card. Preview-image selection, card rendering, container dimensions, and fill/fit behavior already belong to Core. Focal-point control completes that workflow by allowing the listing owner to identify the important part of the image.

The Directorist Image Gallery extension should remain responsible for advanced multi-image gallery presentation. It may consume Core focal-point data in the future, but the basic focal-point control should not require Gallery or any other extension.

Product assessment: high potential as a Core quality feature, low potential as a standalone extension.

The problem in plain language

Directorist listing cards usually display images inside fixed or responsive containers. When the source image and card have different shapes, object-fit: cover fills the card by cropping part of the image.

The browser normally crops from the center. That can hide the important subject:

• A person's face can be cut off.
• The front of a car can disappear.
• A building entrance can fall outside the card.
• Text or a logo near an edge can be removed.
• The image can look correct on desktop but wrong on mobile.

Image Focal Point lets the listing owner say, “Keep this part visible.” It does not cut, resize, or modify the original image. It only changes the visual position used when Directorist displays the cropped card image.

What the feature does

The frontend Add/Edit Listing form shows a permanent Image focus panel beneath the current Preview image. It always explains the current state:

• Center (default): no custom focal point is stored.
• Custom: the listing owner selected a non-centered position.

From that panel, the owner can:

• Open the editor with Set image focus or Edit focus.
• Drag a marker directly over the important subject.
• Set horizontal and vertical percentages.
• Use Top, Center, or Bottom presets.
• See a live listing-card crop preview.
• Reset the position to the default center from either the panel or editor.
• Cancel without changing the saved position.

For an existing published listing, the Dashboard More menu includes Edit image focus. That shortcut opens the normal Edit Listing form and moves keyboard/visual focus directly to the image-focus panel. It does not create a separate inline editor on the public listing page.

Directorist saves the chosen point and uses it when the preview image is rendered in Core archive cards.

The current feature deliberately controls position only. It does not enlarge the image or save a zoom level. This keeps the editor predictable across Directorist's Cover, Fit, and Original image modes and preserves the existing x/y integration contract.

flowchart LR
    A["Administrator enables Image Focal Point"] --> B["Listing owner uploads or reorders images"]
    B --> C["Current Preview image shows its focus status and actions"]
    C --> D["Owner selects the important point"]
    D --> E["Directorist saves X and Y percentages"]
    E --> F["Core listing card uses object-position"]
    F --> G["Important subject remains visible across crops"]

Loading

Who uses it

Directory administrator

The administrator decides whether the control is available for a directory's Images field.

Path:

1. Open Directorist > Directory Builder.
2. Open Add Listing Form.
3. Expand the section containing Images.
4. Expand the Images field.
5. Enable or disable Image Focal Point.
6. Update the directory configuration.

The option is enabled by default. Existing directory configurations that do not contain the new option also behave as enabled, which makes the feature backward-compatible.

Listing owner

The listing owner controls the crop without needing WordPress admin access or image-editing software.

Steps:

1. Open the frontend Add Listing or Edit Listing form. For a published listing, the owner can also use Dashboard > My Listings > More > Edit image focus.
2. Upload one or more images.
3. Make the intended image the Preview image by moving it to the first position.
4. Check whether the panel says Center (default) or Custom.
5. Click Set image focus or Edit focus.
6. Drag the marker, move the horizontal/vertical sliders, or select a preset.
7. Check the live Listing card preview.
8. Click Done.
9. Save or preview the listing.

If another image is moved into the Preview position, the control follows the new Preview image. Previously saved focal points remain associated with their listing images.

Directory visitor

The visitor does not interact with any extra control. They simply see a better-positioned listing image.

Primary use cases

Directory type	Cropping problem	Focal-point result
Real estate	A building, room feature, or entrance sits away from the center	Keeps the property feature visible on grid and mobile cards
Automotive	The vehicle is photographed from one side or with empty space	Keeps the car, wheel, badge, or front section in frame
Restaurants	The plate or food subject is positioned near an edge	Keeps the dish visible instead of showing mostly background
Hotels and travel	A room, landmark, or person is cropped differently across cards	Preserves the main visual subject across responsive layouts
Professional directories	A person's face is above the center of a portrait	Prevents faces and heads from being cropped out
Product marketplaces	The product occupies only part of a lifestyle photo	Keeps the actual product in view
Brand and service listings	A logo or embedded text is not centered	Keeps important brand content readable

Benefits

Benefits for listing owners

• Gives visual control without requiring Photoshop or a new upload.
• Uses the original image non-destructively.
• Provides an immediate preview before saving.
• Reduces trial-and-error caused by unknown card dimensions.
• Works for both existing media attachments and new uploads.

Benefits for directory administrators

• Produces more consistent, professional listing cards.
• Reduces complaints about incorrectly cropped images.
• Avoids asking every owner to prepare images in one exact aspect ratio.
• Can be enabled or disabled per directory through the existing builder workflow.
• Improves visually sensitive directories such as property, vehicle, hotel, restaurant, and professional listings.

Benefits for visitors

• Makes listings easier to scan because the meaningful subject stays visible.
• Improves visual trust and perceived listing quality.
• Reduces confusing or empty-looking crops.
• Preserves the subject as card width changes between desktop and mobile.

Benefits for Directorist as a product

• Completes the existing Preview Image Settings workflow.
• Adds a recognizable modern-media editing pattern.
• Improves Core without introducing a heavy runtime or image-processing service.
• Creates a stable focal-point API that themes, blocks, mobile clients, and extensions can consume.
• Differentiates card presentation without competing with the Image Gallery extension's purpose.

How it works technically

1. Builder control

The Core Images preset field contains an enable_image_focus toggle. This keeps the capability aligned with Directorist's directory-specific Add Listing Form builder.

Implementation:

• includes/modules/multi-directory-setup/builder-preset-fields.php
• templates/listing-form/fields/image_upload.php

2. Frontend editor

After the EZ Media Uploader initializes, Directorist adds a persistent status/action panel for the current Preview item. Reordering or replacing the Preview image immediately updates the panel to that image's saved state. The editor supports mouse, touch, keyboard arrows, range inputs, presets, focus trapping, Escape-to-close, and a mobile scroll layout.

The Dashboard shortcut adds directorist_edit_focus=1 to the normal Edit Listing URL. The Add Listing script then finds the image field regardless of its builder section label, scrolls it into view, highlights the panel briefly, and focuses its primary action.

Implementation:

• assets/src/js/global/components/image-focal-point.js
• assets/src/js/global/add-listing.js
• assets/src/scss/component/_add-listing.scss

3. Data model

Coordinates are saved as percentages from 0 to 100:

x = horizontal position
y = vertical position

Example:

{
  "55": {
    "x": 50,
    "y": 10
  }
}

The map is saved in listing meta:

_directorist_image_focal_points

The attachment ID is the map key. The data is listing-specific rather than globally attached to the Media Library item. Therefore, the same attachment can use different positions in different listings.

The centered default does not need its own stored record. When the owner uses Reset to center and saves the listing, Directorist removes that Preview image's custom focal entry. Existing consumers still receive and render the safe 50 / 50 fallback.

All submitted coordinates are numeric, sanitized, and clamped to the 0–100 range. A submitted Preview image must resolve to one of the images selected for that listing.

Implementation:

• includes/helper-functions.php
• includes/classes/class-add-listing.php
• includes/classes/class-submission-controller.php

4. Rendering

Core archive images receive two CSS custom properties:

--directorist-image-focus-x: 50%;
--directorist-image-focus-y: 10%;

Directorist applies them through:

object-position: var(--directorist-image-focus-x, 50%)
  var(--directorist-image-focus-y, 50%);

The 50% 50% fallback preserves the old centered behavior for listings without focal-point data. Core applies the position to archive cards, map popup images, and Dashboard listing thumbnails. The editor reads the same normalized Preview Image configuration as the archive renderer:

• Fill with Container previews the configured frame with object-fit: cover.
• Fit with Container previews the configured frame with object-fit: contain and the selected blur or color background.
• Original previews the source image at its natural aspect ratio instead of forcing the configured crop frame.

Focal data remains editable in every mode because map, Dashboard, custom-template, or future card surfaces may still crop the image.

Implementation:

• includes/model/Listings.php
• includes/model/SingleListing.php
• includes/model/ListingDashboard.php
• assets/src/scss/component/listings/_listing-card.scss

5. Theme and extension integration

Templates that own their image markup can opt into the same behavior without copying Core storage logic:

<?php
$listing_id    = get_the_ID();
$attachment_id = directorist_get_listing_thumbnail_id( $listing_id );
$focus_style   = directorist_get_listing_image_focal_point_style( $listing_id, $attachment_id );
$display       = directorist_get_listing_preview_image_display_config();
?>

<div class="directorist-thumnail-card <?php echo esc_attr( $display['container_class'] ); ?>" style="<?php echo esc_attr( $display['container_style'] ); ?>">
    <img
        class="directorist-image-focal-point"
        src="<?php echo esc_url( wp_get_attachment_image_url( $attachment_id, $display['image_quality'] ) ); ?>"
        alt="<?php echo esc_attr( get_the_title( $listing_id ) ); ?>"
        style="<?php echo esc_attr( $focus_style ); ?>"
    >
</div>

directorist-image-focal-point sets only object-position; it does not impose dimensions or object-fit. Custom templates remain responsible for their own frame and crop behavior.

The normalized display configuration is filterable through directorist_listing_preview_image_display_config. Saved coordinates remain filterable through directorist_listing_image_focal_point.

6. REST API

Directorist REST listing image objects include a focal_point value so non-PHP consumers can reproduce the same crop:

{
  "focal_point": {
    "x": 50,
    "y": 10
  }
}

Implementation:

• includes/rest-api/Version1/class-listings-controller.php
• includes/rest-api/Version2/class-listings-controller.php

7. Cleanup and fallback behavior

• Removing all listing images removes saved focal-point data.
• Removing individual images removes coordinates that no longer belong to selected listing images.
• Changing the Preview image updates the saved featured/preview attachment order.
• Reopening a published listing restores its saved Custom position and panel state.
• Resetting to center removes the custom entry when the listing is saved.
• Invalid or missing values fall back to center.
• If the feature is disabled in the builder, the focal-point UI and focal submission are not added.

Current scope

Included now:

• Directory Builder toggle on the Core Images field.
• Frontend Add/Edit Listing focal-point editor.
• Persistent default/custom status and reset actions for the Preview image.
• Dashboard shortcut for returning directly to the focus control on published listings.
• Existing and newly uploaded image support.
• Preview-image reorder resolution.
• Listing-scoped storage and cleanup.
• Core archive-card rendering.
• Core Google Map and OpenStreetMap popup rendering.
• Core single-listing map popup rendering without destructive pre-cropping.
• Dashboard listing-thumbnail rendering.
• Mode-aware Fill, Fit, and Original editor previews.
• Public PHP helper, filter, CSS utility class, and REST integration contract.
• REST v1 and v2 response data.
• Desktop and mobile behavior.
• Keyboard-accessible controls.

Not included now:

• A focal-point picker in the legacy WordPress admin listing-image metabox.
• Saved crop zoom or image scaling.
• Automatic face, object, or AI subject detection.
• Separate positions for desktop, tablet, and mobile.
• Different focal points for different card templates or aspect ratios.
• Automatic modification of arbitrary third-party markup that bypasses Core; those templates must use the documented opt-in API.
• Advanced per-image Gallery extension editing.

Zoom decision

Current decision

Do not add saved zoom to the first Core focal-point release.

The present control answers one clear question: which part of the image should survive a crop? Saved zoom answers a different question: how tightly should Directorist crop the subject? Combining both immediately would turn the lightweight focal picker into a full crop editor and expand the storage, rendering, REST, compatibility, and image-quality requirements.

An editor-only magnifier is also not recommended right now. If the user can zoom while editing but that zoom is not reflected in the published image, the preview becomes misleading. Any future zoom control must represent a saved visual result rather than temporary inspection magnification.

Why zoom is deferred

Consideration	Focal point today	Additional zoom impact
Image modes	Position remains useful in every mode	Zoom is meaningful for cropped Cover surfaces; Fit and Original should ignore it
Responsive cards	Percent coordinates adapt safely to different sizes	One scale value can create noticeably different crops across card aspect ratios
Image quality	Does not enlarge the source image	Excessive scaling can expose blur and low-resolution uploads
Stored data and REST	Stable x and y values	Requires a new sanitized value and an updated public response contract
Theme compatibility	Neutral utility changes only object-position	Scaling requires an overflow frame, transform rules, and protection from theme transforms
User experience	One simple marker and two coordinates	Adds crop strength, reset state, mode-specific visibility, and more explanation

Safe future implementation contract

Reconsider basic zoom only after repeated customer requests or usage evidence shows that repositioning alone does not solve common crops. If implemented, use these constraints:

1. Treat basic manual zoom as a later Core enhancement, not as its own extension.
2. Show and apply it only where the rendered surface intentionally uses Cover-style cropping. Fit and Original must remain complete or natural-size images and ignore zoom.
3. Save a listing-and-attachment-specific numeric value with 1 as the backward-compatible default. A practical first range is 1 to 2, subject to image-quality validation.
4. Sanitize and clamp the submitted value on the server, just like focal coordinates.
5. Warn or limit the control when the uploaded source cannot support the effective rendered size without visible upscaling.
6. Make the editor reproduce the exact zoomed crop before saving on desktop and mobile.
7. Version and document any REST change. A possible future shape is {"x":45,"y":30,"zoom":1.25}, but the current response remains x and y only.
8. Add a new opt-in zoom helper/class instead of silently making directorist-image-focal-point apply transforms. The existing utility must remain neutral and safe for third-party templates.
9. Test every supported cropped Core surface and provide a centered, 1× fallback for old listings and custom templates.

Device-specific zoom, separate zoom values per card ratio, AI smart cropping, and advanced per-gallery-image crop tools belong in a broader Gallery or Smart Media capability rather than the basic Core focal control.

Product potential assessment

This assessment is based on the implemented workflow, the reported client problem, Directorist's current image architecture, and established focal-point behavior in WordPress and Shopify. It is not based on Directorist usage telemetry or a large customer survey.

Product dimension	Assessment	Reason
Breadth of use	High	Almost every visual directory uses listing preview images
Severity when needed	High	A bad crop can hide the actual person, property, product, or vehicle
Frequency	Medium to high	It appears whenever source and card aspect ratios differ
User learning cost	Low	Dragging a marker and checking a preview is familiar and visual
Runtime cost	Very low	Rendering uses two small values and one CSS property
Storage cost	Very low	One small listing-meta map stores percentage coordinates
Compatibility risk	Low to medium	Core templates work automatically; custom templates may need adoption
Standalone willingness to pay	Low	Users normally expect basic image positioning to work without an add-on
Core differentiation value	High	It visibly improves listing quality across many directory niches

Potential conclusion

The feature has strong adoption potential because it solves a common visual defect with little setup or performance cost. Its strongest value is retention, perceived quality, and fewer crop-related support requests—not direct standalone add-on revenue.

Core versus extension decision

Decision factor	Core feature	Separate extension
Owns the Preview image and card crop	Yes	No
Needed across many directory niches	Yes	Yes, but an extra install adds friction
Changes a business workflow	No	Extensions are better suited to new workflows
Requires an external service	No	No extension boundary is necessary
Has meaningful standalone monetization	Limited	Weak standalone product proposition
Overlaps Directorist Image Gallery	No; it improves the Core preview image	An extension could confuse customers about Gallery ownership
Backward-compatible fallback	Yes, centered crop	Extension activation would create inconsistent base behavior
Support simplicity	One Core behavior	Extra compatibility, licensing, activation, and support surface

Final packaging decision

Ship the manual focal-point picker as a Directorist Core image capability.

Do not make users install or purchase an extension to fix the crop of a Core listing preview image. Treat this as a quality and usability improvement to the existing Core Images field and archive renderer.

Relationship with the Image Gallery extension

Directorist Image Gallery remains a separate extension because it adds a broader gallery workflow: unlimited gallery images, gallery layouts, columns, lightbox behavior, custom dimensions, and gallery cropping.

Recommended boundary:

• Core: preview-image selection, manual focal point, centered fallback, archive-card crop rendering, and REST focal data.
• Image Gallery extension: multi-image gallery presentation, lightbox, gallery columns, gallery-specific sizing, and future per-gallery-image controls.

Future Gallery integration should read the Core focal-point API rather than duplicate storage or create a second incompatible picker.

When a premium media feature would make sense

A future premium Gallery or “Smart Media” capability could be justified if it adds substantial functionality beyond the manual Core control, such as:

• Automatic face or object detection.
• AI-recommended focal points.
• Bulk focal-point editing for many listings.
• Different focus rules per device or layout.
• Per-gallery-thumbnail focal points.
• Automated quality warnings for low-resolution or badly composed images.
• Media optimization, smart crops, or externally generated derivatives.

The simple manual picker should remain the shared Core foundation for those advanced features.

Recommended rollout

Core release

1. Keep the Directory Builder option enabled by default.
2. Announce it as “Keep the important part of listing images visible on every card.”
3. Document the frontend Add/Edit Listing workflow.
4. Include backward compatibility and REST behavior in developer notes.
5. Test Core grid, list, search-result, category, location, and mobile archive surfaces.

Follow-up Core improvements

1. Add parity to the legacy WordPress admin listing-image metabox.
2. Confirm import/export and listing-clone workflows copy or intentionally reset focal metadata.
3. Add automated PHP and browser regression coverage.
4. Confirm React/block/mobile clients consume the REST focal-point value.
5. Review support evidence before designing the deferred Cover-only zoom contract.

Optional Gallery enhancement

1. Read the Core focal_point REST value.
2. Apply it to Gallery thumbnails that use cover cropping.
3. Consider per-image editing only if the Gallery product needs it.

Acceptance criteria

The feature is ready when all of the following are true:

• The builder toggle is visible and does not require resetting an existing directory.
• The control appears only when enabled and a Preview image exists.
• Existing and newly uploaded Preview images can save a focal point.
• Reordering images preserves the correct Preview attachment.
• The saved coordinate reloads in the editor.
• Published listings expose an Edit image focus shortcut from the listing Dashboard.
• The Add/Edit Listing media panel clearly reports Center (default) or Custom.
• Resetting to center returns the UI to its default state and removes custom metadata after submission.
• Core archive cards use the stored position.
• Fill, Fit, and Original editor previews reflect their active Core mode.
• Fit preview shows the complete image and configured background treatment.
• Original preview does not force the configured crop ratio.
• Google Map, OpenStreetMap, single-listing map, and Dashboard thumbnails use the stored position.
• The documented third-party utility class and PHP helpers reproduce the focal position without forcing template dimensions.
• Listings without focal metadata remain centered.
• Invalid values cannot escape the 0–100 range.
• Removed images do not leave active focal data.
• Desktop, keyboard, touch, and mobile modal flows remain usable.
• REST consumers receive a predictable x and y pair.
• The current release does not save or apply zoom, and the neutral focal utility does not impose transforms.

Verification completed for the current implementation

• The editor and published archive were compared in Fill, Fit, and Original modes with pixel and ratio sizing.
• Fit mode reproduced both custom-color and blurred-background treatments while keeping the complete image visible.
• Original mode displayed an 823 × 1024 source at its natural aspect ratio without the configured crop frame.
• Custom, centered, reset, reopened, reordered Preview-image, and Dashboard shortcut states were exercised.
• The Dashboard 44 × 44 cover thumbnails rendered custom focal values and retained 50% 50% for default images.
• OpenStreetMap popup images rendered the focal utility class, custom CSS variables, and cover positioning.
• Google Map popup markup rendered the selected Preview/gallery source, focal utility class, and CSS variables. Interactive Google rendering remained unavailable locally because the configured API project returns ApiProjectMapError.
• The single-listing popup used a proportional 300 × 173 attachment source instead of a destructive 150 × 150 pre-crop, then applied focal positioning in CSS.
• Disabling the existing builder option removed the toolbar and editor completely.
• Keyboard movement updated the coordinates and preview, and the 390 × 844 modal stayed within its viewport without internal horizontal overflow.
• PHP syntax checks passed for all changed PHP files.
• The focal-point JavaScript module passed the repository ESLint rules.
• The legacy production build completed successfully.
• Browser QA used query-scoped filters only; the temporary QA bootstrap was removed and no listing or Directorist setting was changed.

External product and UX references

• WordPress FocalPointPicker developer documentation explains that focal points solve unwanted cropping across aspect ratios and can drive CSS object-position.
• WordPress Cover block documentation exposes a focal-point picker as a standard image setting.
• Shopify image documentation describes focal points as a way to keep the important image area in frame across screen sizes and theme crops.
• Directorist All Listing Settings already places preview-image quality, fill/fit, container dimensions, and background behavior in Core.
• Directorist Image Gallery documentation defines the extension around multi-image gallery layouts, gallery cropping, columns, and display—not basic Core preview-image positioning.