Skip to content

Commit

Permalink
Add some more tests for phone number handling, and clean up some docu…
Browse files Browse the repository at this point in the history 
…mentation.

Remove `preprocessFn`, since this is not really a responsibility of Autolinker. The input text can simply be preprocessed before passing it in.
  • Loading branch information
@gregjacobs
gregjacobs committed Mar 29, 2015
1 parent de943c8 commit 28d0b1a
Show file tree
Hide file tree
Showing 8 changed files with 1,032 additions and 866 deletions.
113 changes: 70 additions & 43 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,20 +1,24 @@
# 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.
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".
- 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 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).
- 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!

Expand All @@ -23,7 +27,8 @@ Hope that this utility helps you as well!

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

```html
<script src="path/to/Autolinker.min.js"></script>
Expand All @@ -49,14 +54,15 @@ JavaScript:

```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
// 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()](http://gregjacobs.github.io/Autolinker.js/docs/#!/api/Autolinker-static-method-link) method:
Using the static [link()](http://gregjacobs.github.io/Autolinker.js/docs/#!/api/Autolinker-static-method-link)
method:

```javascript
var linkedText = Autolinker.link( textToAutolink[, options] );
Expand All @@ -70,10 +76,12 @@ 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()](http://gregjacobs.github.io/Autolinker.js/docs/#!/api/Autolinker-method-link) method repeatedly (i.e. use the "class" form above).
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()](http://gregjacobs.github.io/Autolinker.js/docs/#!/api/Autolinker-method-link)
method repeatedly (i.e. use the "class" form above).



#### Example:

```javascript
Expand All @@ -83,7 +91,8 @@ var linkedText = Autolinker.link( "Check out google.com", { className: "myLink"

## 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()](http://gregjacobs.github.io/Autolinker.js/docs/#!/api/Autolinker-static-method-link). These include:
These are the options which may be specified for linking. These are specified by
providing an Object as the second parameter to [Autolinker.link()](http://gregjacobs.github.io/Autolinker.js/docs/#!/api/Autolinker-static-method-link). These include:

- [newWindow](http://gregjacobs.github.io/Autolinker.js/docs/#!/api/Autolinker-cfg-newWindow) : Boolean<br />
`true` to have the links should open in a new window when clicked, `false` otherwise. Defaults to `true`.<br /><br />
Expand All @@ -95,21 +104,23 @@ These are the options which may be specified for linking. These are specified by
- [className](http://gregjacobs.github.io/Autolinker.js/docs/#!/api/Autolinker-cfg-className) : String<br />
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"/"twitter" suffixes for styling url/email/twitter links differently.

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

1) URL links will have the CSS classes: "myLink myLink-url"<br />
2) Email links will have the CSS classes: "myLink myLink-email", and<br />
3) Twitter links will have the CSS classes: "myLink myLink-twitter"<br />

- [urls](http://gregjacobs.github.io/Autolinker.js/docs/#!/api/Autolinker-cfg-urls) : Boolean<br />
`true` to have URLs auto-linked, `false` to skip auto-linking of URLs. Defaults to `true`.<br />
- [email](http://gregjacobs.github.io/Autolinker.js/docs/#!/api/Autolinker-cfg-email) : Boolean<br />
`true` to have email addresses auto-linked, `false` to skip auto-linking of email addresses. Defaults to `true`.<br /><br />
- [phone](http://gregjacobs.github.io/Autolinker.js/docs/#!/api/Autolinker-cfg-phone) : Boolean<br />
`true` to have phone numbers auto-linked, `false` to skip auto-linking of phone numbers. Defaults to `true`.<br /><br />
- [twitter](http://gregjacobs.github.io/Autolinker.js/docs/#!/api/Autolinker-cfg-twitter) : Boolean<br />
`true` to have Twitter handles auto-linked, `false` to skip auto-linking of Twitter handles. Defaults to `true`.<br /><br />
- [replaceFn](http://gregjacobs.github.io/Autolinker.js/docs/#!/api/Autolinker-cfg-replaceFn) : Function<br />
A function to use to programmatically make replacements of matches in the input string, one at a time. See the section
A function to use to programmatically make replacements of matches in the input string, one at a time. See the section
<a href="#custom-replacement-function">Custom Replacement Function</a> for more details.


Expand All @@ -128,14 +139,16 @@ var linkedText = Autolinker.link( "http://www.yahoo.com/some/long/path/to/a/file
```

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

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

Using the same pre-configured [Autolinker](http://gregjacobs.github.io/Autolinker.js/docs/#!/api/Autolinker) instance in multiple locations of a codebase (usually by dependency injection):
Using the same pre-configured [Autolinker](http://gregjacobs.github.io/Autolinker.js/docs/#!/api/Autolinker)
instance in multiple locations of a codebase (usually by dependency injection):

```javascript
var autolinker = new Autolinker( { newWindow: false, truncate: 25 } );
Expand All @@ -155,8 +168,9 @@ autolinker.link( "Go to www.google.com" );

## Custom Replacement Function

A custom replacement function ([replaceFn](http://gregjacobs.github.io/Autolinker.js/docs/#!/api/Autolinker-cfg-replaceFn)) may be provided to replace url/email/twitter matches on an individual basis, based
on the return from this function.
A custom replacement function ([replaceFn](http://gregjacobs.github.io/Autolinker.js/docs/#!/api/Autolinker-cfg-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:

Expand All @@ -167,36 +181,42 @@ var linkedText = Autolinker.link( input, {
replaceFn : function( autolinker, match ) {
console.log( "href = ", match.getAnchorHref() );
console.log( "text = ", match.getAnchorText() );

switch( match.getType() ) {
case 'url' :
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( twitterHandle );

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

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

return '<a href="http://newplace.to.link.twitter.handles.to/">' + twitterHandle + '</a>';
}
}
Expand All @@ -206,23 +226,30 @@ var linkedText = Autolinker.link( input, {

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()](http://gregjacobs.github.io/Autolinker.js/docs/#!/api/Autolinker-method-getTagBuilder)).
2. An [Autolinker.match.Match](http://gregjacobs.github.io/Autolinker.js/docs/#!/api/Autolinker.match.Match) object which details the match that is to be replaced.
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()](http://gregjacobs.github.io/Autolinker.js/docs/#!/api/Autolinker-method-getTagBuilder)).
2. An [Autolinker.match.Match](http://gregjacobs.github.io/Autolinker.js/docs/#!/api/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:

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.
- 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](http://gregjacobs.github.io/Autolinker.js/docs/#!/api/Autolinker.HtmlTag) instance, which can be used to build/modify an HTML tag before writing out its HTML text.
- 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](http://gregjacobs.github.io/Autolinker.js/docs/#!/api/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/](http://gregjacobs.github.io/Autolinker.js/docs/#!/api/Autolinker)
The full API docs for Autolinker may be referenced at:
[http://gregjacobs.github.io/Autolinker.js/docs/](http://gregjacobs.github.io/Autolinker.js/docs/#!/api/Autolinker)


## Changelog
Expand Down
Loading

0 comments on commit 28d0b1a

Please sign in to comment.