Linden Lab Official:Viewer Web Widgets

NOTE: This is an official Second Life API provided and documented by Linden Lab. Its use is subject to the API Terms of Use.

Important: Work-in-progress! Expect these widgets to change over time. Watch this page for updates.

These viewer web widgets are a first attempt at making the current Second Life Viewer login screen features available for easy use in third-party viewers. Linden Lab provides a base Javascript library that searches the DOM of a given page, populating specifically-named divs with widget content.

Basic implementation

The example below shows the simplest way to implement these widgets. Simply include the sl.widgets.js library, then include a div with both id="[the widget you want]" and class="second-life-widget".

   <head>
       <script type="text/javascript" src="http://lecs-viewer-login-agni.s3.amazonaws.com/pubwidgets/v1/modules/sl.widgets.js">
       </script>
   </head>
   <body>

   </body>

</html> </html4strict>

Version 1 of the main sl.widgets.js library currently lives here:

http://lecs-viewer-login-agni.s3.amazonaws.com/pubwidgets/v1/modules/sl.widgets.js

This library will pull in all the supporting content it needs -- other Javascript files, CSS, and the content for each widget. It uses its own version of jQuery, and will create a separate namespace to avoid conflicts if you already have jQuery installed.

Widgets

Widget Options

Each widget has 2 configuration options that can be passed to it.

The number of items a particular widget can have.
The callback javascript function that needs to be called when someone clicks the particular event/item inside the widget.

All configuration is passed to widgets through a global javascript variable called - slconfig. It's a javascript object which further contains individual configuration object for each widget. Below is an example of setting some options to what's what now widget.

var slconfig = {}; slconfig['whatshotnow'] = {

   itemsPerPage : 4,
   onclick: localClick

};

function localClick(stuff){

   alert(stuff);
   return false;

}

</script> </html4strict>

In the above code we do couple of things.

Define a global javascript object called slconfig.
Set the config object for what's how not widget. This needs to be called 'whatshotnow'. For other widgets please refer below sections.
We also set onclick functionality. We are setting it to a localClick function which is defined later in the code. Please make sure you don't add () next to the function name as it would result in calling the function which we don't want. We just need to set the function name.
The local function gets passed slurl of the event or destination.

Widget Size Precedence

Items per page
Width defined in css

When items per page is passed, the widget resizes to fit those number of items. It won't take into consideration whether the widget fits the container or not. When the items per page isn't passed - the size of the widgets is taken from the css file. This again has an order. By default all widgets use Second Life widgets css, and can be over-ridden by your local css file or inline css.

What's hot now

This widget displays a thumbnail list of destinations with people (a population of 25 or less, in the last ~10 minutes). The cutoff number may change over time; 25 was chosen as a reasonable performance threshold.

With the main js library loaded, include this div in your html markup:

<div id="whats-hot-now-widget" class="second-life-widget"></div>

This widget expects the above div to be a fixed height of 148px. It will adapt its content to 100% of the div's width, so you can make it as wide as you like. To control positioning, size, and other parameters, just style the #whats-hot-now-widget in your own page's CSS.

This widget takes 2 options. It needs to be set in slconfig['whatshotnow'] object. Below are the options.

itemsPerPage - the number of items in the widget per page.
onclick - a javascript function which needs to be called when an item in this widget gets clicked. The javascript function is called back with the clicked item slurl. When this option is set, the overlay which usually shows up is cancelled.

Destinations

This widget displays a thumbnail list of destinations from a category. The default category is 'Featured Events'. It can be changed from the select box in the widget. The maximum number of destinations shown is 24.

With the main js library loaded, include this div in your html markup:

<div id="destinations-widget" class="second-life-widget"></div>

This widget expects the above div to be a fixed height of 148px. It will adapt its content to 100% of the div's width, so you can make it as wide as you like. To control positioning, size, and other parameters, just style the #destinations-widget in your own page's CSS.

This widget takes 2 options. It needs to be set in slconfig['destinations'] object. Below are the options.

itemsPerPage - the number of items in the widget per page.
onclick - a javascript function which needs to be called when an item in this widget gets clicked. The javascript function is called back with the clicked item slurl. When this option is set, the overlay which usually shows up is cancelled.

Localization

Widget strings can be localized by adding ?lang=[de|es|fr|ja|pt] to your page's URL.

Future roadmap

In the near future we plan to add widgets for each item on the current Second Life Viewer login screen:

Editors' Picks slideshow (the big one, top left)
Destinations main widget (with category selector)
Upcoming events
Second Life Blog

Other features we plan to enable for all widgets:

Ability to set custom click function: currently the default click behavior triggers a modal notification dialog in addition to initiating a secondlife:// teleport action. We plan to enable a widget setting that can override this with a custom javascript function.

For other features or requests, please file a Jira and/or discuss in the talk page here.