Complex callback option

[aziraphale]

Having some way to control the generated <a> tags is something that I needed and it appears to be something that others have needed as well ([1], [2]), so I decided to go all-out and create quite a comprehensive callback option that passes to the callback a whole load of data about the link being processed and allows the callback to override attributes, the link text, and the prefix/suffix strings. It's slightly complicated to use, but I wanted to create something that covered a wide range of use cases, rather than having dozens of forks with slightly different callback implementations to suit slightly different scenarios.

As with my other pull request, I haven't included the files in /dist/ - again, ask me if you'd like them to be included, but that sounded like conflict hell to me.

Speaking of conflicts, this PR will conflict with my other PR, but only because they both insert code in the same places (e.g. adding lines to the docblock at the end of the options list). Resolving the conflicts should be very simple.

[gregjacobs]

Hey, you're totally right that having a callback is useful and gives a lot of flexibility. I'd like to give this one a little thought though first before merging.

Part of what I'm thinking is to give people the option to return either straight HTML from their callback function, or otherwise an Object (map) of what they would like changed (like in your implementation - great idea btw). Just trying to think of a way to simplify the process if at all possible. Also thinking of possibly naming the option replaceFn or something along those lines, just to be clear that this function will perform the replacements rather than being a function that is called when all of the replacements are complete.

Quick question: what do you think the big use cases for this feature are? I'm guessing that one of them is to add a css class to the anchor tags that are generated. Maybe this one can be a general option as well.

[aziraphale]

By all means - if you can make the usage simpler, please do so! I was well aware as I conceptualised and wrote the functionality that it was rather complicated (hence the 'complex' part of the branch name) but, as I said before, I wanted it to cover as many possible requirements as it could. I don't always come up with the most usable code interfaces for things like this :)

As for the use cases, yes, adding a CSS class was exactly what I needed it for. I could also envisage something like doing some kind of anti-spam obfuscation on email address link hrefs, doing something fancy with Twitter handles (like Twitter's now-abandoned Hovercards functionality), etc... I think CSS classes would be the most common use, though.

[jamcole]

I like the simplicity of the way https://github.com/bryanwoods/autolink-js does it, a similar syntax would be nice...
Basically only the url is fed in, and the output is returned completely by the callback:

// Input
"This is a link to image http://example.com/logo.png".autoLink({
  callback: function(url) {
    return /\.(gif|png|jpe?g)$/i.test(url) ? '<img src="' + url + '">' : null;
  }
});
// Output
"This is a link to image <img src='http://example.com/logo.png'>"

This would be good for adding data- attributes, rel="nofollow", etc.

[rjmunro]

@jamcole I think you need 2 parameters - The real URL and the friendly URL, so an email address would be called with "mailto:john@example.com" and "john@example.com", a twitter handle "https://twitter.com/rjmunro" and "@rjmunro" etc.

A basic implementation would be:

function (url, friendly) {
    return '<a href="' + url + '">' + friendly + '</a>'
}

A third parameter called options could also be used, to allow anything else useful to be passed, for example, type might be weather it is a plain web page (http or https), twitter or mailto link, secure could be true for https (including twitter handles if you are using the https twitter link).

For example (assuming options.class is passed through if defined):

function (url, friendly, options) {
    return '<a href="' + url + '" class="' + options.class || options.type + '">' + friendly + '</a>'
}

[gregjacobs]

Hey guys. Decades late, I know, but finally got this in there.. Tried to make the most comprehensive interface possible to cover every case. Check out the replacement function section of the readme if you're interested: https://github.com/gregjacobs/Autolinker.js#custom-replacement-function

Closing this one for now since I did go in a different direction, but thanks for your help and input!!