`Image` Component

Web HTML facilitates a wide-varieties of displaying images using various image tags like <img>, <amp-img> and <picture> in their respective outputs. Bissetii supports them seemlessly in their respective outputs.

This component is available starting from v1.11.0.

Hugo

Bissetii prepared some Hugo interfaces to generate image seamlessly across all output formats.

Shortcodes

By default, it is hard to process images across multiple outputs while maintaining a single input format. Hence, Bissetii prepared the following shortcodes to standardize the image rendering. These shortcodes are specific to Bissetii which works differently from Hugo.

`image` Shortcode

image shortcode is a quick-and-easy image insertion. It does not require any data file configurations. Depending on Bissetii version, image shortcode may behaves differently.

Version `v1.13.0` and Above

The shortcode complies to the following pattern:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{{< image [ALT]
	[URL]
	[WIDTH]
	[HEIGHT]
	[ISMAP]
	[LOADING]
	[SRCSET]
	[LAYOUT]
	[CLASS]
	[SIZES] >}}

ALT - COMPULSORY. The image alternate text (alt=).
URL - COMPULSORY. The fallback image URL source (src=). Bissetii’s compatible relative URL is allowed and shall be processed into absolute URL as the final output.
WIDTH - COMPULSORY - Width of the image (width=). It is compulsory because some output formats has strict rule for it.
HEIGHT - COMPULSORY - Height of the image (height=). It is compulsory because some output formats has strict rule for it.
ISMAP - OPTIONAL - Specify the image is mapped under an anchor hyperlink (ismap). It only accepts "true" or "false" (it’s a string).
LOADING - OPTIONAL - The image loading mode. It ONLY accepts eager or lazy.
SRCSET - OPTIONAL - Specify the image’s source URL set (srcset=). The value shall be the final compiled long string version. To disable it, simply supply an empty string ("").
LAYOUT - COMPULSORY - Specify the image layout using Bissetii’s values. There are 4 values:
1. responsive - ensures the image is always responsive.
2. responsive-amp-only - ensures the responsiveness only applies to AMPHTML output format.
3. responsive-height-only - ensures the responsiveness only applies to height. For Vanilla HTML5, width= attribute is retained while height= attribute is removed even when there is a valid value.
4. responsive-width-only - ensures the responsiveness only applies to height. For Vanilla HTML5, height= attribute is retained while width= attribute is removed even when there is a valid value.
CLASS - OPTIONAL. Specify the CSS class attribute (class=).
SIZES - OPTIONAL. Specify the responsive image sizes (sizes=). This field is automatically removed if SRCSET is empty.

To use it, simply call it inside the markdown. Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{{< image "My Portrait" "/img/me/portrait.png" "200" "400"
	"false" "lazy" "/img/me/portrait-2x.png 2x, /img/me/portrait-3x.png 3x"
	"responsive-amp-only" "id-img-portrait"
	"(min-width: 640px) 2x" "John Smith" >}}

		⥥



<img alt="My Portrait"
	src="https://bissetii.zoralab.com/img/me/portrait.png"
	class="id-img-portrait"
	srcset="https://bissetii.zoralab.com/img/me/portrait-2x.png 2x,https://bissetii.zoralab.com/img/me/portrait-3x.png 3x"
	sizes="(min-width: 640px) 2x"
	loading="lazy"/>

Version `v1.12.5` and Below

The shortcode complies to the following pattern:

1
2
3
4
5
6
7
8
9
{{< image [ALT]
	[URL]
	[WIDTH]
	[HEIGHT]
	[ISMAP]
	[LOADING]
	[SRCSET]
	[LAYOUT]
	[CLASS] >}}

ALT - COMPULSORY. The image alternate text (alt=).
URL - COMPULSORY. The fallback image URL source (src=). Bissetii’s compatible relative URL is allowed and shall be processed into absolute URL as the final output.
WIDTH - COMPULSORY - Width of the image (width=). It is compulsory because some output formats has strict rule for it.
HEIGHT - COMPULSORY - Height of the image (height=). It is compulsory because some output formats has strict rule for it.
ISMAP - OPTIONAL - Specify the image is mapped under an anchor hyperlink. To disable it, simply supply an empty string ("").
LOADING - OPTIONAL - The image loading mode. It ONLY accepts eager or lazy.
SRCSET - OPTIONAL - Specify the image’s source URL set (srcset=). The value shall be the final compiled long string version. To disable it, simply supply an empty string ("").
LAYOUT - COMPULSORY - Specify the image layout using Bissetii’s values. There are 4 values:
1. responsive - ensures the image is always responsive.
2. responsive-amp-only - ensures the responsiveness only applies to AMPHTML output format.
3. responsive-height-only - ensures the responsiveness only applies to height. For Vanilla HTML5, width= attribute is retained while height= attribute is removed even when there is a valid value.
4. responsive-width-only - ensures the responsiveness only applies to height. For Vanilla HTML5, height= attribute is retained while width= attribute is removed even when there is a valid value.
CLASS - OPTIONAL. Specify the CSS class attribute (class=).

`picture` Shortcode

For images requiring the use of <picture> tag in Vanilla HTML5 and using data file to organize the image data (as opposed to image shortcode), Bissetii supplied picture shortcode for the job.

Version `v1.13.0` and Above

The shortcode complies to the following pattern:

{{< picture [DATASET_PATH]  >}}

DATASET_PATH - COMPULSORY. The Hugo data pathing to the image data set. For example, if the data file is located in data/bissetii/data/pictures/sample.toml where the data directory is called data/ and the dataset is grouped as IMG01, the Hugo data pathing shall be: bissetii.data.pictures.sample.IMG01.

Data File Structure

The data file shall be stored inside your Hugo data/ directory stated inside your configuration file. The file structure is as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
[IMG01]
IsMap = false
LoadingMode = "lazy"
Class = "my-class"
URL = "/img/bg/img_placeholder.svg"
Width = "400"
Height = "300"
Layout = "responsive-amp-only"
SrcList = """
/img/bg/img_480w.svg 480w,
/img/bg/img_800w.svg 800w,
/img/bg/img_1024w.svg 1024w,
/img/bg/img_2048w.svg 2048w,
/img/bg/img_4096w.svg 4096w
"""
Sizes = """
(max-width: 480px) 20vw,
(max-width: 900px) 75vw
"""

[IMG01.AltText]
en = "picture elements"
zh-hans = "图画元素"




# Picture Source HTML Tag
[IMG01.Sources.01]
Type = "image/svg+xml"
SourceSet = """
/img/bg/img_800w.svg 1x,
/img/bg/img_1024w.svg 2x,
/img/bg/img_2048w.svg 3x
"""
Media = "(min-width: 20em)"

[IMG01.Sources.02]
Type = "image/svg+xml"
SourceSet = """
/img/bg/img_800w.svg 1x,
/img/bg/img_1024w.svg 2x,
/img/bg/img_2048w.svg 3x
"""
Media = "(min-width: 40em)"

Calling the shortcode against the data file above yields:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
<picture>
		<source srcset="https://bissetii.zoralab.com/img/bg/img_800w.svg 1x,https://bissetii.zoralab.com/img/bg/img_1024w.svg 2x,https://bissetii.zoralab.com/img/bg/img_2048w.svg 3x" media="(min-width: 20em)" type="image/svg&#43;xml">
		<source srcset="https://bissetii.zoralab.com/img/bg/img_800w.svg 1x,https://bissetii.zoralab.com/img/bg/img_1024w.svg 2x,https://bissetii.zoralab.com/img/bg/img_2048w.svg 3x" media="(min-width: 40em)" type="image/svg&#43;xml">

<img alt="picture elements"
	src="https://bissetii.zoralab.com/img/bg/img_placeholder.svg"
	class="my-class"
	loading="lazy"/>
</picture>

Go

Coming Soon.

HTML

Bissetii supports the <img> and <amp-img> seamlessly and accordingly based on their respective output formats. Additionally, starting from version v1.13.0, <picture> tag for non-AMPHTML output format is now available.

Basic Image Inclusion

To cater responsive images, Bissetii recommends the following HTML codes for quick and easy usage.

Vanilla HTML5

For vanilla HTML5, the basic image inclusion example would be:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
<img alt="image srcset with sizes"
	src="https://bissetii.zoralab.com/img/bg/img_480w.svg"
	srcset="https://bissetii.zoralab.com/img/bg/img_480w.svg 480w,
		https://bissetii.zoralab.com/img/bg/img_800w.svg 800w,
		https://bissetii.zoralab.com/img/bg/img_1024w.svg 1024w,
		https://bissetii.zoralab.com/img/bg/img_2048w.svg 2048w,
		https://bissetii.zoralab.com/img/bg/img_4096w.svg 4096w"
	sizes="(max-width: 480px) 20vw,(max-width: 900px) 75vw"
	width="200"
	height="150"
	loading="lazy"
/>

Line 1 - COMPULSORY - alt text for describing the image when the image fails to load or to allow a search engine bot is trying to comprehend the image easier while analyzing the web page.
Line 2 - COMPULSORY - the fallback version of the image URL.
Line 3-7 - OPTIONAL - the responsive image URL sources and their configurations. Best use would be the image width or resolution (e.g. 1x, 2x). The browser will comprehend the last and only download the one that is making sense.
Line 8 - OPTIONAL - the display size based on inline CSS media query. It works closely with srcset attribute. sizes attribute shall only exist when srcset is available.
Line 9 - OPTIONAL - the width of the image you plan to display in px unit. It’s recommended to state the attribute for consistency purposes.
Line 10 - OPTIONAL - the height of the image you plan to display in px unit. It’s recommended to state the attribute for consistency purposes.
Line 11 - OPTIONAL - the image loading instruction. Setting the value lazy allows user to only load the image when it enters view port. This saves download bandwidth for the case of mobile users with bad connectivity.

AMPHTML

For AMPHTML, the basic image inclusion example would be:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
<amp-img alt="image title/purpose"
	src="https://bissetii.zoralab.com/en/img/bg/img_placeholder.svg"
	srcset="https://bissetii.zoralab.com/en/img/bg/img_480w.svg 480w,
		https://bissetii.zoralab.com/en/img/bg/img_800w.svg 800w,
		https://bissetii.zoralab.com/en/img/bg/img_1024w.svg 1024w,
		https://bissetii.zoralab.com/en/img/bg/img_2048w.svg 2048w,
		https://bissetii.zoralab.com/en/img/bg/img_4096w.svg 4096w"
	sizes="(max-width: 480px) 20vw,(max-width: 900px) 75vw"
	width="200"
	height="150"
	layout="responsive">
</amp-img>

The main difference is the use of its custom <amp-img> AMPHTML tag instead of the conventional <img> HTML tag. Also, it has a tailing close tag (</amp-img>).

Line 1 - COMPULSORY - alt text for describing the image when the image fails to load or to allow a search engine bot is trying to comprehend the image easier while analyzing the web page.
Line 2 - COMPULSORY - the fallback version of the image URL.
Line 3-7 - OPTIONAL - the responsive image URL sources and their configurations. Best use would be the image width or resolution (e.g. 1x, 2x). The browser will comprehend the last and only download the one that is making sense.
Line 8 - OPTIONAL - the display size based on inline CSS media query. It works closely with srcset attribute. sizes attribute shall only exist when srcset is available.
Line 9 - OPTIONAL - the width of the image you plan to display in px unit. It’s recommended to state the attribute for consistency purposes.
Line 10 - OPTIONAL - the height of the image you plan to display in px unit. It’s recommended to state the attribute for consistency purposes.
Line 11 - OPTIONAL - the AMP layout instruction. Setting the value to responsive will set the image size to resize based on the screen size automatically.

<amp-img> is always loaded lazily.

Art-Directed Image Inclusion

Sometimes, the image needs to be art-directed where small screen should be presented with other images or cropped version (completely different image). Bissetii recommends the following HTML implementations based on your output formats.

Vanilla HTML5

For vanilla HTML5, it is highly recommended to use <picture> HTML tag alongside its <source> child HTML tag. The reason is to keep the HTML codes sane and maintainable where each sources can be detailed easily in its own HTML line. Although srcset and sizes can do the same job, it would be insane to stuff too many things inside them.

Here is an example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
<picture>
	<source srcset="//holloway-seraphim:8080/img/bg/img_800w.jpg 1x,
		//holloway-seraphim:8080/img/bg/img_1024w.jpg 2x,
		//holloway-seraphim:8080/img/bg/img_2048w.jpg 3x"
		type="image/jpeg"
		media="(min-width: 20em)" type="image/svg&#43;xml">
	<source srcset="//holloway-seraphim:8080/img/bg/img_1x.png 1x,
		//holloway-seraphim:8080/img/bg/img_2x.png 2x,
		//holloway-seraphim:8080/img/bg/img_3x.png 3x"
		type="image/png"
		media="(min-width: 40em)" type="image/svg&#43;xml">
	<img alt="picture elements"
		src="//holloway-seraphim:8080/img/bg/img_placeholder.svg"
		width="400"
		height="300"
		loading="lazy"/>
</picture>

Some noticable changes would be:

Each sources now has its own srcset, media, and even file type changes.
You can define more sources and let the browser to the best selection accordingly.
The type must be a compliant MIME type value. E.g. image/jpeg and not image/jpg.
You no longer need to specify srcset and sizes for the fallback img tag. It makes no sense to cause confusion between the 2.

AMPHTML

Currently, there is no way to specify multiple sources for art-directing image display. You will need to compile the final value and stuff it inside the existing srcset and sizes respectively.

CSS

This section covers all the CSS part for Image component. Please go through each sub-section carefully as they affects Bissetii styling directly.

CSS Variables

Bissetii provided a list of CSS variables dedicated for image styling alternation without needing to recompile Sass. These variables are best applied directly to the image HTML tag. Example:

<img src="..." alt="..." style="--image-max-width: 450px;">
<amp-img src="..." alt="..." style="--image-max-width: 450px;" ... ></amp-img>

To set it globally, the variables can be applied to the <body> tag. Example:

<body style="--image-max-width: 30vw" ...>

`--image-max-width`

Affects the image max width. The value must be compliant to max-width: CSS field. Default is 100%.

`--image-max-height`

Affects the image max height. The value must be compliant to max-width: CSS field. Default is unset.

`--image-height`

Affects the image immediate height. The value must be compliant to height: CSS field. Default is auto.

`--image-filter`

Affects the image overlaying effect. The value must be compliant to filter: CSS field. Default is unset.

`--image-border`

Affects the image border. The value must be compliant to border: CSS field. Default is none.

`--image-border-radius`

Affects the image border radius (or roundness corder). The value must be compliant with border-radius: CSS field. Default is 0.

`--image-animation`

Affects the image CSS animation. The value must be compliant with animation: CSS field. Default is unset.

Javascript Parts

This component does not rely on any Javascript.

Sass

Depending on release version, the Sass files work differently. Bissetii does not package Sass codes explictly so please view them via the git repository.

`v1.13.0` and Above

Bissetii uses Dart Sass to compile the styling Sass codes into CSS file. This component’s Sass codes is available at the following location:

pkg/components/internal/image

`v1.12.5` and Before

The Sass scripts responsible for styling image are located at:

assets/css/bissetii/modules/core/_Image.scss

Researches

Here are the researches done to ensure Image component meets the necessarily quality assurances:

Image Web User Interface Architectural Design Analysis (https://doi.org/10.5281/zenodo.4925642)

Epilogue

That is all about Image component in Bissetii. If you need more feature or encountered a bug, Please feel free to contact us by filling an issue ticket at our Issue Section. We will be glad to help you.

Image Component

Hugo

Shortcodes

image Shortcode

Version v1.13.0 and Above

Version v1.12.5 and Below

picture Shortcode

Version v1.13.0 and Above

Data File Structure

Go

HTML

Basic Image Inclusion

Vanilla HTML5

AMPHTML

Art-Directed Image Inclusion

Vanilla HTML5

AMPHTML

CSS

CSS Variables

--image-max-width

--image-max-height

--image-height

--image-filter

--image-border

--image-border-radius

--image-animation

Javascript Parts

Sass

v1.13.0 and Above

v1.12.5 and Before

Researches

Epilogue

`Image` Component

`image` Shortcode

Version `v1.13.0` and Above

Version `v1.12.5` and Below

`picture` Shortcode

Version `v1.13.0` and Above

`--image-max-width`

`--image-max-height`

`--image-height`

`--image-filter`

`--image-border`

`--image-border-radius`

`--image-animation`

`v1.13.0` and Above

`v1.12.5` and Before