Important Note: Be sure to use CB 3.3.3 (Joomla/Wordpress) or CB 3.3.21 (Magento 2) to make use of this article. It uses the latest recommended functions (deprecated functions are upwards compatible).
The question type object provides callback functions for the various events that happen while a user configures a product.
Create the file [customization_assets_dir]/javascript/custom_questions.js. CB will automatically load this file if present (or a min.js file if present).
A JS Question Type Object (a plain JavaScript object) with a set of functions. and pass it as a parameter the function registerQuestionType() of the ConfigBox AMD module configbox/configurator.
Example custom_questions.js
define(['cbj', 'configbox/configurator'], function(cbj, configurator) {
// Custom question type object
var customType = {
// .. set of methods to implement (see below on this page)
}
// Replace Name_of_your_type with your type name
configurator.registerQuestionType('Name_of_your_type', customType);
}); |
In this file you can register any number of question types.
init() - will run on page load and the function needs to initialise any JS-powered content in the question
initEach() - will run on page load AND each time the configurator view gets refreshed via AJAX calls
onSystemSelectionChange(event, questionId, selection) - runs when the system changes a selection (auto-selects, selection removals from rule engine, etc). If the variable selection is null, it means deselection.
onQuestionActivation(event, questionId) - runs when the rule engine activates the question
onQuestionDeactivation(event, questionId) - runs when the rule engine deactivates the question
onAnswerActivation(event, questionId, answerId) - runs when the rule engine activates an answer of the question
onAnswerDeactivation(event, questionId, answerId) - runs when the rule engine deactivates an answer of the question
onValidationChange(event, questionId, validation) - runs when the validation engine alters validation settings for the question (calculation based min/max values)
onValidationMessageShown(event, questionId, message) - runs when the engine instructs to show a validation message for the question
onValidationMessageCleared(event, questionId) - runs when the engine instructs to hide a validation message for the question
Full example
define(['configbox/configurator'], function(configurator) {
var customQuestionType = {
/**
* Will run on page load and the function needs to initialise any JS-powered content in the question
*/
init: function() {
},
/**
* Will run on page load AND each time the configurator view gets refreshed via AJAX calls
*/
initEach: function() {
},
/**
* Runs when the system changes a selection (auto-selects, selection removals from rule engine, etc)
* @param {Event} event
* @param {Number} questionId
* @param {String|NULL} selection - NULL on deselect, the internal selection value for the answer instead
*/
onSystemSelectionChange: function(event, questionId, selection) {
},
/**
* Runs when the rule engine activates the question
* @param {Event} event
* @param {Number} questionId
*/
onQuestionActivation: function(event, questionId) {
},
/**
* Runs when the rule engine deactivates the question
* @param {Event} event
* @param {Number} questionId
*/
onQuestionDeactivation: function(event, questionId) {
},
/**
* Runs when the rule engine activates an answer
* @param {Event} event
* @param {Number} questionId
* @param {Number} answerId
*/
onAnswerActivation: function(event, questionId, answerId) {
},
/**
* Runs when the rule engine deactivates an answer
* @param {Event} event
* @param {Number} questionId
* @param {Number} answerId
*/
onAnswerDeactivation: function(event, questionId, answerId) {
},
/**
* Runs when the validation engine changes validation for a question
* @param {Event} event
* @param {Number} questionId
* @param {Object} validation - plain object with vars minval and maxval
* values of each are either NULL for no validation or a number
*/
onValidationChange: function(event, questionId, validation) {
},
/**
* Runs when the engine instructs to show a validation message
* @param {Event} event
* @param {Number} questionId
* @param {String} message - Plain text message to display
*/
onValidationMessageShown: function(event, questionId, message) {
},
/**
* Runs when the engine instructs to remove a validation message
* @param {Event} event
* @param {Number} questionId
*/
onValidationMessageCleared: function(event, questionId) {
}
}
// Now we register the custom question type to the configurator engine
configurator.registerQuestionType('customtype', customQuestionType);
}); |
Important note: Upgrade to CB 3.3.3 (or CB 3.3.12 for Magento 2). In prior versions you needed to check if the event actually concerns the given question type:
var customQuestionType = {
onValidationMessageShown: function(event, questionId, message) {
// Checks if the validation message is for 'customtype' questions and ignores
// the event if not
if (cbj('#question-' + questionId).is('.type-customtype') === false) {
return;
}
}
//.. other methods
configurator.registerQuestionType('customtype', customQuestionType);
}
|
Compare with built-in question type JS Objects which are located in [applicaton assets folder]/javascript/questions.js.
There is a number of JS framework functions to support coding question types. See this article for the most useful methods.