NewsGator Knowledge Base

FIX: "A program is trying to access e-mail addresses you have stored in Outlook" warning

Thu, 16 Oct 2008 05:33:15 GMT

The information in this article applies to:

NewsGator 1.3, 2.0

SYMPTOMS

You may see the following warning in Outlook:

"A program is trying to access e-mail addresses you have stored in Outlook. Do you want to allow this?"

This message may pop up when you navigate to the NewsPage, or when attempting to post an existing item to your weblog.

This most commonly occurs on Outlook 2002/XP with SP3 installed.

CAUSE

This has been confirmed to be a problem with the versions of NewsGator listed above, under certain circumstances.

RESOLUTION

This problem was first fixed in NewsGator versions 2.0.3.1 and higher, which is available from http://www.newsgator.com/downloads.aspx.

INF: Subscribing to protected LiveJournal feeds

Thu, 16 Oct 2008 05:31:32 GMT

To subscribe to a protected LiveJournal feed, you must append ?auth=digest to the end of the feed URL. For example, if the feed you're subscribing to is:

http://exampleuser.livejournal.com/data/rss

to access the secure feed, the URL should be changed to:

http://exampleuser.livejournal.com/data/rss?auth=digest

If you are using one of our desktop clients, the news reader will prompt you for username and password when it reads the feed. NewsGator Online users should see this FAQ for steps to subscribe to a secure feed.

For more information about LiveJournal authentication, see the official LiveJournal FAQ.

INF: How to search your feeds in Outlook

Thu, 16 Oct 2008 05:31:26 GMT

Description:

Using Search Folders with Outlook 2003, you can use search folders to view your news. Search folders provide a flexible "virtual folder" on top of existing folders in Outlook. One way to use a search folder is to display all unread posts across all of your news folders and group these unread posts by their folder.

The information in this article applies to:

All versions of NewsGator Inbox with Outlook 2003

Procedure:

Select a mail folder in Outlook.
Click File | New | Search Folder.
Select Create a custom Search Folder in the Select a Search Folder list.
Click the [Choose...] button to specify your criteria.
Enter a name for the folder, such as Unread News.
Click the [Criteria...] button.
Click the More Choices tab.
Select Only Items that are: and select unread in the list.
Click [OK].
Click the [Browse] button.
Clear all of the selected folders then select your Base news folder.
Check the Search subfolders box.
Click [OK].
Click [OK] twice to create the search folder.
Your new new search folder displays at the bottom of the folder view, under Search Folders.

INF: How to Use FeedDemon’s Newspaper Instead of the News Item List

Tue, 29 Jul 2008 14:41:33 GMT

The information in this article applies to:

FeedDemon 2.5+

A lot of customers rely on the news item list, many of whom have been using FeedDemon for a long time. But it’s also clear that many of these customers don’t realize that FeedDemon’s newspaper view has evolved to the point that it does pretty much everything the news item list does (plus a lot more). This article describes how to use the newspaper view as a replacement for the news item list.

It takes a little getting used to, but many people who dropped the news item list in favor of the newspaper view now can’t imagine using FeedDemon any other way.

Based on feedback from users, there are three main reasons why people like the news item list:

It enables quickly scanning headlines
It enables locating previously read items
It enables navigating via the keyboard

Fortunately, FeedDemon’s newspaper view offers these same benefits :)

Although the newspaper defaults to showing summaries, you can use the icons at the top right to toggle between full posts, summaries and headlines.

Personally, I like showing summaries because that enables me to quickly scan the first sentence or two of each item, but you can make the newspaper look more like the news item list by switching to headlines. Here’s the same feed showing only headlines:

Tip: If you choose to show only headlines, try increasing the number of items to display per page (Tools > Options > Reading).

And while the newspaper view defaults to showing only unread/flagged items, you can change the newspaper filter to display previously read items:

Last but not least, the newspaper view offers even better keyboard handling than the news item list. When the newspaper has the focus (Ctrl+B), the following shortcuts are enabled:

Previous item	Ctrl+ArrowUp or K
Next Item	Ctrl+ArrowDown or J
Next page	Ctrl+ArrowRight
Previous page	Ctrl+ArrowLeft
Flag item	F
Send item (email, blog, del.icio.us)	S
Clip item	C
Mark item read/unread	R
Open/expand item	Enter
Open item link	V
Open item link in new tab	T
Open item link in external browser	E
Reload newspaper	Ctrl+F5

Tip: You can change these shortcuts by selecting Tools > Keyboard Shortcuts > Newspaper.

We realize this post won’t win everyone over – some people will still prefer keeping the news item list visible. But try keeping it hidden for a couple days and see what you think. And if you feel bold, try using the Next Page” button to mark everything on the current page as read and move to the next page. That way you can stop marking individual items as read and speed read your way through your unread items.

PRB: Error "Windows can't find {URL}" when opening links in FireFox

Fri, 11 Jul 2008 13:33:21 GMT

This informaiton in this article applies to:

FeedDemon
FireFox

Description:
When using FireFox as the default browser within Windows, opening FeedDemon links in the external browser produces an error similar to Windows cannot find {URL}.

Cause:
This error occurs when the file extention definition for HyperText Transfer Protocol becomes corrupted.

Solution:

Open Windows Explorer
Select Tools and then Folder Options
Select the File Types tab
Select Extension: (NONE), File Type: HyperText Transfer Protocol
Click Advanced toward the bottom of the window
In the Edit File Type window, select Open and click Edit
Clear the DDE message box (which should contain "%1")
Click OK, Click OK
Repeat for File Type: HyperText Transfer Protocol with Privacy

INF: Downloading Podcasts with FeedDemon

Fri, 11 Jul 2008 13:17:45 GMT

If you're new to FeedDemon, you might not know that you can use it to download podcasts (AKA: "enclosures") and sync them with iTunes. When an article has a podcast associated with it, a paperclip icon will appear beneath its title, as illustrated by this screen shot:

Clicking this icon adds the podcast to FeedStation (a free "podcatcher" that's bundled with FeedDemon), which takes care of downloading it and then copying it to iTunes:

If you're subscribed to a feed whose podcasts you always want to download, you can skip clicking the paperclip icon and tell FeedDemon to automatically download all podcasts by editing the feed's properties:

In my case, I selectively download podcasts for most feeds, but I have automatic downloading enabled for IT Conversations since I generally want to listen to every IT Conversations podcast.

FeedDemon's online help has more details on this process, including:

How to schedule downloads to occur after a specific time (such as when you're away from your computer)
How to copy podcasts to Windows Media Player rather than iTunes
How FeedDemon's "safe list" protects against downloading executable files

Bonus Tip: You can drag-and-drop any hyperlink onto FeedStation to add it to the download queue. This works not only with hyperlinks inside of FeedDemon, but also those in Firefox and Internet Explorer.

Widget How-To's - Customizing a Widget Footer

Mon, 07 Jul 2008 11:33:13 GMT

This Knowledge Base article only applies to premium Editor's Desk accounts. A premium level account allows for customization of the HTML, CSS, and JavaScript of your widgets. If you'd like more information about how you can take advantage of this more robust version of Editor's Desk, please contact Craig Lachman. His contact information is included in the confirmation email that was sent to you when you signed up for a basic Editor's Desk account.

In the Template HTML pane of your widget, simply perform these two steps:

1. Create a custom footer.

The custom footer code should be placed at the beginning of the widget HTML, and will look much like the following:

{stringify CustomFooter}
 <div class="footerClass">
  <a onclick="${ShowGetThisJS}"><img src="GetThis.jpg"></a>
 </div>
CustomFooter

Although you don't see it, the default footer code looks like the following. If you want to only make small adjustments to the widget footer, you can simply copy this into the CustomFooter tags like so and make modifications there:

{stringify CustomFooter}
<div class="buzzFooter" style="width:100%; padding:0px; background-color: #EEE;"> 
 <div style="float:left; width:66px; background-color:#eee;">
  <nobr>
  <a title="Get This" style="cursor: pointer;" href="javascript:void(0)" onclick="${ShowGetThisJS}">
  <img border="0" style="margin: 3px;" alt="Get This" src="${BuzzAppUrl}/images/getThis_grey.png" /></a>
  </nobr>
 </div>
 <div style="float:right; text-align:right; padding:7px 4px 0px 3px !important; padding:4px 4px 0px 3px; width:55px;">
 <img border="0" style="cursor: pointer;" onclick="window.open(\'http://www.newsgatorwidgets.com\')" 
 src="${NGBaseUrl}/NGBuzz/Images/PoweredbyNG.gif" alt="Powered by NewsGator" />
 </div>
 <br clear="all" />
</div>
CustomFooter

2. Call the custom footer.

By default, the widget footer function call will look like this. It is located towards the bottom of the widget HTML code:
${% getBuzzFooter() %}
To call your custom footer, change it to:
${% getBuzzFooter({footerTemplate:CustomFooter}) %}

If you have additional questions, or need personalized help on this topic, please send an email to Private Label Support.

Using the ${BuzzId} token in the JavaScript template to uniquely name functions

Fri, 27 Jun 2008 10:57:43 GMT

In the template HTML of a widget, the unique BuzzId of your widget has always been accessible by using the ${BuzzId} token. Only recently has the BuzzId now become available in the JavaScript.

The BuzzId is a helpful token in that it can be used to uniquely name CSS classes, object Ids, and function names. By uniquely identifying widget objects, you can ensure that your widget will load properly, without CSS collisions or JavaScript function name confusion.

In the JavaScript, if you have a function defined like so:

function getText_${BuzzId}(name){
alert("hello " + name);
}

In the template HTML you would call it like this:

onclick="window['getText_' + ${BuzzId}]('world')";

Or if it is a function you'd like to run after the widget renders (like calling the LoadTabs function), you can place it in a post render callback:

${% AddPostRenderCallback(function(){ window['getText_' + BuzzId]('world'); }) %}

Logging Attention Data From Flash or Flex widgets

Wed, 04 Jun 2008 12:12:44 GMT

Note: This article should not be used for HTML/Javascript based widgets. Those widgets should use the functions provided by the widget framework.

You can log attention events to NewsGator by sending an HTTP request with certain parameters on it. This can be done in a variety of way, for instance by using the URLLoader class.

The endpoint URL is http://nmp.newsgator.com/ngbuzz/attn.ashx

The endpoint accepts the following arguments:

1. buzzId (required) - The numeric ID of the widget to log against, or the name of the widget (if name is sent, orgCode is required)

2. orgCode - The orgCode the widget is from. Only required if buzzId is a name rather than a numeric ID.

3. eventName (required) - the name of the event to log. See paragraph on Event Types.

4. trkP - The parent widget's tracking GUID, if any. If the parent widget had a tracking GUID this must be sent to correctly identify the instance. Otherwise it may be omitted. Properly creating and handling trkM and trkP is the topic of another article.

5. trkM - This widget's tracking GUID, if any. For descendant widgets this must be sent to identify the widget instance, for the root/non-descendant instance it may be omitted. Properly creating and handling trkM and trkP is the topic of another article.

6. mid - The buzzId of this widget's master widget, if any. Required if this widget is a subordinate widget, otherwise must be omitted.

7. pid – (optional) The Newsgator PostID that the event is related to. This is never required, and should only be sent for events that are related to a specific post such as emailing, rating, or clicking a post link. This should never be sent for non-post specific events such as sharing the widget, or clicking on header/footer images.

Event Types

The following events are supported. These should be used in the eventName parameter.

1. view - This indicates that a widget was rendered. For simple widgets this is straightforward. For complex widgets such as Checkbox or Tabs, the behavior and meaning of this depends on how the widget is written. This event is automatically logged by the widget framework. You will only need to log this event in cases where your Flash/Flex widget is included directly on the page, without being wrapped in an HTML widget such as on MySpace.

2. click - Indicates that the user has clicked through to the source content. This is a very important metric as it indicates revenue opportunities for widget clients.

3. rate - Indicates that a user clicked the ratings stars in the toolbar.

4. clip - Indicates that a user clipped/saved a post.

5. im - Indicates that a user sent the post via IM.

6. email - Indicates that the user sent the post using email.

7. comment - Indicates that the user commented on the post.

8. custom1 through custom9 - These events are not defined. Any widget may use them in any way it sees fit. Custom1 is used by the default Accordion template to indicate clicks on an accordion header, and by the default Paging template to indicate paging forward/back. Currently all custom events roll up under “other interactions” in our reporting interface. Also, NewsGator has developed internal conventions for these events. You are not required to follow them, but you may wish to. They are described in the KB article “Keeping Track of User Interaction In Your Widgets”, http://newsgator.mykbpro.com/Article_AC95F.aspx

Example requests:

Log a click event for buzzId 5694 on post 123465
http://nmp.newsgator.com/ngbuzz/attn.ashx?buzzId=5694&eventName=click&pid=123465

Log a click event for widget “Demo” in orgcode “test” for post 123465

http://nmp.newsgator.com/ngbuzz/attn.ashx?buzzId=Demo&orgCode=test&eventName=click&pid=123465

Log a custom1 event for a descendant of widget 5694
http://nmp.newsgator.com/ngbuzz/attn.ashx?buzzId=5694&eventName=custom1&trkM=ABD13BB2-54DE-48D5-B729-3B6BDA7ADDAC

Log a custom1 event for a different descendant of widget 5694
http://nmp.newsgator.com/ngbuzz/attn.ashx?buzzId=5694&eventName=custom1&trkP=ABD13BB2-54DE-48D5-B729-3B6BDA7ADDAC&trkM=493F7453-A1AB-43E4-BD6A-C38609A66C6B

ActionScript:
The following is some basic ActionScript code that should get you through most scenarios:

public function logEvent(attentionDataType:String, buzzId:String, postId:String="", orgCode:String="", trkM:String="", trkP:String="", referrerUrl:String=""):void
{
var cacheBreaker:String = new String(Math.random()); //used to ensure response isn't cached
var additionalParams:String = "";

                if (orgCode != "")
                {
                                additionalParams += "org=" + encodeURIComponent(orgCode);
                }

                //add param if not empty
                if (trkM != "")
                {
                                additionalParams += "&trkM=" + encodeURIComponent(trkM);
                }

                //add param if not empty
                if (trkP != "")
                {
                                additionalParams += "&trkP=" + encodeURIComponent(trkP);
                }

                // add param if not empty
                if (postId !="")
                {
                                additionalParams += "&pId=" + encodeURIComponent(postId);
                }

                if (referrerUrl != "")
                {
                                additionalParams += "&u=" + encodeURIComponent(referrerUrl);
                }

                //compose url
                var req:URLRequest = new URLRequest("http://nmp.newsgator.com/NGBuzz/attn.ashx?"
                                + "eventName=" + encodeURIComponent(attentionDataType)
                                + "&t=" + encodeURIComponent(cacheBreaker)
                                + "&buzzId=" + encodeURIComponent(buzzId)
                                + additionalParams);

                //kick off request to the url
                var loader:URLLoader = new URLLoader();
                loader.load(req);
}

Re-configuring or customizing the Sharing (Get This) feature

Wed, 04 Jun 2008 07:37:23 GMT

Re-configuring the the default Sharing/GetThis The default Sharing template allows for some customization through configuration. All of the configuration settings are passed in the argument object to getBuzzFooter() as in this example: ${% getBuzzFooter({ buzzId: 1234, sharingOptions: "blogger, typepad, netvibes" }) %} The options are: 1) buzzId - by setting this the shared widget will be different than the sharing widget. Ie, "Get This Widget" becomes "Get Some Other Widget". This options determines what the "Other Widget" is. 2) sharingOptions – A comma-separated list specifying which sharing elements to display on the “Get This” panel of the widget. The possible values are: Blogger, Typepad, Netvibes, Google, Pageflakes, Create, LiveDotCom, LiveSpaces, Facebook, Limited, All, Email, and Script. "All" includes all elements. "Limited" includes all elements except LiveDotcom and LiveSpaces (which can't support custom javascript). “Email” displays the "Send to a friend" feature. "Script" displays the embed code. “Create” displays the “create your own widget” 3) fbApiKey - If this is set then Facebook will automatically be added to the default set of sharingOptions. If you provided a custom set of SharingOptions you will need to include Facebook explicitly. The Facebook API Key is shown in the Developer Application on Facebook.com. ***** More on Facebook support below. 4) emailSharingTemplate - specify a template for the "Send to a friend" email. This should be the name of an ASPX page on the server. 5) preserveExtraArgs - If this is set to true then the extra arguments that were passed to the hosting widget will be included in the sharing links. For instance, if there was an xmlUrl argument, the same argument will be present in the sharing links. Creating A Custom Sharing/GetThis** Note: Before you go to the trouble of doing a custom Get This, consider changing configuration on the existing one as described above. To create your own custom “Get This” panel, your widget HTML will need to be structured something like this: {stringify CustomGetThis} <div>This is where the HTML for your custom sharing template goes</div> CustomGetThis *(All your current widget code here)* ${% getBuzzFooter({getThisTemplate:CustomGetThis}) %} Note: you may also be able to use the configuration options with a custom template, if the custom template isn't too different from the default. Default Sharing/Get This Template The following HTML code, if placed in the above mentioned location, would yield the same sharing panel as the basic default sharing code. Use this as a starting point for your custom sharing panel, and modify it as needed. <div id="${GetThisBoxId}" class="ng_getThis" style="display:none"> <div style="background-color: #ebebeb; border: 1px #999999 solid; padding: 5px;"> <img alt="close" onclick="${HideGetThisJS}" src="${BuzzAppUrl}/Images/close.gif" style="float:right; cursor:pointer;" /> <strong>Add this to your site</strong> </div> <div style="margin:10px 0px 0px 0px; padding: 0px 5px;"> Want to put this widget on your blog or personal homepage? Choose your site from the list below. <div style="margin:5px 0px 0px 10px;"> {if /typepad/i.test(SharingOptions)}<div class="ng_getIcon"><a target="_blank" href="${TypepadLink}"><img border="0" align="absmiddle" alt="TypePad" src="${BuzzAppUrl}Images/typepad.gif"/> <strong>TypePad</strong></a></div>{/if} {if /blogger/i.test(SharingOptions)}<div class="ng_getIcon"><a target="_blank" href="${BloggerLink}"><img border="0" align="absmiddle" alt="Blogger" src="${BuzzAppUrl}Images/blogger.gif"/> <strong>Blogger</strong></a></div>{/if} {if /netvibes/i.test(SharingOptions)}<div class="ng_getIcon"><a target="_blank" href="${NetvibesLink}"><img border="0" align="absmiddle" alt="Netvibes" src="${BuzzAppUrl}Images/netvibes.gif"/> <strong>Netvibes</strong></a></div>{/if} {if /google/i.test(SharingOptions)}<div class="ng_getIcon"><a target="_blank" href="${GoogleLink}"><img border="0" align="absmiddle" alt="iGoogle" src="${BuzzAppUrl}Images/google.gif"/> <strong>iGoogle</strong></a></div>{/if} {if /pageflakes/i.test(SharingOptions)}<div class="ng_getIcon"><a target="_blank" href="${PageflakesLink}"><img border="0" align="absmiddle" alt="Pageflakes" src="${BuzzAppUrl}Images/Pageflakes.gif"/> <strong>Pageflakes</strong></a></div>{/if} {if /LiveDotCom/i.test(SharingOptions)}<div class="ng_getIcon"><a target="_blank" href="${LiveDotComLink}"><img border="0" align="absmiddle" alt="Live.com" src="${BuzzAppUrl}Images/LiveDotCom.gif"/> <strong>Live.com</strong></a></div>{/if} {if /LiveSpaces/i.test(SharingOptions)}<div class="ng_getIcon"><a target="_blank" href="${LiveSpacesLink}"><img border="0" align="absmiddle" alt="Live.com" src="${BuzzAppUrl}Images/LiveSpaces.gif"/> <strong>Live Spaces</strong></a></div>{/if} {if /Facebook/i.test(SharingOptions)}<div class="ng_getIcon"><a target="_blank" href="${FacebookLink}"><img border="0" align="absmiddle" alt="Facebook" src="${BuzzAppUrl}Images/Facebook.gif"/> <strong>Facebook</strong></a></div>{/if} '{if /Vista/i.test(SharingOptions)}<div class="ng_getIcon"><a target="_blank" href="${VistaLink}"><img border="0" align="absmiddle" alt="Vista Sidebar" src="${BuzzAppUrl}Images/Vista.gif"/> <strong>Vista</strong></a></div>{/if}\n' + </div> <br clear="all"/> </div> {var showScript = /script/i.test(SharingOptions)} {var showEmail = /email/i.test(SharingOptions)} {var showCreate = /create/i.test(SharingOptions)} {if showScript \|\| showEmail \|\| showCreate} <div style="padding: 0px 5px 5px 5px;"> {if showScript} <div style="margin-top:7px !important; margin-top:25px;"> Or copy the embed script code below and paste it on your website. <div style="margin:5px 0px 0px 10px;"> <span style="text-align:left;"><strong>Embed code:</strong> <input type="text" value="<script src="${EmbedScriptSrc}" type="text/javascript"></script>" onclick="this.focus();this.select();" /></span> </div> </div> {/if} {if showCreate} <div style="margin:10px 0px;"> <span class="ng_createNew"><a href="javascript:void(0)" onclick="${ShowSignupJS}">Create your own widget</a></span> </div> {/if} {if showEmail} <div style="margin:10px 0px;"> <span class="ng_createNew"><img src="${BuzzAppUrl}/images/send_friend.gif" onclick="${ShowEmailWidgetJS}" style="cursor:pointer" /></span> </div> {/if} <div class="ng_getThisTOS"> If you copy and use this Widget code for use on your website(s), you agree to the following terms and conditions found <a target="blank" href="${NGBaseUrl}admin/pages/legal.html">here</a>. </div> </div> {/if} <div align="center" style="border-top: 1px #999999 solid; padding-bottom: 5px; background-color: #000000; overflow: hidden;"> <a href="http://newsgatorwidgets.com" target="_blank"> <img src="${BuzzAppUrl}Images/poweredby_ng_black.gif" border="0" /> </a> </div> </div> Tokens Available The following tokens are available in the GetThis template, and have the same meaning as in the normal widget templates • ExtraArgs • BuzzId • OrgCode • ApiToken • BuzzAppUrl • NGBaseUrl • UniqueId • BuzzObj • BuzzObjJS • AttentionJS • AttentionClickJS The following tokens contain default links to the sharing sites. These will take into account the arguments passed into getBuzzFooter(). Eg, if you sent in a different BuzzId than the current widget, that will be used. They also include appropriate inheritance tracking GUIDs. • BloggerLink • TypepadLink • NetvibesLink • GoogleLink • PageflakesLink • EmbedScriptSrc • LiveSpacesLink • LiveDotComLink • FacebookLink • VistaLink The following tokens are functions for generating sharing links. They each expect a single object as an argument. The object will be used to generate the arguments to the child widget. This allows you to pass different arguments to the child widget than the ones the parent widget had. • GetBloggerLink • GetTypepadLink • GetNetvibesLink • GetGoogleLink • GetPageflakesLink • GetFacebookLink • GetEmbedScriptSrc • GetLiveSpacesLink • GetLiveDotComLink • GetFacebookLink • GetVistaLink • MyTrackingId - The tracking ID for the current widget. This should be used as the trkP for the child widget. • ChildTrackingId - The tracking ID that should be used as the trkM for the child widget. • GetThisBoxId - The ID used for the GetThis box container • SharingOptions - The sharing options string that was passed into getBuzzFooter(), or the default sharing options string. • EmailSharingTemplate - The custom email sharing template, or null if none was passed in. • ShowGetThisJS - A Javascript call to show the GetThis box. • HideGetThisJS - A Javascript call to hide the GetThis box. • ShowSignupJS - A Javascript call to show the "signup for Editor's Desk" popup. • ShowEmailWidgetJS - A Javascript call to show the "email this widget" popup. ***** Facebook Support** Facebook is somewhat supported out of the box. However, you must manually build a Facebook application first. You can add in the Facebook sharing option and fbApiKey to see the Facebook sharing icon. So basically it looks like this: ${% getBuzzFooter({ fbApiKey: "123abcd" }) %} ${% getBuzzFooter({ sharingOptions: "blogger, typepad, netvibes, facebook", fbApiKey:"123abcd" }) %}

Using the "ng_buzzContainer" to control the location and dimensions of popups

Fri, 23 May 2008 12:07:06 GMT

If you look at the HTML template for one of your widgets you may notice there’s a class “ng_buzzContainer” on the top-level element. You may also notice that there are no CSS styles attached to that class. So why is it there? This container exists so that the widget knows where to put popups. When the widget shows a popup such as an email dialog or the “Get This” dialog, it finds that node and places the popup over it.

This means a couple things to you as a widget author. First, be sure to leave the ng_buzzContainer class in the widget, or be sure to include it if you’re writing a widget from scratch. If you don’t have an element with that class, the widget will still try to show the popups appropriately, but it works a lot better if that class is there. If you don’t have it, your widget will be open to some odd rendering issues. For example your "Get This" dialog may stretch all the way accross your page. Or in IE6 standards mode, popups may render at the height of one line of text. ...and so forth.

Secondly, having this container intact means you can control where the popups appear. When the user clicks something that would cause a popup (eg, the email icon), the widget will start walking up the DOM from the node that was clicked. The first node it encounters with the ng_buzzContainer class is the one that the popup will cover. So, for instance, you could make the popup cover everything in your widget except the header and footer, or just cover one post. Note that you can have multiple elements with the ng_buzzContainer class, so different popups can be made to appear in different places if you’re clever.

Using the BuzzObj.renderTemplate() method for popups or other sub-templating processes

Fri, 23 May 2008 11:45:38 GMT

BuzzObj.renderTemplate()

The renderTemplate() function of the BuzzObj allows you to use the power of the TrimPath templating engine, as well as the modifiers and Built-ins provided by the Widget Framework, after the initial rendering of your widget is complete. It allows you to specify your own template text and provide any data you wish, and then returns to you the resulting string. This is useful for rendering popups and other interface elements, or for working with data from outside NewsGator which may not be ready when your widget is initially loaded.

Using renderTemplate()

renderTemplate() is a property of a particular BuzzObj. This is because it includes functions, such as ${AttentionJS()}, that use data from that widget. Therefore, you must have a reference to a BuzzObj to use renderTemplate(). If you plan to use renderTemplate(), be sure to save off a reference to your BuzzObj somewhere that you can get at it later.

Additionally, you’ll need a template to supply to renderTemplate(). This can come from anywhere, but for this example we’ll use the {stringify} block, which is described in another KB article.

renderTemplate() takes two arguments, the template to use and an optional data object to supply to the template. The data object you provide will be available inside the template under the name Data. renderTemplate() returns the string result of the templating process. Usually this will be HTML that you’ll want to insert into some element using the innerHTML property.

An Example

Create a new widget and paste in the following for the HTML and Javascript.

HTML Template:

{stringify SubTemplate}

        <ul>

        {for item in Data}

               <li>${item}</li>

        {/for}

        </ul>

        Rendered: ${(new Date())|format:"MM/dd/yyyy h:mm:ss a"}

SubTemplate



{eval}

        //Save reference to template

        BuzzObj.SubTemplate= SubTemplate;

{/eval}

<input type="button"

        onclick="ngDemo_showColors(${BuzzObjJS})" 

        value="Colors" />

<input type="button" 

        onclick="ngDemo_showStates(${BuzzObjJS})"     

        value="States" />

<br />



<div id="ngDemo_Target"></div>

Javascript:

function ngDemo_showStates(BuzzObj){

        var states = ["Colorado", "New York", "California", "Alaska"];

        var html = BuzzObj.renderTemplate(BuzzObj.SubTemplate, states);

        document.getElementById("ngDemo_Target").innerHTML = html;

}



function ngDemo_showColors(BuzzObj){

        var colors = ["red", "green", "blue", "magenta", "cyan"];

        var html = BuzzObj.renderTemplate(BuzzObj.SubTemplate, colors);

        document.getElementById("ngDemo_Target").innerHTML = html;

}

When you preview this widget, you should see two buttons. Clicking either of the buttons will render the colors or states, along with the current timestamp.

When Not To Use renderTemplate()

Note that you should not use renderTemplate() for the initial rendering of your widget. It is more appropriate to use {for} loops or {macro} blocks instead.

Using a {stringify} block in the HTML Template

Fri, 23 May 2008 10:23:53 GMT

The {stringify} block is a custom extension to the TrimPath parser used by NewsGator widgets. It turns everything inside the block into a Javascript string, which you can then use. As with other TrimPath block expressions, you can use any syntax you want inside of it, including newlines and curly braces.

Note that tokens and TrimPath expressions inside the {stringify} block are put into the resulting string verbatim – tokens will not be replaced with values, and TrimPath expressions will not be evaluated. This feature is similar to a TrimPath {cdata} block.

What Is It Good For?

The primary purpose for a {stringify} block is to get “subtemplates” into your widget. For instance, some complex widgets have a master widget with many subordinates. Using {stringify} with other features of the widget framework allows you to specify the template for the subordinate widgets inside the master, rather than copying it into each subordinate widget. Another example is for popups that are not rendered until they are needed, for instance in a Google Maps mashup.

In general it’s useful for long chunks of text that would be inconvenient to escape into Javascript strings.

How Do I Use It?

The syntax for a {stringify} block is similar to the long form used for a {cdata} block. It begins with a {stringify} statement that must also include a variable name. The variable name will contain the resulting string, and also acts as the delimited that closes the {stringify} block. Once again, the {stringify} block is closed by repeating the variable name used to open it, not with a closing {/stringify} statement.

For example, paste the following into the HTML Template section of your widget:

{stringify MyText}

This is a stringify block.

MyText

This will create a Javascript variable named “MyText” with the value “This is a stringify block”. Now, paste the following into the HTML Template section:

{stringify TextWithTokens}

This text includes

{if false}

TrimPath syntax:

{/if}

and tokens: ${Post.PostId}

TextWithTokens

{eval}

alert(TextWithTokens);

{/eval}

Now preview the template. You should see an alert box with the exact text inside the {stringify} block. Notice that it includes all the TrimPath syntax.

Note that the variable created by {stringify} is only visible within the context of the HTML template, unless you take steps to make it available elsewhere. One of the easiest ways to save it is to attach is to the BuzzObj for later retrieval. For example:

{stringify CheckboxTemplate}

…code here…

CheckboxTemplate

{eval}

BuzzObj.CheckboxTemplate = CheckboxTemplate;

{/eval}

Advantages Over HTML Elements

An effect similar to this can be accomplished by writing out an HTML <textarea>, <pre> or other element containing the text you want, and then reading that from the document using the element’s innerHTML property. However, this approach is harder than it at first seems. The text returned by innerHTML is not exactly the same as the text you put inside the element. Various browsers will remove quotes around some attributes, apply HTML escaping, eliminate or add tags and perform other modifications. This can lead to very difficult to detect bugs. {stringify} has none of these problems. There are also problems that, while solvable, make this approach unnecessarily difficult. You’ll be happier if you just use {stringify}.

Notes

{stringify} is especially well suited for use with the renderTemplate() function described elsewhere.

${BuzzObjJS} vs. BuzzObj

Thu, 22 May 2008 15:56:49 GMT

The difference between the ${BuzzObjJS} built-in and the BuzzObj built-in can be subtle. BuzzObj is a reference to a JavaScript object. If you were to write it out using ${BuzzObj}, you would probably see something like “[object]”, depending on your browser. That’s because BuzzObj is just a pointer, it has no textual representation.

${BuzzObjJS}, on the other hand, is nothing but text. To be precise, it is a piece of JavaScript code that would evaluate to the BuzzObj. So evaluating ${BuzzObjJS} in JavaScript gives you BuzzObj. If you were to write ${BuzzObjJS} out, you would see something like “ng.buzz.buzzlet_123456”.

That’s probably a bit confusing still, so let me give you some guidelines. You should use BuzzObj anytime you’re directly calling a JavaScript function, for instance from within an {eval} block. ${BuzzObjJS} should be used when you’re trying to write out a bit of HTML that calls back to the BuzzObj.

See the following example taken from a widget’s HTML template:

{eval}

//Note we need to use BuzzObj here because this is pure JS

BuzzObj.tabHandler = new TabHandler(BuzzObj);

{/eval}

<a href=”#” onclick=”${BuzzObjJS}.tabHandler.nextTab()”>

Next Tab

</a>

INF: NewsGator Ping Service

Mon, 19 May 2008 09:48:46 GMT

The information in this article applies to:

NewsGator Platform

NewsGator retrieves all feeds on a normal schedule. However, it is possible to request that a feed be updated ad hoc. This is accomplished by calling NewsGator’s ping service. This service can be called after new content has been added to a feed. NewsGator ping service supports REST and XMLRPC.

Subscription or Taxonomy Inclusion Required
There are a few simple requirements that must be met for the ping service to retrieve a feed. At least one user must be subscribed to the feed or the feed must be present in a known taxonomy within the NewsGator system.

Link vs. XmlUrl
Feeds usually provide two distinct URLs, one for the site or page where the feed lives, we refer to it as the Link. The other URL is for the raw feed, we call this one the XmlUrl. This distinction is important because it affects the way our system looks up feed information internally. Basic pings should pass in the Link. Our backend system will use the Link to look up and retrieve content from the XmlUrl.

Title: Greg Reinacker's Weblog
Link: http://www.rassoc.com/gregr/weblog
XmlUrl: http://www.rassoc.com/gregr/weblog/rss.aspx

Basic Ping vs. Extended Ping
This document covers basic ping functionality only. NewsGator does support extended ping functionality via XMLRPC, however since the ultimate result is the same, there is no need to send an extended ping. If you feel an extended ping is absolutely required, please content NewsGator Support for more information.

Ping Service Endpoint: http://services.newsgator.com/ngws/xmlrpcping.aspx
Authentication is not required.

REST
NewsGator supports GET requests only.

Endpoint: http://services.newsgator.com/ngws/xmlrpcping.aspx

Parameters
[Required]
name: Name of the feed
url: Link (not XmlUrl)

[Optional]
changesURL: Link (not XmlUrl)

Examples: http://services.newsgator.com/ngws/xmlrpcping.aspx?name=GregReinacker'sWeblog&url="http://www.rassoc.com/gregr/weblog"

http://services.newsgator.com/ngws/xmlrpcping.aspx?name=”GregReinacker'sWeblog”&url=”http://www.rassoc.com/gregr/weblog”&changesURL=”http://www.rassoc.com/gregr/weblog"

XMLRPC

Endpoint: http://services.newsgator.com/ngws/xmlrpcping.aspx

Parameters
[Required]
methodName:     weblogUpdates.ping
First value:          Name of the feed
Second value:     Link (not XmlUrl)

Request –

<?xml version="1.0"?>

<methodName>weblogUpdates.ping</methodName>

<param>

<value>Greg Reinacker's Weblog</value>

</param>

<param>

<value>http://www.rassoc.com/gregr/weblog</value>

</param>

</params>

</methodCall>

Response –

<?xml version='1.0'?>

<param>

<value>

<name>flerror</name>

</member>

<name>message</name>

<value>Thanks for the ping.</value>

</member>

</struct>

</value>

</param>

</params>

</methodResponse>

JavaScript section VS. {eval} section

Tue, 13 May 2008 12:23:56 GMT

There are several ways to write JavaScript into your widgets. The most obvious is to put code into the JavaScript pane in Editor’s Desk. The other option is to put script into an {eval} block inside your HTML template via the HTML pane. It is important to understand how the code is loaded and executed differently for these two approaches.

What is {eval}?

{eval} is a TrimPath construct that lets you put arbitrary JavaScript inside the HTML template. Any valid JavaScript can be put inside an {eval} block, including function definitions and calls to other functions. It also doesn’t have restrictions about using curly-braces, as the ${token} syntax does.

What’s the difference?

There are only a few differences between code coming from the JavaScript section and from an {eval} block.

1) JavaScript inside an {eval} block automatically has access to all the tokens, built-ins, and other widget goodness that we provide. JavaScript in the Script section does not.

2) JavaScript inside the Script section is evaluated and executed before your widget is loaded. JavaScript inside an {eval} block is executed during the templating process, after the data and styles for your widget have loaded.

3) Functions declared inside an {eval} block are only visible inside your widget’s template. External code, such as event handlers, cannot access those functions. Anything in the Script section is globally visible.

Which should I use?

95% of the time you want to use the Scripts section, simply because it’s easier to read and maintain. The primary reason to use an {eval} block instead is if you want to read or manipulate data that’s only visible from inside the HTML template.

The NewsGator Widget Framework: A Techincal Overview

Tue, 13 May 2008 08:04:17 GMT

Widget Framework Technical Overview

This document covers technical aspects of how widgets work and some possible ways to use them. Familiarity with HTML, Javascript and the browser loading process will be very helpful in understanding this document, particularly the Widget Script section.

Widget Lifecycle

The widget lifecycle begins when a browser loads an HTML page containing the widget’s script block. The script NewsGator sends to the browser bootstraps the widget. First the script document.write()’s out another script block to load the widget framework Javascript, and also write()’s an empty placeholder <div> that will later contain the widget’s HTML.

The initial loading script also contains the widget’s HTML template encoded in a Javascript string, and the code from the widget’s script section in Editor’s Desk. Notice that this means the widget’s Javascript is interpreted before the widget’s data is loaded, before the widget is rendered, and possibly even before the widget framework code is loaded. Your widget’s scripting code must be developed with this in mind.

The widget now appends a <LINK> element to document to load the widget’s styles, and requests the widget’s data from the NewsGator server. The widget then waits for the data to load. Once the data is loaded the widget’s HTML is rendered (see Widget Template section below) and inserted into the placeholder <div> that was created earlier. Finally, any callbacks registered via AddPostRenderCallback() are invoked, and a view event is logged to the NewsGator servers.

At this point the out-of-the-box widget framework is basically done. Of course the widget is still visible, and there may still be Javascript running for things like tabs or accordions. But the framework won’t do anything else, except for logging attention events as requested by the widget’s HTML and script code.

Widget Template

The widget template is written for a Javascript templating engine called TrimPath Javascript Templates, which is similar to other templating engines such as JST, ASP or Velocity. If you are a developer with a scripting background, you can gain a lot of insight by reading the TrimPath JST documentation, in particular the Syntax page. http://code.google.com/p/trimpath/wiki/JavaScriptTemplates.

In essence the TrimPath JST library turns your widget’s HTML template into a Javascript function that does a bunch of string concatentation. Control constructs such as {for} and {if} are turned into their Javascript equivalents. Tokens such as ${Post.Description} are turned into property accesses, with the properties converted into strings. Because the template is inside a function the Tokens and BuiltIns from Editor’s Desk are not automatically available to Javascript code outside the HTML template. However, it is possible to call out to other Javascript functions and pass tokens to them.

Note that you should not generally put <style> or <script> blocks inside your widget’s HTML template. Your widget’s HTML is inserted into the document using innerHTML and some browsers will not handle <style> or <script> tags correctly. Instead, you should always use the CSS and JavaScript panes in Editor’s Desk for these code elements.

Widget Styles

The widget styles are loaded in via a dynamic <LINK> tag appended to the head. Again, this means they’re on the same playing field as all the other styles on the page. Therefore, you need to think carefully about how you structure your selectors so that they don’t conflict with any other styles on the page. See the KB article on designing widgets for more details.

The widget framework sends your styles to the browser almost verbatim. The only exception is that we look for the ${BuzzId} token and replace it with your widgets actual numeric BuzzId (eg, 90213). This is just a straight string replacement – none of the other tokens or modifiers is available. Using the ${BuzzId} token on CSS selectors is a great way to ensure one widget’s style does not collide with another’s, since without it the two widgets would be very likely to have selectors with identical names.

Widget Script

Generally the widget’s script is loaded into the page as part of the initial widget script block. Note that the widget script is not modified at all, so it’s essentially the same as putting the script straight onto the page. This means that all the functions and variables in the widget script go into the global scope. Therefore, you need to be careful what function and variable names you use so they don’t conflict with the page’s Javascript or other widget’s scripts.

A simple approach to preventing collisions is to put all your Javascript inside one object with a unique name. For example:

var fakeCo_NewsWidget = {

myVariable : 1234,

myFunction : function(){

//do stuff

}

};

Referencing the widget object

Also note that your scripts do not automatically get a reference to the widget object or data. If you need that reference for any reason you should make a Javascript call from within the HTML template to pass that value, as in the following example:

From the Javascript pane:

var fakeCo_NewsWidget = {

buzzObj : null,

initialize : function(buzzObj){

this.buzzObj = buzzObj;

}

};

From the HTML pane:

{eval}

fakeCo_NewsWidget.initialize(BuzzObj);

{/eval}

Note that you can also pass other values out from the HTML template, for example the Posts array or the UniqueName token.

Saving objects into the widget

Sometimes it can be helpful to save references to other Javascript objects into the widget object. For example, some tabbed widgets create an object to handle hiding and showing the tabs, and it can be useful to call methods on that object later.

Javascript allows you to create new properties on objects as you go. For example:

From the HTML pane:

{eval}
BuzzObj.tabHandler = new TabHandler();

{/eval}

Widget Data

Most widgets load data from Editor’s Desk. The data is a Javascript array of objects representing posts. Exactly which posts you get is determined by the settings of the Content section of Editor’s Desk. Note that the posts are loaded from NewsGator’s database – they are not pulled from the source feed each time a widget loads.

The Data token is nothing more than a Javascript array of objects. This means that you can manipulate the posts before rendering them. For example, the NewsBar default template throws out posts with bad FeedNames before rendering them. You could also do things like reorder the posts to group them by feed before showing them. For example:

From the Javascript pane:

function sortByFeedId(a, b){

if(a.FeedId != b.FeedId){

return (a.FeedId - b.FeedId);

} else {

return (a.Title < b.Title ? -1 : 1);

}

From the HTML pane:

{eval}

Data.sort(sortByFeedId);

{/eval}

{for Post in Data}

{/for}

How to ensure that your feed items get displayed in the proper order

Mon, 12 May 2008 12:59:54 GMT

RSS does not have any inherent ordering capabilities in the specification, just because you put items into a feed in a specific order does not mean they will come out that way after being processed by our (or any other) aggregator...

There are three ways to get around this.

1. Use publish dates in the RSS feed.

By default, most aggregators order items in a feed by the published date, with the most recent content presented first.
Note that badly formatted pubdates can be just as bad as not having a pubdate. We try very hard to parse pubdates, but if we can't parse your pubdate we will ignore it. To be safe you should try to conform to a published standard such as ISO 8601.

2. Use Simple List Extensions (SLE) in the feed to create what is known as a “list feed”.

NewsGator supports Microsoft’s SLE extensions to the RSS spec. This is used to create a feed that acts like an ordered list of posts. Posts can be moved to different spots in the list (think of a billboard top 40 music feed).

For more detail: http://blogs.msdn.com/rssteam/archive/2006/03/29/564154.aspx

3. Use NewsGator’s “Manage Posts” feature in Editor’s Desk to order content within Editor’s Desk. Administrators can order posts manually using the “handpicked articles” feature within the Manage Posts utility.

Things to consider when designing your widgets

Mon, 12 May 2008 12:57:22 GMT

Designing Widgets

Designing widgets, especially viral widgets, may be an unfamiliar challenge for many designers. Unlike most HTML designs, widget designs must work well on a number of different web sites. Even worse, the content of the posts within the widget may be unknown. Following are some general guidelines for designing widgets and implementing them in HTML and CSS.

Dealing With Host Pages

Viral widgets will be placed on a huge number of web pages that you don’t know anything about and have absolutely no control over. The pages will use HTML4, XHTML Transitional or XHTML Strict or maybe even HTML5. They might have a DOCTYPE that puts the browser into standards mode or they might leave the browser in quirks mode. They might use CSS to redefine the appearance of basic HTML elements. They will place your widget in odd places on their page.

Because host pages are so unpredictable, dealing with them can be the biggest challenge in designing and coding a widget. You must try to predict what could go wrong with the widget and try to code defensively to avoid problems. The following guidelines will help you on your way.

Avoid complex designs if possible, particularly designs using floats. It can be very difficult to make these layouts work in the face of quirks/standards mode changes and varying CSS rules from the host page. Instead, consider using table-based layouts. Yes, it’s so last century and all the cool designers are using floats, but tables are very predictable across all browsers and in nearly all circumstances.

Some pages, notably Blogger sidebars, use CSS ID selectors that will override CSS class selectors. Therefore you should wrap your entire widget in an element with a carefully chosen ID, and base all your selectors on that ID. For instance, #NewsCo_Photo_Widget_${BuzzId} .title_${BuzzId}. Note that the ${BuzzId} token is used in both the ID and the class name. This protects against overlapping styles from styles on the host page as well similar widgets that may be on the page. This one change may save you enormous amounts of testing and rework time.

Define any CSS styles you use, even those that you use implicitly. For instance it’s good practice to define text-align:left, even though that’s the default, because some blog sidebars may have a different default alignment. Other commonly overlooked styles are color, background-color, font-family and font-size.

Remember that you don’t know whether your widget will be placed on the page. It may be in the center or up against the left or right side of the page. It may also be inside an <IFRAME> just large enough to contain it, as is the case with iGoogle. Therefore it is not wise to create flyouts to show article details or ads.

The amount of horizontal space available to you will vary as well, from 170px in a Typepad sidebar up to as much 800px in the center well of a page. This means you must be careful about using large images. If an image can be made that will work in any size you can make it the background image on an element. That way the browser will show as much as possible while still fitting into the available space. Just remember to make sure the image will make sense in all sizes.

Dealing with Content

If you are using content from feeds that you don’t control consider what might be in the posts. Sometimes posts contain large images, long words or URLs that won’t wrap properly, or other odd HTML Frequently your best bet is to use the stripHTML modifier to remove all HTML from the post Description.

Posts may also have very long descriptions. Some posts descriptions run to several pages of text. So it’s a good idea to use the excerpt modifier to ensure posts don’t go on for too long.

If you are counting on photo or video content in your widget remember that posts do not always have media attached. Even in feeds that nearly always have media there may sometime be a post without media, so be sure to use {if} statements to ensure that the media is available.

Javascript

Writing Javascript code for widgets will be the topic of another article. But remember that your Javascript code is loaded into the global context along with all the other Javascript on that page. Therefore you must be careful about naming your functions and variables because they might conflict with other functions on the page.

The simple solution is to use very uncommon names. A more advanced solution is to use a closure or custom class.

How to write an RSS feed: The industry standard specs

Mon, 12 May 2008 12:01:25 GMT

We generally rely on the RSS 2.0 Specifications as published by the Harvard Law School for guidelines on how we expect the feeds we interact with to be written.

It's also important to note that some of the fields that are defined as optional by the specs, are actually very important to the way that we process the content.

For example, <pubDate> is defined as an optional element in the RSS spec. But feeds that do not provide pubdates are highly susceptible to a number of problems. We always give a pubdate when serving post content from our system, so if the publisher does not provide one, we assign it one equal to the date and time that we pulled it into our system. If a feed with many old posts but no pubdates is introduced into our system for the first time today, we will mark all posts as having today as their pubdate. This can cause some unwanted behavior in widgets, readers, client applications, or API based applications. Also, if we cannot read from your feed for whatever reason (your feed has some malformed XML, or your server is down) for a period of time spanning several new post publications, the same type of problem will occur the next time we successfully find the new posts and pubdates are not supplied.

Note that badly formatted pubdates can be just as bad as not having a pubdate. We try very hard to parse pubdates, but if we can't parse your pubdate we will ignore it. To be safe you should try to conform to a published standard such as ISO 8601.

Also be sure your pubdate includes a timezone. If it doesn't include a timezone we will assume it's in the US Mountain Timezone.

Another essential element for us is the <guid>. This is also defined as optional, but again, non-use or improper use opens your feed to a number of unwanted behaviors. The most likely of which is the introduction of "duplicate" posts whenever edits are made (see "Editing a post item in an RSS feed" for more on this).

How do I begin to put together a list of feeds to offer or promote on my site?

Fri, 09 May 2008 13:46:12 GMT

The way that you make feeds available to your readers is through a collection of feeds called a taxonomy. This is a set of feeds of your choosing, organized into categories for your readers to browse through, and subscribe to. The administration console has a tool called the “Taxonomy Manager” that provides an interface for configuring your taxonomy.

If you need to find feeds to put into your taxonomy, you can go to the NewsGator Online reader (http://www.newsgator.com) and browse through the categories offered in our taxonomy.

Using NewsGator’s Online reader is also a great way to build and organize your initial taxonomy. This can be done by using an account’s subscription list to provide the structure of folders (categories) and feeds that your taxonomy will offer. You can use an existing account, or you can create one specifically for this purpose. Once you have created your category folders, and populated them with feeds, you can export your subscription list as an OPML file (see INF: How to export your subscriptions (OPML) from NewsGator Online). Next, import that OPML file into the Taxonomy Manager in the admin console. Now you have a base taxonomy that you can make changes to through the admin site.

If you have additional questions, or need personalized help on this topic, please send an email to Private Label Support.

DOC: NewsGator Client Upgrades

Fri, 09 May 2008 13:45:13 GMT

The information in this article applies to:

FeedDemon 2.5+
NetNewsWire 3.1+
NewsGator Inbox 3.0+
NewsGator Go!

Am I eligible for an Upgrade?

On Jan 9, 2008 NewsGator Technologies announced that all clients are now Free!

Upgrades are now unrestricted for all users.