Images

All images (excluding icons) rendered using the <Image /> component. This component supports both images present in the WordPress Media Library and those referenced by their URL.

When images are present in the Media Library, the <Image /> component automatically populates most of the <img> attributes. When a source is given, many more properties should be populated on the <Image /> model.

Model Properties

WordPress Attachments

When an attachment ID is available, only two properties are required: attachment_id and either relative_size or wp_size. In most cases, relative_size is used, though certain circumstances call for the use of wp_size.

When an attachment ID is given, many of the properties on the <Image /> model are ignored, deferring instead to WordPress functions and Nova's Image_Settings class.

relative_size

relative_size can be one of four options defined in \PMC\Nova\Theme\Image_Settings::RELATIVE_SIZE_OPTIONS. If the relative size depends on the device type, use the \PMC\Nova\Components\Render_Utilities::determine_value_for_device_type() utility to conditionally set the value.

When using relative_size, set a ratio value in either defaults.json or the brand's override. The ratio is used both to apply the correct CSS to the image and to load the correct image crop.

By default, relative-sized images are cropped, but this can be controlled via the corresponding model property.

wp_size

wp_size accepts any image size registered in WordPress, either by Nova, WordPress, or another plugin. wp_size is used sparingly, typically only when the design calls for an uncropped image of a specific size, such as in the <SponsorBadge /> component.

Image URLs

When an image URL is given, it must be accompanied by alt text. The <Image /> model provides many other properties that control attributes on the resulting image tag, but all are optional or have a default value.

Lazy Loading

By default, the <Image /> component's model will generate an image that is loaded lazily using browser-native lazy loading. Unlike non-Nova sites, the JavaScript-based approach, provided by the lazy-load-0.7 plugin, is not used.

If an image appears in the initial viewport (aka "above the fold"), it should not be loaded lazily. This is controlled via the is_lazy_loaded property on the model.

Image Sizes

Nova defines two types of image sizes: those used with the relative_size property and those referenced in the wp_size property.

The relative_size names are dynamically generated based on the relative sizes and aspect ratios defined in the \PMC\Nova\Theme\Image_Settings::RELATIVE_SIZE_OPTIONS and \PMC\Nova\Theme\Image_Settings::ASPECT_RATIO_MAP constants. Do not use one of these generated names with the wp_size property.

The named image sizes that Nova defines for use with the wp_size property are found in the \PMC\Nova\Theme\Image_Settings::$_map property. The key is the name by which the image size is registered. Each array entry's value is an array of:

• width (integer)
• height (integer)
• crop (boolean)
• aspect ratio (string) - in the format of 16:9
• aspect-ratio name (string) - in the format of sixteenByNine, corresponding to an aspect ratio supported in Nova's CSS and in the ratio property in the <Image /> component's schema