Documentation: How To Use Widgets

skip window navigation skip this window

So What is a Widget, How can you use them (stand alone or within the whole system), What is the XSL for and how can I use just the Javascript.

What is a Widget

Really it is just a set of reusable code. This code can be any of:

Javascript
XSL
HTTP Resources such as Images, CSS or Flash

Each widget is designed to be used either stand alone or part of a larger system.

If we design a [[Widget_Picasaweb?]] which allows you to search and embed Picasa images into your site, then you should be able to use that Widget by itself, without depending on other parts of code. Or you can use it with other bits of code, like Widget Preview to allow a nicer looking preview.

But what is a Widget

Really a Widget is how to do something in HTML. Unlike direct implementations, Zaltana tries to define a standard set of HTML to do a task.

Classic example would be the Image preview widget. If you use a great implementation like Lightbox - you will need to set the 'rel' of each anchor / image of 'lightbox'. If on the other hand you use another great implementation like Lytebox - you will need to add a 'rel' of 'lytebox'. Then there are others that use 'class' and 'rel' together and yet more that use Flash like SlideShowPro.

Each of these require you to change your output. If you are using an application like Joomla, you can template it in there. Zaltana is designed to work across applications and static HTML, without the need to change that HTML.

So in the case of a slideshow we add some HTML that looks like this:

<div class="slideshow">
 <a class="preview" href="/demo/photo/teha.jpg">
  <img src="/z/image/thumbnail/demo/photo/teha.jpg"/>
 </a>
 <a class="preview" href="/demo/photo/dad.jpg">
  <img src="/z/image/thumbnail/demo/photo/dad.jpg"/>
 </a>
</div>

Just add a 'class' of 'slideshow' in a 'div' around your anchors. Or you can just add single popups, not grouped:

 <a class="preview" href="/demo/photo/teha.jpg">
  <img src="/z/image/thumbnail/demo/photo/teha.jpg"/>
 </a>

Implementations

The point then is to provide alternative implementations. The default for the anchor "preview" in the "basic" style is to just add a CSS Hover of the image. This is nice and simple, requires no javascript - but also has many downsides, not least of which is that all the images are all loaded.

A better way is to use one of the many nice javascript libraries - these are not only well designed, but also allow good fallback to standard links for non-Javscript. Graceful Fallback. The implementation in the main system is based on "Lytebox". See the Widget Preview using the various styles to really see the difference.

Why XSL

Each widget could be done in XSL or Javascrip, both or neither. But they are designed to do graceful fallback.

We have three ways to use Lytebox as the Preview Slideshow in Zaltana.

Modify Lytebox to use our Classes - not idea, who wants to maintain other peoples code
Modify Zaltana standard to use Lytebox class - definitely not, as you may not want to use Lytebox - you may prefer to use SlideshowPro but you don't want to keep modifying all your templates and static files to do so.
Use XSL to convert Zaltana HTML into Lytebox HTML - User sees a slight improvement in performance over Javascript below.
Use Javascript to convert Zaltana HTML into Lytebox HTML - Server sees improvement over running XSL on the server.

These last two are the desirable.

Using the Javascript, CSS and Images

(also the other static content run on browser side like Flash)

Each widget is designed so you should be able to use just any part. For example you could take just the images and CSS to integrate into your site. Or you could take a combination of the JS, CSS and Images.

Where possible the Javascript is designed to work by itself and not depend on other server side entries, or other javascript.

The exceptions:

Ext/YUI and other frameworks - sometimes it is just too hard to write all the Javascript to be stand alone. So Ext is used. Where possible it will be optional for some functionality - e.g. Picasa web integration will map Anchors to live queries only with Ext, but the Search call still works from Javascript directly.
Time and Materials - a project management way of saying, sometimes it is just easier in XSL than in Javascript.
Performance - Running lots of transformations on the Client side can be very slow. XSL is far faster and more efficient than processing the DOM with Javascript.
Co-dependence - some Widgets may depend on others being available within the XSL, or within the Javascript.

The Upside of Separate use

Zaltana is trying to bring together a large set of tools, but trying to reduce the coupling across the tools. If we add a Widget to Zaltana to show current Stock prices and have to write the necessary Images, Javascript and CSS to make this work - we want to make it so you can add just that into your site. It is like the CPAN (Perl archive) or PEAR (PHP archive) of whole widgets.

So please feel free to take and integrate any of the widgets standalone - see 'Standalone' sections of each Widgets.

The Downside of Separate Use

Two problems with Standalone or Separate use of Widgets:

Reduced power - not being able to do more advanced or simpler programming. E.g. depending on ExtJS or other Javascript libraries helps faster development, more reliable (not reinventing the wheel, and better testing across browsers), and faster user experience (if every widget had to have all functions self contained they would be very large).
Needing to move with the implementation - if the XSL for example changes the Zaltana HTML into something the Javascript Widget can use (e.g. Lytebox special use of rel="lyteobx[GroupID]") then you will have to do that directly in your code, unless there is a Javascript converter from Zaltana HTML into the specific implementation. This is not always a problem as some of the Javascript implementations already use the Zaltana HTML directly. Yet other Widgets may just be CSS and therefore easily reusable.