Month: April 2006

In Part 1 of this article I showed you how Surfulater’s XML Clipboard Format (SXCF) enables programs to add content to Surfulater. In this second and final part I’ll describe the SXCF in details.

For those familiar with XML you will see that SXCF is XML without an XML declaration or DTD. If you are interested in learning about XML, the Web has plenty of information available. This XML Tutorial is a reasonable starting point.

An SXCF record always starts and ends with:

<SULCONTENT [attributes]>
</SULCONTENT>

attributes consists of a series of compulsory and optional XML attributes which tell Surfulater where the content is coming from, and what to do with it. For example:

action=”add” source=”Clipboard” template=”Clipboard”

tells us to “add” a new article, using the “Clipboard” article template, and that the content has come from the “Clipboard”.

XML elements inside of <SULCONTENT> </SULCONTENT> provide the actual content to add, for each field in an Article, as well as providing additional content like MetaDescription and MetaKeywords, from a Web page.

The XML elements which specify content for a field in an article use the fields name as their element name. eg.

<Title>title text goes here</Title>

In this example the name Title in the XML <Title> element is the name of the article field to place the text “title text goes here”, in.

Article field names are specified in their corresponding HTML Article Template. These field names are typically the same name that you see displayed in Surfulater, but don’t have to be. If you look at an Article Template you will see each field is defined something like this:

<td class=”prompts1″>Title
</td>
<td class=”editbar”>
<img src=”pencil.gif” mce_src=”pencil.gif” idedit=”FLD.Title” />
</td>
<td class=”normal” >
<div class=”celldiv” id=”FLD.Title” />
</td>

The first Title is what’s displayed in the content window. This isn’t the field name. The actual field name is in the <div id=”FLD.Title” ..  /> element. It is this name, after the prefix FLD or FCV that must match the SXCF field name.

Note that I’ve pared this template example down so we can focus on the parts which are important to this discussion.

Handling HTML Markup

Field content that includes HTML markup must be treated in a special way, otherwise it will be processed as XML, instead of HTML. If you look back at Example 2 in Part 1 you will see that the field content inside the <Text> element starts with <![CDATA[ and ends with ]]> This enables normal HTML content to be used within the XML. If CDATA isn’t used, the HTML tags would be treated as XML elements and the result would be a big mess.

The best approach is to always use <![CDATA[ … ]]> for field content, even if it doesn’t include any HTML. See XML CDATA for more information.

Attaching files to Articles 

SXCF elements that contain Surfulater field content include the ability to specify files to store in a Surfulater database. In other words attachments. A standard HTML link to a file looks like this:

<a href=”file://my_test.doc” mce_href=”file://my_test.doc” >

by including an attach=”true” attribute Surfulater will load the specified file and embed it in the database eg. 

<a href=”file://my_test.doc” mce_href=”file://my_test.doc” attach=”true”>

This is used in Example 2 in Part 1

Predefined SXCF Elements 

SXCF implements these predefined XML elements:

<URL></URL>

Attach the specified Web page to the article’s Attachment field. Note that this is only used for attaching Web pages, not files. It is used in conjunction with the action attribute as described below.

<MetaDescription></MetaDescription>

Contains the MetaDescription content from captured Web content. This is not currently used by Surfulater.

<MetaKeywords></MetaKeywords>

Contains the MetaKeywords content from captured Web content. This is not currently used by Surfulater.

<BASE></BASE>

Contains the <BASE href =…> value from the captured Web content. This is used locate HTML items referenced in the content, in the same way it is used in your Browser.

The <SULCONTENT [attributes]> in detail.

Name	Value	Definition
action		Determines how to use the specified SXCF information as follows
action	add	Add a new record
action	attach	Attach content to current record. Only used to attach Web Pages as of 26 Apr 2006
action	update	Reserved for future use
Â
source		Specifies the source of the SXCF information as follows:
source	WebBrowser	Content is being sent from a Web Browser
source	Clipboard	Content is coming from the Clipboard. i.e.. From some other program.
source	UserDirect	Content comes from Surfulater itself. This is only used by Surfulater.
Â
source_application		Provides extra information on the ‘source’ provider.
source_application	InternetExplorer	Content is from IE
source_application	Firefox	Content is from Mozilla Firefox
source_application	MSWord	Content is from Microsoft Word or some other Windows Application
Â
The following attributes are optional.
template	HTML template name	The name of the article template to use for creating this article. If it isn’t specified, the IE template is used. If the specified template doesn’t exist the article won’t be created. (1)
thumbnail	filename	The full path and filename of the thumbnail image to use for the article. The IE template is the only one to include a thumbnail. The other templates can be changed to include a thumbnail as can newly created templates.
deletethumbnail	true | false	If true or not specified the thumbnail image file is deleted once the article is created. false prevents it from being deleted.
emptytextok	true | false	Indicates main text field can be empty. If false or not specified and the text field is empty a notification popup tip will be displayed.

 

This should explain everything you need to start pushing content to Surfulater. It may seem a bit overwhelming at first glance, but if you look back at the examples in Part 1 they really are pretty simple. And of course if you need any help post here or in our support forums.

I mentioned a few posts back that parts of Surfulater had taken on a life of their own. Well SXCF was one such part, and there is still more to be done. For example Perry is pushing for the SXCF to be able to replace an existing attached file with a newer one, which I agree with. Other capabilities include the ability to append content to field in an existing article, or replace it completely. SXCF provides a solid foundation to build these and other capabilities on.

Surfulater provides a simple method to enable content to be added to it from other applications (think MS Word etc.) via. the Windows Clipboard. This was developed for Surfulater’s our own internal use, and has now been extended and opened up following user discussions on our Support Forums.

This is accomplished though a simple, clearly defined format, that enables anyone to add new content to Surfulater, in an open extensible way. As an example one of our Surfulater users, Perry Mowbray, has used this to write an add-in for Microsoft Word that enables Word users to add new content to Surfulater.

In essence whenever Surfulater is running it keeps an eye on information that gets placed into the Windows Clipboard, and if it sees something destined for it, it grabs it and creates a nice new article. For this to work the information placed into the Clipboard needs to follow some simple rules. Lets start with an example:

<SULCONTENT action=”add” source=”Clipboard” template=”Clipboard”>
 <Title>Example 1</Title>
 <Text>Some text for example one</Text>
</SULCONTENT>

This is about as simple as it gets. To try it for yourself, start Surfulater, then right click and choose Save Target As.. on this file and save it as SXCF_Example1.txt Next open the file in Windows Notepad, use Edit|Select All, and then Edit|Copy, to copy it to the Windows Clipboard. Surfulater will pick this up and create the following article:

 
Now for something more complex:

<SULCONTENT action=”add” source=”WebBrowser” source_application=”InternetExplorer” template=”IE” thumbnail=””>
        <Title>Mini HDD</Title>
 <Text><![CDATA[<TR><TH width=”100%” bgColor=#d5d6d5><FONT face=Arial,Helvetica size=2>Tiny
                hard drive garners Guinness World Record as smallest HDD</FONT></TH></TR>
                <TR><TD width=”100%” height=20><FONT face=Arial,Helvetica size=2>Mar. 17, 2004</FONT> —
                <FONT face=Arial,Helvetica size=2><IMG hspace=10 src=”http://deviceforge.com/files/misc/toshiba-tinyhd-thm.jpg” mce_src=”http://deviceforge.com/files/misc/toshiba-tinyhd-thm.jpg”
                align=left vspace=5>Toshiba announced this week that Guinness World
                Records has certified its 0.85-inch hard disk drive (HDD) as the smallest
                HDD in the world. Toshiba claims its 0.85-inch HDD, announced in
                January 2004, is the first HDD to deliver multi-gigabyte data
                storage in a sub-one-inch form factor.</FONT>
                <A href=”http://deviceforge.com/news/NS8560517030.html” mce_href=”http://deviceforge.com/news/NS8560517030.html” >
                <IMG src=”http://deviceforge.com/images/readmore.gif” mce_src=”http://deviceforge.com/images/readmore.gif” align=right border=0></A>
                </TD></TR>]]>
        </Text>
 <Reference><![CDATA[<A href=”http://deviceforge.com/news/200404120922NS2297227508.html” mce_href=”http://deviceforge.com/news/200404120922NS2297227508.html” >
                   http://deviceforge.com/news/200404120922NS2297227508.html</A>]]>
        </Reference>
 <Comments>This is a copy of an article included in the sample Knowledge Base included with Surfulater.
 </Comments>
 <Attachments><![CDATA[I’ve also attached a MS Word Document located on my PC <a href=”file://d:/saig/bin6/test1.doc” mce_href=”file://d:/saig/bin6/test1.doc” attach=”true”>
                     test1.doc</a> Neat huh!]]>
        </Attachments>
</SULCONTENT>

This is a copy of an article from the sample Knowledge Base included with Surfulater, along with some extra content; a Comment and an Attachment. Perform the steps outlined above on this file, SXCF_Example2.txt  to see the result for yourself. The Attachment will be missing unless you just so happen to have a file d:\saig\bin6\test1.doc  And this is what it looks like.

These examples should clearly show the capabilities on offer with Surfulater’s XML Clipboard Format.  I have to say that I think this is pretty neat stuff, not rocket science, but impressive none the less.

In Part 2 of this article I’ll explain the SXCF in detail, enabling you to use it your own applications or in program add-ons.

Note: The examples above and the content of these articles require Surfulater V1.96.0.0 or later.