On this page
Every snippet is automatically editable by SiteGUI editor, i.e: their content and images can be updated by the users if they want. However this does limit template designers' creativeness, those who want template users to have more control over their snippets may utilize Javascript callbacks for updating snippet's content and layout as they see fit.
Snippet using custom JS callbacks should register its function by providing the function code inside the snippet's content. Snippet can use sgScript.register global function to register its function, the function should take 2 parameters: element (el) and stage which will be injected by SiteGUI editor when the callback is executed. Put the code inside a <script> tag and set that tag's class to "register" so the code will be excluded when adding snippet to a page (page does not need it).
<script type="text/javascript" class="register">
sgScript.register((el, stage) => {
if (stage == 'pre') {
//do something
}
}
</script>
Snippet's callback function is executed whenever the snippet is added to a page. The callback function will receive 2 parameters, the first one is the added block wrapper element containing the snippet's content, and the second one is the stage which is set to "init".
Whenever the user edits the snippet, the callback function will be executed, the parameters are the same but the stage is set to "pre", i.e: pre-editing, executed before the user actually edits the snippet. When the user adds or removes snippet's content, this stage is executed again to keep track with the change in the snippet's content.
Finally, when the user finishes editing the snippet and clicks on the "Done" button, the post-editing stage will be executed, the callback function will receive the same parameters which is the block wrapper element containing edited snippet's content and stage set to "post".
By using stage, snippet may register one callback function that can handle each stage as needed.
Snippet's callback function often wants to add custom controls to the editor's sidebar at the left side to allow users to manage the snippet. SiteGUI editor provides a helper function for that, simply create the control element, set event listeners on it and then use sgEditor.addSidebarElement() function to add the control element to the sidebar, the first parameter is the control element and the second parameter can be set to "true" to prepend the element at the top instead of the default appending at the bottom of the sidebar.
Here is an example of a callback function that allows users to align snippet's content left, center or right.
<script type="text/javascript" class="register">
sgScript.register((el, stage) => {
if (stage == 'pre') {
//add is the control element to allow user to adjust alignment
var add = $('<div class="btn-group btn-group-sm mb-2 w-100" role="group"><input type="radio" class="btn-check" name="btnradio" id="align-button1"><label for="align-button1" class="btn btn-left btn-outline-secondary">Left</label><input type="radio" class="btn-check" name="btnradio" id="align-button2"><label for="align-button2" class="btn btn-center btn-outline-secondary">Center</label><input type="radio" class="btn-check" name="btnradio" id="align-button3"><label for="align-button3" class="btn btn-right btn-outline-secondary">Right</label></div>');
add.on('click', '.btn-left', function() {
el.find('.sg-block-content').addClass('text-start').removeClass('text-center text-end');
}).on('click', '.btn-center', function() {
el.find('.sg-block-content').addClass('text-center').removeClass('text-start text-end');
}).on('click', '.btn-right', function() {
el.find('.sg-block-content').addClass('text-end').removeClass('text-center text-start');
})
sgEditor.addSidebarElement('<label class="form-label">Align</label>');
sgEditor.addSidebarElement(add);
}
});
</script>