website/node_modules/autolinker/README.md

Autolinker.js

Because I had so much trouble finding a good autolinking 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:

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:

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

Using with the Bower package manager:

Command line:

bower install Autolinker.js --save

Using with Node.js via npm:

Command Line:

npm install autolinker --save

JavaScript:

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

Usage

Using the static link() method:

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

Using as a class:

var autolinker = new Autolinker( [ options ] );

var 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:

var linkedText = Autolinker.link( "Check out google.com", { className: "myLink" } );
// Produces: "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:

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", and 3) Twitter links will have the CSS classes: "myLink myLink-twitter"

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

var linkedText = Autolinker.link( "Check out google.com", { newWindow: false } );
// Produces: "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:

var linkedText = Autolinker.link( "http://www.yahoo.com/some/long/path/to/a/file", { truncate: 25, newWindow: false } );
// Produces: "<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:

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

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

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

//...

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

//...

autolinker.link( "Go to www.google.com" );
// Produces: "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/twitter matches on an individual basis, based on the return from this function.

Full example, for purposes of documenting the API:

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

var 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 'twitter' :
                var twitterHandle = match.getTwitterHandle();
                console.log( twitterHandle );

                return '<a href="http://newplace.to.link.twitter.handles.to/">' + twitterHandle + '</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:

Full API Docs

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

Changelog

See Releases



JohnCoene/chirp documentation built on May 25, 2021, 6:33 p.m.