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.