RocketChat/Autolinker.js

Name: Autolinker.js

Owner: Rocket.Chat

Description: Utility to Automatically Link URLs, Email Addresses, Phone Numbers, Twitter handles, and Hashtags in a given block of text/HTML.

Created: 2015-06-15 01:40:39.0

Updated: 2016-08-31 22:39:39.0

Pushed: 2015-10-19 12:02:26.0

Homepage:

Size: 2795

Language: JavaScript

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

Autolinker.js

Because I had so much trouble finding a good auto-linking implementation out in the wild, I decided to roll my own. It seemed that everything I found out there was either an implementation that didn't cover every case, or was just limited in one way or another.

So, this utility attempts to handle everything. It:

• Autolinks URLs, whether or not they start with the protocol (i.e. 'http://'). In other words, it will automatically link the text “google.com”, as well as “http://google.com”.
• Will properly handle URLs with special characters
• Will properly handle URLs with query parameters or a named anchor (i.e. hash)
• Will autolink email addresses.
• Will autolink phone numbers.
• Will autolink Twitter handles.
• Will autolink hashtags.
• Will properly handle HTML input. The utility will not change the href attribute inside anchor (<a>) tags (or any other tag/attribute for that matter), and will not accidentally wrap the inner text of an anchor tag with a new one (which would cause doubly-nested anchor tags).

Hope that this utility helps you as well!

Installation

Download

Simply clone or download the zip of the project, and link to either dist/Autolinker.js or dist/Autolinker.min.js with a script tag:

ipt src="path/to/Autolinker.min.js"></script>

Using with the Bower package manager:

Command line:

r install Autolinker.js --save

Using with Node.js via npm:

Command Line:

install autolinker --save

JavaScript:

Autolinker = require( 'autolinker' );
ote: npm wants an all-lowercase package name, but the utility is a class and
hould be aliased with a capital letter

Usage

Using the static link() method:

linkedText = Autolinker.link( textToAutolink[, options] );

Using as a class:

autolinker = new Autolinker( [ options ] );

linkedText = autolinker.link( textToAutoLink );

Note: if using the same options to autolink multiple pieces of html/text, it is slightly more efficient to create a single Autolinker instance, and run the link() method repeatedly (i.e. use the “class” form above).

Example:

linkedText = Autolinker.link( "Check out google.com", { className: "myLink" } );
roduces: "Check out <a class="myLink myLink-url" href="http://google.com" target="_blank">google.com</a>"

Options

These are the options which may be specified for linking. These are specified by providing an Object as the second parameter to Autolinker.link(). These include:

• newWindow : Boolean
  true to have the links should open in a new window when clicked, false otherwise. Defaults to true.
  
  

• stripPrefix : Boolean
  true to have the 'http://' or 'https://' and/or the 'www.' stripped from the beginning of links, false otherwise. Defaults to true.
  
  

• truncate : Number
  A number for how many characters long URLs/emails/Twitter handles/Twitter hashtags should be truncated to inside the text of a link. If the match is over the number of characters, it will be truncated to this length by replacing the end of the string with a two period ellipsis ('..').
  
  Example: a url like 'http://www.yahoo.com/some/long/path/to/a/file' truncated to 25 characters may look like this: 'yahoo.com/some/long/pat..'
  
  

• className : String
  A CSS class name to add to the generated anchor tags. This class will be added to all links, as well as this class plus “url”/“email”/“phone”/“twitter”/“hashtag” suffixes for styling url/email/phone/twitter/hashtag links differently.

  For example, if this config is provided as “myLink”, then:

  1) URL links will have the CSS classes: “myLink myLink-url”
  2) Email links will have the CSS classes: “myLink myLink-email”
  3) Phone links will have the CSS classes: “myLink myLink-phone”
  4) Twitter links will have the CSS classes: “myLink myLink-twitter”
  5) Hashtag links will have the CSS classes: “myLink myLink-hashtag”
  

• urls : Boolean
  true to have URLs auto-linked, false to skip auto-linking of URLs. Defaults to true.
  

• email : Boolean
  true to have email addresses auto-linked, false to skip auto-linking of email addresses. Defaults to true.
  
  

• phone : Boolean
  true to have phone numbers auto-linked, false to skip auto-linking of phone numbers. Defaults to true.
  
  

• twitter : Boolean
  true to have Twitter handles auto-linked, false to skip auto-linking of Twitter handles. Defaults to true.
  
  

• hashtag : Boolean/String
  A string for the service name to have hashtags auto-linked to. Supported values at this time are 'twitter', 'facebook' and 'instagram'. Pass false to skip auto-linking of hashtags. Defaults to false.
  
  

• replaceFn : Function
  A function to use to programmatically make replacements of matches in the input string, one at a time. See the section Custom Replacement Function for more details.

For example, if you wanted to disable links from opening in new windows, you could do:

linkedText = Autolinker.link( "Check out google.com", { newWindow: false } );
roduces: "Check out <a href="http://google.com">google.com</a>"

And if you wanted to truncate the length of URLs (while also not opening in a new window), you could do:

linkedText = Autolinker.link( "http://www.yahoo.com/some/long/path/to/a/file", { truncate: 25, newWindow: false } );
roduces: "<a href="http://www.yahoo.com/some/long/path/to/a/file">yahoo.com/some/long/pat..</a>"

More Examples

One could update an entire DOM element that has unlinked text to auto-link them as such:

myTextEl = document.getElementById( 'text' );
xtEl.innerHTML = Autolinker.link( myTextEl.innerHTML );

Using the same pre-configured Autolinker instance in multiple locations of a codebase (usually by dependency injection):

autolinker = new Autolinker( { newWindow: false, truncate: 25 } );

.

linker.link( "Check out http://www.yahoo.com/some/long/path/to/a/file" );
roduces: "Check out <a href="http://www.yahoo.com/some/long/path/to/a/file">yahoo.com/some/long/pat..</a>"

.

linker.link( "Go to www.google.com" );
roduces: "Go to <a href="http://www.google.com">google.com</a>"

Custom Replacement Function

A custom replacement function (replaceFn) may be provided to replace url/email/phone/Twitter handle/hashtag matches on an individual basis, based on the return from this function.

Full example, for purposes of documenting the API:

input = "...";  // string with URLs, Email Addresses, Twitter Handles, and Hashtags

linkedText = Autolinker.link( input, {
replaceFn : function( autolinker, match ) {
    console.log( "href = ", match.getAnchorHref() );
    console.log( "text = ", match.getAnchorText() );

    switch( match.getType() ) {
        case 'url' :
            console.log( "url: ", match.getUrl() );

            if( match.getUrl().indexOf( 'mysite.com' ) === -1 ) {
                var tag = autolinker.getTagBuilder().build( match );  // returns an `Autolinker.HtmlTag` instance, which provides mutator methods for easy changes
                tag.setAttr( 'rel', 'nofollow' );
                tag.addClass( 'external-link' );

                return tag;

            } else {
                return true;  // let Autolinker perform its normal anchor tag replacement
            }

        case 'email' :
            var email = match.getEmail();
            console.log( "email: ", email );

            if( email === "my@own.address" ) {
                return false;  // don't auto-link this particular email address; leave as-is
            } else {
                return;  // no return value will have Autolinker perform its normal anchor tag replacement (same as returning `true`)
            }

        case 'phone' :
            var phoneNumber = match.getPhoneNumber();
            console.log( phoneNumber );

            return '<a href="http://newplace.to.link.phone.numbers.to/">' + phoneNumber + '</a>';

        case 'twitter' :
            var twitterHandle = match.getTwitterHandle();
            console.log( twitterHandle );

            return '<a href="http://newplace.to.link.twitter.handles.to/">' + twitterHandle + '</a>';

        case 'hashtag' :
            var hashtag = match.getHashtag();
            console.log( hashtag );

            return '<a href="http://newplace.to.link.hashtag.handles.to/">' + hashtag + '</a>';
    }
}

The function is provided two arguments:

1. The Autolinker instance that is performing replacements. This can be used to query the options that the Autolinker instance is configured with, or to retrieve its TagBuilder instance (via autolinker.getTagBuilder()).
2. An Autolinker.match.Match object which details the match that is to be replaced.

A replacement of the match is made based on the return value of the function. The following return values may be provided:

• No return value (undefined), or true (Boolean): Delegate back to Autolinker to replace the match as it normally would.
• false (Boolean): Do not replace the current match at all - leave as-is.
• Any String: If a string is returned from the function, the string will be used directly as the replacement HTML for the match.
• An Autolinker.HtmlTag instance, which can be used to build/modify an HTML tag before writing out its HTML text.

Full API Docs

The full API docs for Autolinker may be referenced at: http://gregjacobs.github.io/Autolinker.js/docs/

Contributing

Pull requests definitely welcome.

• Make sure to add tests to cover your new functionality/bugfix.
• Run the grunt command to build/test (or alternatively, open the tests/index.html file to run the tests).
• When committing, please omit checking in the files in the dist/ folder after building/testing. These are only committed to the repository for users downloading Autolinker via Bower. I will build these files and assign them a version number when merging your PR.
• Please use tabs for indents! Tabs are better for everybody (individuals can set their editors to different tab sizes based on their visual preferences).

Changelog

See Releases