Skip to content

Sqwidget Tutorial

Jump to bottom Edit New page
Graeme Sutherland edited this page Nov 10, 2010 · 18 revisions

This tutorial leads you through all that is need to get started working with Sqwidget to build you own easily-deployable widget. We begin with a very simple embedded block of text and move all the way through to something a lot more complex and useful.

But first, a little bit of architecture of Sqwidget will help you work out what we are trying to do.

A Sqwidget widget is put in a page using a small piece of html embed code that contains a <div> element that the resulting widget will be put into, and a <script> element to load sqwidget.js, Sqwidget's core code. So, you need to put this embed code on any page where you want your widget to appear.

Here's the simplest possible embed code:

    <div data-sqwidget="src:spec.html"></div>
    <script type="text/javascript" charset="utf-8" src="sqwidget.js"></script>

How does this work? Well, once sqwidget.js is loaded it arranges to load jQuery for itself. Then, once the DOM is settled, sqwidget code is executed that goes and looks for any divs in the page that have a data-sqwidget attribute. In this case, the data-sqwidget attribute is set to src:spec.html. This tells sqwidget to load the widget specification file from spec.html and use that to populate this div with the spec.html widget.

So, what is a widget specification and how does it work?

A widget spec can be:

  • a plain text document
  • a snippet of html
  • a full html specification file, which can include:
    • a default template in the html <body> which is rendered into the widget
    • <style> elements in the <head> that are added to the destination page
    • JavaScript <script> elements that are configuration or widget controller code
    • Templates contained in <script type="text/template"> elements

So, let's start at the simplest and work up to a complex example.

Hello World

The simplest widget is a text string that can be embedded somewhere else. The embed code looks like this:

        <div data-sqwidget="src:helloworld.html"></div>

and the specification file looks like this:

hello world

The result here is that the string 'hello world' is embedded into the embed <div>.

Inserting an HTML snippet

        <div data-sqwidget="src:helloworld.html"></div>

and the specification file looks like this:

<strong>Colours</strong>
<ul>
    <li>red</li>
    <li>green</li>
    <li>blue</li>
</ul>

The simplest example

Here's probably the simplest widget specification:

<!doctype html>
<html>
<head>
    <title>text sqwidget</title>
</head>
<body>
    <p><strong>This is a sqwidget widget</strong></p>
</body>
</html>

Because the default behaviour of Sqwidget is to display the body section of the specification in the div as the widget, this widget does nothing but display This is a sqwidget widget.

You can find this example in the sqwidget repository at samples/tutorial/part1/index.html.

I have used it on my website Sell tickets online No Fee

Add a custom sidebar
Clone this wiki locally