<image>
Summary
The <image> element provides a placeholder for displaying an image.
The actual image to display must be a file which media type is of that “image”, that is, starting with image/.
In PageSeeder, the image file must be a PageSeeder document and the <image> element also expresses a relationship between the PSML document and the referenced image file enabling two-way tracking of both files. In effect, an image is similar to a transclusion of an image document.
Requires at least one of the following attributes: @src, @docid, @uriid.
Usage context
| Element category | |
|---|---|
| PSML level | portable |
| Permitted content | none (empty element) |
| Permitted parent | |
| HTML equivalent | <img> |
| OpenXML equivalent |
Attributes
This element includes the following attributes:
| Name | Type | Required | Description |
|---|---|---|---|
| alt | xs:string | no | Alternative description for non-visual readers |
| archived | boolean | no | Whether the image is archived |
| docid | document-id | no | Document ID of the referenced image, if any |
| height | xs:positiveInteger | no | Height in pixels |
| labels | label-list | no | Comma separated list of image labels |
| src | xs:string | no | Path for image |
| unresolved | boolean | no | A boolean to flag images which reference could not be resolved |
| uriid | xs:long | no | The URI ID of the image being referenced |
| width | xs:positiveInteger | no | Width in pixels |
The @unresolved and @archived attributes are informational and ignored by upload.
@alt
Alternative description for non-visual readers.
@archived
A boolean flag indicating whether the image is archived. INFORMATIONAL - ignored by upload.
This attribute was introduced in PSML v1.3 in PageSeeder 5.99.
@docid
If the referenced image has a document id, it is included.
It overrides the @uriid on upload.
@height
The height of the image in pixels. If this attribute is omitted, the image is rendered using the default behavior of the layout engine.
@labels
A comma separated list of image labels.
This attribute was introduced in PSML v1.3 in PageSeeder 5.99.
@src
The path for the image in PageSeeder. This path can be as follows:
- Relative (for example,
images/mypic.png or ../common/anotherpic.jpg) - Absolute (for example,
/ps/myproject/mygroup/images/diagram.png) - Permalink (for example,
/ps/uri/123.png)
It overrides the @docid and @uriid on upload.
To create permalinks, the path refers to the URI ID of the image (/ps/uri/[uri id].[extension]).
To provide a clue to external applications about the media type of the image, you can add an extension after the URI ID in the path. For example, Microsoft Office requires that the path to images include an extension to display them.
On export, the image @src is always relative.
An image @src must not point to an external location, so it cannot start with either “http://” or “https://”. It must always be URL encoded unless document/@level="processed".
@unresolved
If true, the target document doesn't exist. INFORMATIONAL - ignored by upload.
@uriid
The URI ID of the image being referenced.
Ignored if uploading to different PageSeeder server.
@width
The width in pixels. If this attribute is omitted, the image is rendered using the default behavior of the layout engine.
Examples
Image with permalink
Image using a permalink:
<image src="/ps/uri/23.png" uriid="23" alt="Example"/>
When an image uses a permalink, the URI ID must match the ID in the @src attribute.
Image with path
Image using a PageSeeder path instead of a permalink. In PageSeeder, the URI ID is used to determine what the actual image is. PageSeeder ensures that the path corresponds to the path of the image.
<image src="/ps/doc/examples/images/sample.jpg"
uriid="186034"
width="600"
height="400"
alt="A sample image"/>
Schema
XML Schema
<xs:element name="image">
<xs:complexType>
<xs:attribute name="archived" type="xs:boolean"/>
<xs:attribute name="src" type="xs:string" use="required"/>
<xs:attribute name="width" type="xs:positiveInteger"/>
<xs:attribute name="height" type="xs:positiveInteger"/>
<xs:attribute name="alt" type="xs:string"/>
<xs:attribute name="uriid" type="xs:long"/>
</xs:complexType>
</xs:element>
Relax Schema
element image {
attribute archived { xs:boolean }?,
attribute src { text},
attribute uriid { xs:long }?,
attribute width { xs:positiveInteger }?,
attribute height { xs:positiveInteger }?,
attribute alt { text }?,
empty
}
Compatibility
This element was introduced in the first draft of PSML and is well-supported from PageSeeder 5.1.
Up to PageSeeder 5.7, much like HTML, <image> is a declarative element, in other words, it defines a placeholder for the image referenced by a URL to be displayed.
From PageSeeder 5.8, the <image> element also expresses a relationship between an image file and the PSML document that contains it. Like other type of two-way cross-references, it is possible to track the use of images and ensure that the <image> element references an actual image.
From PageSeeder 5.99, images can have their own labels.