Welcome to the wonderful world of MrSite widgets. Using the SDK, you've got plenty of scope to create something awesome for yourself, or for users that download your widget. It's important to remember to make your own documentation for each widget that you produce, and it goes without saying that the easier you make it, the more beneficial it is for everyone.
This documentation assumes that you're at an intermediate level in and JavaScript.
Editables for widgets are built with the same functionality as editables for themes, however the application is a little different. Before we get stuck into using editables and getting them to talk to your widget, let's run through what's available.
Add a textbox editable to your widget, perfect for when you need the user to enter some custom text.
Initial settings: Key, Visible name, Default value
Add a textarea editable to your widget. Useful if you need your user to add more text than what a text box gives.
Initial settings: Key, Visible name, Default value
Add a rich textarea editable to your widget. The rich textarea displays a TinyMCE editor.
Initial settings: Key, Visible name, Default value
Add a slider editable to your widget. Sliders give the user a ranged selection, based on the minimum and maximum values that you add to the initial settings. Remember to set a default value so that the slider has a starting point in the range.
Initial settings: Key, Visible name, Min, Max, Default value
Dropdown box editables present the user with defined choices for your widget. You can either select to show products, categories, pages, polls or create a custom dropdown box.
Initial settings: Key, Visible name, Values: {"Products", "Categories", "Pages", "Polls", "Custom"}
Using Custom will let you add custom Key and Value options to the dropdown.
By adding the images editable, users can choose to upload or select images from the image gallery, and insert them into the widget. Each gallery item or photo also has settings for a Title, Description and Hyperlink.
Initial settings: Key, Visible name, Default value
By adding the gallery editable, users can choose to upload or select images from the image gallery, and insert them into the widget. Each gallery item or photo also has settings for a Title, Alt tag.
Initial settings: Key, Visible name, Default value
The colour editable presents a colour picker to the user.
Initial settings: Key, Visible name, Default value
The preview button allows you to preview your widget inside of the administration panel, just as the customer would see it when building their page.
One of the files included with your new widget is the Meat. The Meat is the file that we use to present the widget on the users website, so any markup that you use in this file will show up once the widget is dropped onto a page. We'll wrap up your widget in a wrapper ID, giving it it's own instance on the page.
<script>
(function(settings) {
$(function() {
var $wrapper = $('#' + settings.wrapperId);
var $widget = $wrapper.find('.myWidget');
});
})(MrSite.Widget.getSettings());
</script>
The markup for your widget:
<div class="myWidget">
//widget code goes in here
</div>
Okay, so you're ready to get stuck into making your new widget awesome. Lets start of by adding a Textbox only as your first editable. Below is an example of what you might write into the initial settings for this editable.
Initial settings: Key: mytextbox, Visible name: Enter something cool, Default value: hello world
Now, as we have an initial value for this textbox, we can grab this value and display it on our website. Firstly though, make sure you've added your newly authored widget to a page, and you've saved and published.
Note: You don't need to publish if you're using Seller, Pro Seller or Pro Seller Plus.
<script>
(function(settings) {
$(function() {
var $wrapper = $('#' + settings.wrapperId);
var $widget = $wrapper.find('.myWidget');
var $myTextbox = settings.mytextbox;
$('.myWidget').append($myTextbox);
});
})(MrSite.Widget.getSettings());
</script>
<div class="myWidget">
'Hello world' will go in here.
</div>
If you've added the image editable to your widget, then you'll need to use a template for grabbing those images and displaying them on your website. There are a few templating options out there, but for this example we'll use jQuery.tmpl. If you need to use external scripts or CSS in your widget, you can add them by dragging and dropping the .js file into the Assets area under Settings for that widget.
In this example, we'll add an images editable with the following settings: Key: myimages, Visible name: Choose an image, Default value: myimages
<script>
(function(settings) {
$(function() {
var $wrapper = $('#' + settings.wrapperId);
var $widget = $wrapper.find('.mySlideshow');
$widget.find('script.slideshow').tmpl(settings).appendTo('.myGallery');
});
})(MrSite.Widget.getSettings());
</script>
<div class="mySlideshow">
<script class="slideshow" type="text/x-jQuery-tmpl">
{{each(i,item) myimages}}
<img class="myImage" src="${item.url}" />
{{/each}}
</script>
<div class="myGallery">
//My images go in here
</div>
</div>
You can also grab the other settings from the array, by adding ${item.title} or ${item.url} into the template area of your widget.