Simplest way

The easiest way to upload a file is to base64 encode the contents and pass it to the create method. Unfortunately this method is limited to around 35MB.

const uploadContentVersion = (fileName: string, file: Buffer): Promise<jsforce.RecordResult> =>
  connection.sobject('ContentVersion').create({
    PathOnClient : fileName,
    VersionData : file.toString('base64')
  })

Multipart form data

The trick here is that you need to encode the request correctly as per the example in the documentation.

Example request body

--boundary_string
Content-Disposition: form-data; name="entity_content";
Content-Type: application/json
 
{  
    "Name" : "Marketing Brochure Q1 - Sales",
    "Keywords" : "sales, marketing, first quarter"
}
 
--boundary_string
Content-Type: application/pdf
Content-Disposition: form-data; name="Body"; filename="2011Q1MktgBrochure.pdf"
 
Updated document binary data goes here.
 
--boundary_string--

Using the nodejs request library

The popular nodejs `request` library provides a formData option which can be used like below:

import request from 'request'
import jsForce from 'jsforce'

const uploadContentVersion = (metadata: ContentVersionMetadata, file: Buffer): Promise<jsForce.RecordResult> =>
  new Promise((resolve, reject) => {
    const connection: jsForce.Connection = // ...create jsForce connection

    request.post({
      url: connection.instanceUrl + '/services/data/v49.0/sobjects/ContentVersion',
      auth: {
        bearer: connection.accessToken
      },
      formData: {
        entity_content: {
          value: JSON.stringify(metadata),
          options: {
            contentType: 'application/json'
          }
        },
        VersionData: {
          value: file,
          options: {
            filename: metadata.PathOnClient,
            contentType: 'application/octet-stream'
          }
        }
      }
    }, (err, response) => {
      if (err)
        reject(err)

      resolve(JSON.parse(response.body))
    })
  })

Example using `form-data` library

You could also create the formData object manually like this.

  const formData = new FormData()

  formData.append('entity_content', JSON.stringify(metadata), { contentType: 'application/json' })
  formData.append('VersionData', file, {
    filename: metadata.PathOnClient,
    contentType: 'application/octet-stream'
  })

  // then make request using formData object

Full example attaching to Case

export const addFileToCase = async (caseId: string, fileName: string, file: Buffer): Promise<string> => {
  // We use the helper method created previously
  const uploadResult = await uploadContentVersion(file, {
    PathOnClient: fileName,

    // For updates you can also add the following params
    // ContentDocumentId: '',
    // ReasonForChange: ''
  })

  if (!uploadResult.success) {
    throw new Error(`Failed to upload file for case "${caseId}"`)
  }

  const contentDocument = await connection.sobject<{
    Id: string,
    ContentDocumentId: string
  }>('ContentVersion').retrieve(uploadResult.id)

  const linkResult = await connection.sobject<TRes>('ContentDocumentLink').create({
    ContentDocumentId: contentDocument.ContentDocumentId,
    LinkedEntityId: caseId,
    ShareType: 'V'
  })

  if (!linkResult.success) {
    throw new Error(`Failed to link content document for case "${caseId}"`)
  }

  return uploadResult.id
})

/// <summary>
/// Factory for creating ObjectInfo objects for ObjectInfoProvider.
/// </summary>
public class ObjectInfoFactory { ... }

“Factory for creating ObjectInfo objects for ObjectInfoProvider.” difficult to say what that means since it could be interpreted different ways. But wouldn’t it be great if we could see what the code does. Maybe we could even search the codebase and see how it is being used in other parts of the library.

Read the source Luke…

In my opinion one of the most beneficial things you can do is read the source code. Documentation is hard and there are many times I have worked with libraries where the documentation and examples are not up-to-date. Not to mention subtle unexpected behaviors that occur when working with other people’s code.

Reading source code has served me well over the years and as a result I have made a number of humble contributions to open source projects and had fun reading the code for projects like Chromium (Chrome Browser), Samba (SMB/CIFS), FFMPEG, and so on. I find that different ecosystems tend to come with an associated culture. Working more closely with Microsoft .NET recently I have found a bit of a new roadblock… the source code is not always readily available.

I tried to picture clusters of information as they moved through the computer. What did they look like? Ships, motorcycles. With the circuits like freeways. I kept dreaming of a world I thought I’d never see. And then one day, I got in.
Kevin Flynn – Tron Legacy

DnSpy (https://github.com/0xd4d/dnSpy) is a debugger and .NET assembly editor. You can use it to edit and debug assemblies even if you don’t have any source code available. Below I have an example of what it looks like viewing a dll from the DotNetNuke project.

That project (DotNetNuke) is open source so we don’t necessarily need to decompile it but it’s just an example. This is a tool I have used extensively in the last few months and has made working with closed source legacy code a lot less painful.

It is also possible to use dnSpy to patch dll’s. There are two main ways to do this you can edit the decompiled C# source code. However doing so will require recompilation and I have found that this seldom works. The other option is to edit the IL code of a method or property. This is a much better way as long as you don’t mind rolling up your sleeves and reading through the CIL instructions. Honestly it’s not that hard, at least it’s easier than using a hex editor.

SCRIPT1004: Expected ';'
File: example.js, Line: 9, Column: 35

And the line it was pointing to looked like this.

var test = 1; //@todo: add new feature

Well it turns out that if conditional compilation (http://msdn.microsoft.com/en-us/library/ie/121hztk3(v=vs.94).aspx) is turned on using /*@cc_on @*/ in any script. Using the @ symbol anywhere at the start of a comment causes Internet Explorer to throw a syntax error.

The minimum reproducable test case is:

/*@cc_on @*/
var test = 1; //@todo: add new feature

Which can be fixed by putting a space in front of the @ symbol like this.

/*@cc_on @*/
var test = 1; // @todo: add new feature

This becomes an issue in larger codebases where you cannot know if other scripts have turned conditional compilation on at all. As far as I know there isn't a workaround. However you can show a console message warning that conditional compilation is on like this.

/*@if (@_jscript) if ('console' in self && 'log' in console) console.log('Conditional compilation is turned on!'); @end @*/

Keep in mind however that a syntax error caused by the @ symbol will trigger before the above runs.

Faux-Mustache

So the simplest approach to converting the template and data into the output we need is to just use String.prototype.replace(). Note I am using mustache/handlebars syntax for the template syntax in this section. None of the template variables escape html so don’t use in production with unsafe data.

var tpl    = "<p>Is this a template? {{test}}.</p>";
var output = tpl.replace('{{test}}', 'Yes it is!');

However this will only work if we have a single {{test}} template variable in our template because String.prototype.replace() only replaces the first item. You can use the third flags parameter to do a global replace using a string input but it is non-standard. So we have to use a regex instead.

var tpl    = "<p>Is this a template? {{test}}.</p>";
var re     = /\{\{test\}\}/gmi;
var output = tpl.replace(re, 'Yes it is!');

This works and for really simple applications you could easily just use this method instead of a template engine. But the data that we want to replace is hard-coded which means we can’t update it very easily and we need a new replace call for each additional variable. So what we want is to be able to pass in any data as properties of an object like this.

var Template = function(tpl, data){
    return tpl.replace(/\{\{(.*?)\}\}/gmi, function(match, p1) {
        var prop = p1.trim();
        return data.hasOwnProperty(prop) ? data[prop] : '';
    });
};

var tpl    = "<p>Is this a template? {{test}} {{test2}}.</p>";
var data   = {
    test: 'Yes',
    test2: 'it is!'
};
var output = Template(tpl, data);

This is better but it still has some issues. Most notably we have no way to access descendant properties. It would be great to be able to do this {{user.name}}. So lets make it happen.

var Template = function(tpl, data){
    return tpl.replace(/\{\{(.*?)\}\}/gmi, function(match, p1) {
        var prop = p1.trim().split('.'),
            obj  = data;
        while(prop.length && typeof(obj) != 'undefined')
            obj = obj[prop.shift()]
        return typeof(obj) != 'undefined' ? obj : '';
    });
};

var tpl    = "<p>Hi {{user.name}}! You are from {{user.location}}.</p>";
var data   = {
    user: {
        name: 'Pat',
        location: 'Australia'
    }
};
var output = Template(tpl, data);

Great so that works pretty well and it’s only nine lines of code to boot. However there are still two big features missing and they are template compilation and the ability to work with arrays.

Compilation

Template compilation allows us to avoid re-executing the regex and looping through every property every time we use the template. So lets look at how we could update the previous example to return a compiled function.

var Template = function(tpl){
    var cursor = 0,
        code = "var r=[];\n", 
        re = /\{\{(.*?)\}\}/gmi;
    
    var add = function(line, tag) {
        if(tag) {
            code += "r.push(data."+line+");\n";
        } else {
            code += line != '' ? 'r.push("' + line.replace(/"/g, '"') + "\");\n" : '';
        }
    };
    
    while(match = re.exec(tpl)) {
        add(tpl.slice(cursor, match.index));
        add(match[1], true);
        cursor = match.index + match[0].length;
    }
    
    add(tpl.substr(cursor, tpl.length - cursor));
    code += 'return r.join("");';

    try {
        result = new Function('data', code); 
    } catch(err) {
        console.error("'" + err.message + "'", " in \n\nCode:\n", code, "\n");
    }

    return result;
};

var tpl    = "<p>Hi {{user.name}}! You are from {{user.location}}.</p>";
var data   = {
    user: {
        name: 'Pat',
        location: 'Australia'
    }
};
var compiledTemplate = Template(tpl);
var output = compiledTemplate(data);

So now we have a function we can call to parse the template with different data whenever we need to. Note the above is based on the blog post by John Resig (jQuery) here and the template engine from Krasimir Tsonev here.

How it works is that it generates a new Function() that looks like this:

function(data) {
    var r=[];
        
    r.push("<p>Hi ");
    r.push(data.user.name);
    r.push("! You are from ");
    r.push(data.user.location);
    r.push(".</p>");

    return r.join(""); 
}

Lets update it to work with arrays. Ideally it would be great to be able to use a template like this {{#items}}{{.}}{{/items}} which loops through an array of items just like you would when using mustache.

var Template = function(tpl, data){
    var cursor = 0,
        code = "var r=[];\n", 
        re = /\{\{(.*?)\}\}/gmi;
    var add = function(line, tag) {
        if(tag) {
            if(line.charAt(0) === '#') {
                code += "for(var i=0, len=data."+line.slice(1)+".length; i<len; i++){\n";
                code += "var el=data."+line.slice(1)+"[i];\n";
            } else if (line.charAt(0) === '/') {
                code += "};\n";
            } else {
                code += line === '.' ? "r.push(el || data);\n" : "r.push(data."+line+");\n";
            }
        } else {
            code += line != '' ? 'r.push("' + line.replace(/"/g, '"') + "\");\n" : '';
        }
    };
  
    while(match = re.exec(tpl)) {
        add(tpl.slice(cursor, match.index));
        add(match[1], true);
        cursor = match.index + match[0].length;
    }
    
    add(tpl.substr(cursor, tpl.length - cursor));
    code += 'return r.join("");';
    try { result = new Function('data', code); }
    catch(err) { console.error("'" + err.message + "'", " in \n\nCode:\n", code, "\n"); }
    return result;
};

var tpl    = "<p>Hi {{user.name}}! You like:</p>"+
             "<ul>{{#user.likes}}<li>{{.}}</li>{{/user.likes}}</ul>";
var data   = {
    user: {
        name: 'Pat',
        likes: ['Code', 'Boardgames', 'Cooking']
    }
};
var output = Template(tpl)(data);

So as you can see this is a little more complex. Of course it is still missing a lot of features but the point isn’t to create a fully featured template engine (plenty of those exist).

Unfortunately it isn’t possible to re-create all of the mustache features using this approach simply because of the ambiguity in the way mustache handles objects, arrays, and variables with the hash (#) prefix. The alternative is to use something like this http://jsfiddle.net/a9o9Lw0x/1/ however this will likely perform a lot worse since we need to dynamically handle the block (#) tags and at that point you may as well use a proper template engine.

Embedded Javascript (EJS)

Now that we have template compilation it is fairly trivial to make a Embedded Javascript (EJS) style template engine. Let’s have a look at how it is done.

var Template = function(tpl){
    var cursor = 0,
        code   = "with(data) { var r=[];\n", 
        re     = /<%(.*?)%>/gmi;
    
    var add = function(line, tag) {
        if(tag) {
            code += line.charAt(0) === '=' ? "r.push("+line.slice(1).trim()+");\n" : line+"\n";
        } else {
            code += line != '' ? 'r.push("' + line.replace(/"/g, '"') + "\");\n" : '';
        }
    };
    
    while(match = re.exec(tpl)) {
        add(tpl.slice(cursor, match.index));
        add(match[1], true);
        cursor = match.index + match[0].length;
    }
    
    add(tpl.substr(cursor, tpl.length - cursor));
    code += 'return r.join(""); }';
    try { result = new Function('data', code); }
    catch(err) { console.error("'" + err.message + "'", " in \n\nCode:\n", code, "\n"); }
    return result;
};

var tpl    = "<p>Hi <%= user.name %>! You are from <%= user.location %>.</p>"+
             "<ul>"+
             "<% for(var i=0; i < user.likes.length; i++) { %>"+
                 "<li><%= user.likes[i] %></li>"+
             "<% } %>"+
             "</ul>";
var data   = {
    user: {
        name: 'Pat',
        location: 'Australia',
        likes: ['Code', 'Boardgames', 'Cooking']
    }
};
var output = Template(tpl)(data);

Well that’s it for the rundown on how to create a simple template engine.

Basically drawBezierSplit() allow you to draw a section of a quadratic bezier curve. It uses a quadratic bezier curve (quadraticCurveTo) because this is the default curve type built into the AS3 drawing API. For reference the HTML5 canvas API uses cubic curves by default.

/**
 * Animates bezier-curve
 * 
 * @param ctx       The canvas context to draw to
 * @param x0        The x-coord of the start point
 * @param y0        The y-coord of the start point
 * @param x1        The x-coord of the control point
 * @param y1        The y-coord of the control point
 * @param x2        The x-coord of the end point
 * @param y2        The y-coord of the end point
 * @param duration  The duration in milliseconds
 */
function animatePathDrawing(ctx, x0, y0, x1, y1, x2, y2, duration) {
    var start = null;
    
    var step = function animatePathDrawingStep(timestamp) {
        if (start === null)
            start = timestamp;
        
        var delta = timestamp - start,
            progress = Math.min(delta / duration, 1);
        
        // Clear canvas
        ctx.clearRect(0, 0, ctx.canvas.width, ctx.canvas.height);
        
        // Draw curve
        drawBezierSplit(ctx, x0, y0, x1, y1, x2, y2, 0, progress);
        
        if (progress < 1) {
            window.requestAnimationFrame(step);
        }
    };
    
    window.requestAnimationFrame(step);
}

/**
 * Draws a splitted bezier-curve
 * 
 * @param ctx       The canvas context to draw to
 * @param x0        The x-coord of the start point
 * @param y0        The y-coord of the start point
 * @param x1        The x-coord of the control point
 * @param y1        The y-coord of the control point
 * @param x2        The x-coord of the end point
 * @param y2        The y-coord of the end point
 * @param t0        The start ratio of the splitted bezier from 0.0 to 1.0
 * @param t1        The start ratio of the splitted bezier from 0.0 to 1.0
 */
function drawBezierSplit(ctx, x0, y0, x1, y1, x2, y2, t0, t1) {
    ctx.beginPath();
    
    if( 0.0 == t0 && t1 == 1.0 ) {
        ctx.moveTo( x0, y0 );
        ctx.quadraticCurveTo( x1, y1, x2, y2 );
    } else if( t0 != t1 ) {
        var t00 = t0 * t0,
            t01 = 1.0 - t0,
            t02 = t01 * t01,
            t03 = 2.0 * t0 * t01;
        
        var nx0 = t02 * x0 + t03 * x1 + t00 * x2,
            ny0 = t02 * y0 + t03 * y1 + t00 * y2;
        
        t00 = t1 * t1;
        t01 = 1.0 - t1;
        t02 = t01 * t01;
        t03 = 2.0 * t1 * t01;
        
        var nx2 = t02 * x0 + t03 * x1 + t00 * x2,
            ny2 = t02 * y0 + t03 * y1 + t00 * y2;
        
        var nx1 = lerp ( lerp ( x0 , x1 , t0 ) , lerp ( x1 , x2 , t0 ) , t1 ),
            ny1 = lerp ( lerp ( y0 , y1 , t0 ) , lerp ( y1 , y2 , t0 ) , t1 );
        
        ctx.moveTo( nx0, ny0 );
        ctx.quadraticCurveTo( nx1, ny1, nx2, ny2 );
    }
    
    ctx.stroke();
    ctx.closePath();
}

/**
 * Linearly interpolate between two numbers v0, v1 by t
 */
function lerp(v0, v1, t) {
    return ( 1.0 - t ) * v0 + t * v1;
}

document.addEventListener('DOMContentLoaded',function(){
    var docCanvas = document.getElementById('canvas'),
        ctx = docCanvas.getContext('2d');

    animatePathDrawing(ctx, 0, 100, 150, -50, 300, 100, 5000);
});

Note: Click on the result tab to restart the animation.

Credit to Andre Michelle (andre-michelle.com) for the original inspiration.

Rage is a popular all-night Australian music video program broadcast on ABC1 on Friday nights, Saturday mornings and Saturday nights. It was first screened on the weekend of Friday, 17 April 1987.

Since 1998 rage has posted all their episode playlists online. So I created a website that combines these playlists with YouTube allowing you to travel back through time and re-experience rage’s recent history.

Please note: all the matching of track to video is done programmatically so some tracks particularly older ones may not be available (depending on whether someone has uploaded them).

Behind the Scenes (v2 – 2020)

The original version of the site was written using the Lithium PHP Framework in 2012. The site ran well until 2019 when a number of issues cropped up. So I had a plan in mind for a re-envisioned version to address the following issues:

• Over the years Google has been reducing the number of requests that can be made to the Youtube search API. When the site was first developed the project had millions of requests in quota. Now it is down to 100s per month. I tried contacting the black hole that is Google support with no luck. So I needed an alternative to using the Youtube search API.
• The ABC website scraper needs to be rewritten since the ABC site has changed.
• I wanted to make the website static, and have it connect to a serverless backend to avoid having to host and maintain a server.

Given these requirements I decided on the following plan:

1. Write a new API backend hosted on Cloudflare workers.
2. Dump the playlist data stored in MySQL into flat files (JSON).
3. Use scheduled Github workers to scrape the ABC website and update the data directory.
4. Convert the frontend to be a static single page application (SPA).

The project is broken into three parts; the API backend, the static frontend SPA, and the ABC scraper script run via Github workers.

For the backend API my initial plan was to write this using Rust (https://www.rust-lang.org/). Cloudflare workers have good support for Rust and I enjoy working with the language.

However I ran into some issues writing a YouTube search scraper and given that there was already a NodeJS package for this purpose it didn’t seem like a great idea to re-invent the wheel. So I ended up writing the final version using Typescript.

The logic is fairly simple when a request is made for a specific music video, it will first check for a cached result stored in Cloudflare KV storage. If the cached data cannot be found it will then go off and grab the data from YouTube.

There is also another endpoint that proxies the data from Github, providing the correct CORS headers for the frontend.

All in all it was fun to re-visit the project.

Checkout the interview with ABC about the site for more details https://web.archive.org/web/20150402201331/https://open.abc.net.au/explore/31540

Source code and data

Scraping the data (particularly the 90s web pages) wasn’t easy due to broken and inconsistent markup so I have posted a database dump in case anyone else wants to play with the data.

Playlists: 1,694
Tracks: 201,316
Approx. Play Time: 1 year, 173 days, 5 hours, 46 mins

https://github.com/patrickgalbraith/rageagain (Source code and data repo)

Changelog

17th January 2020

Features

• RAGEAgain is back after a long hiatus!
• Fixing the site required a complete rewrite. Source code is now available here https://github.com/patrickgalbraith/rageagain.

12th June 2017

Features

• Adjusted Youtube search algorithm to ignore Aria chart information and de-rank reaction and karaoke videos

4th March 2013

Features

• Migrated to new sever (initial load should be significantly faster)
• Finally implemented listing by special
• Updated to jQuery 1.9.1

3rd September 2012

Features

• Updated to include latest playlists
• New special playlist; Top 200 which plays the most played tracks in ascending order (i.e. most played first).
• Individual playlist/tracks are now bookmarkable and browser back button works
• Keyboard shortcuts (spacebar = pause/play, arrow left = prev, arrow right = next)
• Note: If you click on the video you may need to click outside of video for the keyboard events to trigger again. This is because the video will capture any keyboard events.
• Added anchor links to quickly skip to specific year.
• Added warning for users on unsupported/outdated browsers.
• Updated jquery to 1.8.1 (mainly fixes player not appearing in Internet Explorer 8/9)

Bug Fixes

• Fixed issue with tracklist being capped at 200 which caused the first tracks to not be played.
• Massive database overhaul
• Fixed broken 1999 playlists
• Added 30+ missing/incomplete playlists
• Removed a few duplicate playlists
• Removed all duplicate tracks (some tracklists had been entered twice)
• Fixed tracks containing unescaped html entites and tags

29th August 2012

First public release

28th July 2012

Private release

Installation (iPad)

1. Add this page as a bookmark
2. Select and copy the Javascript in the textarea below.
3. Go to your bookmarks and tap “edit”. Then tap the new bookmark you just made of this page.
4. Edit the name and paste the Javascript in the field for the URL.
5. Click done.

javascript:(function(){var%20objectTags=document.getElementsByTagName(‘object’);var%20objectTagsArr=new%20Array();for(var%20i=0;i<objectTags.length;i++){objectTagsArr[i]=objectTags[i];}for(i=0;i<objectTagsArr.length;i++){var%20objectTag=objectTagsArr[i];if(objectTag.data.indexOf('http://www.youtube.com/')>=0){var%20youtubeID=objectTag.data.match(/(?:youtube\.com\/(?:[^\/]+\/.+\/|(?:v|e(?:mbed)?)\/|.*[?&]v=)|youtu\.be\/)([^’&?\/ ]{11})/i)[1];var%20newIframeElem=document.createElement(‘iframe’);newIframeElem.class=’youtube-player';newIframeElem.type=’text/html';newIframeElem.width=640;newIframeElem.height=385;newIframeElem.src=’http://www.youtube.com/embed/’+youtubeID;newIframeElem.frameborder=0;var%20newElem=objectTag.parentNode.replaceChild(newIframeElem,objectTag);}}})();

Source code with formatting

javascript:(function(){
	var objectTags = document.getElementsByTagName('object');
	var objectTagsArr = new Array();
	
	for (var i = 0; i < objectTags.length; i++) {
		objectTagsArr[i] = objectTags[i];
	}
	
	for (i = 0; i < objectTagsArr.length; i++) {
		var objectTag = objectTagsArr[i];
		if(objectTag.data.indexOf('http://www.youtube.com/') >= 0) {
			var youtubeID = objectTag.data.match(/(?:youtube\.com\/(?:[^\/]+\/.+\/|(?:v|e(?:mbed)?)\/|.*[?&]v=)|youtu\.be\/)([^'&?\/ ]{11})/i)[1];
			
			var newIframeElem = document.createElement('iframe');
			newIframeElem.class = 'youtube-player';
			newIframeElem.type = 'text/html';
			newIframeElem.width = 640;
			newIframeElem.height = 385;
			newIframeElem.src = 'http://www.youtube.com/embed/'+youtubeID;
			newIframeElem.frameborder = 0;
			
			objectTag.parentNode.replaceChild(newIframeElem, objectTag);
		}
	}
})();

Download: http://wordpress.org/extend/plugins/default-thumbnail-plus

Thumbnail Selection Hierarchy

The hierarchy below determines what thumbnail will be chosen, in other words the plugin first checks if the user has manually set a featured image. If not then it checks if it has a custom field containing an attachment id, and so on. Once the plugin gets to the last step if no default thumbnail image is set then no post thumbnail will be displayed.

1. Featured Image
2. Custom Field
3. Image Attachment
4. Embedded image
5. Embedded video
6. Category/Tag/Taxonomy Thumbnail
7. Default Thumbnail

Add Filter (Category/Tag/Taxonomy Thumbnail)

You can add filters which allow you to select a thumbnail for a specific category, tag, or custom taxonomy. The value field is required and must contain either a comma separated list of slug, id, or title for a existing category, tag, or custom taxonomy. Any post that does not have a post-thumbnail set and has the specified tag, or is a member of the category or taxonomy will show the default thumbnail specified.

Use image attachment if available

Automatically use the post’s first available image attachment for the thumbnail. This is useful for older posts that haven’t got a featured image set.

Custom Field

Enter a custom field key here, it’s value if set will become the default post thumbnail for that post. The custom field value can either be an Attachment ID, or a link to an image.

Note: If the custom field value contains a link to an image it will output a simple image tag and attempt to populate the width and height attributes. However the aspect ratio may not match other thumbnails. The plugin does not check if the image exists or is of valid type or size.

Use embedded image if available

Automatically use the post’s first available embedded image for the thumbnail. This is useful if you embed external images.

Note: This option does not work with has_post_thumbnail() or get_post_thumbnail_id(). If the “cache external images” option is set then the plugin will automatically resize, crop the image and store a local copy.

Use embedded video if available

Automatically use the post’s first available embedded video for the thumbnail (YouTube only).

Note: This option does not work with has_post_thumbnail() or get_post_thumbnail_id(). If the “cache external images” option is set then the plugin will automatically resize, crop the image and store a local copy.

Excluded posts

List of posts to be ignored by this plugin. Comma separated e.g. 10, 2, 7, 14.

Note: These posts may still display a thumbnail if one has been set manually (using the “Set featured image” button on the post page).

Functions

The following functions work to directly return post thumbnail even if the plugin hooks have been disabled. This allows you to disable the filters and call the plugin manually. This should only be used if you are creating a custom theme and can ensure that DefaultThumbnailPlus is installed.

dpt_post_thumbnail_id($post_id, $size = null, $attr = ”)
Returns the post thumbnail ID. Doesn’t work with embedded images.

dpt_post_thumbnail_html($post_id, $size = null, $attr = ”)
Directly calls the default post thumbnail function. Works the same as calling get_the_post_thumbnail().

dpt_post_thumbnail_src($post_id, $size = null)
Returns href to post thumbnail image.

Why can’t I see any thumbnails with my custom theme?

A number of themes use has_post_thumbnail() to check if a post thumbnail exists before calling the_post_thumbnail() to display the thumbnail. The problem with this is that thumbnails that are linked to directly (either external images or video thumbnails) won’t return correctly for this check and therefore may not show.
 
To fix this issue you will need to look for the following code in your theme:

if(has_post_thumbnail()) {
    the_post_thumbnail(...);
}

 
And simply remove the call to has_post_thumbnail() so you are left with this:

the_post_thumbnail(...);

TwentyEleven

The header only works with image attachments, i.e. embedded images/video thumbnails won’t show.

The header attachment width also has to be greater than the custom-header width option (default 1000px). This is generally a good thing though since it prevents low resolution images from displaying in the header.

WooThemes

WooThemes call a function called woo_image() rather than using the default WordPress functionality. This causes the default post thumbnail to never show.

So to fix this you need to override the woo_image() function with a custom implementation that reverts to using WordPress’s in-built functions. To do this paste the following code into the TOP of the themes functions.php file found in /wp-content/themes/your_themes_name after the opening <?php tag.

//Override the default woothemes image function and revert to using the default wordpress function.
if ( ! is_admin() && ! function_exists('woo_image')){
    function woo_image($args) {
        global $post;

        $size = null;
        $attr = array();
        $before = '';
        $after = '';
        $class = '';

        if ( !is_array($args) )
            parse_str( $args, $args );

        extract($args);

        if(empty($id))
            $id = $post->ID;

        if(isset($width) && isset($height))
            $size = array($width, $height);

        $attr['class'] = 'woo-image '.$class;

        if(isset($alt))
            $attr['alt'] = $alt;

        $output = $before . get_the_post_thumbnail($id, $size, $attr) . $after;

        if($return == TRUE)
            return $output;
        else
            echo $output;
    }
}

 
The downside is that it won’t recreate all of woo_image()’s features. However it shouldn’t cause issues with most themes.

Truncating Text

There are two ways in which I needed to truncate text; by the number of characters, and by the number of words.

Original text:

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque tellus enim, iaculis eget imperdiet et, sodales id magna.

Limited to 9 chars:

Lorem ips
123456789

Limited to 9 words:

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque
1 2 3 4 5 6 7 8 9

Truncating Text by Char

The function to truncate text by char is very simple.

function truncate_chars($text, $limit, $ellipsis = '...') {
    if( strlen($text) > $limit ) 
        $text = trim(substr($text, 0, $limit)) . $ellipsis; 
    return $text;
}

 
Basically you just count the number of chars using strlen if the length is greater than the limit then return a subset of the string.
 
You can improve this function by preventing it from chopping a word in half by searching the string for the next white space character.

function truncate_chars($text, $limit, $ellipsis = '...') {
    if( strlen($text) > $limit ) {
        $endpos = strpos(str_replace(array("\r\n", "\r", "\n", "\t"), ' ', $text), ' ', $limit);
        if($endpos !== FALSE)
            $text = trim(substr($text, 0, $endpos)) . $ellipsis;
    }
    return $text;
}

 
Just one little note about these functions they aren’t multibyte safe. If you need to perform truncation of multibyte strings (Korean, Chinese, Japanese, etc) then look into using the multibyte string functions instead http://php.net/ref.mbstring.
 

Truncating Text by Word

Truncating text by words is fairly simple as well we just break the text into pieces using whitespace characters as the separator. However I have come across a few potential pitfalls. The obvious way to break the text into words is like this $words = explode(' ', $text, $limit + 1);. However the issue with this is that it doesn’t take into account all whitespace characters (like tabs and line breaks).

The way that WordPress and a lot of other people do it is like this:

function truncate_words($text, $limit, $ellipsis = '...') {
    $words = preg_split("/[\n\r\t ]+/", $text, $limit + 1, PREG_SPLIT_NO_EMPTY);
    if ( count($words) > $limit ) {
        array_pop($words);
        $text = implode(' ', $words);
        $text = $text . $excerpt_more;
    }
    return $text;
}

Which works well however it has one major issue in that if you feed it text containing line breaks or tabs it will replace those line breaks with normal spaces ‘ ‘. The better way to do it is rather than using implode on the word array, capture the offset of the last word using the PREG_SPLIT_OFFSET_CAPTURE flag then use this offset to split the string.

function truncate_words($text, $limit, $ellipsis = '...') {
    $words = preg_split("/[\n\r\t ]+/", $text, $limit + 1, PREG_SPLIT_NO_EMPTY|PREG_SPLIT_OFFSET_CAPTURE);
    if (count($words) > $limit) {
        end($words); //ignore last element since it contains the rest of the string
        $last_word = prev($words);
           
        $text =  substr($text, 0, $last_word[1] + strlen($last_word[0])) . $ellipsis;
    }
    return $text;
}

 
This method ensures that the integrity of the whitespace is retained. It is also significantly faster (see performance comparison at the end of the post).
 

Truncating with CSS

One interesting thing about all of this is that in many cases text truncation should really be handled at the client side. It makes sense that the page contains the full-text data but trims it if the content area is too small to hold everything when displayed.

A good example to illustrate this is imagine if you design a menu which contains a list of items. Now the width of the menu is fixed so some items may need to be truncated to fit the width of the list. However if the user can adjust the font size suddenly the list needs to be remade server-side to compensate for presentation changes. You can also run into issues if the font is not monospaced (monospaced = each character has same width) since limiting the number of characters won’t result in a consistent width.

In this case truncation can be handled with the CSS text-overflow property.
 

 
As the below code shows it is very easy to implement and is fairly well supported (IE6, Opera 9+, Safari, Chrome)

p {
  white-space: nowrap;
  width: 250px;
  overflow: hidden;
  -o-text-overflow: ellipsis;
  -ms-text-overflow: ellipsis;
  text-overflow: ellipsis;
}

 
See http://developer.mozilla.org/en/CSS/text-overflow for more info.

However this doesn’t work at all if you apply it to a DIV which contains nested elements. The nested elements will be clipped without an ellipsis being appended. You can workaround this issue by applying the same styles to all the nested elements.

#mydiv, #mydiv * {
  white-space: nowrap;
  width: 250px;
  overflow: hidden;
  -o-text-overflow: ellipsis;
  -ms-text-overflow: ellipsis;
  text-overflow: ellipsis;
}

Truncating HTML

Ok so now we get to the tricky part. The issue with truncating HTML is that you cannot use an approach similar to what you would use for plain text. The reason for this is obvious if you truncate HTML as text then you run the risk of splitting the text in the middle of a HTML tag or attribute. So what we need is to be able to differentiate between the HTML tags and text, this requires parsing the HTML.

If you look online you will find some solutions to this problem that use regular expressions to parse the HTML. Parsing HTML with regular expressions is a bad idea if you are interested in how HTML is parsed by browsers then have a look at How Browsers Work: Behind the Scenes of Modern Web Browsers.

Fortunately the PHP DomDocument class can handle all the difficult parsing for us. So what we want is to parse the HTML using DomDocument that way we can accurately traverse the DOM and count the number of characters or words in any of the text nodes. Then we can remove any superfluous nodes and reconstruct the HTML document.

class TruncateHTML {
    
    public static function truncateChars($html, $limit, $ellipsis = '...') {
        
        if($limit <= 0 || $limit >= strlen(strip_tags($html)))
            return $html;
        
        $dom = new DOMDocument();
        $dom->loadHTML($html);
        
        $body = $dom->getElementsByTagName("body")->item(0);
        
        $it = new DOMLettersIterator($body);
        
        foreach($it as $letter) {
            if($it->key() >= $limit) {
                $currentText = $it->currentTextPosition();
                $currentText[0]->nodeValue = substr($currentText[0]->nodeValue, 0, $currentText[1] + 1);
                self::removeProceedingNodes($currentText[0], $body);
                self::insertEllipsis($currentText[0], $ellipsis);
                break;
            }
        }
        
        return preg_replace('~<(?:!DOCTYPE|/?(?:html|head|body))[^>]*>\s*~i', '', $dom->saveHTML());
    }
    
    public static function truncateWords($html, $limit, $ellipsis = '...') {
        
        if($limit <= 0 || $limit >= self::countWords(strip_tags($html)))
            return $html;
        
        $dom = new DOMDocument();
        $dom->loadHTML($html);
        
        $body = $dom->getElementsByTagName("body")->item(0);
        
        $it = new DOMWordsIterator($body);
        
        foreach($it as $word) {            
            if($it->key() >= $limit) {
                $currentWordPosition = $it->currentWordPosition();
                $curNode = $currentWordPosition[0];
                $offset = $currentWordPosition[1];
                $words = $currentWordPosition[2];
                
                $curNode->nodeValue = substr($curNode->nodeValue, 0, $words[$offset][1] + strlen($words[$offset][0]));
                
                self::removeProceedingNodes($curNode, $body);
                self::insertEllipsis($curNode, $ellipsis);
                break;
            }
        }
        
        return preg_replace('~<(?:!DOCTYPE|/?(?:html|head|body))[^>]*>\s*~i', '', $dom->saveHTML());
    }
    
    private static function removeProceedingNodes(DOMNode $domNode, DOMNode $topNode) {        
        $nextNode = $domNode->nextSibling;
        
        if($nextNode !== NULL) {
            self::removeProceedingNodes($nextNode, $topNode);
            $domNode->parentNode->removeChild($nextNode);
        } else {
            //scan upwards till we find a sibling
            $curNode = $domNode->parentNode;
            while($curNode !== $topNode) {
                if($curNode->nextSibling !== NULL) {
                    $curNode = $curNode->nextSibling;
                    self::removeProceedingNodes($curNode, $topNode);
                    $curNode->parentNode->removeChild($curNode);
                    break;
                }
                $curNode = $curNode->parentNode;
            }
        }
    }
    
    private static function insertEllipsis(DOMNode $domNode, $ellipsis) {    
        $avoid = array('a', 'strong', 'em', 'h1', 'h2', 'h3', 'h4', 'h5'); //html tags to avoid appending the ellipsis to
        
        if( in_array($domNode->parentNode->nodeName, $avoid) && $domNode->parentNode->parentNode !== NULL) {
            // Append as text node to parent instead
            $textNode = new DOMText($ellipsis);
            
            if($domNode->parentNode->parentNode->nextSibling)
                $domNode->parentNode->parentNode->insertBefore($textNode, $domNode->parentNode->parentNode->nextSibling);
            else
                $domNode->parentNode->parentNode->appendChild($textNode);
        } else {
            // Append to current node
            $domNode->nodeValue = rtrim($domNode->nodeValue).$ellipsis;
        }
    }
    
    private static function countWords($text) {
        $words = preg_split("/[\n\r\t ]+/", $text, -1, PREG_SPLIT_NO_EMPTY);
        return count($words);
    }
    
}

View the above source code standalone
View old source code standalone (version 1)
 

/**
 * Iterates individual words of DOM text and CDATA nodes
 * while keeping track of their position in the document.
 *
 * Example:
 *
 *  $doc = new DOMDocument();
 *  $doc->load('example.xml');
 *  foreach(new DOMWordsIterator($doc) as $word) echo $word;
 *
 * @author pjgalbraith http://www.pjgalbraith.com
 * @author porneL http://pornel.net (based on DOMLettersIterator available at http://pornel.net/source/domlettersiterator.php)
 * @license Public Domain
 *
 */

final class DOMWordsIterator implements Iterator {
    
    private $start, $current;
    private $offset, $key, $words;

    /**
     * expects DOMElement or DOMDocument (see DOMDocument::load and DOMDocument::loadHTML)
     */
    function __construct(DOMNode $el)
    {
        if ($el instanceof DOMDocument) $this->start = $el->documentElement;
        else if ($el instanceof DOMElement) $this->start = $el;
        else throw new InvalidArgumentException("Invalid arguments, expected DOMElement or DOMDocument");
    }
    
    /**
     * Returns position in text as DOMText node and character offset.
     * (it's NOT a byte offset, you must use mb_substr() or similar to use this offset properly).
     * node may be NULL if iterator has finished.
     *
     * @return array
     */
    function currentWordPosition()
    {
        return array($this->current, $this->offset, $this->words);
    }

    /**
     * Returns DOMElement that is currently being iterated or NULL if iterator has finished.
     *
     * @return DOMElement
     */
    function currentElement()
    {
        return $this->current ? $this->current->parentNode : NULL;
    }
    
    // Implementation of Iterator interface
    function key()
    {
        return $this->key;
    }
    
    function next()
    {
        if (!$this->current) return;

        if ($this->current->nodeType == XML_TEXT_NODE || $this->current->nodeType == XML_CDATA_SECTION_NODE)
        {
            if ($this->offset == -1)
            {
                $this->words = preg_split("/[\n\r\t ]+/", $this->current->textContent, -1, PREG_SPLIT_NO_EMPTY|PREG_SPLIT_OFFSET_CAPTURE);
            }
            $this->offset++;
            
            if ($this->offset < count($this->words)) { 
                $this->key++;
                return;
            }
            $this->offset = -1;
        }

        while($this->current->nodeType == XML_ELEMENT_NODE && $this->current->firstChild)
        {
            $this->current = $this->current->firstChild;
            if ($this->current->nodeType == XML_TEXT_NODE || $this->current->nodeType == XML_CDATA_SECTION_NODE) return $this->next();
        }

        while(!$this->current->nextSibling && $this->current->parentNode)
        {
            $this->current = $this->current->parentNode;
            if ($this->current === $this->start) {$this->current = NULL; return;}
        }

        $this->current = $this->current->nextSibling;

        return $this->next();
    }

    function current()
    {
        if ($this->current) return $this->words[$this->offset][0];
        return NULL;
    }

    function valid()
    {
        return !!$this->current;
    }

    function rewind()
    {
        $this->offset = -1; $this->words = array();
        $this->current = $this->start;
        $this->next();
    }
}

View the above source code standalone
 

/**
 * Iterates individual characters (Unicode codepoints) of DOM text and CDATA nodes
 * while keeping track of their position in the document.
 *
 * Example:
 *
 *  $doc = new DOMDocument();
 *  $doc->load('example.xml');
 *  foreach(new DOMLettersIterator($doc) as $letter) echo $letter;
 *
 * NB: If you only need characters without their position
 *     in the document, use DOMNode->textContent instead.
 *
 * @author porneL http://pornel.net
 * @license Public Domain
 *
 */
final class DOMLettersIterator implements Iterator
{
    private $start, $current;
    private $offset, $key, $letters;

    /**
     * expects DOMElement or DOMDocument (see DOMDocument::load and DOMDocument::loadHTML)
     */
    function __construct(DOMNode $el)
    {
        if ($el instanceof DOMDocument) $this->start = $el->documentElement;
        else if ($el instanceof DOMElement) $this->start = $el;
        else throw new InvalidArgumentException("Invalid arguments, expected DOMElement or DOMDocument");
    }

    /**
     * Returns position in text as DOMText node and character offset.
     * (it's NOT a byte offset, you must use mb_substr() or similar to use this offset properly).
     * node may be NULL if iterator has finished.
     *
     * @return array
     */
    function currentTextPosition()
    {
        return array($this->current, $this->offset);
    }

    /**
     * Returns DOMElement that is currently being iterated or NULL if iterator has finished.
     *
     * @return DOMElement
     */
    function currentElement()
    {
        return $this->current ? $this->current->parentNode : NULL;
    }

    // Implementation of Iterator interface
    function key()
    {
        return $this->key;
    }

    function next()
    {
        if (!$this->current) return;

        if ($this->current->nodeType == XML_TEXT_NODE || $this->current->nodeType == XML_CDATA_SECTION_NODE)
        {
            if ($this->offset == -1)
            {
                // fastest way to get individual Unicode chars and does not require mb_* functions
                preg_match_all('/./us',$this->current->textContent,$m); $this->letters = $m[0];
            }
            $this->offset++; $this->key++;
            if ($this->offset < count($this->letters)) return;
            $this->offset = -1;
        }

        while($this->current->nodeType == XML_ELEMENT_NODE && $this->current->firstChild)
        {
            $this->current = $this->current->firstChild;
            if ($this->current->nodeType == XML_TEXT_NODE || $this->current->nodeType == XML_CDATA_SECTION_NODE) return $this->next();
        }

        while(!$this->current->nextSibling && $this->current->parentNode)
        {
            $this->current = $this->current->parentNode;
            if ($this->current === $this->start) {$this->current = NULL; return;}
        }

        $this->current = $this->current->nextSibling;

        return $this->next();
    }

    function current()
    {
        if ($this->current) return $this->letters[$this->offset];
        return NULL;
    }

    function valid()
    {
        return !!$this->current;
    }

    function rewind()
    {
        $this->offset = -1; $this->letters = array();
        $this->current = $this->start;
        $this->next();
    }
}

View the above source code standalone (Note the DOMLettersIterator class was created by pornel)

Well I didn’t say it was going to be easy. As you can see it takes a fair bit of work to do and a lot more lines of code compared to the simple text truncate functions. It is also significantly more expensive to process.

You can use the above class like this:

require('DOMLettersIterator.php'); 
require('DOMWordsIterator.php'); 
require('TruncateHTML.php');

$html = '<p>This is <strong>test</strong> html text.</p>';

$output = TruncateHTML::truncateChars($html, '11', '...');
echo $output;

$output = TruncateHTML::truncateWords($html, '3', '...');
echo $output;

 
In summary if you need to truncate HTML I would always recommend you first consider whether it is possible to strip the tags and process it as plain text. Of course you could always throw caution to the wind and devise a rudimentary regex based solution, which may work ok if you can live with the limitations. Otherwise the above approach (or something similar to it) is a good option especially if accuracy is important.
 

Performance Comparison

The following numbers represent the average execution time in microseconds to execute each function 1000 times. Smaller is better.

truncate_chars: 1,446
truncate_chars2: 4,858 (second version that retains words)
truncate_words: 23,401 (WordPress version)
truncate_words2: 12,562
TruncateHTML::truncateChars: 874,875
TruncateHTML::truncateWords: 1,397,687

As you can see the HTML truncation functions are over 100 times slower than their text equivalents so you definitely want to consider caching their output.

Download: http://wordpress.org/extend/plugins/recent-posts-plus

1: Title

Default: Recent Posts

This field sets the title of the widget. It works the same as every other widget.

2: Number of posts

Default: 5

Changes how many posts are displayed in the widget. Enter ‘-1′ to display all posts.

3: Include post thumbnail

Default: no

Displays the post thumbnails of each post.

If this option is hidden you may not have a theme with post-thumbnails enabled. You can manually enable and add post-thumbnails to each post or you can download the Default Thumbnail Plus plugin automatically display a default image.

4: Include post excerpt

Default: no

Displays the post excerpt of each post.

5: Show expert options

Default: no

Show/hide the expert options panel. These options should be used with more care.

6: Limit post title

Default: (no limit)

Limits the numbers of characters or words to display of each posts title.
Example: For the post title “Look at this title” setting this option to 7 chars would result in “Look at…”

7: Limit post excerpt

Default: (no limit)

Limits the numbers of characters or words to display of each posts excerpt.

8: Limit ellipsis

Default: …

Sets the string to append to post titles or excerpts that have been shortened.

9: Post date format

Default: M j

Sets the PHP date format to use when displaying the post date.
See http://php.net/manual/en/function.date.php for overview of the options available.

Note: the date format can be overriden in the output template, which allows for multiple date formats in one entry, see section “12: Widget output template”.

10: Thumbnail size

Default: 50 x 50

Sets the size of the post thumbnail in pixels.

11: WP_Query options

This is an advanced option that modifies what posts are shown in the widget. This option specifies extra arguments to use in the WP_Query request and as such is very flexible even allowing this widget to show pages rather than posts, show oldest posts first, or filter posts by tag or category. The WP_Query options must be specified in valid JSON format (validate here http://jsonlint.com/).

These are the default args that are sent to WP_Query:

{
"post_type": "post",
"posts_per_page": <same as Number of posts setting>, 
"orderby": "date",
"order": "DESC"
}

List of options:

{
"post_type": "post", //post, page, revision, attachment, any
"post_status": "publish", //publish, pending, draft, auto-draft, future, private, inherit, trash, any.
"posts_per_page": "5", //overrides number of posts setting
"offset": "3", //number of posts to skip over 
"post__in": [2, 3, 4], //only show posts 2, 3 and 4
"post__not_in": [2, 3, 4], //exclude posts 2, 3 and 4
"ignore_sticky_posts": "1", //ignore sticky posts or not. Default value is 0, don't ignore (requires WordPress 3.1+).
"caller_get_posts": "1", //ignore sticky posts or not. Deprecated as of Version 3.1 in favor of 'ignore_sticky_posts'.
"author": "1", //author ID
"author_name": "john", //post author's name, use 'user_nicename' (NOT name)
"orderby": "date", //none, ID, author, title, date, modified, parent, rand, comment_count, meta_value, meta_value_num  
"order": "DESC", //ASC or DESC
"tag": "cooking,baking", //display posts that have "either" of these tags
"tag": "bread+baking+recipe", //display posts that have "all" of these tags
"tag_id": "13",
"cat": "1, 2, -3", //category ID 1, 2 but not 3
"category_name": "articles,news",
"year": "2011",
"meta_query" : [] //see below
}

For a full listing see http://codex.wordpress.org/Class_Reference/WP_Query

Ordering by custom fields

You can change the sort order to be based on a specified custom field using meta_value and meta_value_num as the orderby option.

Note: The difference between meta_value and meta_value_num is that the meta_value_num is sorted as a numeric value (i.e. meta_value would be ordered as a string e.g. 1, 3, 34, 4, 56, 6 whereas meta_value_num would be 1, 3, 4, 6, 34, 56).

The following example would order posts by custom field rating showing in order of highest rated to lowest rated.

{
     "meta_key": "rating",
     "order": "DESC",
     "orderby": "meta_value_num"
}

Utilizing the meta_query option

Note: This option requires WordPress 3.1+

Filter or show posts with a certain custom field value using the meta_query option.

The following example would display posts with a custom field called mood with a value of happy:

{
    "meta_query": [
        {
           "key": "mood", //Custom field key
           "value": "happy", //Custom field value
           "type": "CHAR", //Custom field type. Possible values are 'NUMERIC', 'BINARY', 'CHAR', 'DATE', 'DATETIME', 'DECIMAL', 'SIGNED', 'TIME', 'UNSIGNED'
           "compare": "=" //Operator to test. Possible values are '=', '!=', '>', '>=', '<', '<=', 'LIKE', 'NOT LIKE', 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN'
        }
    ]
}

The following example would display posts if they have a custom field rating of between 5 and 10 or if they have a custom field mood with a value of happy:

{
    "meta_query": {
        "relation": "OR", //Possible values are 'AND', 'OR'
        "0": {
            "key": "rating",
            "value": [5, 10],
            "type": "NUMERIC",
            "compare": "BETWEEN"
        },
        "1": {
            "key": "mood",
            "value": "happy",
            "type": "CHAR",
            "compare": "="
        }
    }
}

12: Widget output template

This is an advanced option that modifies the output of the widget. You can modify the output with template tags and add custom classes or tags for styling.

By default the widget outputs posts in this format:

<li>
{THUMBNAIL}
<a title="{TITLE_RAW}" href="{PERMALINK}">{TITLE}</a>
{EXCERPT}
</li>

You can modify the output by including the following template tags:

{ID} The post ID
{THUMBNAIL} The post thumbnail IMG tag if it exists, otherwise nothing
{TITLE_RAW} The post title
{TITLE} The post title, will be trimmed if it exceeds "Option 6: Limit post title chars"
{EXCERPT_RAW} The post excerpt
{EXCERPT} The post excerpt, will be trimmed if it exceeds "Option 7: Limit post excerpt chars"
{PERMALINK} The post permalink url
{DATE} The post date, the format is defined by the "Option 9: Post date format" setting
{DATE[php_date_format]} As of 1.0.4: Customized date format which overrides the default date format setting. E.g. {DATE[l jS F Y]} would display like "Monday 1st January 2011"
{AUTHOR} The post author name
{AUTHOR_LINK} The post author website url
{AUTHOR_AVATAR} As of 1.0.7: Displays the author's avatar if available
{COMMENT_COUNT} The total number of comments, Trackbacks, and Pingbacks for the post
{META[name]} As of 1.0.5: Displays the value of the specified custom field. E.g. {META[Currently Reading]} or {META[Rating]}. Note: Only returns the first result.
{ELLIPSIS}...{/ELLIPSIS} As of 1.0.9: Overrides option "8: limit ellipsis" for the excerpt. 
                         You can use other templates tags within the {ELLIPSIS} tags but not PHP and it will only be appended to the excerpt if it is truncated. 
                         Example: {ELLIPSIS}... <a href="{PERMALINK}">(more)</a>{/ELLIPSIS}

Using raw PHP in the Widget output template

As of 1.0.7 you can add raw PHP code to the widget output template.

Note: This will require the PHP code you enter to be run though eval which will likely have a small performance penalty. However if you don't enter any PHP code eval will not be run. Be careful not to give untrusted users permission to modify widget settings since it could be a potential security risk.

The following example displays the author's avatar at 32px size:

<li>
<?php echo get_avatar(get_the_author_meta('user_email'), 32); ?>
<a title="{TITLE_RAW}" href="{PERMALINK}">{TITLE}</a>
{EXCERPT}
</li>

You can access some of the existing template tag values with the $widget_ouput_template_params array e.g. $widget_ouput_template_params['{ID}'] contains the current posts ID.

Examples of Styling the Output

The look of the widget output depends a lot on what theme you are using. By default the output looks somewhat like the image below. Thankfully we can improve this with very little effort and a few additions to your themes stylesheet.

The first thing you need to do is go to Appearance -> Editor and select the Stylesheet option on the right (it should be selected by default but just make sure). After that paste one of the following styles at the bottom of the stylesheet depending on the look you want.

Note these are just basic examples you can do a lot more with more with CSS. These examples also depend a lot on the theme you are using, more complex themes may require additional styling. Hopefully these examples can point you in the right direction.

.widget_recent_entries li {
    clear: both;
    margin: 5px 0;
}
.widget_recent_entries .wp-post-image {
    vertical-align: text-top;
    margin: 0 5px 0 0;
}

.widget_recent_entries li {
    clear: both;
    margin: 15px 0;
}

.widget_recent_entries .wp-post-image {
    float: left;
    margin: 0 5px 0 0;
}

.widget_recent_entries li p {
    margin-top: 5px;
    color: #707070;
}

.widget_recent_entries li {
    clear:both;
    margin: 5px 0;
}

.widget_recent_entries .wp-post-image {
    vertical-align: middle;
    margin: 0 5px 0 0;
}

The above example has the thumbnail size set to 25px x 25px.

.widget_recent_entries li {
    clear:both;
    margin: 10px 0;
    text-align: center;
}

.widget_recent_entries .wp-post-image {
    margin: 0 5px 0 0;
}

.widget_recent_entries li a {
    display: block;
}

The above example has the thumbnail size set to 100px x 100px.