Ortext Key Linking

In addition to supporting timelining, theĀ Ortext Build plugin enables internal key linking. Post-to-post links within the ortext can be made via an [otx] shortcode containing the link key. These key links are most useful for maintaining content external to the ortext, such as bibliographic references. Key links ease the process of importing and updating such content. Key links also provide an easy means for passing citation specifications to the linked post.

To use key linking with an external bibliographic reference manager, you need a unique key associated with each bibliographic reference. You use that unique key as the linking key. With references, a handy type of key is {author}-{publication date}. If you use a simple form of the first author’s last name and the publication date, you can easily remember the reference key. You can then link to the reference in the WordPress rich-text editor by pressing the key-link buttonkey-link iconand adding the link key to the key-value field that appears. The key-link button appears in the rich-text editor after the Ortext Build plugin has been activated. Because of time and knowledge constraints, we haven’t made the key-link button available in the text view or just-write (no distractions) editors.

By having key-linked references, you can easily import (and re-import) references into WordPress. You don’t have to worry about breaking established reference links or requiring references to be imported under a specific permalink slug. You can also link to the reference before you have actually imported the reference into your ortext. Use the Ortext BibTex Importer plugin to import references in BibTex format and create individual posts for them in a custom post_type, e.g. refs.

Key links include a short form for passing citation specifications to the linked post. In the key link, any text after the @ symbol is passed to the linked post as the query variable otxrp. TheĀ Ortext Formatting plugin takes the value of the otxrp and displays it above the linked post prefaced by the text “Reference point:”. For example, suppose you want to reference p. 79 in Diego Garcia’s 2004 book, I Long for Your Visit. In your external reference manager, you establish the key Garcia-2004 for that reference. You insert a link to that reference within your ortext by inserting the key link “Garcia-2004@p. 79”. That key link will resolve to a hyperlink to the reference page with “Reference point: p. 79” displayed at the top. Of course, at some point you also have to import that reference into your ortext.

Key links are implemented via the otx shortcode. From the admin side (writing posts), a key link appears in the content as the shortcode [otx “{key@cs}”] [/otx]. The @ and any text after it are optional. When the post is displayed, the key link is resolved to a hyperlink with the class otx-link. If an @ follows the key, then the hyperlink includes the query variable otxrp containing the URL-encoded text following the @. You can add a key link that doesn’t contain any content. That’s appropriate for a note at the end of a sentence. That key link will be resolved to a hyperlinked caret (^ ). The key-link button allows you to quickly search by post type for the relevant post to link.

Key links are available for all post types, not just references. Each post is automatically associated with a key of the form {post-type}-{post ID number}. Most of the post-to-post links in this ortext (other than reference links) have been set with the automatic key links. However, you can set your own link keys. The link key for any post is included in the post meta under the meta-key otx-key. If you change the otx-key value, you will break any key links that you have already inserted using the old key. The Ortext BibTex Importer sets the otx-key to the value specified in the relevant BibTex string.

External hosting locations for datasets are imported via the otx-key for datasets. For importing datasets, it’s generally convenient to set the dataset otx-key to a clean file name for a version of the dataset.

In serving a page to readers, key links require additional queries to resolve the links. Hence key links should be flipped to full-URL links before pages are served at scale in an operational environment. The Ortext Build plugin includes utility functions to flip links between key links and standard permalink hyperlinks. The key link is included as the value of the query variable otxkey to allow the permalink to be flipped back to the key link. As distributed, this ortext has its key links already flipped to standard permalink hyperlinks.

The Ortext Build plugin’s key linking involves code that’s relatively difficult to secure. In particular, the thick box pop-up for linking must be secured against exploits. Securing it well requires considerable technical expertise. We lack confidence that we have strongly secured the linking box. Hence we have appended to the plugin name SECURITY HAZARD. We strongly recommend not putting the Ortext Build plugin on a publicly accessible server. This plugin should only be used on a local server secure behind a fire wall.

Key links are an experimental feature of this ortext. We have some preliminary thoughts on advantages and disadvantages of key links. You are encouraged to think about key links for large works, their advantages and disadvantages, how you could make them better, and whether you want to use them.

Leave a comment (will be included in public domain license)

Your email address will not be published. Required fields are marked *