This topic has not yet been rated - Rate this topic

Defining Custom Buttons

Custom buttons are displayed in the Shortcuts gallery of the Blog Account ribbon tab. You can define custom buttons to do one or both of the following:

Direct the user to a webpage.
Notify users of new content and other online activity by updating the button image or tooltip text.

Format

Button definitions are provided by using the <button> subelement of the <buttons> element. Up to four buttons can be defined. The following table lists the valid subelements of the <button> element.

<id>	Required. The unique identifier for the button (scoped to the current blog).
<text>	Required. A description of the button (tooltip).
<imageUrl>	Required. The URL for the 24x24 Portable Network Graphics (PNG) image that is used as the button’s bitmap.
<clickUrl>	Required. The URL to which to direct an external browser when the user clicks the button.
<notificationUrl>	Optional. The URL to poll for notifications. For more information, see the “Button Notification” section later in this topic.

The following is an example of the <buttons> element.

<buttons>    
   <button>
      <id>0</id>
      <text>What's new</text>
      <imageUrl>images/SpacesFriends.png</imageUrl>
      <clickUrl><![CDATA[  
         http://spaces.live.com/default.aspx?page=whatsnew
      ]]></clickUrl>      
      <notificationUrl><![CDATA[ 
         button_notifications/friends.xml
      ]]></notificationUrl>     
    </button>
    
    <button>
      <id>1</id>
      <text>Statistics</text>
      <imageUrl>images/SpacesStats.png</imageUrl>
      <clickUrl><![CDATA[ 
         {blog-homepage-url}Settings/Stats/
      ]]></clickUrl>
    </button>    
  </buttons>

Button Notification

Button notification is an optional feature of buttons that is enabled by the presence of the <notificationUrl> element in a button definition. Notifications have the following capabilities:

Set the interval at which Windows Live Writer polls for new notifications.
Specify a custom image, such as the "gleam" overlay, to be used for notification.
Specify custom text for the notification. This text replaces the standard tooltip text.
Specify whether the notification image or text should be “cleared” when the user clicks the button.

If a notification is available, Writer immediately updates its display to the specified image or text.

In most cases, when the user clicks the button, the notification will be “cleared”. However, in some cases this action may not be appropriate. For example, if the notification mechanism is used to update the image with a numeric overlay that indicates how many friends are currently online, the notification should not be cleared when a click occurs.

To query for notifications, Writer requests the content of the <notificationUrl> element, passing the following parameters as part of the URL query string:

blog_id – The blog’s internal identifier (from the blogId attribute of the RSD <api> element).
button_id – The button’s identifier (from the <id> subelement of the <button> element).
image_url – The “base” image URL of the button (from the <imageUrl> subelement of the element).

The following is a response that indicates that the button should display a notification.

<?xml version="1.0" encoding="utf-8"?>
<notification
      xmlns="http://schemas.microsoft.com/wlw/buttons/notification">
  <checkAgainMinutes>1</checkAgainMinutes>
  <text>New content from 4 friends available</text>
  <imageUrl>images/SpacesFriendsNew.png</imageUrl>  
  <resetOnClick>Yes</resetOnClick>
</notification>

This response tells Writer to:

Check for another notification in one minute.
Change the tooltip text to “New content from 4 friends available”.
Change the button image to “images/SpacesFriendsNew.png”.
Clear the notification image and text if the user clicks the button.

The following example shows a response that indicates that the button should not display a notification:

<?xml version="1.0" encoding="utf-8"?>
<notification
      xmlns="http://schemas.microsoft.com/wlw/buttons/notification">
  <checkAgainMinutes>1</checkAgainMinutes>
</notification>

This response tells Writer to check for another notification in one minute.

The following table lists the valid subelements of the <notification> element that are returned from the <notificationUrl>.

`<checkAgainMinutes>`	Required. The number of minutes to wait until checking for another notification.
`<text>`	Optional. An override to the button (tooltip) text that describes the notification.
`<imageUrl>`	Optional. The URL for the override to the button image (24x24 PNG) that visually signals the notification.
`<resetOnClick>`	Optional; defaults to true. Indicates whether Writer should reset the button to its default image and text whenever the user clicks the button.

Securing Button Content and Notifications

Some content associated with notifications may be considered private to an individual blog. For example, comments may be public, but blog statistics may be private. In such cases, the URLs that are used to serve content or notifications can be secured by using Digest authentication. Under these circumstances, Writer responds to the credentials challenge by using the current blog’s user name and password.

Did you find this helpful? Yes No

Not accurate

Not enough depth

Need more code examples

(1500 characters remaining)