- Simple: Once again, we try to make our plugins as easy to use as possible. This one is no exception: create a <div> with a number in it, call the script with this <div>'s ID, and ta-da, you have a fancy counter set on that number. Then to update the counter, you'll have to call a function, but it's quite easy.
- Can be updated manually or automatically: As you can see in the examples, the counter can be be updated manually (Demo 2) or you can set it so it periodically calls a server script via an AJAX request and uses the returned value as a new target. This is also easy, you just need to specify the URL to that script when you initialize the counter.
- Customizable refreshing period: If you are worried about bandwidth or your server's load, you can increase the wait between refreshes. If you're running a small website with little activity, you probably don't want to refresh the counter very often. However, if you are launching a new product to be downloaded by millions of users, with a special page counting the number of downloads live, you would probably set a shorter delay so that your users could see all the activity in real time.
- Detects client activity: If the visitor leaves his/her desk for a cup of coffee or even for a week long vacation, your server won't sit there sending updates to that client forever. Once the period since last refresh has expired, the AJAX call is not executed instantly, it waits for a trigger, which is... a mouse move! The counter will not refresh until the user moves the mouse. While it might sound like a restriction, if the user is actually using the website, it's not a problem. This just helps prevent unnecessary ajax calls to your server.
- Auto-expands when maxed out: You can set the number of displayed digits in the options. If the counter tries to display a bigger number than it can handle, it will not stay at 9999 or roll back to 0, it will add an extra column on the fly.
- Callback function: You can specify a function to execute when the counter reaches its target. While this is probably not necessary for an automatic counter, it might be useful if you use the counter with full controls.
- Uses container's HTML as starting value: When generating the document, if you put a number inside the element to receive the counter, this number will be used to initialize the counter. No need to start from 0 and then try to catch up 6 million (which might freeze the browser, see Know Issues).
- Cross-Browser Compatible: Tested in the major browsers: Firefox 2 & 3, Internet Explorer 6 & 7, Opera 9, Safari 3. All on Windows systems. We didn't get a chance to test on Mac or Linux. If anyone encounters any problems in other browsers/operating systems, please let us know. We only support real browsers -- No need to email us with IE4 or AOL issues because, well, we don't really care.
- Modify style: There is not much style in the counter, just one image used as background for each spinner. But this image defines the whole look of your counter, including the height and width, and you are welcome to use a different image if you like. You can either use the provided image, or create you own. Just take a look at the template included in the download package, it should help you get started.
- Modify animation: This one is a little complex: the counter has two speed properties, the starting duration and the cruise duration. the starting duration is pretty much how long the counter will take to reach full speed, and the cruise duration is the time taken to rotate from one number to the next. It takes testing to find the values you like, but can produce cool results.
- Animation can be skipped: if the difference between two values is too big and the counter is spinning for several minutes (that means you did not estimate the refresh rate correctly). You can directly jump to the targeted value by simply double-clicking on the counter. You might want to write this near the counter, because users will not guess it.
- Getter and setter: For advanced users, you can manually set the counter's value or retrieve it thanks to included functions.
What you'll need:
And yes, you actually do need version 1.2 of Mootools. If you are already using a previous version of Mootools then the Odometer will not work unless you upgrade. Sure, upgrading is a slight hassle, but trust us, it's worth it in the long run.
- Eventuallly a server-side script: Unlike other UvumiTools scripts which are mostly client-side only tools, UvumiTools Odometer must be paired with a server-side script if you use the auto-refreshing option. This script must return a integer and nothing more. If the returned value is not an integer, the counter will not crash, it will simply ignore it and not update.
Mootools Dependencies: If your website already contains some Mootools 1.2 stuff (from this wesite or elsewhere), then you're stoked because you can use a single Mootools library for everything. All you'll need is the UvumiTools Odometer script, and to make sure your library contains the following classes:
- FX.Transitions (optional)
- element: Can be the ID of an HTML element, or the element it-self, if grabbed the mootools way with the $() function. If you don't understand what it means, just pass the element's ID. The element should be a block element, preferably a <div>.
- Options: an object that will allow you to modify some properties of the script. Options are optional (of course). If you just want to keep default value, you don't need this second parameter.
- counterClass: This CSS class will be added to the counter container. This will allow you to style a few properties, like the the border or margin. Default is odometer. Style for this CSS class is already defined in the downloadable style sheet.
- digits: The number of digits to display in the counter, even if the value is lower. Default is 6. If the counter goes over it, new digits will automatically be added.
- image: Very important, the path to the image to use in the counter. If this is not set correctly, the whole script falls appart, so be careful. Default is css/odometer.gif which corresponds to the location of file included in the package.
- overlay: This one is a touch of fanciness. It added an transparent PNG over the counter, to simulate shadows and highlights. Default is css/overlay.png which corresponds to the location of the file included in the package.
- startDuration: Defines how long it takes to the counter to rech full speed, in milliseconds. Default is 1200 milliseconds.
- cruiseDuration: The time it takes to roll from one number to the next one, when at full speed. Default is 100 milliseconds.
- transition: Define the transition style of the animation. If you play with this one and the duration options you can get some cool effects, but generally slower to execute, so should be reserved for small counts. Default is linear. If you change this option, you must include the Fx.Transitions class to the mootools library (is inluded in the version you can download on this page).
- onComplete: Event function fired when the counter reached its target. Receives the current value as a parameter. By default, it's empty.
- url: The URL to the auto-refresh script (which must return a number). must be absolute or relative to the document. Default is false which means auto-refresh is disabled.
- refreshRate: How long the counter must wait before refreshing. The timer only starts when the previous animation is done. Default is 10 seconds.
- indicatorClass: When the counter is refreshing, a indicator is displayed next to the counter. This indicator receives a CSS class so you can style it the way you want. Default is loading which corresponds to the class already defined in the downloadable style sheet.
First, you simply import the files provided in the zip archive into your document. While you can insert <script> tags anywhere, we recommend you put them inside the <head> tag:
<link rel="stylesheet" type="text/css" media="screen" href="css/uvumi-odometer.css"/>
Then you must prepare the HTML code. You need one <div>. Let's just give it the ID "myCounter".
Then we initialize the odometer object with this div's ID. Don't forget to wrap the ID with quotes when passing it to the object (double or single, doesn't matter);
In the end, if we put everything together. Mootools requires a strict Doctype to work properly. Use something like this:
You should get something like this. A counter set to 0 and it does nothing. It has 6 digits because that's the default option.
Let's try to set a starting value. Just write a number inside the div. Let's say 3427 because it's my favorite number.
Alright, refresh your page (not this one, the one we are pretending to build). Now it says 3427. I like 3427.
Ok, it's great, but still not counting. We're going to set a URL to auto-refresh the counter. We just need to add this URL to the Odometer options when we initialize it. Here our script is called 'refresh-counter.php' and is located in the same folder as the document.
Now we have a counter that starts at 3427 and updates its value frenquently. If you loaded this page a while ago, refresh it if you want to see it start from 3427.
Ok, let's try other options: 4 digits, 3 seconds refresh rate
Now we're going to do more advanced stuff using manual controls. It's not that advanced for Mootools users, but for novices this part requires Mootools basics, like adding an event, calling object functions. Those are really basic procedures so we won't explain them here. To learn Mootools we recommand reading the Mootorials.
First, we are going to see the countTo() function.
We are going to create a counter with value 500, and a button that says "count to 600":
<button id="myButton" type="button" >Count to 600</button>
When we inialize the button, we're going to use default options (no refresh) and we're going to save the instance in a variable named 'counter'.
Saving the object in a variable is important so we have a way to access it later.
Next we add a click event to the button. Don't forget it must be placed inside a domready function.
Ok, so now we have it all set, we just need to replace the "..." with what we want the button to do when clicked. For this first example we said we wanted to test the counter's countTo() function.
We are just going to call that function with the value we want to count to: 600.
Try clicking the button :
Now we're going to see the setValue(), which set the counter directly to the passed value, without counting. Just replace countTo by setValue in the previous example (and eventually change the button so it says something different).
Finally, getValue(), returns the counter's value. If called when the counter is counting, the value returned is the final one, not the current. In the exemple we are just going to display the value in an alert dialog.
- No negative value: If the passed value is negative, the counter stop to zero for one obvious reason: there is no minus sign.
- Giant offsets: Because of its complexity, if you increase or decrease the counter by a large margin (like hundreds of thousands, or millions), the page might freeze for a while. This issue only happens if you try to have the counter jump too big of a gap between numbers, and is not related to big numbers in general. For example, counting from 20000000 to 20000100 won't be a problem, but counting from 1 to 500000 will probably cause a hiccup.
- 20080929 - Version 1.0.0: Initial release. Stable with Mootools 1.2