Creates an image-object to render <picture> and <img> tags.

Image-Object

An image-processing class for use within Rendering Hublify-CMS-Templates.

An instance of this class represents a Hublify-MAM-Asset that can be transformed and saved into the Hublify CMS's special file-cache, without changing the original MAM-Asset-File.

This class is designed to generate:

• URLs of transformed / cached image-files, or ...
• complete <img>-tags of transformed / cached files, or ...
• complete <picture>-tags of transformed / cached files.

Syntax

To create a new image object:

image(?string $assetLabel = null, ?array $assetData = null): hublify_var_ext_image

Parameter

• $assetLabel
  The MAM-AssetLaber.
  
  
• $assetData
  Optional asset data. Can be set later or is retrieved later inside dynamically.
  See function assetData(...) for details, below!

Return

Returns the image-object.

Examples

Some quick examples as an overview of the generic capabilities of this image-object.

Responsive picture

Very simple, very useful! 

Assuming you have an image-asset stored in your Hublify-MAM under the label "myMAMLabel" and assuming you have pic_config "default" in your Render-ENV, you just need to call:

Source (twig)

{{ hublify.image('myMAMLabel').render_picture('default') }}

Output (html)

<picture>
    <source type="image/webp" media="(max-width: 576px)" srcset="cache/res/my-super-pic.w576.webp" />
    <source type="image/webp" media="(max-width: 1024px)" srcset="cache/res/my-super-pic.w1024.webp" />
    <source type="image/webp" media="(max-width: 2048px)" srcset="cache/res/my-super-pic.w2048.webp" />
    <source type="image/webp" media="(min-width: 2049px)" srcset="cache/res/my-super-pic.w-full.webp" />

    <img src="/files//products/my-super-pic.jpg" alt="See this!" title="Hublify,YEAH!" />

</picture>

Inline Transformations

For example to crop an image (100x100 pixel, from top-left) and to store it in webp-format, just call:

{% set myImg = hublify.image('mam-f5ea66df').crop(100,100,'tl').format('webp') %}

<img src="{{ myImg.url() }}">

Render: <picture> ...

With this image-object you can easily render complete <picture> elements.

In order to render a picture-element, you need to specify the viewport-breakpoints / image-widths (pixel) that you would like. This can be done in multiple ways. Choose which ways suit best for you:

• Configure in H-CMS' Render-ENV.
  Central comfortable version. Less necessity to hardcode details in your twig-templates.
  
  
• Configure parameters in twig-templates.

Of course, you can both ways in parallel.

Render-ENV

You can configure one or more picture-render-configs in the central Hublify-CMS's Render-ENV.
The benefit of this is, that you do not have to hardcode in your templates the breakpoints / max-widths / etc. you want to use.

Render-ENV Config, Example

{
    "env": {
        ...

        "pic_configs": {

            "<picEnvCfg-Label>": {         // (required) Set your own label(s).

                "picSources": [            // (required) Define as many following "w_max"es, as you like!

                    {                      // ---- Example Entry #1  (most simple)
                        "w_max": 576,      // (required) Max-Width (pixel)
                    },

                    {                      // ---- Example Entry #2  (with all possible variables)
                        "w_max": 1024,         // (required) Max-Width (pixel)
                        "format": "webp",      // (optional, default "webp") Target-Graphicfile-Format. Allowed: "webp|png|jpg|gif".
                        "quality": 100,        // (optional, default "82") Target-Compression-Quality (0-100).

                        "img_transformation": "<imgTransLabel>", // (optional) Refer from here to a transformation, below.
                                                                 // See section in JSON:  "imgTransformations"

                        "media": "<tr-label>", // (optional)    
                        "sizes": "<tr-label>", // (optional) Reserved / Not implemented, yet.
                    },

                    ...
                ]
            }
        },

        // ------------------------  Generic Hublify-Image-Transformation-Configs
        "imgTransformations": {
            "<imgTransLabel>": [
                {
                    "func": "<function>",     // (required) E.g. "resize"
                    "params": {               // (optional) Necessary parameters depend on chosen "func"!
                        "width": 1024,
                        ...
                    }
                },
                ...
            ]
        }
    }
}

Simple, ENV Example

This defines a pic-config "default", just with the max-width-image-sizes.

...
    "env": {
        ...
        "pic_configs": {
            "default": {
                "picSources": [
                    { "w_max": 576 },
                    { "w_max": 768 },
                    { "w_max": 992 },
                    { "w_max": 1200 },
                    { "w_max": 1400 },
                   { "w_max": 4096 }
                ]
            }
        }
    }

If you want to learn more about the render environments: Render-Environments

Inline Parameter

Instead of using the configuration via Hublify CMS' Render-Env, you can pass all configs as parameters directly.

yet to document ...

Render: <img> ...

With this image-object you can easily render complete <img> elements!

See below functions for setting, also:  css-class, -style, lazy-loading, alt- and title-texts.

Source (twig)

{{ hublify.image('mam-f5ea66df').crop(100,100,'tl').format('webp').render_image() }}

Output (html)

 <img src="/cache/res/aProductPic.cph100w100.webp" alt="Produkc!" title="Hublify,YEAH!" />

Render: url

Alternatively, you can have the image transformed and get only the resulting server-relative url-path.

Source (twig)

{{ hublify.image('mam-f5ea66df').crop(100,100,'tl').format('webp').url() }}

Output (html)

 /cache/res/aProductPic.cph100w100.webp

Functions

Once you have a image-object, you can use following functions on it (before rendering).

addTransformations(...)

Appends transformations.

These are not directly executed. This function can be called multiple times.

Syntax

addTransformations(?array $transformations): bool

• $transformations One or more transformations.
  Numerical array containing objects of the structure:

[
     {
         "func": "<transformation-func>",    // (required) See
         "params": { ... }                   // (optional/required) Depends on the trans-func!
     },
     ...
 ]

alt(...)

Sets the "alt"-attribute string.

If this is NULL the alt-text, configured in the Hublify-MAM for this asset is used.

Syntax

alt(?string $str): hublify_var_ext_image

assetData(...)

Presets internal properties, needed for rendering from MAM-Asset-Data.

Use this function for better performance!

If you have this asset-data already available anyhow, for example within product-list-data, you will want to pass it into here to simply skip any redundant MAM/DB-Queries!

Syntax

assetData(?array $assetData): hublify_var_ext_image

$assetData should contain (other keys are simply ignored):

[mb_label] - string|null (optional)

[mb_path] - string (optional, default NUL) If this is present, it is used in order
            to skip later MAM-DB-Querying.

[mb_meta] - array|null (optional)

[mb_alt] - string|null (optional)

[mb_title] - string|null (optional)

blur(...)

Adds a blur-filter-step to the image-process.

Syntax

blur(int $radius = 5, int $sigma = 2): hublify_var_ext_image

charcoal(...)

Adds a charcoal-filter-step to the image-process.

Syntax

charcoal($radius = 5, $sigma = 2): hublify_var_ext_image

class(...)

Sets the "class"-attribute string.

Syntax

class(?string $str): hublify_var_ext_image

clearTransformations(...)

Clears previously added transformations.

INFO: This can not UNDO any already executed tronsformations on the file, of course!

Syntax

clearTransformations(): bool

crop(...)

Extracts a region of the image.

Syntax

crop($width, $height, string $mode = 'cc'): hublify_var_ext_image

• $width
  The width
  
  
• $height
  The height
  
  
• $mode
  • "tl" - Top-Left
  • "tc" - Top-Center

  • "tr" - Top-Right

  • "cl" - Center-Left

  • "cc" - Center-Center

  • "cr" - Center-Right

  • "bl" - Bottom-Left

  • "bc" - Bottom-Center

  • "br" - Bottom-Righ
    
    

cropexact(...)

Syntax

cropexact($width, $height, $x = null, $y = null): hublify_var_ext_image

format(...)

Syntax

format(?string $format, ?array $params = null): hublify_var_ext_image

Formats: webp, png, jpg, gif

generateTransformationLabel(...)

Generates and sets a transformation-label. If no transformations are yet configured, NULL is set and returned.

Syntax

generateTransformationLabel(): ?string

getTransformationLabel(...)

Syntax

getTransformationLabel(): ?string

getTransformations(...)

Returns the currently set transformations.

The returned numerical array contains objects of this structure:

 [
     {
         "func": "<transformation-func>",
         "params": { ... }
     },
     ...
 ]

Syntax

getTransformations(): array

grayscale(...)

Sets the grayscale-step to the image-process.

Syntax

grayscale(): hublify_var_ext_image

lazy(...)

Activates the loading-lazy image-attribute.

Syntax

lazy($lazy = true): hublify_var_ext_image

mirror_hz(...)

Sets the horizontal-mirror-step to the image-process.

Syntax

mirror_hz(): hublify_var_ext_image

mirror_vt(...)

Sets the vertical-mirror-step to the image-process.

Syntax

mirror_vt(): hublify_var_ext_image

render_picture(...)

Renders a complete responsive picture-html-element and creates / caches all necessary image-files.

Syntax

render_picture(?string $picEnvCfg = null, ?array $params = null): string

Quick-Dump of Comment:

     * @param string|null $picEnvCfg The label of config within H-CMS' render-environment.
     *
     * @param array|null $params
     * [picEnvCfg] - string (optional, default NULL)
     *    or
     * [picSources] - array (optional, default NULL
     *   [w_max] - int (required) The max-width in pixels.
     *   [img_transformation] - string (optional) An image-transformation-label for transf-process to use.
     *                          If  not given, a simple "resize()"-transformation is used.
     *   [media] - string (optional) If not given it is autogenerated as:   "(max-width: <w_max>px)".
     *             Else, e.g. "(max-width: 736px)", "(orientation: landscape)", "(orientation: portrait)"
     *   [sizes] - mixed (optional) Reserved - NOT IMPLEMENTED, yet!
     *
     * [transformationConfigs] - array (optional, default NULL) array of multiple transformation-arrays.
     *
     * [alt] - string (optional, default NULL) If NULL, the "alt"-text from the MAM is used, if set there.
     * [title] - string (optional, default nULL) If NULL, the "title"-text from the MAM is used, if set there.
     * [style] - string (optional, default NULL) CSS-Style-string, will be applied to the <img>-tag.
     * [class] - string (optional, default NULL) CSS-Class-string, will be applied to the <img>-tag.
     *
     * [transformationConfigs] - array (optional, default NULL) array of multiple transformation-arrays.
     *
     *
     * @return string Returns the rendered <picture>-element.

Example: "(twig) inline picture transformations"

{% set cfg = {
  "picSources": [
    {
      "w_max": 768,
      "quality": 90,
      "media": "(max-width:992px)"
    },
    {
      "w_max": 576,
      "quality": 90,
      "media": "(min-width:992px)"
    }
  ]
} %}

{{ hublify.image().render_picture(null, cfg) }}

resize(...)

Adds a resize-step to the image-process.

Syntax

resize($height, $width = 0, bool $bestFit = false): hublify_var_ext_image

$height The new image-height in pixel. If "0" then it will be scaled proportionally to new width. 

$width The new image-width in pixel. If "0" then it will be scaled proportionally to new height.

$bestfit 

setTransformationLabel(...)

Syntax

setTransformationLabel(?string $label): hublify_var_ext_image

strip(...)

Sets the strip-step to remove meta-payload-data to the image-process.

Syntax

strip(): hublify_var_ext_image

style(...)

Sets the "style"-attribute string.

Syntax

style(?string $str): hublify_var_ext_image

title(...)

Sets the "title"-attribute string.

If this is NULL the title, configured in the Hublify-MAM for this asset is used.

Syntax

title(?string $str): hublify_var_ext_image

transform(...)

Transforms and caches the image and gets all data on that.

Syntax

transform(?string $picEnvCfg = null, ?array $params = null): array

Source-Code Comment:

    /**
     * Transforms and caches the image and gets all data on that.
     *
     *
     * @param string|null $picEnvCfg The label of config within H-CMS' render-environment.
     *
     * @param array|null $params
     * [picEnvCfg] - string (optional, default NULL)
     *    or
     * [picSources] - array (optional, default NULL
     *   [w_max] - int (required) The max-width in pixels.
     *   [img_transformation] - string (optional) An image-transformation-label for transf-process to use.
     *                          If  not given, a simple "resize()"-transformation is used.
     *   [media] - string (optional) If not given it is autogenerated as:   "(max-width: <w_max>px)".
     *             Else, e.g. "(max-width: 736px)", "(orientation: landscape)", "(orientation: portrait)"
     *   [sizes] - mixed (optional) Reserved - NOT IMPLEMENTED, yet!
     *
     * [transformationConfigs] - array (optional, default NULL) array of multiple transformation-arrays.
     *
     * [alt] - string (optional, default NULL) If NULL, the "alt"-text from the MAM is used, if set there.
     * [title] - string (optional, default nULL) If NULL, the "title"-text from the MAM is used, if set there.
     * [style] - string (optional, default NULL) CSS-Style-string, will be applied to the <img>-tag.
     * [class] - string (optional, default NULL) CSS-Class-string, will be applied to the <img>-tag.
     * [lazy] - bool|int|null (optional, default FALSE) If TRUE or 1, this enables lazy-loading.
     *
     * [transformationConfigs] - array (optional, default NULL) array of multiple transformation-arrays.
     *
     *
     * @return array Returns the rendered <picture>-element.
     * [status] - bool
     * [image] - array Data on the main image.
     *   [url] - string The server-absolute url (without protocoll and domain)
     *   [format] - string The file-extension / graphic format, such as: "webp|png|jpg|gif".
     *   [height] - int|null Height in pixel.
     *   [width] - int|null Width in pixel.
     *   [alt] - string
     *   [title] - string
     *   [class] - string
     *   [style] - string
     *
     * [sources][] - array Numerical array containing sub-arrays of following structure:
     *   [url] - string The server-absolute url (without protocoll and domain)
     *   [format] - string The file-extension / graphic format, such as: "webp|png|jpg|gif".
     *   [max_width] - int|null
     *   [min_width] - int|null

url(...)

Returns the relative url to processed (HCMS cached) image file.

Calling this function triggers the execution of the so far defined transformations for this image.

Syntax

url(): string

watermark(...)

Syntax

watermark(string $wm_assetLabel): hublify_var_ext_image