The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
HTML-Object-v0.4.0
River stage one • 1 direct dependent • 2 total dependents
1 ++
/ HTML::Object::DOM::Element::Image

NAME

HTML::Object::DOM::Element::Image - HTML Object DOM Image Class

SYNOPSIS

    use HTML::Object::DOM::Element::Image;
    my $img = HTML::Object::DOM::Element::Image->new || 
        die( HTML::Object::DOM::Element::Image->error, "\n" );

VERSION

    v0.2.0

DESCRIPTION

This interface represents an HTML <img> element, providing the properties and methods used to manipulate image elements.

INHERITANCE

    +-----------------------+     +---------------------------+     +-------------------------+     +----------------------------+     +-----------------------------------+
    | HTML::Object::Element | --> | HTML::Object::EventTarget | --> | HTML::Object::DOM::Node | --> | HTML::Object::DOM::Element | --> | HTML::Object::DOM::Element::Image |
    +-----------------------+     +---------------------------+     +-------------------------+     +----------------------------+     +-----------------------------------+

PROPERTIES

Inherits properties from its parent HTML::Object::DOM::Element

alt

A string that reflects the alt HTML attribute, thus indicating the alternate fallback content to be displayed if the image has not been loaded.

Example:

    <img src="/some/file/image.png" alt="Great Picture" />

See also Mozilla documentation

complete

This does nothing and always returns true under perl environment.

Under JavaScript environment, this returns a boolean value that is true if the browser has finished fetching the image, whether successful or not. That means this value is also true if the image has no src value indicating an image to load.

See also Mozilla documentation

crossOrigin

A string specifying the CORS setting for this image element. See CORS settings attributes for further details. This may be undef if CORS is not used.

Example:

    my $image = $doc->createElement( 'img' );
    $image->crossOrigin = "anonymous";

See also Mozilla documentation

currentSrc

Under perl environment, this returns the same value as "src", but under JavaScript environment, this returns a string representing the URL from which the currently displayed image was loaded. This may change as the image is adjusted due to changing conditions, as directed by any media queries which are in place.

See also Mozilla documentation

decoding

An optional string representing a hint given to the browser on how it should decode the image. If this value is provided, it must be one of the possible permitted values: sync to decode the image synchronously, async to decode it asynchronously, or auto to indicate no preference (which is the default). Read the decoding page for details on the implications of this property's values.

Example:

    my $img = $doc->createElement( 'img' );
    $img->decoding = 'sync';
    $img->src = '/some/where/logo.png';

See also Mozilla documentation

height

An integer value that reflects the height HTML attribute, indicating the rendered height of the image in CSS pixels.

See also Mozilla documentation

isMap

Provided with a boolean value and this sets or gets the HTML attribute ismap that indicates that the image is part of a server-side image map. This is different from a client-side image map, specified using an <img> element and a corresponding <map> which contains <area> elements indicating the clickable areas in the image. The image must be contained within an <a> element; see the ismap page for details.

See also Mozilla documentation

loading

Provided with a string (eager or lazy) and this sets or gets the loading HTML attribute that provides a hint to the browser to optimize loading the document by determining whether to load the image immediately (eager) or on an as-needed basis (lazy).

See also Mozilla documentation

naturalHeight

Under perl environment, this always return 0, but you can change this value.

Under JavaScript environment, this returns an integer value representing the intrinsic height of the image in CSS pixels, if it is available; else, it shows 0. This is the height the image would be if it were rendered at its natural full size.

See also Mozilla documentation

naturalWidth

Under perl environment, this always return 0, but you can change this value.

Under JavaScript environment, this returns an integer value representing the intrinsic width of the image in CSS pixels, if it is available; otherwise, it will show 0. This is the width the image would be if it were rendered at its natural full size.

See also Mozilla documentation

referrerPolicy

A string that reflects the referrerpolicy HTML attribute, which tells the user agent how to decide which referrer to use in order to fetch the image.

You can use whatever value you want, but the values supported by web browser are:

no-referrer

This means that the Referer HTTP header will not be sent.

origin

This means that the referrer will be the origin of the page, that is roughly the scheme, the host and the port.

unsafe-url

This means that the referrer will include the origin and the path (but not the fragment, password, or username). This case is unsafe as it can leak path information that has been concealed to third-party by using TLS.

Example:

    my $img = $doc->createElement( 'img' );
    $img->src = '/some/where/logo.png';
    $img->referrerPolicy = 'origin';

    my $div = $doc->getElementById('divAround');
    $div->appendChild( $img ); # Fetch the image using the origin as the referrer

See also Mozilla documentation

sizes

A string reflecting the sizes HTML attribute. This string specifies a list of comma-separated conditional sizes for the image; that is, for a given viewport size, a particular image size is to be used. Read the documentation on the sizes page for details on the format of this string.

Example:

    <img src="/files/16870/new-york-skyline-wide->jpg"
         srcset="/files/16870/new-york-skyline-wide->jpg 3724w,
                         /files/16869/new-york-skyline-4by3->jpg 1961w,
                         /files/16871/new-york-skyline-tall->jpg 1060w"
         sizes="((min-width: 50em) and (max-width: 60em)) 50em,
                        ((min-width: 30em) and (max-width: 50em)) 30em,
                        (max-width: 30em) 20em">

See also Mozilla documentation

src

A string that reflects the src HTML attribute, which contains the full URL of the image including base URI.

See also Mozilla documentation

srcset

A string reflecting the srcset HTML attribute. This specifies a list of candidate images, separated by commas (',', U+002C COMMA). Each candidate image is a URL followed by a space, followed by a specially-formatted string indicating the size of the image. The size may be specified either the width or a size multiple. Read the Mozilla srcset documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/srcset> for specifics on the format of the size substring.

Example:

    "images/team-photo.jpg 1x, images/team-photo-retina.jpg 2x, images/team-photo-full 2048w"

Another example:

    "header640.png 640w, header960.png 960w, header1024.png 1024w, header.png"

See also Mozilla documentation

useMap

A string reflecting the usemap HTML attribute, containing the page-local URL of the <map> element describing the image map to use. The page-local URL is a pound (hash) symbol (#) followed by the ID of the <map> element, such as #my-map-element. The <map> in turn contains <area> elements indicating the clickable areas in the image.

Example:

    <map name="mainmenu-map">
        <area shape="circle" coords="25, 25, 75" href="/index.html" alt="Return to home page">
        <area shape="rect" coords="25, 25, 100, 150" href="/index.html" alt="Shop">
    </map>

    <img src="menubox->png" usemap="#mainmenu-map" />

See also Mozilla documentation

width

An integer value that reflects the width HTML attribute, indicating the rendered width of the image in CSS pixels.

See also Mozilla documentation

x

Provided with an integer, and this sets or gets the horizontal offset of the left border edge of the image's CSS layout box relative to the origin of the <html> element's containing block.

Since this is a perl environment, this has no effect, but you can still set whatever value you want.

See also Mozilla documentation

y

Provided with an integer, and this sets or gets the vertical offset of the top border edge of the image's CSS layout box relative to the origin of the <html> element's containing block.

Since this is a perl environment, this has no effect, but you can still set whatever value you want.

See also Mozilla documentation

METHODS

Inherits methods from its parent HTML::Object::DOM::Element

decode

Since this is a perl environment, there is no decoding of the image, and this always returns undef.

Under a JavaScript environment, this returns a Promise that resolves when the image is decoded and it's safe to append the image to the DOM. This prevents rendering of the next frame from having to pause to decode the image, as would happen if an undecoded image were added to the DOM.

See also Mozilla documentation

AUTHOR

Jacques Deguest <jack@deguest.jp>

SEE ALSO

Mozilla documentation, Mozilla documentation on image element

COPYRIGHT & LICENSE

Copyright(c) 2021 DEGUEST Pte. Ltd.

All rights reserved

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.