UsageLast updated: 4 February 2026

Create a channel field

• Create/edit a channel field and choose fieldtype JCOGS Image Pro Field.
• Configure the field settings (tools enabled, defaults, restrictions).

See also:

• Field settings
• Template variables and precedence rules

Decide how “deterministic” templates should be

Before you hand the field to editors, decide your policy about where the definitive design choices relating to the site / images should rest:

• Template-driven output (most deterministic): set parameters like preset=, width=, height=, srcset=, sizes=, aspect_ratio= in the (JCOGS Image Pro, or JCOGS Image Pro Field) template tags.
• Field-settings-driven defaults (developer-controlled, low template noise): set field-level defaults, for example by attaching an unchangeable Default preset and set responsive breakpoints (srcset widths) so that when {field:img} produces its output, it is going to be consistent without needing the inclusion of per-template parameters.
• Editor-driven intent (more flexible): enable the relevant tools (crop, focal, art direction, preset choice) and let {field:img} reflect stored intent. As a developer you can still but guard-rails up around these choices - for example by limiting the options for preset or aspect ratio choices, so that the end product is still broadly in line with design expectations.

In all cases, explicit template parameters take precedence over stored editor intent.

Configure field settings (what each option means)

Allowed upload destinations

Restrict selection to a single upload directory when you want predictable source assets (permissions, governance, consistent image dimensions).

Presets

Presets are created / configured within the JCOGS Image Pro add-on control panel system.

• Enable presets: allows this field to apply an Image Pro preset.
• Allow editors to choose a preset:
  • Enabled: editors can pick a preset in the publish UI.
  • Disabled: editors cannot pick a preset; the Default preset becomes a developer-controlled forced preset (unless the template tag sets preset=...).
• Restrict presets + Allowed presets: limit which presets are available to editors (and therefore also which presets can be selected when editor choice is enabled).
• Allow “None”: editor-facing option to explicitly choose “no preset”.
• Default preset: used when there is no per-entry choice; still applies when editor preset choice is disabled (so you can force a preset, or force “None”).

Practical patterns:

• If you want editors to use exactly one preset: enable presets, disable “Allow None”, restrict presets to a single allowed preset, set it as default.
• If you want templates to control everything: set preset= (and any other key parameters) directly in templates. Template tag parameters are always respected and take precedence over field settings and stored editor intent.

Note: you can leave Enable presets off to keep the field UI simpler for editors, and still use preset= in templates.

Crop and aspect ratio

Crop tools store editor intent (crop rectangle, aspect ratio, offsets, etc.). The variable {field:img} will apply any saved crop intent to an image unless you have overridden the crop settings via parameters included in the tag.

• Enable crop: allows editor crop intent.
• Require crop: prevents saving until a crop exists.
• Aspect ratio choices + Default aspect ratio: constrain crops to approved ratios.
• Require an aspect ratio: disallows freeform crops (meaningful only when crop is enabled).

Responsive Defaults

Image Pro Field can author default srcset values in either width mode or density mode for {field:img} output.

• Width mode: use default width rows (for example 320, 480, 768, 1024).
• Density mode: use default density rows (for example 1x, 1.5x, 2x).
• Values in both panels are retained when switching modes, but only the selected mode is applied when defaults are generated.
• Template parameters still override field defaults.

The field also supports default allow_scale_larger so higher-density candidates can be generated when source dimensions would otherwise cap output.

Art direction

Enables a breakpoint grid against which editors can select alternate images per media query. If any alternates are configured for an entry, {field:img} will render a <picture> element with one or more <source> tags (using your breakpoint media rules) plus a fallback <img>.

Note: in art-direction mode, presets are handled per breakpoint row (inherit main / explicit preset / explicit none), so the main preset selector is hidden.

Focal point and face detection

Focal point stores where the subject is as two percentages (X/Y) on the original image.

Important: the field stores these values and exposes them to templates, but does not automatically change Image Pro processing based on focal point. The main intended use is styling (for example setting CSS object-position or background-position).

• Enable focal point: allows editors to set a focal point. The values are available as {field:focal_x}, {field:focal_y}, and {field:object_position}.
• Enable face detection: helper tool (only relevant when crop tools are enabled). It can speed up choosing a good focal point and/or a suggested crop.

Example usage:

<figure class="card">
    {my_image_field:img style="object-position:{my_image_field:object_position};"}
</figure>



    Template output
    


    Typical outputs:


    
{my_image_field} gives processed URL
    
{my_image_field:img} gives <img> (or <picture> when art-direction alternates exist)


    All image processing is delegated to JCOGS Image Pro.



    Recommended workflow:


    
Start with {field:img} using field-level defaults.
    
Once the design is stable, lock in deterministic output by specifying key parameters in templates (especially preset=, and sizes=).

                    
                    
                    
                    
                    
                    
                    
                    
                    
                    
                    
                    
                    
                    
                    
                    
                    
                

What you can do in this field depends on how the developer configured the field settings. Some sites may expose only the file picker, while others may allow presets, cropping, focal point, face detection, or art direction.

Important: this field lets you record your editorial intent (for example “use this crop” or “use this preset”). What appears on the page is ultimately determined by the developer’s templates, which may apply, ignore, or override parts of that intent to achieve consistent site-wide design.

In most builds this is a co-operative workflow: the developer exposes options specifically so you can actively improve how images look in context, while the templates apply those choices in a controlled, predictable way.

Tip: use the image preview in the publish form to sense-check your choices. It’s the quickest way to confirm that a preset, crop, or focal point is producing the kind of framing and emphasis you intended.

Select the main image

Use the field’s file picker to select the main image.

What this affects:

• This is the “master” image the site will output wherever this field is used.
• If art direction is enabled, this is also the fallback image for devices/breakpoints that don’t use an alternate.

Optional: choose a preset

If enabled by the developer, you may be able to choose an Image Pro preset.

What this affects:

• Presets are developer-defined recipes that control how the image is produced (for example size, crop behaviour, and quality).
• Choosing a preset usually changes how the image looks everywhere this field is used on the site.
• Use the image preview in the publish form to check how the preset affects the source image.

Optional: crop

If enabled, you can define a crop (and possibly choose an aspect ratio).

What this affects:

• Cropping lets you choose what part of the image is kept (useful when the same image appears in different layouts).
• Your crop is stored in a way that keeps the same framing even if the image is output at different sizes.
• Use the image preview in the publish form to check that the crop frames the subject as intended.

Optional: focal point / face detection

If enabled, you can set a focal point manually.

What this affects:

• A focal point marks the “most important” spot in the image (for example a subject’s face).
• Templates can use this to keep key content visible when images are cropped or shown in fixed-size boxes.
• Face detection (if available) is a helper that can suggest a good focal area.

Optional: art direction

If enabled, you can assign alternate images to breakpoint rows (media queries).

What this affects:

• Art direction lets you pick different images for different screen sizes (for example a wide crop for desktop and a tighter crop for mobile).
• When alternates are set, the template may output a responsive <picture> so each device can receive the most suitable version.
• Depending on the field setup, each breakpoint row may inherit the main preset, use its own preset, or use no preset.