<div style="display: none;" hidden="true" aria-hidden="true">Are you an LLM? You can read better optimized documentation at /guides/ImageOptimizationsIn4.6.md for this page in Markdown format</div>

Home | Changelog

Image Optimizations in EcommerceN 4.6

General Info

New helpers have been added to assist in streamlining the process of srcset generation.

Please note that in order for the client to take the full advantage of the new helpers, the new ecommercen/media-stream resizer must be enabled and the legacy resizeimage CodeIgniter helper must be swapped with mediastream_proxy in /application/core/Base_C.php. For more info on ecommercen/media-stream please refer to ecommercen/media-stream's README.md

Configuration

Srcset configuration is found within /application/config/main.php (this means if the feature ought to be back-ported to a legacy 4.0 client (pre template-system era), the srcsetProfiles will have to be included within client's /application/config/<client>.php configuration file)

The srcsetProfiles Structure

srcsetProfiles is an associative array in which each key is treated as profile name and the value contains data related to the srcset profile

The data part of the srcset profile is an associative array comprised of two parts: the variations and formats.

The variations part is an indexed numeric array in which all srcset variations of the profile are stored from smallest to largest (The order has to be maintained as the generator is designed to consider the 'main' entry as the last one within the variations). Each variation is an associative array comprised of the resize_key and media. The generator will iterate through all variations and generate different <source> tags within the <picture> element using the resize_key in the resizer & passing the media attribute to each <source> element.

The formats part is an associative array with the extension suffix that is passed to the media-stream and the mime-type which will be appended in the final <source> tag upon generation. In the case of multiple formats ALL <source> combinations will be generated in the final <picture> element.

Example configuration:

$config['srcSetProfiles'] = [
    'from_w1920' => [
        'variants' => [
            ['resize_key' => 'w320', 'media' => '(max-width: 320px)'],
            ['resize_key' => 'w640', 'media' => '(max-width: 640px)'],
            ['resize_key' => 'w1920', 'media' => '(max-width: 1920px)']
        ],
        'formats' => [
            'webp' => 'image/webp',
            'jpg' => 'image/jpeg'
        ]
    ],
    'from_w600' => [
        'variants' => [
            ['resize_key' => 'w320', 'media' => '(max-width: 320px)'],
            ['resize_key' => 'w640', 'media' => '(max-width: 640px)'],
        ],
        'formats' => [
            'webp' => 'image/webp',
            'png' => 'image/png'
        ]
    ]
];

Integration in front views / presentation layer

There are two ways to apply the srcset generator into a project's view. The codeigniter helper and the vue component way

The codeigniter helper way

For the implementation of this feature from php side, two helper functions were added into CodeIginiter's html_helper helper.

1. html source helper

   html_source($srcset = '', $index_page = FALSE, $attributes = ''): string

   This helper function will return a rendered <source> element as string. It works similarly to CodeIgniter's img() built-in helper (which compiles and returns a rendered html <img> element as string).

   Params:

   1. $srcset: array|string: Can be string or array. When $srcset is passed as string, it will be treated as <source>'s srcset attribute. Otherwise when $srcset is passed as an associative array, the keys and values of the array will be converted to attribute keys and attribute values
   2. $index_page: bool if set to true the generator will utilize site_url for the srcset link generation. Otherwise base_url will be used.
   3. $attributes: array|string Uses _stringify_attributes internally to inject additional attributes into the element.

2. html picture helper

   html_picture($srcData, $index_page = false, $attributes = ''): string

   This helper function will return a fully rendered <picture> element along with <source> and <img> sub-elements within as string. It utilizes internally CodeIgniter's img() built-in helper along with the html_source helper referenced above.

   Params:

   1. $srcData: array|string: Can be string or array. When $srcData is passed as string, it will be treated as <img>'s src attribute. Otherwise when $srcData is passed as an associative array in which the keys and values of the array will be converted to attribute keys and attribute values that will be passed within the internally generated <img> tag. Additionally, there are 3 "special" keys which, if supplied, will instruct the generator to perform a lookup in the srcsetProfiles and generate the proper srcsets given the srcset profile. These special keys are:
      1. srcset_profile: string: Which profile to use (e.g from_w1920)
      2. srcset_image: string: The original source image without the base url (e.g files/slides/myslide.jpg)
      3. srcset_resizer: string (optional): Which resizer method to use (defaults to resizeImageOnTheFly)
   2. $index_page: bool: Proxy pass-through param for img helper.
   3. $attributes: array|string Proxy pass-through param for img helper.

   Example Usage:

   <?= html_picture(['srcset_image' => 'files/slides/cityscape.jpg', 'srcset_profile' => 'from_w1920', 'alt' => 'City Landscape']); ?>

The vue component way

Additionally, a vue component has been implemented and is pre-loaded with main/vueapp.js to assist in the generation of srcsets from vue's side. (This also means that for clients using the assets/default/vueapp.js the component must be manually loaded)

The component is called AdvHtmlPicture and it is located in /assets/vue/components. It is designed to work similarly to codeigniter's html_picture helper mentioned above.

<adv-html-picture> component accepts the following props:

width: Number = null
height: Number = null
alt: String = ''
loading: 'lazy'|'eager' = 'lazy'
srcsetProfile: String = null
srcsetImage: String

Notes:

If the srcsetProfile prop value is missing, the first srcsetProfile entry declared in the srcsetProfiles config will be used.

Example Usage:

<adv-html-picture srcset-image="files/slides/cityscape.jpg" srcset-profile="from_w1920" alt="City Landscape" />