Relation

Relation

In graph terminology a relation represents a directed edge, a reference from one asset to another. For the purpose of being able to treat all relations equally, there's a subclass for each supported relation type, encapsulating the details of how to retrieve, update, and (optionally) inline the asset being pointed to.

These are some examples of included subclasses:

  • relations.HtmlAnchor An anchor tag in an HTML document <a href='...'>.
  • relations.HtmlImage An <img src='...'> tag in an HTML document.
  • relations.CssImport An @import declaration in a CSS asset.
  • relations.CacheManifestEntry A line in a cache manifest.

Constructor

new Relation(config)

Source:

Create a new Relation instance. For existing assets the instantiation of relations happens automatically if you use the populate transform. You only need to create relations manually when you need to introduce new ones.

Note that the base Relation class should be considered abstract. Please instantiate the appropriate subclass.

Options:

  • from The source asset of the relation.
  • to The target asset of the relation, or an asset configuration object if the target asset hasn't yet been resolved and created.
Parameters:
Name Type Description
config Object

The relation configuration

Members

baseUrl :String

Source:

Get the url of the first non-inlined ancestor of the from-Asset

Type:
  • String

canonical :Boolean

Source:

Get or set the canonical state of a Relation

If AssetGraph has a canonicalRoot property, AssetGraph will detect absolute URLs matching AssetGraph.canonicalRoot as if they were of hrefType rootRelative.

The getter tell you if Relation.href will be prepended with Assetgraph.canonicalRoot.

The setter will change the Relation's href to be prefixed with AssetGraph.canonicalRoot if true, and without if false

Type:
  • Boolean

crossorigin :Boolean

Source:

Get the relations cross origins status defined as differences in protocol or hostname.

This property is quite useful as part of a population query to ensure that the graph doesn't expand beyond the current host or file system

Type:
  • Boolean

fragment :String

Source:

Get or set the fragment identifier part of the href of the relation.

Setting a fragment with a non-empty value requires the value to begin with #

Type:
  • String

from :Asset

Source:

The source asset of the relation.

Type:

href :String

Source:

Get or set the href of the relation. The relation must be attached to an asset.

What is actually retrieved or updated depends on the relation type. For HtmlImage the src attribute of the HTML element is changed, for CssImport the parsed representation of the @import rule is updated, etc.

Most of the time you don't need to think about this property, as the href is automatically updated when the url of the source or target asset is changed, or an intermediate asset is inlined.

Type:
  • String

hrefType :String

Source:

Either 'absolute', 'rootRelative', 'protocolRelative', 'relative', or 'inline'. Decides what "degree" of relative url refreshHref() tries to issue, except for 'inline' which means that the target asset is contained in a data: url or similar.

Type:
  • String

(constant) isRelation :Boolean

Source:

Property that's true for all relation instances. Avoids reliance on the instanceof operator.

Type:
  • Boolean

node :Object

Source:

The ATS/DOM-node where the Relation originates in the parent document

Type:
  • Object

to :Asset

Source:

The target asset of the relation.

Type:

Methods

attach(position, adjacentRelation) → {Relation}

Source:

Attaches the relation to an asset.

The ordering of certain relation types is significant (HtmlScript, for instance), so it's important that the order isn't scrambled in the indices. Therefore the caller must explicitly specify a position at which to insert the object.

Parameters:
Name Type Description
position String

"first", "last", "before", or "after".
adjacentRelation Relation

The adjacent relation, mandatory if the position is "before" or "after".
Returns:

The relation itself (chaining-friendly).

Type
Relation

detach() → {Relation}

Source:

Detaches the relation from the asset it is currently attached to. If the relation is currently part of a graph, it will removed from it.

Detaching implies that the tag/statement/declaration representing the relation is physically removed from the referring asset. Not all relation types support this.

Returns:

The relation itself (chaining-friendly).

Type
Relation

inline() → {Relation}

Source:

Inline the relation. This is only supported by certain relation types and will produce different results depending on the type (data: url, inline script, inline stylesheet...).

Will make a clone of the target asset if it has more incoming relations than this one.

Returns:

The relation itself (chaining-friendly).

Type
Relation

refreshHref() → {Relation}

Source:

Update href of a relation to make sure it points at the current url of its target asset.

It's not necessary to call this function manually as long as the source and target assets of the relation have only been moved by having their url property changed (the recommended way), but some transforms will need this after some low-level surgery, such as attaching an existing relation to a different asset.

Returns:

The relation itself (chaining-friendly).

Type
Relation

remove() → {Relation}

Source:

Removes the relation from the graph it's currently part of. Doesn't detach the relation (compare with relation.detach()).

Returns:

The relation itself (chaining-friendly).

Type
Relation

toString() → {String}

Source:

Get a brief text containing the type, id of the relation. Will also contain the .toString() of the relation's source and target assets if available.

Returns:

The string, eg. `"[HtmlAnchor/141: [Html/40 file:///foo/bar/index.html] => [Html/76 file:///foo/bar/otherpage.html]]"``

Type
String