Skip to content

Sqwidget Tutorial

Jump to bottom Edit New page
grasuth edited this page Nov 11, 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 more complex and more 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 makes a place 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:widget-source-file.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 source from spec.html and use that to populate this div with the spec.html widget.

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

The widget source 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>. Simple, and not terribly useful.

Inserting an HTML snippet

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

and the specification file looks like this:

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

This inserts the given html snipped into the embed <div>. This is useful for putting a bit of html from one place into another.

A full html document specification

The embed code still looks the same:

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

And the specification contains multiple parts, including widget css, a default template, and some controller JavaScript:

<!DOCTYPE html>
<html>
    <head>
        <style>
            #mywidget {
                font-size:1.2em;
                font-family:sans-serif;
                color:#336;
            }
            #mywidget li {
                padding:0.5em;
                list-style:none;
                width:10em;
            }
            #mywidget .r {background-color:#fcc;}
            #mywidget .g {background-color:#cfc;}
            #mywidget .b {background-color:#ccf;}
            #mywidget .black {background-color:#333; color:#fff;}
        </style>
    </head>
    
    <body>
        <div id=mywidget>
            <strong>Colours</strong>
            <ul id=colours>
                <li class=r>red</li>
                <li class=g>green</li>
                <li class=b>blue</li>
            </ul>
        </div>
        
        
        <script>
            document.getElementById("colours").innerHTML +=
                "<li class='black'>black</li>";
        </script>
    </body>
</html>

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

Add a custom sidebar
Clone this wiki locally