Eposic Archive: JavaScript Animated D6 Dice Roller Documentation, The D6 Class
This page is in the Eposic Archive. Web pages in the Eposic Archive are possibly out of date and will not be maintained, but are being retained for historical purposes. Thank you for visiting Eposic!
The D6 class is used to animate a single group of any number of d6 dice; it also generates the HTML code for the dice, and, optionally, a button which can be clicked to roll the dice. An optional callback mechanism allows you to capture the dice rolls and update your web page depending on the values of the rolls.
Number of dice to roll:
Links: Roll the Dice | Hide the Button | Change Button Label
There are several methods and properties defined in the D6 class, one of which is not documented here. The undocumented method is not intended for public access, but is used internal to the class. The methods documented below are all those intended to be accessed by a developer making use of the D6 class on a web page.
Moreover, the D6 class makes use of the D6AnimBuilder class, which is not documented. It is a method of the D6AnimBuilder class that actually generates the HTML code for the dice. The D6AnimBuilder does provide some capabilities beyond what the D6 class affords the developer. However, it is left as an exercise for the reader to study the D6AnimBuilder class and learn how to use it if you wish to do something more than the documented classes easily support.
The D6 class supports a single group of d6 dice, all of which are rolled simultaneously. The dice are all co-located on the page. If you need to use multiple groups of dice, or dice in various locations on the web page, you will need to use the D6Animator and D6AnimGroup classes.
All of the methods and properties of the D6 class are class methods and properties. This means that to call them, you do not instantiate an object of the D6 class. You merely call them directly from the D6 class. For instance, if you wish to call the roll method of the D6 class, the syntax for doing so is:
D6.roll();
Methods and Properties
- setBaseUrl(baseUrl) Class method
- dice(numDice, callbackFunction, callbackData, useImages, buttonLabel) Class method
- roll() Class method
- setButtonLabel(buttonLabel) Class method
- diceToShow(numDiceToShow) Class method
- quickRandom(base) Class method
- numDice Class property
- numDiceShown Class property
setBaseUrl(baseUrl)
Class Method: Sets the base URL for the dice image repository used by the D6 class.
Arguments:
- baseUrl - The URL to the directory where the dice images reside. Defaults to the empty string, which indicates that the images reside in the same directory as the web page. Optional
Description:
If your dice image repository is located in some directory other than the one where your web page is located, you need to call the setBaseUrl method to set the URL of the directory where the dice images reside. Refer to the discussion of the baseUrl class property of the D6Animator class for more details about the use of the baseUrl.
You should call the setBaseUrl method of the D6 class at most once. If you call this method, you must call it before you call the dice method, or it will have no effect.
dice(numDice, callbackFunction, callbackData, useImages, buttonLabel)
Class Method: Generates the HTML for the specified number of dice, and optionally, for a button that can be clicked to roll the dice.
Arguments:
- numDice - The maximum number of dice to be animated by the D6 class. If this argument is less than 1 or logically false, it defaults to 1. Optional, but required if any other arguments are supplied.
- callbackFunction - The function to be called each time the dice associated with the D6 class are rolled. If you do not supply an argument, a special no op function is used (which basically does nothing). Optional, but required if callbackData, useImages, or buttonLabel are supplied.
- callbackData - A variable or value you want to be passed to the callbackFunction when that function is called. If you do not supply an argument, the null value is used. Optional, but required if useImages or buttonLabel are supplied.
- useImages - A boolean value. If true, the D6 class uses images to animate the dice. If false, the D6 class uses ascii text to animate the dice. If you do not supply this argument, it defaults to true. Optional, but required if buttonLabel is supplied.
- buttonLabel - The label for the generated button used to roll the dice. If this argument has the value none, the button will not be created. If this argument is not supplied or is otherwise logically false, it defaults to the string Roll Dice. Optional
Description:
The dice class method of the D6 class is called in the location on your web page where you want the dice to appear. The first argument, numDice, indicates how many dice you want to appear, at most. However, you can use the diceToShow method to reduce the number of dice that are displayed at any given time.
The callback function you supply will be called each time the dice are rolled, whether that be by clicking the generated button or by calling the roll method (see below). The callback function is called after all the dice finish rolling. The function is called as follows:
callbackFunction(total, callbackData, results)
The callbackFunction that is called is whatever function you supply as the second argument of the dice method. The total argument of the callbackFunction is the total of all visible dice. The callbackData argument is the same value that you pass as the third argument of the dice method. The results argument is an array that contains as many elements as the maximum number of dice allowed (see the numDice class property). Each element of the results array is a number in the range 1 to 6.
The values in the results array are in the same order as the dice appear on the web page. Thus, the first element of the results array corresponds to the first die on the web page. If you wish only to examine the results for the visible dice, restrict your examination of the results array to the first X elements, where X is equal to the value of the numDiceShown class property.
No method is provided to allow you to change the callbackFunction or callbackData once you've called the dice method.
The JavaScript Animated D6 Dice Roller Tutorial walks through examples of the usage of the callback function.
roll()
Class Method: Rolls the dice associated with the D6 class.
Arguments:
None
Description:
The dice that are created by the dice method are not rolled automatically. To roll the dice, you have two options. The first option is to generate a button that will roll the dice when clicked. This button is generated if the fifth argument to the dice method is not the string "none". The second option is to programmatically call the roll method.
For example, if you wanted the dice to be automatically rolled when the web page loads, you can enter this line of code in your JavaScript (as is done in the example code in this web page):
window.onload = D6.roll;
Or you can call the method any where in your web page that you can call JavaScript from. For example, you could create a link using the javascript: protocol, such as this:
<a href='javascript:D6.roll(); void 0;'>Roll the Dice</a>
setButtonLabel
Class Method: Set the label of the dice rolling button, or hide the button from view.
Arguments:
- buttonLabel - The label for the button, or the keyword "none". Defaults to "Roll Dice". Optional
Description:
If you have a web page with a lot going on, and you want to change the label of the dice rolling button based on events happening on the page, you call the setButtonLabel class method to set the button's label to what you desire. If the argument is not supplied or is logically false, the string "Roll Dice" is used instead. If you pass the keyword "none", the button is made invisible. To make the button reappear, call the setButtonLabel method with any argument other than the keyword "none".
If you want more control over the dice rolling button than these class methods allow, you can always choose to create your own. If you do this, just hide the generated button by using the keyword "none" as the fifth argument of the dice method.
diceToShow(numDiceToShow)
Class Method: Displays the specified number of dice, up to the maximum number of dice allowed.
Arguments:
- numDiceToShow - The number of dice to display. This number may be as low as 0, to hide all the dice, or as high as the numDice class property, to show all of the dice. Defaults to 0 if not supplied. Optional
Description:
This method hides all the dice except the first numDiceToShow dice. The numDiceShown class property is updated to the number of dice that are still displayed.
quickRandom(base)
Class Method: Generate a number without animating it. Allows a number outside the range of 1 to 6 to be generated.
Arguments:
- base - The maximum value you wish to be generated. The generated value will be in the range of 1 to base. Optional
Description:
Generates a value without displaying an animation for it. The generated value will be in the range 1 to base. If base is less than 2, the returned value is always 1.
numDice
Class Property: The maximum number of dice allowed.
Description:
This is the maximum number of dice that can be rolled. This number is equal to the first argument of the dice method.
numDiceShown
Class Property: The visible number of dice, which can be as low as 0 or as high as the value of the numDice class property.
Description:
This is the number of dice visible, as set by the last call to the diceToShow method.
