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:

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.Â

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:

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:

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.

Putting a new release out is always a high pressure time, so many things to do and check and then worry about whether you’ve got everything right. It typically comes at the end of long days of coding, getting everything you want to get into a release, in place and tested. The biggest concern is always whether you’ve slipped up somewhere and the release has got a problem which will cause your users some grief. The first 24-48 hours of a new release are usually my most restless and even though I’ve been doing this for a long time, the trepidation is ever present.

I’m pleased to say that most releases go without a hitch, which is just how it should be.Â The last release V1.96.0.0 fell a bit short though, with two quite serious problems being revealed. The first was that keys like Enter and Del didn’t work during articleÂ editing, if you started editing via. the slow click method. Fortunately if you started editing by clickingÂ the pencil or any of the other methods, everything worked properly, so there was a straightforward workaround. This problem occurred because of the changes (improvements) I’d made to the HTML editing code, and it simply didn’t show up in my testing.

The second problem was of greater concern, and it turned out had been around forever. As you probably know you can add content to Surfulater while it is hidden away in the Windows System Tray. When you work this way a small notification windowÂ appears above theÂ System Tray and informs you thatÂ contentÂ has been saved and where, then after 5 seconds it disappears.

Â

I’d had a few reports saying theÂ notification window would stay around for a minute or so instead of 5 seconds, however I’d never been able to reproduce this. To make things more difficult it seemed to only occur when certain other unknown software was running. This all changed with the V1.96.0.0 release when Dan Lucas reported a related problem where his web Browser was loosing focus when the notification window appeared. I wasn’t able to replicate this problem either, however I did finally get to see the problem with the window not closing and content not being captured, which I have to say I was pleased to see.

It turned out that the fix for the window not closing took all of a few minutes to implement, but Dan’s problem of the Browser loosing focus took another whole day. I had a fair idea why this might happen, but I was working in the dark because I couldn’t see it for myself. Dan was a fantastic help and let me send him some pre-release versions, to verify I had indeed resolved the issue.

Long story short, new releases are always a trying time for us software developers. These days the Internet is a huge boon though, as we can quckly turn around a new release and get it in your hands.

So this release is, as I said in the release notes, primarily to fix a few pesky problems in the V1.96.0.0 release.Â IÂ also took this as an opportunity to squeeze in a few other things that I wanted to get into the last release, but had run our of time, plusÂ some bits and pieces. See the release notes here and in the Help for full details.

My clock tells me it is now 26 and a bitÂ hours since V1.96.2.0 was released and so far it has been smooth sailing. Hopefully the release seas will remain calm for a time.

It’s here, and just in time for Easter. As I mentioned in my last blog post the latest Surfulater release somehow got away from me, delaying its release more than I like. I try to get a new release out about every 4-6 weeks and have been reasonably successful at that so far.

There are several reasonsÂ why this releaseÂ tookÂ longer. FirstÂ researching the requirements to import bookmarks from seven different sources was time consuming, as was testing. Next we’ve had some greatÂ new users come on board these pastÂ few months and this resulted in higher levels of forum activity and direct communications. All great stuff, but there are only so many hoursÂ in the day, so something has to give. Then there has been other diversions such as the great Tucows review and OnFolio being purchased by Microsoft, leaving some users contemplating its future, worrying about their data, and looking at alternatives like Surfulater. And finally the list of things I wanted to do for this release kept on growing, as you’ll see by the over 40 items in the release notes. The good news is that it is out and I can breath a sigh of relief and have a bit of an easter break.

But before I do, I’ll run through some of the new features in this release.

The ability to import bookmarks has been on the todo list for a quite some time. Many of you will have read of my reluctance to clutter Surfulater with hundreds or evenÂ thousands of bookmarks (one person told me he has over 10,000), but as you will see I finally relented. This is the new File|Import sub-menu:

From here you can import bookmarks from Mozilla Firefox, Internet Explorer and any application that can Export bookmarks in either Netscape or XBEL Bookmark formats. For the latter I’ve specifically included support for Compass, Linkman and Powermarks programs. See the Help topic Power Features | Importing Bookmarks for more information.

The Web Browser context menu includes a new item to enable you to Bookmark web pages in Surfulater as shown here:

Â

Â

Next I spent quite a chunk of time improving the user interface for content editing and fixing related problems as reported by Mark Vincenzes and others.Â Â Improvements include a dotted outline around the field that has focus as shown here:

When anÂ articleÂ field has focus you can press F2Â or left click to edit the field. If you left clicked to give the field focus in the first place, you need to wait about .5 of a second before clicking a second time. The behaviour of Tab and BackTab (Shift+Tab) have also been improved. They now move the focus to the next or previous field within an article. Finally if you’ve made editing changes and press Escape you are now given options to save the changes, discard them or continue editing. Further improvements are also slated. See the Release Notes for full details.

Briefly moving back to Bookmarks, you will see that they include a new Rating field. As you hoverÂ your mouse over the rating stars, they change color to indicate their potential new setting. The selected rating is also displayed in a popup tip and on the status bar.

To lock a rating in,Â click onÂ a star and the colors of the selected stars change again to indicate their final setting.

I’ve only added the Rating field to the new Bookmark article template, however it is easily added to any template. You’ll be able to search Ratings when Advanced Search is implemented.Â

The Bookmark template also includesÂ Modified and Visited fields which can also be used in other templates. Also note that the collapsed Bookmark layout in the content window differs to the other article templates in that it includes the Web address and doesn’t allow editing. There is also a new Note article template with its own characteristics. All of this highlights the flexibility inherent in Surfulater’s design.

IÂ want to touch on two final updates before I call it a day.

First approximately 40 new images have been added to the Knowledge Tree image selection palette. I’ve also updated a number of images with complimentary, but better looking images. Again see the release notes for full details.

Â

And last but not least the XML Clipboard Format that Surfulater uses to capture content from other applications has been updated to enable better integration withÂ applications other than Web Browsers. This is the result ofÂ lengthy Forum and private discussions between Perry Mowbray and myself. I intend to write aÂ Blog post detailing theÂ updated format in the next few days.

I’ve only covered the main updates in V1.96.0.0 here, so ensure you read the release notes in the Help (and in the Forums) to get the complete picture.

In case you are wondering what is happening in the world of Surfulater right now I have good news and good news. The next release is very, very close with important new features such as the ability to Import Bookmarks from Browsers and from a range of Bookmarking programs including Linkman, Compass and PowerMarks,Â along with a new Bookmark article template and a range of other goodies. The release notes are shaping up to be the longest so far!

This is a partial screen grab of the new Bookmark template:

This release has taken on a bit of a life of its own and because of that it is coming out later thanÂ scheduled. This has alsoÂ put meÂ behind on posting here on the blog which is really frustrating as I’m bursting with things I want to write about.

The bottom line is that I’m wrapping up the last few loose ends, then I need to update the Help and then release. I’ll be disappointed if it isn’t released by the end of this week.