Getting Started with Flash Atom

Welcome! I'm very pleased that you have chosen to use the Flash Atom Readers from TUFaT.com for your news syndication. This document will provide you with a few guidelines to get you started.

Your Atom download includes everything that you see in the online demo, as well as the Flash 2004 Professional source code (.fla and .as files). Let's suppose that you want to put one of the Atom readers in your web page. We'll use the third Atom reader from set #1 in our example.

Step 1: Specify Atom URL

Locate the "config.xml" file for the Atom reader that you want to use (#3 from set 1 in my case), and open it using a good text editor like Textpad. If you are using Atom set #1, the config.xml file for each applet is located in the "deploy" subfolder. In the config.xml file, locate this tag:

<atomfeedurl><![CDATA[ http://eastethnia.blogspot.com/atom.xml ]]></atomfeedurl>

If you are using an earlier version of these Atom feeds, the RSS URL may be located in "index.html" as a Flash <param>. Please note that there are TWO locations where the Atom feed should be set in such cases, as underlined below:

This is where the Atom URL should be set. Be sure to specify the full HTTP path. If the applet uses "feedList.xml", then this tag will be in that file instead of config.xml.

Some of the Atom readers allow you to have multiple feeds loaded simultaneously, as in the first Atom reader from set 1. The HTML from these readers looks more like this:

In this case, you would open the "feedList.xml" file and manually input the Atom URLs. As you can see, it's quite self-explanatory. The menuLabel is what is displayed as the Atom feed title, and the linkURL is the actual Atom data source.

<feed>
    <menuLabel>Apple</menuLabel>
    <linkURL><![CDATA[ http://eastethnia.blogspot.com/atom.xml ]]></linkURL>
</feed>

If you are using version 1.0 of these Atom readers, the tags from feedList.xml may look something like this instead (same concept, just slightly different format):

<feed>
    <menuLabel>Perez Hilton</menuLabel>
    <linkURL>http://www.perezhilton.com/atom.xml</linkURL>
</feed>

You should always re-test your Atom reader after every change, by re-uploading to your web server. If you get "undefined" errors in your Atom reader, this might mean that your website administrator has disabled remote URL fetching in PHP. These Atom readers use a file called "rssProxy.php" to retrieve the Atom data. This requires a command that looks something like this:

readfile( $feedURL );

You can check to ensure that remote URL fetching is allowed by doing the following: open proxy.php and change $feedURL to your actual Atom URL, surrounded by quotes. Like this:

readfile( "http://eastethnia.blogspot.com/atom.xml" );

Then, open proxy.php directly using your web browser, by typing the full http:// path to proxy.php into your browser's address bar. You should see a large amount of XML data in your browser. After you've confirmed that remote URL fetching is available on your web server, be sure to change this file back to its original content.

If you get an error like this one, then you should contact your web host and ask to have URL file-access enabled.

Warning: readfile(): URL file-access is disabled in the server configuration in /home/rss2/rssReader01/deploy/proxy.php

If your Atom feed still will not load, try validating the feed at: http://www.feedvalidator.org/ These Atom readers require that the feed be an XML-based Atom 2.0-compliant feed. This is a very strict requirement. A feed is "valid" if it conforms to the Atom 2.0 specification.

Step 2: Configure Options

Each of the TUFaT.com Atom Readers includes an XML configuration file, usually titled "config.xml". Editing this file is entirely optional, but if you do choose to edit it, please use a good text editor like Textpad. You should not use Dreamweaver or Frontpage! You'll see a lot of options like these:

<titleText>
    <fontFace>Arial CE</fontFace>
    <fontSize>11</fontSize>
    <fontColor>990033</fontColor>
    <fontROColor>204279</fontROColor>
    <bold>true</bold>
    <italic>false</italic>
    <underline>true</underline>
</titleText>

I won't go over what all of these mean, since there are a lot and they are fairly self-explanatory. If you're not sure what an option does, try changing it and re-load the Atom reader. If you don't see any change, then the option may control something that is not very obvious, like refresh delay.

One option that most users need is the ability to control the link target of the Atom news links. In other words, when a user clicks on a link in the Atom reader, should a new browser window open, or should the link open into the same window? This can be changed using the "urlTarget" option at the bottom of the config.xml file:

<urlTarget>_blank</urlTarget>

Possible options include _blank, _self, _parent, _top, or a "named" window.

If you see "RO" in the name of an XML option, that probably refers to a rollover behavior - i.e., the behavior observed when the mouse is positioned over a link. Lines from the config.xml file that begin with <!-- and end with --> are comments, not actual configuration items.

Of course, the most important configuration option is the Atom Feed URL tag which, as previously noted, would be located either in config.xml or feedList.xml, depending on the Atom reader that is used. Or, if using version 1.0, it's in the HTML file as a <param> tag (see above).

<rssfeedurl><![CDATA[ http://eastethnia.blogspot.com/atom.xml ]]></rssfeedurl>

Step 3: Embed in Your Website

Do you remember that HTML from Step 1? The code that begins with <object> and ends with </object>? You should copy/paste that entire block of code into your website template. You should not use Dreamweaver or Frontpage to do this. Use Textpad so to directly edit the HTML source code. I strongly advise that you have someone with a strong knowledge of HTML do this for you. Then, copy the config.xml file and the SWF file to the same directory as the HTML.

I've embedded the <object> block on this page for example (you can do a View... Source on your web browser to inspect the code):

Thanks for your patronage of TUFaT.com, and good luck! These Atom Readers are (c) 2005 - 2007, and are not for re-sale or re-distribution. You may use them on your own website, but please do not compete with TUFaT.com in the sale or distribution of the applets! It's only by honoring this that I can keep these applets inexpensive.

thanks!
Darren