An Ultralink Root is the primary way to configure/customize Ultralink functionality and is used to extend it with your own custom behaviors. A Root is simply a directory with a specific file structure that can be accessed by the Ultralink code. You use the remoteRoots option to load your Root and activate its settings and functionality.
As your author your own Roots, use the Ultralink Root Debugger to perform sanity checks and test out your custom link type functionality.
Top-level Directory Structure
| .htaccess | optional | Can be used to ensure that the directory will be remotely accessible. |
| linkTypes/ | optional | A directory containing all the custom link type files this Root is providing. |
| options.json | required | Contains an Ultralink Options object. Dictates the customization this Root provides. |
| optional | .htaccess |
| Can ensure that the directory will be remotely accessible. | |
| optional | linkTypes/ |
| A directory containing all the custom link type files this Root is providing. | |
| required | options.json |
| Contains an Ultralink Options object. Dictates the customization this Root provides. | |
Ultralink Roots typically reside in web-accessible locations and thus need to be accessible from within the different environments that the Ultralink code will execute in. Web browsers have security measures that prevent access to some kinds of remote resources without an explicit OK (via the Access-Control-Allow-Origin response header) from the server hosting them. So wherever you host your Root, make sure to set up your web server to permit remote access to it. Below is an example for servers that support .htaccess.
<IfModule mod_headers.c>
Header set Access-Control-Allow-Origin "*"
</IfModule>
options.json
This file is an Ultralink Options object that you can customize with whatever settings you need. When the Ultralink code loads your Root, the first thing it does is look for the options.json file and load all the options contained in it as if you had manually passed that object into Ultralink.start() or Ultralink.setOptions(). Most options will simply override the existing values but some will merge or add their passed in value to the already existing one.
In this file you specify the way that you want Ultralinks to behave when this Root is loaded, how the content is identified (scanningGuides) and define any link types (customLinkTypes) you want to create. You can even put additional remoteRoots options that will causes those Roots to load whenever yours is (any cyclical Root references will just be ignored after the initial load).
If you find yourself invoking Ultralink.start() with a large amount of options it might be preferable to instead move those settings into an options.json file inside an Ultralink Root and pass the URL to that Root to Ultralink.start() through the remoteRoots option instead. If you are going to be creating any new link types, then you must use an Ultralink Root because the files required to create a new link type (like the icon, etc.) must reside in the linkTypes/ directory.
linkTypes
Inside this directory there exists one subdirectory for each new link type defined in the customLinkTypes option of the options.json file. For a step-by-step example on the basics of link type creation, see our handy How To Create Link Types walkthrough.
Each link type directory inside linkTypes/ must be named after the link type itself as specified in the customLinkTypes object. The structure inside this directory looks like this:
| icon/ | required | A directory containing an image or multiple image files. |
| view.(html, js, css) | optional | If this link type has an Inline View, then these are the files that provide the logic and structure for that view. |
| message.js | optional | A portion of the Inline View logic that can be pulled into the Ultralink Core. |
| insights.js | optional | A file that defines what Ultralink insights are supplied by this link type, what arguments they take and how they are handled. |
| auth/ | optional | A directory containing the authentication endpoints and logic for authenticating an Ultralink Core with a service (no public support yet). |
| required | icon/ |
| A directory containing an image or multiple image files. | |
| optional | view.(html, js, css) |
| If this link type has an Inline View, then these are the files that provide the logic and structure for that view. | |
| optional | message.js |
| A portion of the Inline View logic that can be pulled into the Ultralink Core. | |
| optional | insights.js |
| A file that defines what Ultralink insights are supplied by this link type, what arguments they take and how they are handled. | |
| optional | auth/ |
| A directory containing the authentication endpoints and logic for authenticating an Ultralink Core with a service (no public support yet). | |
You can add whatever other structure you want (3rd-party libraries, img directory etc.) but the above files and directories have special significance. You can also add your own additional infrasture (to share betwen multiple link type Inline Views) alongside the link type directories just as long as their do not conflict with any future link type names you might want to use (convention is to start any of these directories with an underscore "_" character).
customLinkTypes
Before diving into each of the above link type directory parts in detail, here is list of all the link type attributes you can customize. Many of these affect whether you need any of the optional link type files above. We will be referring to some of these as we explain the different parts
| name | required | string | A human friendly name for the link type. This is used in a lot of places to refer to the link type. |
| icon | optional | filename | A path to this link type's icon image relative to icon/ if using a single icon file. |
| iconShrinkage | optional | float | How much this link type's icon should be shrunk relative to link's background image. Defaults to 0.75. |
| iconAdjustX | optional | float | How much this link type's icon should be horizontally adjusted relative to it's width. Defaults to 0.0. |
| iconAdjustY | optional | float | How much this link type's icon should be vertically adjusted relative to it's height. Defaults to 0.0. |
| iconBackground | optional | float | If false, indicates that the icon should not be drawn over the standard link background (and not shrunk). |
| pane | optional | true | false | Indicates whether this link type should be black shadowed and have an Inline Pane. |
| view | optional | true | false | Indicates whether this link type has an Inline View. Requires view.(html, js, css) files. |
| viewType | optional | light | dark | The visual style of the Inline Pane. Defaults to dark. |
| w | optional | int | The width of the Inline Pane. Defaults to 500. |
| h | optional | int | The height of the Inline Pane. Defaults to 350. |
| message | optional | true | false | Indicates whether the Inline View has a companion message.js file. |
| insights | optional | true | false | Indicates whether the Inline View has a companion insights.js file. |
| autoPop | optional | true | false | always | Can indicate if the Inline Pane should auto-pop when there are few other links or auto-pop all the time. |
| prefix | optional | partial URL | For link types in the 'Search' category, this is used to construct the final search link. |
| quote | optional | true | false | For link types in the 'Search' category, this indicates whether the word used in the final search link should have quotes around it. |
| cloneFrom | optional | link type | During Ultralink construction, this link type should copy it's URL from the link of the specified link type in the Ultralink. |
| detectors | optional | array | An array of regular expression strings that will match URLs to this link type. This is used in many places. |
| affiliateTag | optional | string | Specifies the affiliate tag used in this link type. Used when needing to re-write the affiliate tag. |
| newWindowSuppress | optional | true | false | This causes a click to navigate to the link as opposed to bringing up a new tab (even if user settings prefer that behavior). |
| viewDesktopOnly | optional | true | false | Indicates whether the Inline View for this link type should be ignored on mobile browsers. |
| auth | optional | link type | Indicates what link type provides authenticated API calls for this link type (almost always the link type itself). |
| suppliesAuth | optional | true | false | Indicates that this link type has authenticatin logic in auth/. |
| authType | optional | oauth1 | oauth2 | Type of authentication supplied in auth/. Defaults to oauth2. |
| endpointDomain | optional | partial URL | A partial URL for the Ultralink Core to match against when clearing it's API cache for a link type. |
| required | name | string |
| A human friendly name for the link type. This is used in a lot of places to refer to the link type. | ||
| optional | icon | filename |
| A path to this link type's icon image relative to icon/ if using a single icon file. | ||
| optional | iconShrinkage | float |
| How much this link type's icon should be shrunk relative to link's background image. Defaults to 0.75. | ||
| optional | iconAdjustX | float |
| How much this link type's icon should be horizontally adjusted relative to it's width. Defaults to 0.0. | ||
| optional | iconAdjustY | float |
| How much this link type's icon should be vertically adjusted relative to it's height. Defaults to 0.0. | ||
| optional | iconBackground | float |
| If false, indicates that the icon should not be drawn over the standard link background (and not shrunk). | ||
| optional | pane | true | false |
| Indicates whether this link type should be black shadowed and have an Inline Pane. | ||
| optional | view | true | false |
| Indicates whether this link type has an Inline View. Requires view.(html, js, css) files. | ||
| optional | viewType | light | dark |
| The visual style of the Inline Pane. Defaults to dark. | ||
| optional | w | int |
| The width of the Inline Pane. Defaults to 500. | ||
| optional | h | int |
| The height of the Inline Pane. Defaults to 350. | ||
| optional | message | true | false |
| Indicates whether the Inline View has a companion message.js file. | ||
| optional | insights | true | false |
| Indicates whether the Inline View has a companion insights.js file. | ||
| optional | autoPop | true | false | always |
| Can indicate if the Inline Pane should auto-pop when there are few other links or auto-pop all the time. | ||
| optional | prefix | partial URL |
| For link types in the 'Search' category, this is used to construct the final search link. | ||
| optional | quote | true | false |
| For link types in the 'Search' category, this indicates whether the word used in the final search link should have quotes around it. | ||
| optional | cloneFrom | link type |
| During Ultralink construction, this link type should copy it's URL from the link of the specified link type in the Ultralink. | ||
| optional | detectors | array |
| An array of regular expression strings that will match URLs to this link type. This is used in many places. | ||
| optional | affiliateTag | string |
| Specifies the affiliate tag used in this link type. Used when needing to re-write the affiliate tag. | ||
| optional | newWindowSuppress | true | false |
| This causes a click to navigate to the link as opposed to bringing up a new tab (even if user settings prefer that behavior). | ||
| optional | viewDesktopOnly | true | false |
| Indicates whether the Inline View for this link type should be ignored on mobile browsers. | ||
| optional | auth | link type |
| Indicates what link type provides authenticated API calls for this link type (almost always the link type itself). | ||
| optional | suppliesAuth | true | false |
| Indicates that this link type has authenticatin logic in auth/. | ||
| optional | authType | oauth1 | oauth2 |
| Type of authentication supplied in auth/. Defaults to oauth2. | ||
| optional | endpointDomain | partial URL |
| A partial URL for the Ultralink Core to match against when clearing it's API cache for a link type. | ||
| required | name | |
| string | ||
| A human friendly name for the link type. This is used in a lot of places to refer to the link type. | ||
| optional | icon | |
| filename | ||
| A path to this link type's icon image relative to icon/ if using a single icon file. | ||
| optional | iconShrinkage | |
| float | ||
| How much this link type's icon should be shrunk relative to link's background image. Defaults to 0.75. | ||
| optional | iconAdjustX | |
| float | ||
| How much this link type's icon should be horizontally adjusted relative to it's width. Defaults to 0.0. | ||
| optional | iconAdjustY | |
| float | ||
| How much this link type's icon should be vertically adjusted relative to it's height. Defaults to 0.0. | ||
| optional | iconBackground | |
| float | ||
| If false, indicates that the icon should not be drawn over the standard link background (and not shrunk). | ||
| optional | pane | |
| true | false | ||
| Indicates whether this link type should be black shadowed and have an Inline Pane. | ||
| optional | view | |
| true | false | ||
| Indicates whether this link type has an Inline View. Requires view.(html, js, css) files. | ||
| optional | viewType | |
| light | dark | ||
| The visual style of the Inline Pane. Defaults to dark. | ||
| optional | w | |
| int | ||
| The width of the Inline Pane. Defaults to 500. | ||
| optional | h | |
| int | ||
| The height of the Inline Pane. Defaults to 350. | ||
| optional | message | |
| true | false | ||
| Indicates whether the Inline View has a companion message.js file. | ||
| optional | insights | |
| true | false | ||
| Indicates whether the Inline View has a companion insights.js file. | ||
| optional | autoPop | |
| true | false | always | ||
| Can indicate if the Inline Pane should auto-pop when there are few other links or auto-pop all the time. | ||
| optional | prefix | |
| partial URL | ||
| For link types in the 'Search' category, this is used to construct the final search link. | ||
| optional | quote | |
| true | false | ||
| For link types in the 'Search' category, this indicates whether the word used in the final search link should have quotes around it. | ||
| optional | cloneFrom | |
| link type | ||
| During Ultralink construction, this link type should copy it's URL from the link of the specified link type in the Ultralink. | ||
| optional | detectors | |
| array | ||
| An array of regular expression strings that will match URLs to this link type. This is used in many places. | ||
| optional | affiliateTag | |
| string | ||
| Specifies the affiliate tag used in this link type. Used when needing to re-write the affiliate tag. | ||
| optional | newWindowSuppress | |
| true | false | ||
| This causes a click to navigate to the link as opposed to bringing up a new tab (even if user settings prefer that behavior). | ||
| optional | viewDesktopOnly | |
| true | false | ||
| Indicates whether the Inline View for this link type should be ignored on mobile browsers. | ||
| optional | auth | |
| link type | ||
| Indicates what link type provides authenticated API calls for this link type (almost always the link type itself). | ||
| optional | suppliesAuth | |
| true | false | ||
| Indicates that this link type has authenticatin logic in auth/. | ||
| optional | authType | |
| oauth1 | oauth2 | ||
| Type of authentication supplied in auth/. Defaults to oauth2. | ||
| optional | endpointDomain | |
| partial URL | ||
| A partial URL for the Ultralink Core to match against when clearing it's API cache for a link type. | ||
Link Type Icons
The icon/ directory is the only part of a link type directory that is mandatory for all link types. The default way of providing a link type icon is to store 5, square png files named 16.png, 32.png, 64.png, 128.png and 256.png inside the icon/ directory. The resolution of these should correspond to the name (16.png should be 16X16 pixels, etc.). For best results, the images should have an alpha channel and no background. Ideally, the contents of these images should be cropped flush with the edges, but it isn't required. When the link UI is constructed for this link type, the code picks the most appropriate icon image for the display size and resolution, scales it by a factor of 0.75 and centers it over a standard, white link background.
As mentioned in the table above, there are some attributes you can use to customize parts of this process. Although, having 5 differently sized png files is a very compatible solution, you can instead tell the Ultralink code to only use a single image in every case by using the icon setting. The value of this setting is simply the filename of a single image file (of any browser compatible image type) residing in icon/ that you want to use instead of the 5 seperate pngs. It is actually preferable to use this setting if you have an image in the svg format you can use for the link type image.
If the size, proportioning or offset of your link type image doesn't look quite right when you test it out, there are some attributes you can use to smooth things over. The iconShrinkage attribute allows you to customize the scale factor of your provided image as it is overlaid on the white link background. By default, it scales the image down by 0.75. In general, that value produces a nice margin for icons which are mostly square and cropped flush with their edges.
You can also use the iconAdjustX and iconAdjustY attributes to proportionally nudge your icon center if it improves the overall look. Both of those attributes default to 0.0.
If you would prefer to not use the standard, white link background provided, you can author your icon images with their own backgrounds and set the iconBackground attribute to false. This will no longer shrink, nudge or overlay your icon image on to the standard link background.
Inline Views
If you want your link type to do anything more than provide a hyperlink or bring up an iframe for that hyperlink (using the pane attribute) then you are going to want to provide an Inline View.
By setting both the pane and view attributes to true, you signal to the Ultralink code that your link type can have a black shadow and that it should use the view.html, view.js and view.css files in your link type directory to produce it.
You can also set the message attribute to true to indicate that there is also a message.js file present that can be picked up by the Ultralink Core and the front-end Ultralink code. Although you can make API calls in view.js, if you want to author Ultralink insights for your link type or leverage any sort of API caching beyond the scope of a single page, you will want to move your API calls into message.js.
The insights attribute indicates that you are providing Ultralink insights for this link type through the interfaces and logic found in insights.js. Any API calls your insights depend on must be implemented and correctly connected in message.js.
To learn about Inline View and insight authoring, check out our InlineView documentation.
Authentication
For certain kinds of link types (Twitter, Google+, AngelList, etc.), it can make sense to allow the end user to authenticate the Ultralink Core with their own user account so that it can programmatically access resources behind the links. You can only do this in environments where the Ultralink Core is in a secure, sandboxed location such as a browser extension or the Ultralink Windows app. At the moment, this functionality is not publicly documented or available but we plan to open it up in the future. Contact Us if you are interested getting Ultralink authentication support added for a specific service.
The link types that do currently support this kind of authentication provide the logic to do so through the auth/ directory. If the resources behind your link can be accessed by iframing the link or with un-authenticated API calls, then you don't need to worry about Ultralink Core authentication.