Inline Links

QName: f:inline-links

Adds support for automatic text parsing and discovery and tracking of linked references within text-based markup (referred to here
as "inline links").

When this feature is present on a node, any persistence operations (such as create or update) will run some additional
logic over your text fields. If text is discovered, it is potentially parsed and the discovered contents of the text
are inspected for inline links.

If your text fields contain HTML, the HTML is parsed and the DOM is inspected for elements that have special data
attributes on them to indicate references to other nodes within Cloud CMS. In addition, external links for anchors
and image tags are discovered and will be represented as standalone nodes (of type n:linked-resource) within
the content graph.

If your text isn't HTML but contains URLs (starting with http:// or https://), then those external links will
likewise be discovered and presented as standalone nodes (of type n:linked-resource) within the content graph.

Inline links use Relator Properties under the hood to automatically track references
and model associations from the source document to the linked document. These associations are of type a:links-to.

The links are stored in a property on your source document JSON called inline-links.

The presence of inline links between a source document and a linked document will prevent the linked document from
being deleted. Editors who try to delete a linked document will receive an error message indicating that the linked
document cannot be deleted. The error message will further explain which source documents are linked to the linked
document so that the editors can remove those references before deleting.

Configuration

Inline Links Example

Suppose you have a content type called my:article.

We give this content type the f:inline-links mandatory feature so that it looks like this:

{
    "title": "Article",
    "type": "object",
    "properties": {
        "title": {
            "title": "Title",
            "type": "string"
        },
        "body": {
            "title": "Body",
            "type": "string"
        }        
    },
    "_qname": "my:article",
    "_type": "d:type",
    "mandatoryFeatures": {
        "f:inline-links": {}
    }
}

Suppose we now create an article with the following JSON:

    "title": "Hello World",
    "body": "<p><a href='https://gitana.io'>Cloud CMS is awesome</a></p>"

When we save it, the HTML anchor tag will be discovered. The following will happen:

  • A Linked Resource (of type n:linked-resource) will be created to represent the https://gitana.io web resource.
  • A relator property will be automatically added under the inline-links property on our JSON.
  • Our HTML will be modified so that we can work out which relator property goes with which DOM element.

The result will look like something like this:

    "title": "Hello World",
    "body": "<p><a data-link-id='linkId1' data-ref='node://platformId/repositoryId/branchId/nodeId' href='https://gitana.io'>Cloud CMS is awesome</a></p>",
    "inline-links": {
        "ref": "node://platformId/repositoryId/branchId/nodeId",
        "id": "nodeId",
        "typeQName": "n:linked-resource",
        "qname": "o:nodeId",
        "title": "https://gitana.io",
        "linkId": "linkId1"
    }

Note that the data-link-id DOM attribute was automatically added to our HTML. This gives Cloud CMS the ability to
figure out which property goes with which inline link that its tracking. As you save, update and delete content
within Cloud CMS, these properties and these associations are automatically adjusted and maintained for you.

Also notice that the data-link-ref attribute was added. This provides a way to get a reference to the thing being
linked right from the DOM.

You can populate the data-link-ref attribute directly if you wish. Suppose you have an image node (of type my:image)
and the image node's reference is node://platformId/repositoryId/branchId/imageNodeId. You could create the following:

    "title": "My Article",
    "body": "<p><img data-ref='node://platformId/repositoryId/branchId/imageNodeId' src='someUrl'></p>"

The data-ref will be parsed and the relators will get built out for you. Your JSON will look like this:

    "title": "My Article",
    "body": "<p><img data-link-id='imageLinkId' data-ref='node://platformId/repositoryId/branchId/imageNodeId' src='someUrl'></p>",
    "inline-links": {
        "ref": "node://platformId/repositoryId/branchId/imageNodeId",
        "id": "imageNodeId",
        "typeQName": "my:image",
        "qname": "o:imageNodeId",
        "title": "My Image",
        "linkId": "imageLinkId"
    }

Note that this accomplishes the same thing as the aforementioned. The difference is that the anchor href or image
src aren't parsed since you've already identified the linked resource.