Customizing the Launchpad On-Page Menu

Introduction

Launchpad On-Page is a standalone, customizable viral sharing menu that will allow you to quickly and easily convert your Web content into portable widgets. The sharing menu allows users of your site to post the content widget to their destination of choice, such as Google, Facebook, MySpace, etc.

This guide discusses many of the configuration options available for customizing the service menu, using the Launchpad On-Page APIs.

Audience for this Guide

This guide is for developers who are tasked with implementing Clearspring Launchpad On-Page Share Menu with their Web content and wants to customize the look and feel of the share menu.

This guide assumes that the reader is familiar with Launchpad On-Page and its APIs. To become familiar with the APIs review them at: http://www.clearspring.com/docs/tech/apis/on-page

Changing the services (social networks, bookmarks, etc.) available on the menu is not covered in this guide. Please review the “Launchpad-OnPage Guide: Configuring Services“ available at: http://www.clearspring.com/docs/tech/guides

Share Menu

Launchpad On-Page allows you to add the Clearspring Share Menu to any type of content that you want shared. By default the menu is fully displayed at 400px by 210px, blue user interface, etc.

LPoP Menu Standard

The menu can be fully customizable using the Widget Console or the simple configuration API. The following sections will highlight common customizations of the menu using the configuration API.

Menu Sizing

The Launchpad On-Page menu defaults to 400px by 210px. In most cases this menu size works well. However in cases where the size needs to be adjusted, the Launchpad On-Page configuration API makes it simple to do so.

When calling the menu methods, ShowMenu() or CreateMenu(), you can define the height and width of the menu. To define the size of the menu add the menuWidth and menuHeight values, such as:

<script type="text/javascript">
  $Launchpad.ShowMenu(
        {userId: "UID", 
         widgetName: "Hello World", 
         source: "PutWidgetHere", 
         menuWidth:200, 
         menuHeight:300});
</script>

The above code will give you a menu like this (actual size):

LPoP Menu Short

The values for the height and width of the menu can be between 160 to 800px. This provides a large range of options for menu sizes. Some examples of different sized menus are as follows (sizes adjusted):

The configuration option for sizing provides significant flexibility for defining a menu that fits your needs.

Share Button

Some implementations of Launchpad On-Page may not warrant the full display of the menu. In these cases the menu can be hidden behind a share button, that when clicked will display the menu.

To use the button option of the Launchpad On-Page menu you simply use the ShowButton() method, as such:

<script type="text/javascript">
  $Launchpad.ShowButton(
        {userId: "UID", 
         widgetName: "Hello World", s
         ource: "PutWidgetHere”});
</script>

The above code simply display the following:

LPoP Btn Standard

When the button is clicked the default menu will be displayed below the button. As we saw above the menu can be sized (and as we will see later in this document, customized). The following shows some example of button mode with customized menus.

When using the sharing button (either the standard button or a custom button described below) you may want to have the menu displayed else where on the page. For example, your page has images that can be shared. The sharing button is placed below each image so the user can easily see that they can grab the image. However you would prefer to place the menu to the right of the image, as to not obstruct the image below. This is easily accomplished using the targetElement configuration parameter, as shown below.

<script type="text/javascript">
    $Launchpad.ShowButton(
          {userId: "UID", 
           widgetName: "Image13", 
           source: "PutWidgetHere", 
           targetElement : “Image13-menu”});
</script>

The value of the targetElement configuration is the value of a DIV tag. The menu will be placed within the DIV tag. In the example code above, the menu will be placed in the DIV tag with ID value “Image13-menu” when the Share button is pressed.

Custom Share Button

If you are not fond of our buttons your do not have to use them. You can substitute our button for a custom button image, a link, or what ever. To do so you can use the CreateMenu() function, which lets you create a menu object, using the same configuration parameters you used for ShowMenu() and ShowButton(), but will not be initially visible.

When you create your menu with the CreateMenu() function you will add the actionElement parameter. This parameter will be the page element, anywhere on the page, that when clicked will display the menu. The menu will be positioned relative this element. The following code provides an example for using an image as the button.

<a id="getButton" href="#"><img src="starBtn.png" width="76" height="74" border="0"></a>

<script type="text/javascript">
  $Launchpad.CreateMenu(
        {userId: "UID", 
         widgetName: "New Btn", 
         source: "PutWidgetHere", 
         actionElement : "getButton"});
</script>

The anchor above has an ID of getButton. This ID is the string value for the actionElement parameter. When the starBtn image is clicked the menu will be displayed below it. The following examples show the star button, from the code example above, and a simple text link. Note, you should add the CreateMenu() call after you defined the actionElement value in the page.

Clearspring provides several custom buttons that can be used. These button images and their URL are as follows:

	http://cdn.clearspring.com/launchpad/static/cs_button_share1.gif
	http://cdn.clearspring.com/launchpad/static/cs_favicon.png http://cdn.clearspring.com/launchpad/static/cs_favicon.gif
	http://cdn.clearspring.com/launchpad/static/cs_favicon2.png

These images can be used directly from their URL and do not require you to download them. To uses any of these directly you would do as follows:

<a id="csShareBtn" href="#">
   <img src="http://cdn.clearspring.com/launchpad/static/cs_button_share1.gif " width="125" height="16" border="0"></a>

<script type="text/javascript">
  $Launchpad.CreateMenu(
        {userId: "UID", 
         widgetName: "CS Btn", 
         source: "PutWidgetHere", 
         actionElement : "csShareBtn"});
</script>

As described above with the Share Button using the targetElement configuration parameter allows for placing the Sharing Menu anywhere on the page. The following example shows how to use the targetElement with a custom share button.

<a id="getButton" href="#">
  <img src="starBtn.png" width="76" height="74" border="0"></a>

<script type="text/javascript">
  $Launchpad.CreateMenu(
        {userId: "UID", 
         widgetName: "Image12", 
         source: "PutWidgetHere", 
         actionElement : "getButton", 
         targetElement : “Image12-menu”});
</script>

Single Service per Button

Using custom sharing buttons with the ability to define single services (see “Launchpad-OnPage Guide: Configuring Services”) provides a way to give users a single click option to grab content.

For example, you know that the majority of grabs for your content are posted to MySpace, Facebook and Digg. You want users to recognize that these services are supported and with a single click easily grab, but you do not want to prohibit users of other services from grabbing your content. Using custom sharing buttons and setting single services you can provide users with this experience.

First you want to define your buttons:

<a id="mysBtn" href="#">
   <img src="http://www.myspace.com/favicon.ico" width="16" height="16" border="0"></a>&nbsp;
<a id="fcbBtn" href="#">
   <img src="http://www.facebook.com/favicon.ico" width="16" height="16" border="0"></a>&nbsp;
<a id="digBtn" href="#">
   <img src=http://digg.com/favicon.ico  width="16" height="16" border="0"></a>&nbsp;
<a id="csmBtn" href="#">
   <img src="http://cdn.clearspring.com/launchpad/static/cs_favicon.png"  width="16" height="16" border="0"></a>

The first three buttons will be used for the single service, MySpace, Facebook and Digg respectively. The last button, which is the Clearspring star (*) image, will display the full menu.

LPoP Single Srv Btns

Next we will define a CreateMenu() for each button we have defined above (remember that this should be defined after the buttons). The CreateMenu() will include the actionElement for each button defined. For the first three buttons defined above (MySpace, Facebook and Digg) we will set the servicesInclude parameter. In this example we want each button to represent a single service so the value of the servicesInclude will only include the one service identifier (check out the On-Page API documentation, http://www.clearspring.com/docs/tech/apis/on-page, for a list of all the services). The final button, the Clearspring star, will display the Launchpad On-Page menu, but we will exclude the services represented by the individual buttons. To do this we use the servicesExclude parameter. The value of servicesExclude is the list of services we define as individual buttons.

<script type="text/javascript">
  $Launchpad.CreateMenu(
        {userId: "UID", 
         widgetName: "MyWidget", 
         source: "PutWidgetHere", 
         servicesInclude : ['digg'], 
         actionElement : "digBtn"}); 
  $Launchpad.CreateMenu(
        {userId: "UID", 
         widgetName: "MyWidget", 
         source:  "PutWidgetHere", 
         servicesInclude : ['myspace'], 
         actionElement : "mysBtn"}); 
  $Launchpad.CreateMenu(
        {userId: "UID", 
         widgetName: "MyWidget", 
         source:  "PutWidgetHere", 
         servicesInclude : ['facebook'], 
         actionElement : "fcbBtn"}); 
  $Launchpad.CreateMenu(
        {userId: "UID", 
         widgetName: "MyWidget", 
         source: "PutWidgetHere", 
         servicesExclude : ['digg','myspace','facebook'], 
         actionElement : "csmBtn"}); 
</script>

When completed the page will include four icons for each service. When the user clicks the MySpace icon the user will be directed to “Post to MySpace Profile” screen.

LPoP Single Srv Btn Menu

Leveraging custom buttons and service configurations provides you the ability to fully customize the Launchpad On-Page experience.

Defining the Bookmark

When using the bookmark services it is important to set the URL that you want the users to be bookmarked. This is done using the bookmarkURL parameter with either ShowMenu(), CreateMenu() or ShowButton(). The value of the parameter is a string that represents the URL to be book, for example:

<script type="text/javascript">
  $Launchpad.ShowMenu(
        {userId: "UID", 
         widgetName: "Menu Size", 
         source: "PutWidgetHere", 
         bookmarkUrl : “http://www.clearspring.com”});
</script>

This flexibility allows for defining the bookmarkURL to any URL. There are cases where the page containing the sharing menu is not the page that should be bookmarked. For instance the page with the menu is a product demo page and the actual URL of the product is different

To make life easier then having to add a URL to each page you can use the javascript location.href function to get the current pages URL. The following provides an example of using javascript with the bookmarkURL parameter.

<script type="text/javascript">
  var pageUrl = location.href;
  $Launchpad.ShowMenu(
       {userId: "UID", 
        widgetName: "Menu Size", 
        source: "PutWidgetHere", 
        bookmarkUrl : pageUrl});
</script>

Displaying Embed on the Menu

Many users are accustom to seeing the embed code when grabbing widget for their site. The Launchpad On-Page menu provides several methods of obtaining the embed code. One method is selecting the embed icon on the Popular tab, which is the first screen seen by the user. Another method is to locate embed within the All tab. Also within the All tab a user can search or use the drop down filters to locate the embed button.

Alternatively you can configure the menu to display the embed code directly on the menu. This raises the level of embed code directly to the user without any additional clicking. To enable the embed code on the menu you set the embed value to true for menuConfig option. This menuConfig option can be added to showMenu(), createMenu() and showButton(). The following code shows how to use menuConfig.

<script type="text/javascript">
  $Launchpad.ShowMenu(
        {userId: "UID", 
         source: "PutWidgetHere", 
         widgetName: "Menu with Embed", 
         menuConfig: { embed : true }});
</script>

The above code will display the following menu:

The user, if desired, can easily select the copy button to grab the embed code. In addition, when this capability is enabled, the Embed tab is removed to eliminate user confusion.

Customizing the Menu Appearance

The Launchpad On-Page menu can be customized very easily. When using the Widget Console you are able to choose between four default color template for your Sharing Menu; Grey, White, Black and Blue. In addition the Widget Console allow you to fully customized the look and feel of the menu. This section will describe how to customize the look and feel of the menu from the On-Page APIs.

When styling the menu via the API requires using the menuConfig setting. The following demonstrates using the customization options via the API:

<script type="text/javascript">
   $Launchpad.ShowMenu(
     {userId: "UID", 
      widgetName: "Style Menu", 
      source: "PutWidgetHere", 
      menuConfig: {
        style: {
          menubar: {alpha: 100, background: 15461355, foreground: 5197647, hover: 11579568, selected: 26316}, 
          menu: {chrome: 15461355, alpha: 100, background: 16777215, foreground: 3355443, link: 26316, title: 3355443, hover: 6273502}}, 
          }
      }
  );
</script>

The above customization will generate a menu that looks like the following:

The menu customization is broken down into three sections; styling, display and global.

Styling

The menu provides the ability to style the look of the menu to allow you to integrate the menu with your page. The style options are as follows:

style : {
        menubar : {
            alpha       : 1,            // bar opacity (1 – 100)
            background  : 0x000000,	// bar background color - HEX
            foreground  : 0x989898,     // font color - HEX
            hover       : 0x1096bf,     // color on mouse hover - HEX
            selected    : 0xFFFFFF},    // color when selected - HEX
        menu : {
            alpha       : 1,            // bar opacity (1 – 100)
            chrome      : 0xFFFFFF,	// menu border color - HEX
            background  : 0xFFFFFF,	// maneu background - HEX
            foreground  : 0x666666,	// font color - HEX
            link        : 0x3c7ddb,	// text link color - HEX
            title       : 0x333333,	// text titles color - HEX
            hover       : 0x1096bf}	// text link hover state color - HEX
    }

The style:menubar options provides a way to style the look and feel of the menu bar, see the following screen shot:

The style:menu options provides a way to style the look and feel of the menu, see the following screen shot:

Display

The display configurations are the programmatic equivalent to the widget configuration in the Widget Console. To use the display configuration the options format is as follows

   display : {
     singleService  : '',	// alternative to using serviceInclude
     popular        : {		// popular tab features
        asList      : true,     // display as list or buttons
        text        : true,	// show text with icon, when available
        embed       : false,	// display embed on menu
        embedHeight : 1   	// set embed box height (1-3 lines)
     },
     menu_nav      : {
        getandshare : {show:true, text:true}, // show or hide tab
        gallery     : {show:true, text:true}, // show or hide tab 
        info        : {show:true, text:true}, // show or hide tab
        options     : {show:true, text:true}, // show or hide tab
        about       : {show:true},            // show or hide tab
        faq         : {show:true},            // show or hide tab
        categories  : {show:true},            // show or hide tab
        text        : true                    // display button text
     }
   }

Global

Global settings are useful defining common setting across the menu. These options are defined as follows:

 global : {
      animate     : true,
      services    : '',
 }

Questions / Comments / Concerns

We welcome and encourage all feedback in this process.
Please feel free to reach us through our forum at http://www.clearspring.com/forum/

clearspring - the widget network.

Platform