To allow various HTML embedded content elements to be used directly in SVG and support dynamic loading of content.
Owner:
Nobody
12.1. Overview
Embedded content is content that imports another resource into the document, or content from another vocabulary that is inserted into the document.This is the same definition asHTML'sembedded content.
SVG supports embedded content with the use of‘image’ and‘foreignObject’ elements.
Except‘canvas’ and‘foreignObject’, embedded content is compatible withResource Hints for prioritizing downloading of external resources.
12.2. Placement of the embedded content
Thex,y,width, andheight geometry properties specify the rectangular region into which the embedded content is positioned (thepositioning rectangle). Thepositioning rectangle is used as the bounding box of the element; note, however, that graphics may overflow the positioning rectangle, depending on the value of theoverflow property.
The elements in the HTML namespace do not have SVG presentation attributes for the geometry properties. Most of these elements, however, accept the HTMLwidth andheightdimensional attributes, which are used as presentational hints to set default values for the corresponding sizing properties.
The HTML dimensional attributes must be parsed and interpretted as defined in the HTML specification [HTML]. Specifically, they only accept integer values, not CSS lengths with units. On a‘canvas’ element,the attributes are slightly different: they affect the rendered bitmap, not only its layout.
Thex andy geometry properties can only be set on HTML-namespaced elements via CSS.
When the embedded content consists of a document fragment (e.g., a‘foreignObject’, an‘audio’ or‘video’ with user-agent generated controls, or a‘video’,‘audio’, or‘canvas’ displaying HTML fallback content), thepositioning rectangle defines the bounds of acontaining block for laying out the child content using CSS. The scale of the containing block is defined in the current coordinate system, including all explicit and implicit (e.g.,‘viewBox’) transformations. The‘foreignObject’, or other element that is positioned using SVG layout attributes, is implicitlyabsolutely-positioned for the purposes of CSS layout. As a result, any absolutely-positioned child elements are positioned relative to this containing block. Again, theoverflow property determines whether content that extends outside thepositioning rectangle will be hidden.
A value of zero for eitherwidth orheight disables rendering of the element and its embedded content.
The'auto' value forwidth orheight is used to size the corresponding element automatically based on theintrinsic dimensions orintrinsic aspect ratio of the referenced resource. Computation of automatically-sized values follows theDefault Sizing Algorithm defined for replaced elements in CSS layout [css-images-3]. In particular, when the referenced resource does not have an intrinsic size (such as an‘iframe’ or an image types with no defined dimensions), it is assumed to have a width of 300px and a height of 150px.
CSS positioning properties (e.g.top andmargin) have no effect when positioning the embedded content element in the SVG coordinate system. They can, however, be used to position child elements of a‘foreignObject’ or HTML embedding element.
The‘image’ elementindicates that the contents of a complete file are to berendered into a given rectangle within the current usercoordinate system. The‘image’ element can refer to rasterimage files such as PNG or JPEG or to files with MIME type of"image/svg+xml".Conforming SVGviewers need to support at least PNG, JPEG and SVG formatfiles.SVG files must be processed insecure animated modeif the current document supports animation,or insecure static mode if the current document is static.
The result of processing an‘image’ is always a four-channelRGBA result. When an‘image’element references an image (such as many PNG or JPEGfiles) which only has three channels (RGB), then the effect isas if the object were converted into a 4-channel RGBA imagewith the alpha channel uniformly set to 1. For a single-channel (grayscale)raster image, the effect is as if the object were convertedinto a 4-channel RGBA image, where the single channel from thereferenced object is used to compute the three color channelsand the alpha channel is uniformly set to 1.
The‘preserveAspectRatio’ calculations are appliedafter determining theconcrete object size, and only have an effect if that size does not match theintrinsic aspect ratio of the embedded image. If a value ofobject-fit is used that ensures that the concrete object size matches the intrinsic aspect ratio (i.e., any value other than the defaultfill), then the‘preserveAspectRatio’ value will have no effect; theimage-rendering rectangle will be that determined when scaling and positioning the object with CSS. The‘preserveAspectRatio’ attribute can therefore be safely used as a fallback for most values ofobject-fit andobject-position; it must be explicitly set tonone to turn off aspect ratio control, regardless ofobject-fit value.
For example, if the image element referenced a PNG or JPEGandpreserveAspectRatio="xMinYMinmeet", then the aspect ratio of the raster would bepreserved (which means that the scale factor from image'scoordinates to current user space coordinates would be the samefor both X and Y), the raster would be sized as large aspossible while ensuring that the entire raster fits within theviewport, and the top/left of the raster would be aligned withthe top/left of the viewport as defined by the attributesx,y,width andheight on the‘image’ element. If the valueof‘preserveAspectRatio’ was'none'then aspect ratio of the image would not be preserved. Theimage would be fit such that the top/left corner of theraster exactly aligns with coordinate (x,y) and the bottom/right corner ofthe raster exactly aligns with coordinate (x+width,y+height).
For‘image’ elements embedding an SVG image,the‘preserveAspectRatio’ attribute on the rootelement in the referenced SVG image must be ignored,and instead treated as if it had a value ofnone.(see‘preserveAspectRatio’ for details).This ensures that the‘preserveAspectRatio’ attribute onthe referencing‘image’ has its intended effect,even if it isnone.
When the value of the‘preserveAspectRatio’ attribute on the‘image’isnotnone,theimage-rendering rectangle determinedfrom the properties of the‘image’ elementwill exactly match the embedded SVG's intrinsic aspect ratio.Ignoring the‘preserveAspectRatio’ attribute from the embedded SVGwill therefore not usually have any effect.The exception is if the aspect ratio of that imageis determined from absolute values for thewidth andheight attributeswhichdo not match its‘viewBox’ aspect ratio.This is an unusual situation that authors are advised to avoid, for many reasons.
The user agent stylesheet sets the value of theoverflow propertyon‘image’ element tohidden.Unless over-ridden by the author, images will therefore be clipped tothepositioning rectangle defined by the geometry properties.
New in SVG 2.Previous versions of SVG required that theoverflow (and alsoclip)property on the embedded SVG be ignored.The new rules ensure that an overflowingslice layoutcan be safely used without compromising the overflow control from the referenced image.
The resource referenced by the‘image’ element represents aseparate document which generates its own parse tree anddocument object model (if the resource is XML). Thus, there isno inheritance of properties into the image.
Unlike‘use’, the‘image’ element cannot referenceelements within an SVG file.
Since image references always refer to a complete document, a target-only URL is treated as a link to the same file, which is rendered again as an independent embedded image. Since the embedded image is processed in a secure mode, its own embedded references are not processed, preventing infinite recursion.
<?xml version="1.0" standalone="no"?><svg width="5cm" height="3cm" viewBox="0 0 50 30" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> <title>Recursive SVG</title> <desc>An SVG with two recursive image reference to itself. One reference uses the file name as a relative URL, the other uses a target fragment only. When viewed in a processing mode that supports external file references, the embedded images should be rendered; however, the embedded image must be processed in secure mode, so the recursion only happens once. The appearance should be three nested red circles in a bulls-eye pattern; the innermost circle has solid fill because of target styles. </desc> <style type="text/css"> #target:target { fill: red; } </style> <circle stroke="red" stroke-width="5" fill="none" cx="50%" cy="50%" r="12" /> <image xlink:href="recursive-image.svg" x="25%" y="25%" width="50%" height="50%" /> <image xlink:href="#target" x="45%" y="45%" width="10%" height="10%" /></svg>
HTML elements, in the HTML namespace, used as children of'video','audio','iframe' and'canvas' elements within an SVG document fragment behave as specified in HTML. This applies in particular tofallback content;if fallback content is rendered,the embedded element behaves like an SVG‘foreignObject’ element to contain the HTML content.This would occur, for example,for a‘video’ element if the user agent does not support the specified video formats,or for a‘canvas’ element if scripting is disabled.
<svg xmlns="http://www.w3.org/2000/svg" xmlns:html="http://www.w3.org/1999/xhtml"> <html:video src="http://example.org/dummyvideo" controls="controls"> <html:p>The video format is not supported by this browser.</html:p> </html:video></svg>
The HTML specification is applicable also for the'track' and'source' elements.
Currently, within an SVG subtree, these tagnames are not recognized by the HTML parser to be HTML-namespaced elements, although this may change in the future. Therefore, in order to include these elements within SVG, one of the following must be used:
An XML serialization that recognizes namespace declarations (such as stand-alone SVG or XHTML).
Namespaced elements as created via thecreateElementNS DOM API method.
A‘foreignObject’ element to wrap the HTML-namespaced elements, which will then be correctly parsed.
Other HTML elements in an SVG subtree,other than those inside a‘foreignObject’ element,must be treated asunknown elements for rendering purposes.
Many HTML elements will be treated as a parse error by the HTML parser, causing the SVG fragment to terminate.
SVG is designed to be compatible with other XML languagesfor describing and rendering other types of content.The‘foreignObject’element allows for inclusion of elements in a non-SVG namespace whichis rendered within a region of the SVG graphic using other user agent processes. Theincluded foreign graphical content is subject to SVGtransformations, filters, clipping, masking and compositing.Examples includeinserting aMathML expression intoan SVG drawing [MathML3],or adding a block of complex CSS-formatted HTML text or form inputs.
The HTML parser treats elements inside the‘foreignObject’ equivalent to elements inside an HTML document fragment. Anysvg ormath element, and their descendents, will be parsed as being in the SVG or MathML namespace, respectively; all other tags will be parsed as being in the HTML namespace.
SVG-namespaced elements within a‘foreignObject’ will not be rendered,except in the situation where a properly defined SVGfragment, including a root‘svg’ element isdefined as a descendent of the‘foreignObject’.
A‘foreignObject’may be used in conjunction with the‘switch’ element andthe‘requiredExtensions’ attribute toprovide proper checking for user agent support and provide analternate rendering in case user agent support is notavailable.
This specification does not define how‘requiredExtensions’ values should be mapped to support for different XML languages; a future specification may do so.
It is not required that SVG user agent support the abilityto invoke other arbitrary user agents to handle embeddedforeign object types; however, all conforming SVG user agentswould need to support the‘switch’ element andmust be able to render valid SVG elements when they appear asone of the alternatives within a‘switch’element.
It is expected that commercial Web browsers willsupport the ability for SVG to embedCSS-formatted HTML and also MathML content,with the rendered content subject to transformations and compositing defined in the SVG fragment.At this time, such a capability is not a requirement.
<?xml version="1.0" standalone="yes"?><svg width="4in" height="3in" xmlns = 'http://www.w3.org/2000/svg'> <desc>This example uses the 'switch' element to provide a fallback graphical representation of an paragraph, if XMHTML is not supported.</desc> <!-- The 'switch' element will process the first child element whose testing attributes evaluate to true.--> <switch> <!-- Process the embedded XHTML if the requiredExtensions attribute evaluates to true (i.e., the user agent supports XHTML embedded within SVG). --> <foreignObject width="100" height="50" requiredExtensions="http://example.com/SVGExtensions/EmbeddedXHTML"> <!-- XHTML content goes here --> <body xmlns="http://www.w3.org/1999/xhtml"> <p>Here is a paragraph that requires word wrap</p> </body> </foreignObject> <!-- Else, process the following alternate SVG. Note that there are no testing attributes on the 'text' element. If no testing attributes are provided, it is as if there were testing attributes and they evaluated to true.--> <text font-size="10" font-family="Verdana"> <tspan x="10" y="10">Here is a paragraph that</tspan> <tspan x="10" y="20">requires word wrap.</tspan> </text> </switch></svg>
Thex,y,width andheight IDL attributesreflect the computed values of thex,y,width andheight properties and their correspondingpresentation attributes, respectively.
Thex,y,width andheight IDL attributesreflect the computed values of thex,y,width andheight properties and their correspondingpresentation attributes, respectively.
