To load the lucky wheeler Javascript library please insert the following line once in your html site:
<!-- lucky wheeler javascript -->
<!-- include this line anywhere in document -->
<script type="text/javascript" src="http://www.your.url.com/your/path/wheel.js"></script>
<!-- / lucky wheeler javascript -->
The wheel then can be initialized in two ways:
For this approach simply the following must be inserted into the HTML document
<script type="text/javascript">
var my_options = {
// options are explained below
};
wheel_create_here('My Rotate Button Label',my_options);
</script>
Thereby a lucky wheel is created exactly in the position where the code is inserted. Along with the wheel a rotate button having the label My Rotate Button Label is created.
In case you want to apply custom styling to your Lucky Wheel (eg. define specific positioning) then you can use the second approach where you set the div anchor and buttons as desired, eg as follows:
<div id="my_wheel_id"></div>
<button id="my_rotate_button_id">My Rotate Button Label</button>
.. and initialize the wheel (add the code AFTER the HTML!) as follows:
<script type="text/javascript">
var my_options = {
// ... options explained below
};
new Wheel('my_wheel_id','my_rotate_button_id',my_options);
</script>
Wheel options are as follows, explained inline:
{
// Number of possible throws before the dice (and buttons) are deactived.
/
// Number of possible throws before the dice (and buttons) are deactived.
// Optionl, default = 0.
// 0 infinite throws / dice will never be deactivated
// or if a result_set is given, will be thrown exactly the remaining
// number of throws considering the first_throw_nr
// N > 0 exactly N throws
// ATTENTION: if a result set is given aswell as a first_throw_nr and the
// total throw count can grow highger than the result_set count, the drawn
// results will be drawn according to the fallback_strategy.
//
possible_throws: 0,
// Fallback strategy to use, if for a given result set and an expected
// number of results, there are too few results given.
// Optional, default: wrap-around. Possible values:
// 'wrap-around' Drawing will begin from the first given result again
// 'random' A random result according to the given probabilities will be drawn.
fallback_strategy: 'wrap-around',
// List of all possible values and their probablities.
// Required.
// The probabilities will be normalized, ie actual probability = given probability / sum of all probabilities
// The key property is used both to identify the result and is passed to the callback function.
// The description property is shown in the middle of the wheel for a result.
// The color_img property denotes the color image to be used (if you have three alternating colors
// set the property as follows)
// The label_img property denotes the label image holding the correct graphics for a result
// NOTE: the images are used for browsers not supporting any rotation
value_set : [
{key: "1", probability: 1, description:'do this', color_img:'color-1.jpg', label_img:'label-1.png'},
{key: "2", probability: 1, description:'do that', color_img:'color-2.jpg', label_img:'label-2.png'},
{key: "3", probability: 1, description:'dont do this', color_img:'color-3.jpg', label_img:'label-3.png'},
{key: "4", probability: 1, description:'dont that', color_img:'color-1.jpg', label_img:'label-4.png'},
{key: "5", probability: 1, description:'do this?', color_img:'color-2.jpg', label_img:'label-5.png'},
{key: "6", probability: 1, description:'do that?', color_img:'color-3.jpg', label_img:'label-6.png'}
],
// List of predefined result keys
// Optional
// If given the dice can automatically only be thrown as many times as there are given keys.
// Can take two forms, the values must be strings as used for keys in the value set, otherwise an error occurs:
// Form 1 : array of keys
result_set: ['1','2','1','2'],
//Form 2: Comma separated (string) list
result_set: '1,2,3,4,5,6',
// Index (starting at 0) of result_set keys to use for this sequence.
// Optional (default = 0), natural number incl. zero.
// Static example, in this case '3' would be the first result
first_throw_nr: 2,
// Generic image settings
// Required
images : {
// Base URL of the base folder where your images reside.
// Required.
// MUST have a trailing slash
base_url : 'http://www.your-domain.com/your/image/path/',
// Size of images
// Required.
// Images will be scaled to this size, required for positioning
img_size : 400,
// Arrow image to use (should be pointing at topmost field.
// Optional.
select_img: : 'init.png'
},
// Callback function to handle results
// Optional
// Will be called at each rotation/throw.
// Passed arguments is the rotation/throw number (inclusive this throw, it will be the n-th one)
// and the result key as defined in value_set.
result_callback: function(throw_nr, result_key){
// your handling here
},
// Callback function to be called upon permanent deactivation of wheel
// Optional
finished_callback: function(){
// your function here
}
};
The lucky wheel structure is identical to the dice structure in terms, ie to handle the result the optional result_callback-option is used. Ergo the wheel can be set up in the same way as the dice, ie either using embedded variables [Variant 1] or additional questions that may or may not be hidden [Variants 2,3].
Saving results through the result callback
// Instantiate the wheel either within the question text (inserted as HTML)
// or within the Javascript block associated with the according question.
new Wheel('wheel','rotate',{
... your other options here ...
result_callback: function(throw_nr,result_key){
// Variant 1 (No Requirement)
// Save result to embedded data field (need
// not be set through survey flow settings)
Qualtrics.SurveyEngine.setEmbeddedData('result_matrix_embedded'+throw_nr, result_key);
// Variant 2 (Requirement: in Javascript block)
// Set choice by result key, choice index respectively
// Attention: choices must be in correct order (ie choice 1 must have value 1, etc)
self.setChoiceValue('1', result_key, true);
// Variant 3 (Requirement: in Javascript block)
// should you use only 1 dice that can be thrown multiple times
// you can use <throw_nr> instead of the predefined '1'
self.setChoiceValue(throw_nr,result_key,true);
}
});
To generate an image set with all required images you can use the following form.
To keep the overall required number of files (and download sizes) small, it is recommended to use as few colors as possible.
Requirements for form to work: files on webserver with PHP (Extensions: Zip, Imagick)
Wether authorization for image generation is required is set at the beginning of the wheel.php file,
where you also can choose your favourite username/password combination.