Child pages
  • Tutorial - Image Reorderer

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 5.3
Warning

This tutorial is incomplete - treat it with caution.

Section
Column
width60%

This page will walk you through an example of using the Infusion Reorderer's reorderImages() function to reorder image thumbnails in a collection.

This tutorial assumes that:

  • you are already familiar with HTML, Javascript and CSS
  • you are familiar with what the Image Reorderer is and does
  • now you just want to know how to add it to your file.

For more general information about the Reorderer, see Reorderer. For technical API documentation, see Image Reorderer API and Advanced Reorderer API.


Tutorial: How to Use the Image Reorderer

Scenario

Suppose you're not satisfied with any of the image sharing applications currently available on the web, and you're convinced that you can write a better one. You want to use Infusion's Image Reorderer to let your users re-arrange the images in their collections.

There are five basic steps to using the Image Reorderer in your application:

  • Setup: Download and install the Fluid Infusion library
  • Step 1: Prepare your markup
  • Step 2: Write the script
  • Step 3: Add the script to your HTML
  • Step 4: Apply styles

The rest of this tutorial will explain each of these steps in detail.

Column
Panel
borderStyle
borderColor#321137
bgColor#fff
titleBGColor#aab597
borderStylesolid
titleStatussolid

This component is in Production status

solid
Panel
borderStyle
borderColor#566b30
bgColor#fff
titleBGColor#D3E3C4
borderStylesolid
titleOn This Page
Table of Contents
toc
maxLevel
5
minLevel2maxLevel5
Panel
borderColor#321137
bgColor#fff
titleBGColor#c1b7c3
borderStylesolid
titleSee Also
borderStylesolid
Panel
borderColor#321137
bgColor#fff
titleBGColor#cccccc
borderStylesolid
titleStill need help?
borderStylesolid

Join the infusion-users mailing list and ask your questions there.

...

Include Page
Infusion13:Tutorial SetupInfusion13:
Tutorial Setup

...

Step 1: Prepare your markup

Let's suppose you're using a <form> with hidden <input> elements to record the ordering of the images in your collections. A simple (For a description of how to use this <form> approach, see Talking to the Server Using The afterMove Event.) A simple example of this could be:

Code Block
html
html
<form action="#">
    <a href="myImage1.jpg">
        <img src="myImage1.jpg" alt="image 1 thumbnail" />
        <span>Image 1</span>
        <input name="image 1" value="0" type="hidden" /> 
    </a>
    <a href="myImage2.jpg">
        <img src="myImage2.jpg" alt="image 2 thumbnail" />
        <span>Image 2</span>
        <input name="image 2" value="1" type="hidden" /> 
    </a>
    <a href="myImage3.jpg">
        <img src="myImage3.jpg" alt="image 3 thumbnail" />
        <span>Image 3</span>
        <input name="image 3" value="2" type="hidden" /> 
    </a>
    ...
</form>

The Image Reordeer Reorderer needs to know about the 'container' of your image collection. In this case, that could would be the <form> element. But since there may be other <form> elements in the markup, you will need to uniquely identify the <form> you want to use as a container.

The Reorderer accepts a jQuery selector, so you can choose any method that will uniquely identify the <form> element. We'll attach a unique ID to it:

Section
Column
Code Block
html
html
<form action="#" id="reorder-images-form">
    ...
Column
Panel
borderColor#566b30
bgColor#D3E3C4
borderStyleoutset
titleNote
borderStyleoutset

This example uses an ID, but you might, for example, use a CSS class, or the element hierarchy - whatever works, so long as it uniquely identifies the right element.

...

Note
titleForm elements and the Image Reorderer

Currently the Image Reorderer is limited to using <form> elements as its root container. This is a known issue and it is expected that in the future any container can be used as long as it is properly identified. For more information see (FLUID-4019).

You also need to tell the Reorderer which of your images should be reorderable . Most and most of the time, that will likely be all of them, but . But perhaps you want the first image to always be first , since it's the cover of the album - with the Image Reorderer this is possible. For this tutorial, though, we'll make all of the image contained images movable.

You'll tell the Reorderer which items are to be orderable with another jQuery selector. The Image Reorderer understands a default class name for this purpose. You , but you can override that if you like, but for . For this tutorial, we'll go the simple route. The default classname is stick with the defaults classname flc-imageReorderer-item, so let. Let's add that to each of the <a> elements:

Section
Column
Code Block
html
html
<form action="#" id="reorder-images-form">
    <a href="myImage1.jpg" class="flc-imageReorderer-item">
        <img src="myImage1.jpg" alt="image 1 thumbnail" />
        <span>Image 1</span>
        <input name="image 1" value="0" type="hidden" /> 
    </a>
    <a href="myImage2.jpg" class="flc-imageReorderer-item">
        <img src="myImage2.jpg" alt="image 2 thumbnail" />
        <span>Image 2</span>
        <input name="image 2" value="1" type="hidden" /> 
    </a>
    <a href="myImage3.jpg" class="flc-imageReorderer-item">
        <img src="myImage3.jpg" alt="image 3 thumbnail" />
        <span>Image 3</span>
        <input name="image 3" value="2" type="hidden" /> 
    </a>
    ...
</form>
Column
unmigrated-wiki-markup
Panel
borderColor#566b30
bgColor#D3E3C4
titleNote
borderStyleoutset
titleNote

As with the ID on the {{<form>}}, we can use any jQuery selector for the reorderable images. For example, we could attach a unique ID to each movable {{<a>}} with a unique prefix, maybe {{pic-movable1}}, {{pic-movable2}}, etc. Then we could use the jQuery selector {{\[fluid:id^=pic-movable\]}} to override the default selector.

Finally, you'll want to tell the Image Reorderer which part of your markup is the caption for the image. The Image Reorderer will use this information to help make your image collection more usable by people using assistive technologies, such as a screen reader.

You can identify the captions using a custom classname, or use the default selector classname , flc-reorderer-imageTitle:

Code Block
html
html
<form action="#" id="reorder-images-form">
    <a href="myImage1.jpg" class="flc-imageReorderer-item">
        <img src="myImage1.jpg" alt="image 1 thumbnail" />
        <span class="flc-reorderer-imageTitle">Image 1</span>
        <input name="image 1" value="0" type="hidden" /> 
    </a>
    <a href="myImage2.jpg" class="flc-imageReorderer-item">
        <img src="myImage2.jpg" alt="image 2 thumbnail" />
        <span class="flc-reorderer-imageTitle">Image 2</span>
        <input name="image 2" value="1" type="hidden" /> 
    </a>
    <a href="myImage3.jpg" class="flc-imageReorderer-item">
        <img src="myImage3.jpg" alt="image 3 thumbnail" />
        <span class="flc-reorderer-imageTitle">Image 3</span>
        <input name="image 3" value="2" type="hidden" /> 
    </a>
    ...
</form>

...

Step 2: Write the script

YouTo make the HTML you just created do something special, you'll need to create a file to contain your initialization script - the script you write to apply the Reorderer to your image collection.

Section
Column

Create a file, say image-collection.js, and in this file, write a function that looks like this:

Code Block
javascript
javascript
jQuery(document).ready(function () {
    return fluid.reorderImages("#reorder-images-form");
});

In this function call, the parameter to reorderImages(), "#reorder-images-form", is a jQuery selector identifying the element with the ID reorder-images-form. That's all the information required by the fluid.reorderList() function.

By enclosing the function call inside jQuery(document).ready(), we ensure that the HTML is fully rendered before we apply the Reorderer to it.

Column
Panel
borderColor#566b30
bgColor#D3E3C4
borderStyleoutset
titleNoteborderStyleoutset

If you choose to use a custom selector for the movable items (instead of the default classname), you can override the default using options passed as the second parameter. Define an options block that specifies the selector you'd like, and pass it to the function:

Code Block
javascript
javascript
jQuery(document).ready(function () {
    var opts = {
        selectors: {
            movables: "[id^=pic-movable]"
        }
    };
    return fluid.reorderImages("#reorder-images-form", opts);
});

For more information on selectors and other options, see the Image Reorderer API documentation.

...

Step 3: Add the script to your HTML

You'll need to add your initialization script, along with the Infusion library, to you HTML file. In the header of the file, link to the Javascript files with <script> tags:

Code Block
html
html
<script type="text/javascript" src="infusion-1.02/InfusionAll.js"></script>
<script type="text/javascript" src="image-collection.js"></script>

...

Code Block
html
html
<script type="text/javascript" src="infusion-1.0../../../../lib/jquery/core/js/jquery.js"></script>
<script type="text/javascript" src="infusion-1.0../../../../lib/jquery/ui/js/jquery.ui.core.js"></script>
<script type="text/javascript" src="infusion-1.0../../../../lib/jquery/ui/js/jquery.ui.draggablewidget.js"></script>
<script type="text/javascript" src="infusion-1.0/framework/core../../../../lib/jquery/ui/js/jquery.keyboard-a11yui.mouse.js"></script>
<script type="text/javascript" src="infusion-1.0/framework/core/js/Fluid../../../../lib/jquery/ui/js/jquery.ui.draggable.js"></script>
<script type="text/javascript" src="infusion-1.0../../../../framework/core/js/FluidDOMUtilitiesFluidDocument.js"></script>
<script type="text/javascript" src="infusion-1.0/components/reorderer/js/GeometricManager../../../../framework/core/js/jquery.keyboard-a11y.js"></script>
<script type="text/javascript" src="infusion-1.0/components/reorderer../../../../framework/core/js/ReordererFluid.js"></script>
<script type="text/javascript" src="infusion-1.0/components/reorderer../../../../framework/core/js/ImageReordererFluidDOMUtilities.js"></script>
<script type="text/javascript" src="image-collection.../../../../framework/core/js/FluidView.js"></script>

But all of these individual files are not necessary to make it work - the InfusionAll.js file has everything you need.

That's it! That's all you need to do to make your images reorderable!

Step 4: Apply styles

You can style your image gallery any way you choose (of course), but the Infusion Image Reorderer comes with a set of CSS styles that have been carefully created by interface and interaction designers.

Using the default styles

You can take advantage of the Image Reorderer styles provided with the component by simply adding the default styling class names to your markup. The Image Reorderer will take care of the rest.

There are three things you'll want to add styling classnames to:

  1. the container element, using fl-imageReorderer and fl-reorderer-horizontalLayout,
  2. the reorderable elements themselves, using fl-imageReorderer-item, and
  3. the captions, using fl-imageReorderer-caption.

...


<form action="#" id="reorder-images-form" class="fl-imageReordererfl-reorderer-horizontalLayout">
    <a href="myImage1.jpg" class="flc-imageReorderer-item fl-imageReorderer-item">
        <img src="myImage1.jpg" alt="image 1 thumbnail" />
        <span class="flc-reorderer-imageTitle fl-imageReorderer-caption">Image 1</span>
        <input name="image 1" value="0" type="hidden" /> 
    </a>
    <a href="myImage2.jpg" class="flc-imageReorderer-item fl-imageReorderer-item">
        <img src="myImage2.jpg" alt="image 2 thumbnail" />
        <span class="flc-reorderer-imageTitle fl-imageReorderer-caption">Image 2</span>
        <input name="image 2" value="1" type="hidden" /> 
    </a>
    <a href="myImage3.jpg" class="flc-imageReorderer-item fl-imageReorderer-item">
        <img src="myImage3.jpg" alt="image 3 thumbnail" />
        <span class="flc-reorderer-imageTitle fl-imageReorderer-caption">Image 3</span>
        <input name="image 3" value="2" type="hidden" /> 
    </a>
    ...
</form>

The fl-reorderer-horizontalLayout will lay the images out horizontally, and will make sure that the drop marker shows up between the thumbnails properly.

Customizing the styles

Step 1 - Include the Fluid component library

The first step is to include the Fluid component library code in your file. Do this by adding a script tag to the header referencing the Fluid-all.js javascript file:

...


<head>
  <title>Image Collection</title>
  <script type="text/javascript" src="Fluid-all.js"></script>
</head>

Step 2 - Add element IDs

The second step is to add IDs to the elements that the Image Reorderer needs to know about.

First, add an ID to the element that contains all of the image thumbnails. This ID can be anything unique. For this example, we'll use "image-collection":

...


<div id="image-collection">
  ...
</div>

Next, we need to add a unique ID to each of the thumbnail <div> s. This ID must be of a specific form: it must start with the string that was used for the container ID, followed by "lightbox-cell:", a number indicating the index, and finally a ":". This is shown below for our example:

...


<div id="image-collection">
  <div id="image-collectionlightbox-cell:1:"><img src="img1.jpg"/></div>
  <div id="image-collectionlightbox-cell:2:"><img src="img2.jpg"/></div>
  <div id="image-collectionlightbox-cell:3:"><img src="img3.jpg"/></div>
</div>

I know this seems a bit complex, but in the real world, these IDs will be generated by the server, and you won't have to write them by hand.

Step 3 - Add initialization script

The third step is to actually create the Lighbox by calling the initialization script. This initialization function has the form

...


fluid.lightbox.createLightboxFromId (containerId, options);

The Lightbox initialization function allows you to pass in a number of optional parameters to configure some aspects of the Lightbox, including a 'callback' function. The callback communicates changes in the ordering of images back to the server. In its "out-of-the-box" form, the Lightbox includes a default callback function that uses a form with hidden <input> elements in the markup to record the indexes of the elements. For our example, we will disable the default callback by specifying an empty function as one of the optional parameters:

...


<script type="text/javascript">
  fluid.lightbox.createLightboxFromIds ("image-collection", { orderChangedCallback : function(){} });
</script>

Step 4 - Define styles

The final step is to create styles so that 'interesting moments' in the reordering of images are easily apparent to the user.

The Image Reorderer pre-defines a number of class names that will be used for this purpose. It's possible, through the optional configuration, to override these class names, but for this example, we'll just define styles for the default class names.

The first style is the default style to be applied to any image thumbnail. For our example, we'll float the images so that they appear to be in a grid, and give them a background colour:

...



.orderable-default{
    background-color: #eee;
    float: left;
}

The second style is applied to the element that has been selected. A visual indication will inform users that the thumbnail can be moved using keystrokes. For our example, we'll change the background colour:

...


.orderable-selected{
    background-color: #ddd;
    float: left;
}

The Image Reorderer also supports mouse-based drag and drop, and another style is used when the cursor hovers over a thumbnail, to inform users that the thumbnail can be moved using the mouse. For our example, we'll change the background colour again, but we'll use a different colour:

...


.orderable-hover{
    background-color: lightyellow;
    cursor: move;
    float: left;
}

When a thumbnail is in the process of being moved, either by keyboard or by mouse-based drag and drop, a 'dragging' style is applied to the thumbnail to indicate this. We'll change the background colour for this:

...


.orderable-dragging {
    background-color: lightyellow;
    float: left;
}

When the mouse is used to pick up a thumbnail and move it, an 'avatar' is created to represent the thumbnail being dragged. By default, the avatar is a copy of the item. A style is applied that can be used to modify the appearance of the avatar. For our example, we will make it semi-transparent:

...


.orderable-avatar {
    opacity: 0.55;
}

Finally, when the mouse is used to move a thumbnail, a 'drop marker' is displayed in the location where the thumbnail will end up if it is dropped. The last style is used to control what that marker looks like. We'll make it a vertical red bar:

...


.orderable-drop-marker{
    height: 10px !important;
    width: 4px;
    background-color: red;
    float: left;
}

...

<script type="text/javascript" src="../../../../framework/core/js/DataBinding.js"></script>
<script type="text/javascript" src="../../../../framework/core/js/FluidIoC.js"></script>
<script type="text/javascript" src="../../../../components/reorderer/js/ReordererDOMUtilities.js"></script>
<script type="text/javascript" src="../../../../components/reorderer/js/GeometricManager.js"></script>
<script type="text/javascript" src="../../../../components/reorderer/js/Reorderer.js"></script>
<script type="text/javascript" src="../../../../components/reorderer/js/ImageReorderer.js"></script>
<script type="text/javascript" src="image-collection.js"></script>

But all of these individual files are not necessary to make it work - the InfusionAll.js file has everything you need.

That's it! That's all you need to do to make your images reorderable!

...

Step 4: Apply styles

You can style your image gallery any way you choose (of course), or use the default Infusion Image Reorderer style.

Using the default styles

You can take advantage of the Image Reorderer styles provided with the component by simply adding the default styling class names to your markup. The Image Reorderer will take care of the rest.

There are three things you'll want to add styling classnames to:

  1. the reorderer container element, using fl-imageReorderer and fl-reorderer-horizontalLayout,
  2. the reorderable elements themselves, using fl-imageReorderer-item, and
  3. the captions, using fl-imageReorderer-caption.
Code Block
html
html

<form action="#" id="reorder-images-form" class="fl-imageReordererfl-reorderer-horizontalLayout">
    <a href="myImage1.jpg" class="flc-imageReorderer-item fl-imageReorderer-item">
        <img src="myImage1.jpg" alt="image 1 thumbnail" />
        <span class="flc-reorderer-imageTitle fl-imageReorderer-caption">Image 1</span>
        <input name="image 1" value="0" type="hidden" /> 
    </a>
    <a href="myImage2.jpg" class="flc-imageReorderer-item fl-imageReorderer-item">
        <img src="myImage2.jpg" alt="image 2 thumbnail" />
        <span class="flc-reorderer-imageTitle fl-imageReorderer-caption">Image 2</span>
        <input name="image 2" value="1" type="hidden" /> 
    </a>
    <a href="myImage3.jpg" class="flc-imageReorderer-item fl-imageReorderer-item">
        <img src="myImage3.jpg" alt="image 3 thumbnail" />
        <span class="flc-reorderer-imageTitle fl-imageReorderer-caption">Image 3</span>
        <input name="image 3" value="2" type="hidden" /> 
    </a>
    ...
</form>

The fl-reorderer-horizontalLayout will lay the images out horizontally, and will make sure that the drop marker shows up between the thumbnails properly.

Customizing the styles

If you choose to use CSS classname different than the defaults, you can override the defaults using the options parameter to the reorderImages() function.

Specify your classnames using the {[styles}} option, and the required style names:

Code Block
javascript
javascript

var opts = {
    styles: {
        defaultStyle: "myMovableImage",
        imageTitle: "myImageCaption"
    },
};
return fluid.reorderImages("#reorder-images-form", opts);

There are actually many styles used by the Reorderer, affecting how the thumbnails look when the cursor hovers over them, what the avatar looks like while it's being dragged, what the drop marker looks like, and more. For a complete list of styles, see the full technical documentation: Image Reorderer API.

...