HTML 5.1

[NoInterfaceObject]
interface HTMLHyperlinkElementUtils {
  stringifier attribute USVString href;
  readonly attribute USVString origin;
  attribute USVString protocol;
  attribute USVString username;
  attribute USVString password;
  attribute USVString host;
  attribute USVString hostname;
  attribute USVString port;
  attribute USVString pathname;
  attribute USVString search;
  attribute USVString hash;
};

An element implementing the HTMLHyperlinkElementUtils mixin has an associated url (null or a URL). It is initially null.

An element implementing the HTMLHyperlinkElementUtils mixin has an associated set the url algorithm, which sets this element’s URL to the resulting URL string of parsing this element’s href content attribute value relative to this element. If parsing was aborted with an error, set this element’s URL to null.

When elements implementing the HTMLHyperlinkElementUtils mixin are created, and whenever those elements have their href content attribute set, changed, or removed, the user agent must set the url.

This is only observable for blob: URLs as parsing them involves the StructuredClone abstract algorithm.

An element implementing the HTMLHyperlinkElementUtils mixin has an associated reinitialise url algorithm, which runs these steps:

1. If element’s URL is non-null, its scheme is "blob", and its non-relative flag is set, terminate these steps.
2. Set the url.

To update href, set the element’s href content attribute’s value to the element’s URL, serialized.

---

The href attribute’s getter must run these steps:

1. Reinitialise url.
2. Let url be this element’s URL.
3. If url is null and this element has no href content attribute, return the empty string.
4. Otherwise, if url is null, return this element’s href content attribute’s value.
5. Return url, serialized.

The href attribute’s setter must set this element’s href content attribute’s value to the given value.

The origin attribute’s getter must run these steps:

1. Reinitialise url.
2. If this element’s URL is null, return the empty string.
3. Return the Unicode serialization of this element’s URL’s origin.

It returns the Unicode rather than the ASCII serialization for compatibility with MessageEvent.

The protocol attribute’s getter must run these steps:

1. Reinitialise url.
2. If this element’s URL is null, return ":".
3. Return this element’s URL’s scheme, followed by ":".

The protocol attribute’s setter must run these steps:

1. Reinitialise url.
2. If this element’s URL is null, terminate these steps.
3. Basic URL parse the given value, followed by :", with this element’s URL as url and scheme start state as state override.
4. Update href.

The username attribute’s getter must run these steps:

1. Reinitialise url.
2. If this element’s URL is null, return the empty string.
3. Return this element’s URL’s username.

The username attribute’s setter must run these steps:

1. Reinitialise url.
2. Let url be this element’s URL.
3. If url or url’s host is null, or url’s non-relative flag is set, terminate these steps.
4. set the username, given url and the given value.
5. Update href.

The password attribute’s getter must run these steps:

1. Reinitialise url.
2. Let url be this element’s URL.
3. If url or url’s password is null, return the empty string.
4. Return url’s password.

The password attribute’s setter must run these steps:

1. Reinitialise url.
2. Let url be this element’s URL.
3. If url or url’s host is null, or url’s non-relative flag is set, terminate these steps.
4. Set the password, given url and the given value.
5. Update href.

The host attribute’s getter must run these steps:

1. Reinitialise url.
2. Let url be this element’s URL.
3. If url or url’s host is null, return the empty string.
4. If url’s port is null, return url’s host, serialized.
5. Return url’s host, serialized, followed by ":" and url’s port, serialized.

The host attribute’s setter must run these steps:

1. Reinitialise url.
2. Let url be this element’s URL.
3. If url is null or url’s non-relative flag is set, terminate these steps.
4. Basic URL parse the given value, with url as url and host state as state override.
5. Update href.

The hostname attribute’s getter must run these steps:

1. Reinitialise url.
2. Let url be this element’s URL.
3. If url or url’s host is null, return the empty string.
4. Return url’s host, serialized.

The hostname attribute’s setter must run these steps:

1. Reinitialise url.
2. Let url be this element’s URL.
3. If url is null or url’s non-relative flag is set, terminate these steps.
4. Basic URL parse the given value, with url as url and hostname state as state override.
5. Update href.

The port attribute’s getter must run these steps:

1. Reinitialise url.
2. Let url be this element’s URL.
3. If url or url’s port is null, return the empty string.
4. Return url’s port, serialized.

The port attribute’s setter must run these steps:

1. Reinitialise url.
2. Let url be this element’s URL.
3. If url or url’s host is null, url’s non-relative flag is set, or url’s scheme is "file", terminate these steps.
4. Basic URL parse the given value, with url as url and port state as state override.
5. Update href.

The pathname attribute’s getter must run these steps:

1. Reinitialise url.
2. Let url be this element’s URL.
3. If url is null, return the empty string.
4. If url’s non-relative flag is set, return the first string in url’s path.
5. Return "/", followed by the strings in url’s path (including empty strings), separated from each other by "/".

The pathname attribute’s setter must run these steps:

1. Reinitialise url.
2. Let url be this element’s URL.
3. If url is null or url’s non-relative flag is set, terminate these steps.
4. Set url’s path to the empty list.
5. Basic URL parse the given value, with url as url and path start state as state override.
6. Update href.

The search attribute’s getter must run these steps:

1. Reinitialise url.
2. Let url be this element’s URL.
3. If url is null, or url’s query is either null or the empty string, return the empty string.
4. Return "?", followed by url’s query.

The search attribute’s setter must run these steps:

1. Reinitialise url.
2. Let url be this element’s URL.
3. If url is null, terminate these steps.
4. If the given value is the empty string, set url’s query to null.

5. Otherwise, run these substeps:

   1. Let input be the given value with a single leading "?" removed, if any.
   2. Set url’s query to the empty string.
   3. Basic URL parse input, with url as url and query state as state override, and this element’s node document’s document’s character encoding as encoding override.
6. Update href.

The hash attribute’s getter must run these steps:

1. Reinitialise url.
2. Let url be this element’s URL.
3. If url is null, or url’s fragment is either null or the empty string, return the empty string.
4. Return "#", followed by url’s fragment.

The hash attribute’s setter must run these steps:

1. Reinitialise url.
2. Let url be this element’s URL.
3. If url is null or url’s scheme is "javascript", terminate these steps.
4. If the given value is the empty string, set url’s fragment to null.

5. Otherwise, run these substeps:

   1. Let input be the given value with a single leading "#" removed, if any.
   2. Set url’s fragment to the empty string.
   3. Basic URL parse input, with url as url and fragment state as state override.
6. Update href.

4.8.4. Following hyperlinks

When a user follows a hyperlink created by an element subject, optionally with a hyperlink suffix, the user agent must run the following steps:

1. Let replace be false.
2. Let source be the browsing context that contains the Document object with which subject in question is associated.

3. If the user indicated a specific browsing context when following the hyperlink, or if the user agent is configured to follow hyperlinks by navigating a particular browsing context, then let target be that browsing context. If this is a new top-level browsing context (e.g., when the user followed the hyperlink using "Open in New Tab"), then source must be set as the new browsing context’s one permitted sandboxed navigator.

   Otherwise, if subject is an a or area element that has a target attribute, then let target be the browsing context that is chosen by applying the rules for choosing a browsing context given a browsing context name, using the value of the target attribute as the browsing context name. If these rules result in the creation of a new browsing context, set replace to true.

   Otherwise, if target is an a or area element with no target attribute, but the Document contains a base element with a target attribute, then let target be the browsing context that is chosen by applying the rules for choosing a browsing context given a browsing context name, using the value of the target attribute of the first such base element as the browsing context name. If these rules result in the creation of a new browsing context, set replace to true.

   Otherwise, let target be the browsing context that subject itself is in.

4. Parse the URL given by subject’s href attribute, relative to subject’s node document.

5. If that is successful, let URL be the resulting URL string.

   Otherwise, if parsing the URL failed, the user agent may report the error to the user in a user-agent-specific manner, may queue a task to navigate the target browsing context to an error page to report the error, or may ignore the error and do nothing. In any case, the user agent must then abort these steps.

6. If there is a hyperlink suffix, append it to URL.
7. Queue a task to navigate the target browsing context to URL. If replace is true, the navigation must be performed with replacement enabled. The source browsing context must be source.

The task source for the tasks mentioned above is the DOM manipulation task source.

---

When a user downloads a hyperlink created by an element subject, optionally with a hyperlink suffix, the user agent must run the following steps:

1. Parse the URL given by subject’s href attribute, relative to subject.
2. If parsing the URL fails, the user agent may report the error to the user in a user-agent-specific manner, may navigate to an error page to report the error, or may ignore the error and do nothing. In either case, the user agent must abort these steps.
3. Otherwise, let URL be the resulting URL string.
4. If there is a hyperlink suffix, append it to URL.
5. Return to whatever algorithm invoked these steps and continue these steps in parallel.
6. Fetch URL and handle the resulting resource as a download.

When a user agent is to handle a resource obtained from a fetch as a download, it should provide the user with a way to save the resource for later use, if a resource is successfully obtained; or otherwise should report any problems downloading the file to the user.

If the user agent needs a file name for a resource being handled as a download, it should select one using the following algorithm.

This algorithm is intended to mitigate security dangers involved in downloading files from untrusted sites, and user agents are strongly urged to follow it.

1. Let filename be the void value.
2. If the resource has a Content-Disposition header, that header specifies the attachment disposition type, and the header includes file name information, then let filename have the value specified by the header, and jump to the step labeled sanitize below. [RFC6266]
3. Let interface origin be the origin of the Document in which the download or navigate action resulting in the download was initiated, if any.
4. Let resource origin be the origin of the URL of the resource being downloaded, unless that URL’s scheme component is data, in which case let resource origin be the same as the interface origin, if any.
5. If there is no interface origin, then let trusted operation be true. Otherwise, let trusted operation be true if resource origin is the same origin as interface origin, and false otherwise.
6. If trusted operation is true and the resource has a Content-Disposition header and that header includes file name information, then let filename have the value specified by the header, and jump to the step labeled sanitize below. [RFC6266]
7. If the download was not initiated from a hyperlink created by an a or area element, or if the element of the hyperlink from which it was initiated did not have a download attribute when the download was initiated, or if there was such an attribute but its value when the download was initiated was the empty string, then jump to the step labeled no proposed file name.
8. Let proposed filename have the value of the download attribute of the element of the hyperlink that initiated the download at the time the download was initiated.
9. If trusted operation is true, let filename have the value of proposed filename, and jump to the step labeled sanitize below.
10. If the resource has a Content-Disposition header and that header specifies the attachment disposition type, let filename have the value of proposed filename, and jump to the step labeled sanitize below. [RFC6266]
11. No proposed file name: If trusted operation is true, or if the user indicated a preference for having the resource in question downloaded, let filename have a value derived from the URL of the resource in a user-agent-defined manner, and jump to the step labeled sanitize below.

12. Act in a user-agent-defined manner to safeguard the user from a potentially hostile cross-origin download. If the download is not to be aborted, then let filename be set to the user’s preferred file name or to a file name selected by the user agent, and jump to the step labeled sanitize below.

    If the algorithm reaches this step, then a download was begun from a different origin than the resource being downloaded, and the origin did not mark the file as suitable for downloading, and the download was not initiated by the user. This could be because a download attribute was used to trigger the download, or because the resource in question is not of a type that the user agent supports.

    This could be dangerous, because, for instance, a hostile server could be trying to get a user to unknowingly download private information and then re-upload it to the hostile server, by tricking the user into thinking the data is from the hostile server.

    Thus, it is in the user’s interests that the user be somehow notified that the resource in question comes from quite a different source, and to prevent confusion, any suggested file name from the potentially hostile interface origin should be ignored.

13. Sanitize: Optionally, allow the user to influence filename. For example, a user agent could prompt the user for a file name, potentially providing the value of filename as determined above as a default value.

14. Adjust filename to be suitable for the local file system.

    For example, this could involve removing characters that are not legal in file names, or trimming leading and trailing whitespace.

15. If the platform conventions do not in any way use extensions to determine the types of file on the file system, then return filename as the file name and abort these steps.
16. Let claimed type be the type given by the resource’s Content-Type metadata, if any is known. Let named type be the type given by filename’s extension, if any is known. For the purposes of this step, a type is a mapping of a MIME type to an extension.
17. If named type is consistent with the user’s preferences (e.g., because the value of filename was determined by prompting the user), then return filename as the file name and abort these steps.
18. If claimed type and named type are the same type (i.e., the type given by the resource’s Content-Type metadata is consistent with the type given by filename’s extension), then return filename as the file name and abort these steps.

19. If the claimed type is known, then alter filename to add an extension corresponding to claimed type.

    Otherwise, if named type is known to be potentially dangerous (e.g., it will be treated by the platform conventions as a native executable, shell script, HTML application, or executable-macro-capable document) then optionally alter filename to add a known-safe extension (e.g., ".txt").

    This last step would make it impossible to download executables, which might not be desirable. As always, implementors are forced to balance security and usability in this matter.

20. Return filename as the file name.

For the purposes of this algorithm, a file extension consists of any part of the file name that platform conventions dictate will be used for identifying the type of the file. For example, many operating systems use the part of the file name following the last dot (".") in the file name to determine the type of the file, and from that the manner in which the file is to be opened or executed.

User agents should ignore any directory or path information provided by the resource itself, its URL, and any download attribute, in deciding where to store the resulting file in the user’s file system.

To determine which link types apply to a link, a, or area element, the element’s rel attribute must be split on spaces. The resulting tokens are the link types that apply to that element.

Some of the types described below list synonyms for these values. These are to be handled as specified by user agents, but must not be used in documents.

Synonyms: For historical reasons, user agents must also treat link, a, and area elements that have a rev attribute with the value "made" as having the author keyword specified as a link relationship.

...
 <body>
 <h1>Example of permalinks</h1>
 <div id="a">
   <h2>First example</h2>
   <p><a href="a.html" rel="bookmark">This permalink applies to
   only the content from the first H2 to the second H2</a>. The DIV isn’t
   exactly that section, but it roughly corresponds to it.</p>
 </div>
 <h2>Second example</h2>
 <article id="b">
   <p><a href="b.html" rel="bookmark">This permalink applies to
   the outer ARTICLE element</a> (which could be, e.g., a blog post).</p>
   <article id="c">
   <p><a href="c.html" rel="bookmark">This permalink applies to
   the inner ARTICLE element</a> (which could be, e.g., a blog comment).</p>
   </article>
 </article>
 </body>
 ...

<p><label> Topic: <input name=topic> <a href="help/topic.html" rel="help">(Help)</a></label></p>

The specified resource is an icon representing the page or site, and should be used by the user agent when representing the page in the user interface.

User agents are not required to update icons when the list of icons changes, but are encouraged to do so.

There is no default type for resources given by the icon keyword. However, for the purposes of determining the type of the resource, user agents must expect the resource to be an image.

To parse and process the attribute’s value, the user agent must first split the attribute’s value on spaces, and must then parse each resulting keyword to determine what it represents.

Other keywords must be further parsed as follows to determine what they represent:

• If the keyword doesn’t contain exactly one U+0078 LATIN SMALL LETTER X or U+0058 LATIN CAPITAL LETTER X character, then this keyword doesn’t represent anything. Abort these steps for that keyword.
• Let width string be the string before the "x" or "X".
• Let height string be the string after the "x" or "X".
• If either width string or height string start with a U+0030 DIGIT ZERO (0) character or contain any characters other than ASCII digits, then this keyword doesn’t represent anything. Abort these steps for that keyword.
• Apply the rules for parsing non-negative integers to width string to obtain width.
• Apply the rules for parsing non-negative integers to height string to obtain height.
• The keyword represents that the resource contains a bitmap icon with a width of width device pixels and a height of height device pixels.

In the absence of a link with the icon keyword, for Document objects obtained over HTTP or HTTPS, user agents may instead run these steps in parallel:

1. Let request be a new request whose URL is the absolute URL obtained by resolving the URL "/favicon.ico" against the document’s address, client is the Document object’s Window object’s environment settings object, type is "image", destination is "subresource", synchronous flag is set, credentials mode is "include", and whose use-URL-credentials flag is set.
2. Let response be the result of fetching request.
3. Use response’s unsafe response as an icon as if it had been declared using the icon keyword.

<!DOCTYPE HTML>
<html>
  <head>
  <title>lsForums — Inbox</title>
  <link rel=icon href=favicon.png sizes="16x16" type="image/png">
  <link rel=icon href=windows.ico sizes="32x32 48x48" type="image/vnd.microsoft.icon">
  <link rel=icon href=mac.icns sizes="128x128 512x512 8192x8192 32768x32768">
  <link rel=icon href=iphone.png sizes="57x57" type="image/png">
  <link rel=icon href=gnome.svg sizes="any" type="image/svg+xml">
  <link rel=stylesheet href=lsforums.css>
  <script src=lsforums.js></script>
  <meta name=application-name content="lsForums">
  </head>
  <body>
  ...

<!DOCTYPE HTML>
<html>
  <head>
  <title>Exampl Pictures: Kissat</title>
  <link rel="stylesheet" href="/style/default">
  </head>
  <body>
  <h1>Kissat</h1>
  <nav>
    <a href="../">Return to photo index</a>
  </nav>

  <main>
  <figure>
    <img src="/pix/39627052_fd8dcd98b5.jpg">
    <figcaption>Kissat</figcaption>
  </figure>
  <p>One of them has six toes!</p>
  <p><small>This photograph is <a rel="license" href="https://www.opensource.org/licenses/mit-license.php">MIT Licensed</a></small></p>
  </main>
  <footer>
    <a href="/">Home</a> | <a href="../">Photo index</a>
    <p><small>© copyright 2009 Exampl Pictures. All Rights Reserved.</small></p>
  </footer>
  </body>
</html>

Synonyms: For historical reasons, user agents must also treat the keyword "copyright" like the license keyword.

If a user agent follows a link defined by an a or area element that has the noreferrer keyword, the user agent must set their request’s referrer to "no-referrer".

This keyword also causes the opener attribute to remain null if the hyperlink creates a new browsing context.

The appropriate times to obtain the resource are:

• When the external resource link is created on a link element that is already in a Document.

• When the external resource link’s link element is inserted into a document.

• When the href attribute of the link element of an external resource link that is already in a Document is changed.

• When the crossorigin attribute of the link element of an external resource link that is already in a Document is set, changed, or removed.

• When the type attribute of the link element of an external resource link that is already in a Document is set or changed to a value that does not or no longer matches the Content-Type metadata of the previous obtained external resource, if any.

• When the type attribute of the link element of an external resource link that is already in a Document but was previously not obtained due to the type attribute specifying an unsupported type is set, removed, or changed.

• When the external resource link changes from being an alternative stylesheet to not being one, or vice versa.

Quirk: If the document has been set to quirks mode, has the same origin as the URL of the external resource, and the Content-Type metadata of the external resource is not a supported style sheet type, the user agent must instead assume it to be text/css.

Once a resource has been obtained, if its Content-Type metadata is text/css, the user agent must run these steps:

1. Let element be the link element that created the external resource link.

2. If element has an associated CSS style sheet, remove the CSS style sheet in question.

3. If element no longer creates an external resource link that contributes to the styling processing model, or if, since the resource in question was obtained, it has become appropriate to obtain it again (meaning this algorithm is about to be invoked again for a newly obtained resource), then abort these steps.

4. Create a CSS style sheet with the following properties:

   type

   text/css

   location

   The resulting URL string determined during the obtain algorithm.

   This is before any redirects get applied.

   owner node

   element

   media

   The media attribute of element.

   This is a reference to the (possibly absent at this time) attribute, rather than a copy of the attribute’s current value. The CSSOM specification defines what happens when the attribute is dynamically set, changed, or removed.

   title

   The title attribute of element.

   This is similarly a reference to the attribute, rather than a copy of the attribute’s current value.

   alternate flag

   Set if the link is an alternative stylesheet; unset otherwise.

   origin-clean flag

   Set if the resource is CORS-same-origin; unset otherwise.

   parent CSS style sheet

   owner CSS rule

   null

   disabled flag

   Left at its default value.

   CSS rules

   Left uninitialized.

   The CSS environment encoding is the result of running the following steps: [CSS-SYNTAX-3]

   1. If the element has a charset attribute, get an encoding from that attribute’s value. If that succeeds, return the resulting encoding and abort these steps. [ENCODING]

   2. Otherwise, return the document’s character encoding. [DOM]

<!DOCTYPE HTML>
<html>
  <head>
  <title>My Precious</title>
  </head>
  <body>
  <header><h1>My precious</h1> <p>Summer 2012</p></header>
  <p>Recently I managed to dispose of a red gem that had been
  bothering me. I now have a much nicer blue sapphire.</p>
  <p>The red gem had been found in a bauxite stone while I was digging
  out the office level, but nobody was willing to haul it away. The
  same red gem stayed there for literally years.</p>
  <footer>
    Tags: <a rel=tag href="https://en.wikipedia.org/wiki/Gemstone">Gemstone</a>
  </footer>
  </body>
</html>

<!DOCTYPE HTML>
<html>
  <head>
  <title>Gem 4/4</title>
  </head>
  <body>
  <article>
    <h1>801: Steinbock</h1>
    <p>The number 801 Gem 4/4 electro-diesel has an ibex and was rebuilt in 2002.</p>
  </article>
  <article>
    <h1>802: Murmeltier</h1>
    <figure>
    <img src="https://upload.wikimedia.org/wikipedia/commons/b/b0/Trains_de_la_Bernina_en_hiver_2.jpg"
          alt="The 802 was red with pantographs and tall vents on the side.">
    <figcaption>The 802 in the 1980s, above Lago Bianco.</figcaption>
    </figure>
    <p>The number 802 Gem 4/4 electro-diesel has a marmot and was rebuilt in 2003.</p>
  </article>
  <p class="topic"><a rel=tag href="https://en.wikipedia.org/wiki/Rhaetian_Railway_Gem_4/4">Gem 4/4</a></p>
  </body>
</html>

Synonyms: For historical reasons, user agents must also treat the keyword "previous" like the prev keyword.

Conformance checkers may use the information given on the microformats wiki existing-rel-values page to establish if a value is allowed or not: values defined in this specification or marked as "proposed" or "ratified" must be accepted when used on the elements for which they apply as described in the "Effect on..." field, whereas values marked as "discontinued" or values not containing a U+003A COLON character but not listed in either this specification or on the aforementioned page must be reported as invalid. The remaining values must be accepted as valid if they are absolute URLs containing US-ASCII characters only and rejected otherwise. Conformance checkers may cache this information (e.g., for performance reasons or to avoid the use of unreliable network connectivity).

Note: Even URL-valued link types are compared ASCII-case-insensitively. Validators might choose to warn about characters U+0041 (LATIN CAPITAL LETTER A) through U+005A (LATIN CAPITAL LETTER Z) (inclusive) in the pre-case-folded form of link types that contain a colon.

When an author uses a new type not defined by either this specification or the Wiki page, conformance checkers should offer to add the value to the Wiki, with the details described above, with the "proposed" status.