jqPuzzle

Customizable Sliding Puzzles with jQuery

jQuery JavaScript Library turn a simple image into a full-blown sliding puzzle

jqPuzzle lets you easily create sliding puzzles for your web page. Select an image, put it in your page, and add some magic – jqPuzzle will automagically turn it into a full-blown sliding puzzle! If you want, you can highly customize and style your sliding puzzle according to your needs. The interface is available in several languages, and you can add your own texts on the fly.
Since jqPuzzle is all JavaScript, your users won't need any additional plugins or software. jqPuzzle is powered by jQuery, a powerful and straightforward JavaScript library. jQuery rocks!

See jqQuery in action: Animals crossing

If you see a regular image instead of the sliding puzzle,
you might not have JavaScript enabled or jQuery is not compatible with your browser.


You can find more examples on the Demo page ».

Download

Download jqPuzzle.zip
Version 1.02 (2008-03-07)


The ZIP archive includes both the source and the packed code along with the style sheet.

See the project page in the jQuery plugin repository for release notes and older versions of jqPuzzle.

jqPuzzle is tested in Firefox 1.5+, Internet Explorer 6 + 7 and Opera 9. It is also reported to work in Safari. See also the jQuery Browser Compatibility page. jqPuzzle requires jQuery 1.2.1 or higher.

Do you have any suggestions, found bugs, or patches? Drop me a line or use the means provided by the project page in the jQuery plugin repository.

jqPuzzle is dual-licensed under the GPL and MIT licenses. Feel free to modify the source to your needs. I would be nice if you keep the link to the jqPuzzle home page in your puzzles, but you are not obliged to.

If you enjoy jqPuzzle and feel generous, I would gladly accept a donation via my Amazon wish list.

How to use

Preparations

  1. Download the jQuery JavaScript Library from the jQuery home page.
  2. Download jqPuzzle.
  3. Set up your HTML page and copy the jQuery and jqPuzzle files into the same directory.
  4. Copy the following lines into the <head> of your HTML file and adjust the file names, if needed: 
    <script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="jquery.jqpuzzle.js"></script>
<link rel="stylesheet" type="text/css" href="jquery.jqpuzzle.css" />

Set up your sliding puzzle

Option 1: Adding a class name

Insert an image into your page and simply add class="jqPuzzle" to the image tag. That's all!

Example: Show demo »

<img src="street.jpg" alt="Animals crossing" class="jqPuzzle" />
Option 2: Using the CSS micro format

This option allows you to control the most important features of jqPuzzle. It extends Option 1 with a CSS micro format. This format is simply a second class name which is applied to your image tag. The syntax for the micro format (the CSS class) is as follows:

jqp[-LANGUAGE]-rROWS-cCOLS[-hHOLE][-sSHUFFLE_ROUNDS][-FLAGS]

Replace all UPPER CASE words with real values. Properties in brackets [] are optional.

Example 1: 3 rows, 5 columns, hole at position 5 Show demo »

<img src="street.jpg" alt="Animals crossing" class="jqPuzzle jqp-r3-c5-h5" />

Example 2: German, 5 rows, 5 columns

<img src="street.jpg" alt="Animals crossing" class="jqPuzzle jqp-de-r5-c5" />

Example 3: 4 rows, 4 columns, 1 shuffle round

<img src="street.jpg" alt="Animals crossing" class="jqPuzzle jqp-r4-c4-s1" />

Example 4: French, 3 rows, 3 columns, hole at position 5, initially hide numbers, hide moves/seconds display

<img src="street.jpg" alt="Animals crossing" class="jqPuzzle jqp-fr-r3-c3-h5-NDE" />

Example 5: German, 5 rows, 7 columns, initially shuffle pieces, hide shuffle button and seconds display

<img src="street.jpg" alt="Animals crossing" class="jqPuzzle jqp-de-r5-c7-SAE" />
Option 3: The jQuery plugin syntax

With this option, you can fully control all features of your sliding puzzles. jqPuzzle is implemented as an ordinary plugin for jQuery. It adds a new method to the jQuery object. This means that you can harness the full power and elegance of jQuery: Query some elements, call the jqPuzzle()-method and optionally pass in your settings and texts. jqPuzzle does all the work for you, filters the image elements and creates the sliding puzzle(s).

Place the function call in a $(document).ready() structure to make sure the DOM is already loaded. Also make sure that the <script> tag is placed somewhere below the included scripts in your HTML file

Example: The plugin syntax without parameters Show demo »

<script type="text/javascript">
    $(document).ready(function() {
        $('img').jqPuzzle(); // apply to all images
    });
</script>

Of course, you could also use different selectors like $('#box img') (apply to all images in '#box') or $('.puzzle') (apply to all images with class name 'puzzle'). See the jQuery Selectors page for further information.

If you are unfamiliar with jQuery itself, you may want to read Getting Started with jQuery first.

API: The jqPuzzle()-method

jqPuzzle(settings, texts)

The jqPuzzle()-method can have two optional arguments. The first parameter is a settings object that lets you customize your sliding puzzle. Below you can find the full object with its default values defined. If you want to pass in your own settings, you don't need to specify the full object. Just define the varying values (and take note of correct nesting).

API: The settings object with its default values

var settings = {
    rows: 4,                    // number of rows [3 ... 9]
    cols: 4,                    // number of columns [3 ... 9]
    hole: 16,                   // initial hole position [1 ... rows*columns]
    shuffle: false,             // initially show shuffled pieces [true|false]
    numbers: true,              // initially show numbers on pieces [true|false]
    language: 'en',             // language for gui elements [language code]

    // display additional gui controls
    control: {
        shufflePieces: true,    // display 'Shuffle' button [true|false]
        confirmShuffle: true,   // ask before shuffling [true|false]
        toggleOriginal: true,   // display 'Original' button [true|false]
        toggleNumbers: true,    // display 'Numbers' button [true|false]
        counter: true,          // display moves counter [true|false]
        timer: true,            // display timer (seconds) [true|false]
        pauseTimer: true		// pause timer if 'Original' button is activated
                                // [true|false]
    },

    // perform actions when the puzzle is solved sucessfully
    success: {
        fadeOriginal: false,    // cross-fade original image [true|false]
        callback: undefined,    // callback a user-defined function [function]
                                // the function is passed an object as its argument
                                // which includes the fields 'moves' and 'seconds'
        callbackTimeout: 300    // time in ms after which the callback is called
    },

    // animation speeds and settings
    animation: {
        shuffleRounds: 3,       // number of shuffle rounds [1 ... ]
        shuffleSpeed: 800,      // time in ms to perform a shuffle round
        slidingSpeed: 200,      // time in ms for a single move
        fadeOriginalSpeed: 600  // time in ms to cross-fade original image
    },

    // additional style information not specified via css
    style: {
        gridSize: 2,            // space between two pieces in px
        overlap: true,          // if true, adjacent piece borders will overlap
                                // applies only if gridSize is set to 0
        backgroundOpacity: 0.1  // opacity of the original image behind the pieces
                                // [0 ... 1] (0 means no display)
    }
}

The second parameter of the jqPuzzle()-method is the texts objects. It holds all strings which are used in the user interface. By passing in your own object, you can change the texts to your needs.

API: The texts object with its default values

var texts = {
    shuffleLabel:           'Shuffle',
    toggleOriginalLabel:    'Original',
    toggleNumbersLabel:     'Numbers',
    confirmShuffleMessage:  'Do you really want to shuffle?',
    movesLabel:             'moves',
    secondsLabel:           'seconds'
}

Note that jqPuzzle comes with multiple predefined languages which you can directly set with the settings object.

Below you can find some example usage of the plugin syntax with parameters defined:

Example 1: User-defined settings Show demo »

<script type="text/javascript">
    $(document).ready(function() {
        // define your own settings
        var mySettings = {
            cols: 5,
            hole: 11,
            numbers: false,
            control: {
                toggleNumbers: false,
                counter: false,
                timer: false
            },
            animation: {
                shuffleRounds: 1,
                slidingSpeed: 100,
                shuffleSpeed: 200
            }
        };
        // call jqPuzzle with mySettings on an image with id 'myImage'
        $('#myImage').jqPuzzle(mySettings);
    });
</script>

Example 2: User-defined texts, pass null as first parameter Show demo »

<script type="text/javascript">
    $(document).ready(function() {
        // define your own texts
        var myTexts = {
		    shuffleLabel:           'Mix!',
		    toggleOriginalLabel:    'Help!',
		    toggleNumbersLabel:     'Help!!!',
		    confirmShuffleMessage:  'Really mix?'
        };
        // call jqPuzzle with myTexts on all images
        $('img').jqPuzzle(null, myTexts);
    });
</script>

Example 3: Set language, add a callback, redefine a text label Show demo »

<script type="text/javascript">
    $(document).ready(function() {
        // define your own settings
        var mySettings = {
            rows: 3,
            cols: 3,
            language: 'de',
			success: {
                callback: function(results) {
                    alert('Gelöst in ' + results.moves + ' Zügen und ' +
                        + results.seconds + ' Sekunden.');
                }
            }
        };
        // define your own texts
		var myTexts = {
            secondsLabel: 'Sek.'
        };
        // call jqPuzzle with mySettings and myTexts on images with class 'myPics'
        $('.myPics').jqPuzzle(mySettings, myTexts);
    });
</script>

Styling

jqPuzzle comes with a CSS file that includes a standard theme. Depending on your image size you may want to adjust font sizes or change the overall appearance of the sliding puzzle. Note that some CSS properties are set by the jqPuzzle script itself to make sure that the puzzle works properly. These properties can overwrite user-defined properties.

You can also style your puzzles based on an image id. The id will be assigned to the sliding puzzle after the original image has been removed. This way you can individually style each puzzle using CSS selectors which start with #yourImageId instead of the general .jqPuzzle class. Also, user-defined class names (including the CSS micro format) will be transferred to the puzzle and can be used for styling.

Some visual properties can only be set via the plugin syntax by adding a style object inside the settings object. See the description of the settings object for more information.


See examples of all styling methods on the Demo page ».

Languages

jqPuzzle comes out of the box with the above stated languages. You can set the initial language using the CSS micro format or the plugin syntax. It is also possible to add your own translation. Feel free to send me an e-mail with your language.

FAQ Frequently Asked Questions

» Can I use images from remote sites with jqPuzzle?

Sure you can! Just enter a full URL to the image file into the src attribute of the image tag. But keep in mind that the image linked to could be copyrighted.

<img src="http://www.2meter3.de/jqPuzzle/street.jpg" class="jqPuzzle"/>

» Can jqPuzzle scale my images?

No, sorry. Since jqPuzzle runs in the browser, and browser-scaled images are sooo ugly, I decided not to implement this feature. Scale your images first with a real image processor. There are also a couple of online services available.

» Is there any requirement for my images to meet?

Well, the resulting puzzle pieces have to be at least 30 pixels wide and high. Things are getting a little tiny, you know? You can either increase your original image or reduce the number of rows/columns. Feel free to weaken this requirement in the source code.

» What happens if my users do not have JavaScript enabled?

Your users will see the original image instead of the sliding puzzle. It will be styled according to the .jqPuzzle class from the default theme CSS file or your individual id/class.

» Some special characters are not displayed properly. What's going on?

Seems like the charset of your HTML page does not match the one of the jqPuzzle JavaScript file. The plugin files are encoded in UTF-8 (from version 1.02).

If you cannot adjust the charset of your HTML page, you can also explicitly specify the charset for the JavaScript file in the script tag:

<script type="text/javascript" src="jquery.jqpuzzle.js" charset="utf-8"></script/>

Valid XHTML 1.0 Strict jQuery JavaScript Library (Almost) Valid CSS :-)
This page uses syntax highlighting by Chili and flag icons by famfamfam.
Sliding puzzles are also known as n-puzzles, sliding block puzzles, slide puzzles, slider puzzles, and sliding tile puzzles.

If you enjoy jqPuzzle and feel generous, I would gladly accept a donation via my Amazon wish list.

a 2meter3 project