Linden Lab Official:Viewer Web Widgets

From Second Life Wiki
Jump to navigation Jump to search
NOTE: This is an official Second Life API provided and documented by Linden Lab. Its use is subject to the API Terms of Use.
KBcaution.png 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 splash 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". 

<!DOCTYPE html>
<html>
    <head>
        <script type="text/javascript" src="https://lecs-viewer-login-agni.s3.amazonaws.com/pubwidgets/v2/modules/sl.widgets.js">
        </script>
    </head>
    <body>
        <div id="whats-hot-now-widget" class="second-life-widget"></div>
    </body>
</html>

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

https://lecs-viewer-login-agni.s3.amazonaws.com/pubwidgets/v2/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.

  1. The number of items a particular widget can have.
  2. 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 the What's Hot Now widget. 

<script type="text/javascript">
var slconfig = {};
slconfig['whatshotnow'] = {
    itemsPerPage : 4,
    onclick: localClick
};

function localClick(stuff){
    alert(stuff);
    return false;
}
</script>

In the above code we do couple of things.

  1. Define a global javascript object called slconfig.
  2. Set the config object for what's how not widget. This needs to be called 'whatshotnow'. For other widgets please refer below sections.
  3. 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.
  4. The local function gets passed slurl of the event or destination.

Widget Size Precedence

  1. Items per page
  2. 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.

  1. itemsPerPage - the number of items in the widget per page.
  2. 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.

  1. itemsPerPage - the number of items in the widget per page.
  2. 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.

Blogs

This widget displays a list of all recent blog posts from SL.

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

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

This widget expects the above div to be a fixed width of 263px. The height will change based on the css/itemsPerPage options. To control positioning, size, and other parameters, just style the #blogs-widget in your own page's CSS.

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

  1. itemsPerPage - the number of blog listings in the widget per page.
  2. onclick - a javascript function which needs to be called when an item in this widget gets clicked. The javascript function is called back with an object. When this option is set, the overlay which usually shows up is cancelled. Here is what is passed back to the call back - a object with these properties - creator, date, description, link, pubDate, title

Destination Images

This widget displays a scrollable list of featured destinations with larger pictures. The number of destinations shown is 8.

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

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

This widget expects the above div to be a fixed height of 267px and fixed width of 660px. To control positioning, and other parameters, just style the #destination-widget in your own page's CSS.

This widget takes 1 options. It needs to be set in slconfig['destination-images'] object. Below are the options.

  1. 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.

Upcoming Events (List Version)

This widget displays a list of upcoming events sorted with the most recent one at top

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

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

This widget expects the above div to be a fixed width of 263px. 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 #upcoming-events-widget in your own page's CSS.

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

  1. itemsPerPage - the number of items in the widget per page.
  2. 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.


Upcoming Events (Filmstrip Version)

This widget displays thumbnail list of upcoming events sorted with the most recent one at the beginning

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

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

This widget expects the above div to be a fixed height of 143px. 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 #upcoming-events-widget in your own page's CSS.

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

  1. itemsPerPage - the number of items in the widget per page.
  2. 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.

Teleport

The teleport widget provides a more intuitive user experience for links to locations within Second Life (both secondlife:// links and maps.secondlife.com links). If a user has the Second Life viewer installed, the link should launch the viewer and teleport to that location. If the user does not have the viewer installed, the link should take the user to the corresponding page in maps.secondlife.com. The widget provides the following behavior:

  • If the viewer is installed, links to both secondlife:// URLs and maps.secondlife.com URLs should launch the viewer and go to the specified location in-world.
  • If the viewer is not installed, links to both secondlife://URLs and maps.secondlife.com URLs should go to the specified location in maps.secondlife.com.
  • If the link is to something other than a secondlife:// URL or a maps.secondlife.com URL, the link should behave normally and go to the specified href.

To employ the widget requires only two steps:

  • Add the following script tag to your webpage:
 <script type="text/javascript" src="https://lecs-viewer-login-agni.s3.amazonaws.com/pubwidgets/v2/modules/sl.teleport.js"></script>
  • Add the class "sl-teleport" to any links you wish to be controlled by the widget, for example:
<a class="sl-teleport" href="https://maps.secondlife.com/secondlife/MyCoolPlace/000/000/000/">My cool place</a>
or
<a class="sl-teleport" href="secondlife://MyCoolPlace/000/000/000/">My cool place</a>

Future roadmap

For other features or requests, please file a Jira in the 'Web' project for component 'Viewer Login Page' and/or discuss in the talk page here.

Retrieved from "https://wiki.secondlife.com/w/index.php?title=Linden_Lab_Official:Viewer_Web_Widgets&oldid=1210226"