Change the interface from truncateMiddle and truncateSmart options to bundling these in with the truncate option

Author: gregjacobs

Gruntfile.js

@@ -73,6 +73,7 @@ module.exports = function(grunt) {
 					'src/match/Phone.js',
 					'src/match/Twitter.js',
 					'src/match/Url.js',
+					'src/truncate/TruncateEnd.js',
 					'src/truncate/TruncateMiddle.js',
 					'src/truncate/TruncateSmart.js'
 				],

README.md

@@ -101,13 +101,27 @@ providing an Object as the second parameter to [Autolinker.link()](http://gregja
 - [stripPrefix](http://gregjacobs.github.io/Autolinker.js/docs/#!/api/Autolinker-cfg-stripPrefix) : Boolean<br />
   `true` to have the 'http://' or 'https://' and/or the 'www.' stripped from the
   beginning of links, `false` otherwise. Defaults to `true`.<br /><br />
-- [truncate](http://gregjacobs.github.io/Autolinker.js/docs/#!/api/Autolinker-cfg-truncate) : Number<br />
+- [truncate](http://gregjacobs.github.io/Autolinker.js/docs/#!/api/Autolinker-cfg-truncate) : Number/Object<br />
   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 ('..').<br /><br />
+  
   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..'<br /><br />
+  
+  In the object form, both `length` and `location` may be specified to perform 
+  truncation. Available options for `location` are: 'end' (default), 'middle', 
+  or 'smart'. Example usage: 
+  
+    ```javascript
+    truncate: { length: 32, location: 'middle' }
+    ```
+  
+  The 'smart' truncation option is for URLs where the algorithm attempts to 
+  strip out unnecessary parts of the URL (such as the 'www.', then URL scheme, 
+  hash, etc.) before trying to find a good point to insert the ellipsis if it is 
+  still too long. For details, see source code of: (TruncateSmart)[http://gregjacobs.github.io/Autolinker.js/gh-pages/docs/#!/api/Autolinker.truncate.TruncateSmart]
 - [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"/"phone"/"twitter"/"hashtag"

src/AnchorTagBuilder.js

@@ -7,9 +7,11 @@
  *
  * Builds anchor (<a>) tags for the Autolinker utility when a match is found.
  *
- * Normally this class is instantiated, configured, and used internally by an {@link Autolinker} instance, but may
- * actually be retrieved in a {@link Autolinker#replaceFn replaceFn} to create {@link Autolinker.HtmlTag HtmlTag} instances
- * which may be modified before returning from the {@link Autolinker#replaceFn replaceFn}. For example:
+ * Normally this class is instantiated, configured, and used internally by an
+ * {@link Autolinker} instance, but may actually be retrieved in a {@link Autolinker#replaceFn replaceFn}
+ * to create {@link Autolinker.HtmlTag HtmlTag} instances which may be modified
+ * before returning from the {@link Autolinker#replaceFn replaceFn}. For
+ * example:
  *
  *     var html = Autolinker.link( "Test google.com", {
  *         replaceFn : function( autolinker, match ) {
@@ -31,7 +33,7 @@ Autolinker.AnchorTagBuilder = Autolinker.Util.extend( Object, {
 	 */
 
 	/**
-	 * @cfg {Number} truncate
+	 * @cfg {Object} truncate
 	 * @inheritdoc Autolinker#truncate
 	 */
 
@@ -59,13 +61,11 @@ Autolinker.AnchorTagBuilder = Autolinker.Util.extend( Object, {
 	 * @return {Autolinker.HtmlTag} The HtmlTag instance for the anchor tag.
 	 */
 	build : function( match ) {
-		var tag = new Autolinker.HtmlTag( {
+		return new Autolinker.HtmlTag( {
 			tagName   : 'a',
 			attrs     : this.createAttrs( match.getType(), match.getAnchorHref() ),
 			innerHtml : this.processAnchorText( match.getAnchorText() )
 		} );
-
-		return tag;
 	},
 
 
@@ -76,7 +76,7 @@ Autolinker.AnchorTagBuilder = Autolinker.Util.extend( Object, {
 	 * @protected
 	 * @param {"url"/"email"/"phone"/"twitter"/"hashtag"} matchType The type of
 	 *   match that an anchor tag is being generated for.
-	 * @param {String} href The href for the anchor tag.
+	 * @param {String} anchorHref The href for the anchor tag.
 	 * @return {Object} A key/value Object (map) of the anchor tag's attributes.
 	 */
 	createAttrs : function( matchType, anchorHref ) {
@@ -134,24 +134,32 @@ Autolinker.AnchorTagBuilder = Autolinker.Util.extend( Object, {
 
 
 	/**
-	 * Performs the truncation of the `anchorText`, if the `anchorText` is
-	 * longer than the {@link #truncate} option. Truncates the text to 2
-	 * characters fewer than the {@link #truncate} option, and adds ".." to the
-	 * end.
+	 * Performs the truncation of the `anchorText` based on the {@link #truncate}
+	 * option. If the `anchorText` is longer than the length specified by the
+	 * {@link #truncate} option, the truncation is performed based on the
+	 * `location` property. See {@link #truncate} for details.
 	 *
 	 * @private
-	 * @param {String} text The anchor tag's text (i.e. what will be displayed).
+	 * @param {String} anchorText The anchor tag's text (i.e. what will be
+	 *   displayed).
 	 * @return {String} The truncated anchor text.
 	 */
 	doTruncate : function( anchorText ) {
-		var truncateLength = this.truncate || Number.POSITIVE_INFINITY;
-		if (this.truncateSmart) {
-			return Autolinker.truncate.TruncateSmart( anchorText, truncateLength, ".." );
-		}
-		if (this.truncateMiddle) {
-			return Autolinker.truncate.TruncateMiddle( anchorText, truncateLength, ".." );
+		var truncate = this.truncate;
+		if( !truncate ) return anchorText;
+
+		var truncateLength = truncate.length,
+			truncateLocation = truncate.location;
+
+		if( truncateLocation === 'smart' ) {
+			return Autolinker.truncate.TruncateSmart( anchorText, truncateLength, '..' );
+
+		} else if( truncateLocation === 'middle' ) {
+			return Autolinker.truncate.TruncateMiddle( anchorText, truncateLength, '..' );
+
+		} else {
+			return Autolinker.truncate.TruncateEnd( anchorText, truncateLength, '..' );
 		}
-		return Autolinker.Util.ellipsis( anchorText, truncateLength );
 	}
 
 } );

src/Autolinker.js

@@ -102,7 +102,7 @@
  * - An {@link Autolinker.HtmlTag} instance, which can be used to build/modify an HTML tag before writing out its HTML text.
  *
  * @constructor
- * @param {Object} [config] The configuration options for the Autolinker instance, specified in an Object (map).
+ * @param {Object} [cfg] The configuration options for the Autolinker instance, specified in an Object (map).
  */
 var Autolinker = function( cfg ) {
 	Autolinker.Util.assign( this, cfg );  // assign the properties of `cfg` onto the Autolinker instance. Prototype properties will be used for missing configs.
@@ -112,6 +112,15 @@ var Autolinker = function( cfg ) {
 	if( hashtag !== false && hashtag !== 'twitter' && hashtag !== 'facebook' && hashtag !== 'instagram' ) {
 		throw new Error( "invalid `hashtag` cfg - see docs" );
 	}
+
+	// Normalize the `truncate` option
+	var truncate = this.truncate = this.truncate || {};
+	if( typeof truncate === 'number' ) {
+		this.truncate = { length: truncate, location: 'end' };
+	} else if( typeof truncate === 'object' ) {
+		this.truncate.length = truncate.length || Number.POSITIVE_INFINITY;
+		this.truncate.location = truncate.location || 'end';
+	}
 };
 
 Autolinker.prototype = {
@@ -175,40 +184,50 @@ Autolinker.prototype = {
 	stripPrefix : true,
 
 	/**
-	 * @cfg {Number} truncate
+	 * @cfg {Number/Object} truncate
 	 *
-	 * A number for how many characters long matched text should be truncated to inside the text of
-	 * a link. If the matched text is over this number of characters, it will be truncated to this length by
-	 * adding a two period ellipsis ('..') to the end of the string.
+	 * ## Number Form
 	 *
-	 * For example: A url like 'http://www.yahoo.com/some/long/path/to/a/file' truncated to 25 characters might look
-	 * something like this: 'yahoo.com/some/long/pat..'
-	 */
-	truncate : undefined,
-
-	/**
-	 * @cfg {Boolean} truncateMiddle
+	 * A number for how many characters matched text should be truncated to
+	 * inside the text of a link. If the matched text is over this number of
+	 * characters, it will be truncated to this length by adding a two period
+	 * ellipsis ('..') to the end of the string.
 	 *
-	 * When true, truncation will occur at the dead-center of a URL, as opposed to the end of a URL.
-	 * Requires: truncate
+	 * For example: A url like 'http://www.yahoo.com/some/long/path/to/a/file'
+	 * truncated to 25 characters might look something like this:
+	 * 'yahoo.com/some/long/pat..'
 	 *
-	 * For example: A url like 'http://www.yahoo.com/some/long/path/to/a/file' truncated to 25 character might look
-	 * something like this: 'yahoo.com/s..th/to/a/file'
-	 */
-	truncateMiddle : false,
-
-	/**
-	 * @cfg {Boolean} truncateSmart
+	 * Example Usage:
+	 *
+	 *     truncate: 25
 	 *
-	 * When true, ellipsis characters will be placed within a section of the URL causing it to still be somewhat human
-	 * readable.
-	 * Requires: truncate
-	 * Overrides: truncateMiddle
 	 *
-	 * For example: A url like 'http://www.yahoo.com/some/long/path/to/a/file' truncated to 25 character might look
-	 * something like this: 'yahoo.com/some..to/a/file'
+	 * ## Object Form
+	 *
+	 * An Object may also be provided with two properties: `length` (Number) and
+	 * `location` (String). `location` may be one of the following: 'end'
+	 * (default), 'middle', or 'smart'.
+	 *
+	 * Example Usage:
+	 *
+	 *     truncate: { length: 25, location: 'middle' }
+	 *
+	 * @cfg {Number} truncate.length How many characters to allow before
+	 *   truncation will occur.
+	 * @cfg {"end"/"middle"/"smart"} [truncate.location="end"]
+	 *
+	 * - 'end' (default): will truncate up to the number of characters, and then
+	 *   add an ellipsis at the end. Ex: 'yahoo.com/some/long/pat..'
+	 * - 'middle': will truncate and add the ellipsis in the middle. Ex:
+	 *   'yahoo.com/s..th/to/a/file'
+	 * - 'smart': for URLs where the algorithm attempts to strip out unnecessary
+	 *   parts first (such as the 'www.', then URL scheme, hash, etc.),
+	 *   attempting to make the URL human-readable before looking for a good
+	 *   point to insert the ellipsis if it is still too long. Ex:
+	 *   'yahoo.com/some..to/a/file'. For more details, see
+	 *   {@link Autolinker.truncate.TruncateSmart}.
 	 */
-	truncateSmart : false,
+	truncate : undefined,
 
 	/**
 	 * @cfg {String} className
@@ -455,14 +474,13 @@ Autolinker.prototype = {
 			tagBuilder = this.tagBuilder = new Autolinker.AnchorTagBuilder( {
 				newWindow   : this.newWindow,
 				truncate    : this.truncate,
-				truncateMiddle: this.truncateMiddle,
-				truncateSmart:  this.truncateSmart,
 				className   : this.className
 			} );
 		}
 
 		return tagBuilder;
-	},
+	}
+
 };
 
 

src/HtmlTag.js

@@ -170,7 +170,7 @@ Autolinker.HtmlTag = Autolinker.Util.extend( Object, {
 	/**
 	 * Retrieves an attribute from the HtmlTag. If the attribute does not exist, returns `undefined`.
 	 *
-	 * @param {String} name The attribute name to retrieve.
+	 * @param {String} attrName The attribute name to retrieve.
 	 * @return {String} The attribute's value, or `undefined` if it does not exist on the HtmlTag.
 	 */
 	getAttr : function( attrName ) {

src/truncate/TruncateEnd.js

@@ -0,0 +1,12 @@
+/*global Autolinker */
+/**
+ * A truncation feature where the ellipsis will be placed at the end of the URL.
+ *
+ * @param {String} anchorText
+ * @param {Number} truncateLen The maximum length of the truncated output URL string.
+ * @param {String} ellipsisChars The characters to place within the url, e.g. "..".
+ * @return {String} The truncated URL.
+ */
+Autolinker.truncate.TruncateEnd = function(anchorText, truncateLen, ellipsisChars){
+	return Autolinker.Util.ellipsis( anchorText, truncateLen, ellipsisChars );
+};

src/truncate/TruncateMiddle.js

@@ -1,3 +1,4 @@
+/*global Autolinker */
 /**
  * Date: 2015-10-05
  * Author: Kasper Søfren <[email protected]> (https://github.com/kafoso)