Overview.bs

<pre class='metadata'>
Title: CSS Linked Parameters Module Level 1
Shortname: css-link-params
Level: 1
Status: ED
Group: CSSWG
Work Status: exploring
ED: https://drafts.csswg.org/css-link-params/
Editor: Tab Atkins-Bittner, Google, http://xanthir.com/contact/
Editor: Daniel Holbert, Mozilla
Editor: Jonathan Watt, Mozilla
Abstract: This spec introduces a way to pass CSS values into linked resources, such as SVG images, so that they can be used as CSS [=custom environment variables=] in the destination resource. This allows easy reuse of "templated" SVG images, which can be adapted to a site's theme color, etc. easily, without having to modify the source SVG.
Ignored Terms: css value definition syntax
</pre>

<pre class="link-defaults">
spec:selectors-4; type:selector; text::hover
spec:html; type:element
	text: iframe
	text: a
spec:fill-stroke-3; type:property; text:fill
</pre>

Introduction {#intro}
=====================

SVG is stylable with CSS,
and when used inline in HTML,
this capability can be very useful.
For example, an SVG icon can take on a different color based on whether the user is hovering it or not,
just by applying a '':hover'' rule to it that changes the 'fill' property.

When the SVG is referenced in a way that doesn't allow selectors or CSS inheritance from the outer page to apply to it
(such as embedding it via <{img}> or <{iframe}> in HTML),
though, this functionality is lost.
The only way to change the display of such "external" SVG images
is to produce several of them,
and change which image you're referencing.
This incurs delay on the page as a new resource is downloaded,
and disallows dynamic effects like CSS Transitions.

<dfn export lt="CSS link parameter" local-lt="link parameter">CSS link parameters</dfn>
are a way to set CSS <a>custom environment variables</a> on an "external" resource,
either by a CSS property
or thru a special fragment scheme on the URL.
This gives a limited, but powerful, subset of the customizability that "inline" SVG images have
to "external" SVG images.

A [=link parameter=] is a pair of a <<dashed-ident>> name,
and an arbitrary (possibly empty) <<declaration-value>> value.

<div class=example>
	For example, an SVG image can be written to use [=link parameters=],
	allowing it to have its colors changed on the fly,
	like:

	<xmp highlight=html>
		<svg>
			<path fill="env(--color, black)" d="..." />
		</svg>
	</xmp>

	By default, it will fill its shape with black,
	as that's the fallback color specified.
	But [=link parameters=] can customize the color
	in several ways:

	<xmp highlight=html>
		<img src="image.svg#param(--color,green)">
	</xmp>

	<pre highlight=css>
		img {
			link-parameters: param(--color, green);
		}
	</pre>

	<pre highlight=css>
		.foo {
			background-image: url("image.svg", param(--color, green));
		}
	</pre>
</div>

Setting a Link Parameter {#setting}
===================================

An external resource can be accompanied by a list of [=link parameters=],
each entry composed of a <<dashed-ident>> as a key,
and a (possibly empty) <<declaration-value>> as the value.

There are three ways to specify a [=link parameter=]:

* via the 'link-parameters' property,
	which applies to the resource itself
	(if the element represents an external resource),
	and to all external resources used in CSS properties on the element
* via a special syntax in the fragment portion of the URL of an external resource
* via a ''param()'' argument in the ''url()'' syntax

If specified in multiple of these ways,
all of the [=link parameters=] are appended into a single list
for the external resource,
in the order:

1. the 'link-parameters' property on the element, if relevant
2. the [=param()=] URL fragment identifiers
3. the ''param()'' <<url-modifier>>s in ''url()''

If multiple [=link parameters=] exist with the same name,
the last one in the list is used.

How to access [=link parameters=] in the linked resource
is defined in the next section,
[[#using]].


In CSS: the 'link-parameters' property {#link-param-prop}
--------------------------------------

<pre class=propdef>
Name: link-parameters
Value: none | <<param()>>#
Initial: none
Inherited: no
Applies to: all elements and pseudo-elements
Computed value: as specified
Animation type: discrete
</pre>

The 'link-parameters' property is one way to set [=link parameters=]
on the element itself
(if it is an element representing an external resource,
such as an HTML <{img}> or <{iframe}>),
and on all external CSS resources specified on the element
(such as background images, etc).
Its values are:

<dl dfn-type=value dfn-for=none>
	: <dfn>none</dfn>
	:: No [=link parameters=] are specified.

	: <dfn><<param()>>#</dfn>
	:: A list of one or more [=link parameters=].
</dl>

The <dfn>param()</dfn> function specifies a [=link parameter=],
with a key of the <<dashed-ident>>,
and a value of the <css><<declaration-value>>?</css>.
(If the <<declaration-value>> is omitted,
it represents an empty value.)
It has the syntax:

<pre class=prod>
	&lt;param()> = param( <<dashed-ident>> , <<declaration-value>>? )
</pre>


In The URL {#url-frag}
----------

A special "fragment identifier" can be used in the <a for=url>fragment</a> of a URL
used to reference an external resource.
Several examples of existing "fragment identifiers" for SVG documents can be found in <a href="http://www.w3.org/TR/SVG/linking.html#LinksIntoSVG">the SVG 1.1 specification</a>.

The syntax of an <dfn export local-lt="param()">SVG parameter fragment identifier</dfn> is:

<pre class=prod>param( <<dashed-ident>> , <<declaration-value>>? )</pre>

(using the <a>CSS value definition syntax</a>; TODO define an actual parser for it).

<div class="example">
	For example, to set the ''env(--text-color)'' [=custom environment variable=]
	of an SVG image to ''blue'',
	one can reference the image with a url like
	“<code>http://example.com/image.svg#param(--text-color,blue)</code>”.
</div>

Multiple [=link parameters=] can be passed to an image
by appending multiple [=param()=] fragment identifiers to the URL.

<div class="example">
	For example, if the image from the previous example also used ''env(--bg-color)'',
	it could be referenced with a url like
	“<code>http://example.com/image.svg#param(--text-color,blue)param(--bg-color,white)</code>”
	to set both ''env(--text-color)'' and ''env(--bg-color)''.
</div>

Note: Spaces, and some other characters that might be valid in CSS syntax,
are not technically valid in URLs.
In some contexts,
you might need to escape those characters to form a valid URL.
In most cases, though,
such as HTML's <{a}> element or CSS's ''url()'' function,
spaces are accepted and do not need to be escaped.

Setting via the CSS ''url()'' Function {#setting-url}
-----------------------------------------------------

When referencing an external resource via CSS,
the <a>param()</a> function can be used in the ''url()'' function.
But a common use-case is passing in values of the page's own <a>custom properties</a>;
for example, a page might use a ''--primary-color'' <a>custom property</a>,
and want to make an SVG image match.
There's no way, however, to integrate the value of a <a>custom property</a> in CSS into the URL passed to the ''url()'' function.

To accommodate this,
''param()'' is a valid <<url-modifier>>.
All the ''param()''s specified as a <<url-modifier>>
define [=link parameters=],
as for 'link-parameters'.

<div class="example">
	For example,
	if the site is using a ''--primary-color'' custom property to theme its elements with,
	and wanted an SVG background using ''env(--color)'' to reflect it,
	it could write:

	<pre highlight=css>
		.foo {
			background-image: url(
				"http://example.com/image.svg"
				param(--color, var(--primary-color))
			);
		}
	</pre>
</div>

Using Link Parameters {#using}
=====================

When an external resource link has one or more [=link parameters=] specified,
if the linked resource understands CSS
(such as an SVG or HTML document),
then those [=link parameters=]
establish global [=custom environment variables=] for the resource
with their name and value,
accessible with the ''env()'' function in stylesheets.

<div class="example">
	For example, if an SVG image wanted to expose a ''--color'' parameter,
	it could use it like:

	<xmp highlight=html>
		<svg>
			<g style="fill: env(--color);">
				<path d="..." />
			</g>
		</svg>
	</xmp>
</div>

<div class="note">
	It's usually a good idea to make your SVG image usable even if no parameters are given,
	by providing "default values" for each of the custom properties.
	There are several ways to do this.

	1. On each ''env()'' function, provide a fallback value, like ''fill: env(--color, blue)''.
	2. If the ''env()'' is going to be used a lot,
		such that providing a fallback for each individual ''env()'' is troublesome,
		store the [=custom environment variable=] in a [=scoped environment variable=]
		of a different name,
		with the default specified,
		like:

		<pre class="lang-css">
			@env --color2: env(--color, blue);

			/* Alternately, store it in a custom property: */
			:root {
				--color: env(--color, blue);
			}
		</pre>

		In this example, if ''--color'' is provided via a [=linked parameter=],
		''env(--color2)'' will contain its value.
		If not, it will contain the default ''blue'' value.
		In either case, ''env(--color2)'' can be used in the stylesheet unconditionally,
		secure in the knowledge that it will always have a value.
</div>

Note: When we define ''env(parent --color)'' to jump up a scope level,
you won't need to do the rename;
''@env --color: env(parent --color);'' will work just fine.


<h2 class="no-num no-ref" id=priv>
Privacy Considerations</h2>

This specification introduces no new privacy considerations.

<h2 class="no-num no-ref" id=sec>
Security Considerations</h2>

This specification introduces a new way to pass information to a linked resource,
potentially from a hostile source.

While no explicit handshake is established for this channel,
the use of ''env()'' to use the information
minimizes the chance that the linked resource
can be <em>surprised</em> by the information.
The only way for the page to be vulnerable
is to somehow be using an <em>unknown</em> ''env()'' in their styles,
which will just result in invalid properties by default,
and be visible in the developer's Dev Tools.

Any hostile information can also only affect
individual CSS properties that the resource explicitly opts itself into.