PLEASE NOTE: This requires some HTML knowledge and a good understand of CoReg tech.
Getting Started
Ideally, you should place your event handlers in to the Site Javascript file, and in the interests of reducing errors, the contents of your Site Javascript file ought to be wrapped in a jQuery function
$(function() {
// Your stuff here
});
Listening
Each event can be listened for using the following simple javascript code.
Example Listening for an event
$(document).on(sb.Events.EVENT_NAME, function (event, eventArgument1, ...) {
// Place your code to handle this event here
});
Triggering
You can emit the events yourself, although there are very few cases where you would want to. CONTENT_HAS_CHANGED is the most likely that you want to use.
Example Triggering an event
$(document).trigger(sb.Events.EVENT_NAME, eventArgument1, ...);
Available Events
Below is a list of all available events and examples of usage
sb.Events.ALL_QUESTION_BLOCK_CONTENT_LOADED
This event is emitted when the QuestionBlocks handler has finished loading the question block html.
Default Listeners
None
Example Usage
$(document).on(sb.Events.ALL_QUESTION_BLOCK_CONTENT_LOADED, function (event) {
// Do stuff here
});
sb.Events.COMPETITION_CAN_BE_ENTERED
This event is emitted when the FormHandler has determined that the current page is a competition form page, and is the result from the server endpoint as to whether the current user can enter the competition.
Parameters
canEnter
Can the user enter the current competition
reason
If canEnter == false, the reason the user can't enter the competition
Reasons
Reasons
ALREADY_ENTERED
The current user has already entered this competition
CLOSED
The competition is now closed for entries
NOT_FOUND
The server was unable to find the competition specified by the form
NOT_YET_OPEN
The competition is not yet open for entries
Default Listeners
None
Example Usage
$(document).on(sb.Events.COMPETITION_CAN_BE_ENTERED, function (event, canEnter, reason) {
// Do stuff here
});
sb.Events.COMPETITION_FORM_HIDDEN_ENTERED
This event is emitted when the FormHandler has determined that the current page is a competition form page, and that the fieldset should be hidden because the user has previously entered this competition.
Parameters
fieldsetWasHIidden
Was the fieldset in the competition hidden
Default Listeners
None
Overriding Default Behaviour
This event will always pass fieldsetWasHidden as true, unless you override the default behaviour. Which can be done by adding an attribute to the form tag
data-db-hide-entered="false"
Causes the form handler to not hide the fieldset of the competition form.
Example Usage
$(document).on(sb.Events.COMPETITION_FORM_HIDDEN_ENTERED, function (event, fieldsetWasHIidden) {
// Do stuff here
});
sb.Events.COMPETITION_FORM_HIDDEN_LOGGED_IN
This event is emitted when the FormHandler has determined that the current page is a competition form page, and that the fieldset should be hidden because the current user has registered.
Parameters
fieldsetWasHIidden
Was the fieldset in the competition hidden
Default Listeners
None
Overriding Default Behaviour
This event will always pass fieldsetWasHidden as true, unless you override the default behaviour. Which can be done by adding an attribute to the form tag
data-db-hide-logged-in="false"
Causes the form handler to not hide the fieldset of the competition form.
Example Usage
$(document).on(sb.Events.COMPETITION_FORM_HIDDEN_LOGGED_IN, function (event, fieldsetWasHIidden) {
// Do stuff here
});
sb.Events.CONTENT_HAS_CHANGED
This event is emitted when the page content is deemed to have changed, such as when the submit button changes on a Competition form, or a Question Block has been shown on a page.
Parameters
elementThatHasChanged
The element that has changed, if omitted applies to whole document
Default Listeners
Localization
The element that has changed, if omitted applies to whole document
UserHandler
Updates any elements of user content, ie having attribute of data-*="USER.field"
Example Usage
$(document).on(sb.Events.CONTENT_HAS_CHANGED, function (event, elementThatHasChanged) {
// Do stuff here
});
Example Usage when triggering
$(document).trigger(sb.Events.CONTENT_HAS_CHANGED, myElementVariable);
sb.Events.FORM_IS_COMPETITION
This event is emitted when the FormHandler has changed its ability to submit a form. This will occur when the page is fully validated, including all the required fields.
Parameters
enabled
Is submission enabled.
Default Listeners
None
Example Usage
$(document).on(sb.Events.FORM_SUBMISSION_ENABLED, function (event, enabled) {
// Do stuff here
});
sb.Events.FORM_SUBMISSION_ENABLED
This event is emitted when the FormHandler has changed its ability to submit a form. This will occur when the page is fully validated, including all the required fields.
Parameters
enabledIs
submission enabled.
Default Listeners
None
Example Usage
$(document).on(sb.Events.FORM_SUBMISSION_ENABLED, function (event, enabled) {
// Do stuff here
});
sb.Events.HIDING_QUESTION_BLOCK
This can be used to run code before the question block is hidden. Usually this is used to animate hiding the question blocks in a more stylised way.
The handler code should be placed on the co-reg page, if not part of the Site Javascript.
Parameters
selectorString Selector
string for the element to be hidden
container
Container to which the selector is relevant
Default Listeners
None
Overriding Default Behaviour
The Sharebowl code will not try and hide the QuestionBlock if jQuery determines the element to be animated, or already hidden. This code must return true in order for the Question Block component to not hide it.
container.find(selectorString).is(':animated')
Example Usage
$(document).on(sb.Events.HIDING_QUESTION_BLOCK, function (event, selectorString, container) {
container.find(selectorString).slideUp()
});
sb.Events.HIDING_QUESTION_BLOCK_QUESTION
This can be used to run code before the question block question is hidden. Usually this is used to animate hiding the question block questions in a more stylised way. The event also includes the name of the field to be hidden.
The handler code should be placed on the co-reg page, if not part of the Site Javascript.
Parameters
selectorString
Selector string for the element to be hidden
container
Container to which the selector is relevant
Default Listeners
None
Overriding Default Behaviour
The Sharebowl code will not try and hide the QuestionBlock if jQuery determines the element to be animated. This code must return true in order for the Question Block component to not hide it.
container.find(selectorString).is(':animated')
Example Usage
$(document).on(sb.Events.HIDING_QUESTION_BLOCK_QUESTION, function (event, selectorString, container) {
container.find(selectorString).slideUp()
});
sb.Events.QUESTION_BLOCK_REMAINING_COUNT
This event is emitted by default on 'new' Thank You pages, and provides the number of remaining question blocks to the user.
Parameters
remaining
Number of question blocks remaining for user to answer
total
Total number of question blocks available to be answered on site
Default Listeners
None
Example Usage
$(document).on(sb.Events.QUESTION_BLOCK_REMAINING_COUNT, function (event, remaining, total) {
console.log('There are ' + remaining + ' question blocks out of a total of ' + total);
});
Manually triggering the Event
sb.QuestionBlocks.getRemainingCount();
The above function call takes an optional parameter, which is a function, that has the same parameters as the event. The function will be called immediately prior to the event being triggered.
sb.Events.SHOWING_QUESTION_BLOCK
This can be used to run code before the question block is shown. Usually this is used to animate hiding the question blocks in a more stylised way.
The handler code should be placed on the co-reg page, if not part of the Site Javascript.
Parameters
selectorString
Selector string for the element to be hidden
container
Container to which the selector is relevant
Default Listeners
None
Overriding Default Behaviour
The code will not try and show the QuestionBlock if jQuery determines the element to be animated, or already hidden. This code must return true in order for the Question Block component to not hide it.
container.find(selectorString).is(':animated')
Example Usage
$(document).on(sb.Events.SHOWING_QUESTION_BLOCK, function (event, selectorString, container) {
container.find(selectorString).slideOut()
});
sb.Events.SUBMIT_RESPONSE
This event is emitted by the FormHandler, having received a successful response from submitting a form and when the form is valid.
Parameters
formId
The id of the form that was submitted
responseData
The response object returned from the server
Response Data
The responseData object parameter contains the response from the server, which will likely take the following format
data
Object containing form data returned form server
nextUrl
Complete URL Where the server was going to redirect you
flowNodeId
The id of the flow node
Default Listeners
None
Example Usage
$(document).on(sb.Events.SUBMIT_RESPONSE, function (event, formId, responseData) {
// Do stuff here
});
sb.Events.USER_DATA_RECEIVED
This event is emitted when Sharebowl has attempted to determine if the current user is logged in.
Parameters
userData
false, or the userData object
Default Listeners
None
Example Usage
$(document).on(sb.Events.USER_DATA_RECEIVED, function (event, userData) {
if (!userData) {
// not logged in
} else {
// Is logged in
}
});