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 300px, blue user interface, etc.

LPoP Menu Standard

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

Menu Sizing

The Launchpad On-Page menu defaults to 400px by 300px. 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 140 to 900px. 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 two methods of obtaining the embed code. The first is the standard Embed tab. When the tab is elected the user can choose the embed code to grab.

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

Launchpad On-Page can be skinned very easily. When using the Widget Console you were able to choose between four default colors for your Sharing Menu; Grey, White, Black and Blue. Selecting a color simply modifies the customCSS configuration value with the appropriate style sheet (grey.css for grey, white.css for white, etc.)

<script type="text/javascript"> 
  $Launchpad.ShowMenu(
        {userId: UID,
         customCSS: http://cdn.clearspring.com/launchpad/skins/blue.css,  
         widgetName: "Hello World", 
         source: "PutWidgetHere"});  
</script>

For greater control over the appearance, you can create a custom style sheet and attach it to the Sharing Menu using the same customCSS configuration value. When you specify your custom CSS file you must give the full URL, for example: http://www.example.com/menu.css and not just menu.css. If you provide an incorrect URL the Sharing Menu will default to the standard white style.

To customize the Sharing Menu you simply modify the style in your style sheet. Attach your style sheet and it will be combined with the default style. For example it you want to have a simple menu with a snowflake background your style sheet would look as follows:

/* Background */
#launchpad {
  background: #aaa url(http://www.example.com/snow-flakes.jpg) repeat-x top;
  border: 1px solid;
}

/*tabs */
#tabs a {
  color: #fff;
}

#tabs a.active {
  background: none;
  color: #fff; 
  text-decoration: underline;
}
#tabs a:hover, 
#tabs a.active:hover {
  background: none;
  color: #fff;
  text-decoration: underline;
}

.tabsHover {
  background: none;
}

/* Buttons */
.buttonsHover, .buttons a,
.scroll-left,.scroll-right,
.section_embed .copyButton {
  background: none;
  border-color: #999999;
  color: #fff;
}

.buttons a:hover, a.scroll-left:hover, 
a.scroll-right:hover, .section_embed 
a.copyButton:hover {
  background: none;
  border-color: #fff;
  color: #fff;
  font-weight: bolder;
}

/* White Clearspring Logo */
#logo .white { display : block; }

The style sheet above, lets call it snowFlakeStyle.css, places a background image, of snowflakes, on to the menu. The tabs section defines simple styles for the tab item links, how they will act when active and when a mouse hovers over the tab. The button section is similar to the tabs, but encompasses the entire set of button on the menu, i.e., social network destinations, navigation arrows, etc. Finally we use the white Clearspring logo as this fits best into the custom menu layout (note: the Clearspring logo cannot be removed from the menu).

When you have completed the style sheet add the full URL to the customCSS configuration parameter, as follows:

<script type="text/javascript"> 
  $Launchpad.ShowMenu( 
        {userId: UID,
         customCSS: http://www.example.com/snowFlakeStyle.css, 
         widgetName: "Hello World", 
         source: "PutWidgetHere"});
</script>

The result of the snowFlakeStyle.css is as follows:

To customize the Sharing Menu download the sample CSS file from http://cdn.clearspring.com/launchpad/skins/blue.css. Use this file as your template for customization.

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