Title: Installing Social Enterprise Web Widgets/Badges in Your Pages

This feature is part of the Social Enterprise Web option. To add this feature to your TeamPage license, please contact TeamPage Sales. TeamPage currently has four Social Enterprise Web widgets (also sometimes referred to as badges) that you can embed in any web page you control. In order to use these widgets, your TeamPage license must specify this option in Server Setup > License:



Each widget can be associated with either an entire web page, or with part of a page, for example when you would like to be able to add a comment or tag to any specific row in a database report.

The widgets are very easy to add to any page, with just two lines of code:

1. A placeholder DIV that you insert in your page where you would like the widget to appear. If you wish to have multiple widgets on the page, you must create a placeholder DIV for each one.

2. The JavaScript that activates the widgets. This JavaScript is served from your Traction server , and must appear after the placeholder DIVs, usually at the end of your page before the </BODY> tag. The script code that must be embedded is:

<script src="http://yourserver:port/html/js/widgets.js" type="text/javascript"></script>


The Parameters



Each placeholder DIV must be accompanied by parameters that control how the widget will be displayed. These parameters are expressed as HTML attributes.

class

Required. The CSS class= attribute is used to identify the type of widget to display, and must be one of the names in the Widgets table below.
data-host

Required. The base URL (and port if not 80 for HTTP or 443 for HTTPS) of your TeamPage server, e.g., or http://teampage.tractionsoftware.com or http://myserver:8080 .
data-url

Optional. The URL of the current page. This will default to the window.location.href.

If you are putting multiple widgets on a single page, each widget's data-url should be different and should represent the specific item in question. If each item has a real web page that corresponds to it, you should use that page's URL. If there is no such page, you can use an alternate identifier as the URL, e.g. a database primary key.
data-title Optional. The Title of the current page. This will default to document.title.
data-description Optional. The Description of the current page.
data-image Optional. An image URL for the current page.


If metadata like the image and description are not supplied by data- attributes, the widget will attempt to get the data from OpenGraph metadata embedded in the page.

The activity and summary widgets also support the following attributes:

data-buttons Optional. The list of buttons in the order in which they should appear in the widget. The default value is "comment,task,tag,share"


The activity and discussion widgets also support two additional attributes:

data-width Optional. The width of the widget in pixels, e.g. 300
data-height Optional. The height of the widget in pixels, e.g. 600


Finally, if any specific layout changes are needed, you can add an additional style= attribute to further customize the widget, e.g. to add some space above it you would use style="padding-top: 5px;".

The Widgets



Name Example Notes and Example
tmpg-widget-button

The button widget shows the total count of all the Traction comments, tasks, tags, and shares of the current URL. Clicking the button launches the bookmarklet view, opening it to the same tab as the last time the bookmarklet view was displayed (this is stored in a cookie).

<div style="padding-top: 5px;" class="tmpg-widget-button" data-host="http://yourserver:port"></div>

tmpg-widget-summary

The summary widget provides an activity breakdown by type. Clicking the name of the type will open the bookmarklet view to the corresponding tab.

<div style="padding-top: 5px;" class="tmpg-widget-summary" data-host="http://yourserver:port"></div>

tmpg-widget-activity

The activity widget shows all the activity that has happened on the server in reverse chronological order. It also has a breakdown similar to the summary at the bottom. The icon representing each type acts as a button to open the bookmarklet view to the corresponding tab.

<div style="padding-top: 5px;" class="tmpg-widget-activity" data-host="http://yourserver:port"></div>
tmpg-widget-discussion

The discussion widget allows you to display and add Traction comments inside pages from other applications. You can click the "reply" button to reply to an existing comment, or you can click inside the Add a New Comment textbox to type a new comment. The textbox will then turn into a full Traction rich text edit form that supports image and file drag and drop and other Traction editing features.

<div class="tmpg-widget-discussion" data-host="http://yourserver:port" data-height="1500"></div>


Authentication



The widgets are authenticated through a direct connection between the browser and Traction and is compatible with single sign-on. If the person visiting a page containing a widget is not already logged into Traction, the widget will display a login button, e.g.

button
summary
activity
discussion


Performance



Bear in mind that each time a page that contains a widget is loaded, a permission-filtered query is made against your Traction server to return the widget results customized for the user viewing the page.

To minimize unnecessary overload on your Traction server, we recommend putting the widgets on pages that represent specific data objects corresponding to a specific document and not on primary portal pages that may be loaded many thousands of times per day.

Logging



Unlike toolbar buttons, which query against the browser's current URL and which are not logged for privacy reasons, widget page loads are currently logged in the standard traction.log and debug.log files, e.g.

[log Thu Nov 10 11:04:05 EST 2011] (admin) requested /traction/gwt/view?f=body&title=&type=widget/discussion&url=http://traction.tractionsoftware.com/products on port 8081 in 165ms



Attachments:
button.png
summary-1.png
activity.png
discussion.png
SEW.png
buttonlogin.png
summarylogin.png
activitylogin.png
discussionlogin.png
Related Articles
references (1)
SEW1: Social Enterprise Web Documentation
Article: SEW3 (permalink)
Categories: :Doc:Social Enterprise Web
Date: November 9, 2011; 5:18:53 PM Eastern Standard Time

Author Name: Christopher Nuzum
Author ID: cjn