KNotations

Funny how these little bells and whistles can seem o=unimportant until you start creating content yourself :o)

I've long known that we should do something about logging the pings hat the trackback machinery attempts to send out. A trackback 'ping' is a little request we make to a trackback-aware server's "trackback:ping" url for their content we are linked to. That request includes the data about our own content. The other server can, if so configured, use that data - for instance to display a link back to our content's commentary on theirs.

[ASIDE] - This is an extremely trivial note, of the sort that I write up as firstClass conference messages dozens of times every day. I'm posting it here because I'm trying to experiment with making our development notes more publicly visible, and also because in this case it kind-of documents the sidebar-collapsible feature and some design decisions which other developers ought to know about :O)

I find it annoying that the sidebars are all expanded while the page is loading, and then those which are cookie-d to collapse do so after page load. It makes an odd and suddent transition in what the user sees, and makes 'pre-scrolling' very confusing. In case you didn;t know, the sidebars are each collapsible (click the little box icon to the left to toggle this), and the preferences are kept as a cookie. See the screenshots for before and after views o the sidebars during pageload.

There is no need for this - we could easily set up actual display:none style rules before the page content loads instead of acting on the DOM nodes in javascript after pageload. That is, we dynamically write style rules into a little style block which come above the markup for the sidebars, and which declare that certain of the sidebars have the rule display:none applied to them ( the cookie specifies the id's for the selectors )

There are 2 choices for when/how to create the style rules:

1. analyse the cookie in zpt at the server, and write in the style rules in the markup, or
2. write them in javascript dynamically as the page loads in the client but before the sidebars are loaded

Option 2 is best since the cookie only makes sense if js is enabled; otheriwise css-on + js-off could hide content irrevocably

Also ZPT is darned awkward for writing style rules. It is easier to generate css rules as text in javascript and write them into the page than it is to use zpt :O)

I recommend having a bit of js-written styling just before the sidebars ( so the main content loads that little bit faster above them )

I'll do that tomorrow morning.

While I'm at it I'll have an initial look at having the categories sidebar written in js as a tree reflecting the categorical facets hierarchy. We found out today that very long category facet-chains cause a styling glitch in MSIE/win, and I've been meaning to make a js at clientside tree render / drop-down render for the categories for ages.

During PageLoad - all expanded	After PageLoad - some expanded

Those who follow this blog know that we've been planning to expand the range and features of the syndication feeds from Knotes content. The biggest priorities were:

filecasting ('podcasting'... doc-casting)

- delivering file attachments as enclosures ready to download directly from a news reader. In the case of audio or video files, this is usually called 'podcasting'

'full' content feed

Many users now prefer to experience web content almost exclusively through their newsreader of choice; not only reading content without viewing it in a browser, but also invoking editors to bookmark or blog about that content without viewing it on the web. To accomodate this growing preference, many blog publishers now offer 'full content' feeds. In the case of KNotes content, which has a lead-in/summary, main body text and extended-text, we would assume that the extended text should be excluded from 'full' content in feeds, just as it is in our aggregate web views - we'll call this 'full-minus-extended-text' the "main content" of an entry.

RSS 2 support

KNotes has supported RSS 1 and atom formats from its content. We have never wanted to appear to take sides in the atom-vs-RSS contention, but supporting only RSS 1 and atom coiukd appear to be implicit support for atom as the format for future features, since RSS 1 is ad old format. RSS 2 is the RSS format being developed in the near future and includes many useful features which our feeds have not yet supported - we wanted to include support for RSS 2 from KNotes, and begin to explore support for the new features in it.

On the other hand, we want to avoid a confusing proliferation of choice about which feed a user might subscribe to. We already have a choice whether to 'include_discussion', anfd a choice between atom and RSS-1 - making 4 choices in all - if we delivered the complete range of RSS-1,RSS-2,atom X include_discussion X full-content,main-content,summary we would be giving users a choice of 18 feeds :o{

So we've decided that the RSS 2 feed will be 'the' main-content feed and 'the' filecasting feed. In future we might add these features to the atom feed (which is now beginning to feel featureless :o)

As yet, the RSS_2.xml feed does not support the include_discussion search argument, so is only available for level-one content. We'll add support for include_discussion later today, an then put links into the Subscribe sidebar to expose the new RSS 2 filecasting main-content feed to end users. It displays the lead-in anf the html main body, with enclosures for any file attachments in the entry. If there is extended text, this is clearly flagged at the top an bottom of the feed item (for instance "View full content (18405 bytes more)". See the screenshot.

In the meantime, you can get a feel for the new format either by appending '/RSS_2.xml' to a KNotes weblog url, or by trying one of these:

• SIGOSSEE Project News [main content + filecasts]
• KNotations [main content + filecasts]

Some policy decisions remain to be made - for instance, which of the formats should be the 'one' auto-discoverable feed which we link to from the header? I am inclined to think that the new RSS2 feed ought to be the 'one' that users subscribe to when they click the RSS button in safari, etc. We'll get back to that question later :o)

A few how-tos:

1 - How the properties of a weblog itself are used [ these are the fields when you create a new weblog ]

• id - as usual; this is what appears in the URLs
• title - used as the title of the blog and as part of page title for posts and other views
• description - displayed in banner and as DC description in RSS and page metadata
• main text ('about') (rich-text field) - displayed as the 'About this weblog' sidebar if it has any content (else description is used)
  • - you can place arbitrary html here, so it's also a quick & flexible way to customise the sidebar
  • - eg in the about sidebar of my other blog, I've placed some colophon an profile stuff like js that builds summaries of recent del.icio.us and flickr stuff of mine
  • http://www.knownet.com/writing/weblogs/Mike_Malloch

• when logged in with manager role for a blog, you get a 'Manage this Weblog' sidebar at the top right of all views
• this includes links to manage the 'top' and 'sidebar' links -- basically these open subfolders of the weblog
• you can add whatever you like to those folders; the contents are rendered as links

3 - how to post an entry

A - through the web (TTW):

• if you have manager role, you get a 'Manage this Weblog' sidebar at the top right of all views
• if you have weblog contributor role, you get a 'Contribute to this Weblog' sidebar at the top right of all views
• - there is a link there to add a post
• - the fields in the edit form are as follows:
  • title : the post's title
  • lead-in: a brief description used, if present, for listings, RSS etc
  • body: the main content as it will appear in aggregate views ( currenty entries etc )
  • extended: extra content which will show only in one-entry (permalink) views
  • category: a widget for selecting categories from 3 scopes ( site/blog/personal ), or for adding new personal categories
  • ON FIRST EDIT: details for an initial link for the item. This will be a trackback-triggering link. This is automatically filled in when you use one of the bookmarklets or other tools for directly 'blogging' content

B - through an API client (the recommended way for power users)

• in the manage or contribute sidebar, there is a link to set up external weblog editing
• - get yourself a client ( I use 'ecto' for os-x http://ecto.kung-foo.tv/ - there are plenty of others for various OS's )
• - follow the instructions in the set up external weblog editing page fo the blog you want to set up
• - clients vary in how you add a new 'account' ( or similar concept )
• NB - workflow is not yet paid any attention to, but if your client allows workflow management KNotes sets workflow state accordingly

Note that there are bookmarklets for 'blogging this page' in both TTW or API-based

• A bookmarklet is a javascript 'bookmark' that you can add to your bookmarks bar in a browser and invoke on any webpage as an action on it.
• For instance, KNotes has a 'knote-it bookmarklet' link in the contribute/manage sidebar. Add this to your browser bookmarks/favourites and invoke it anywhere to open a new weblog entry edit form pre-populated to link to the page you are viewing at the time (selected text will be used as initial content of the blog entry body). We will shortly add a pop-up-blocker friendly bookmarklet.
• Almost all the API clients also have bookmarklets for quickly 'blogging' web content. For instance ecto has an 'ectoise' bookmarklet. See the documentation for your API client to seee how to install bookmarklets and customise their behaviour.

4 - how to edit entries

A - through the web:

• you will get a toolbar just beneath any entry you are allowed to edit, the pencil icon is for editing
• if clicked from an aggregate view, this opens a mini 'window' within the page ( saving round-trip time )
• if from a one-entry (permalink) view it should open a normal plone edit form

B - through an API client

• usually just find the entry in your client's display and double-click

5 - how to add an attachment to an entry

A - through the web:

• if you are allowed to attach files to an entry, you will see a little MSWord-like icon in the toolbar just beneath the item
• this creates a new KNExFile object within the blog-entry

• almost all clients let you add attachments ithin the body of an entry as you edit its text
• -- that means that the attachments and entry are created in what seems One Step
• -- much more convenient

6 - how to add a trackback-generating link to an entry

A - through the web:

• Note that one trackback-triggering link can be created at the same time as you submit a new blog or discussion entry - fields for this appear near the bottom of the blog entry edit form on first edit
• For adding further trackbacking links: if you are allowed to add trackback-triggering links to an entry, you will see a little Link-like icon in the toolbar just beneath the item
• this creates a new KNLink object within the blog-entry
• you can untick a checkbox in the edit form for the KNLink if you do not want a trackback ping fired off
• ( there is also a blog-level pref for this; eg important for private blogs )

B - through an API client - the easy way!

• almost all clients let you links within the body of an entry as you edit its text
• -- any links within the body are parsed out and turned into KNLink objects
• -- much more convenient
• -- exceptions: if the link already exists it stays there but is not duplicated on subsequent edits; if it has rel="tag" attribute it is ignored (eg technorati tags)

7 - how to set up shared blogging and other permissions

• - if you can manage, you see a link in manage sidebar for 'Set up sharing permissions'
• - this is complicated and fully featured but lmost self-explanatory
• - quite powerful
• - we'll write help for that asap
• - if you have moderator or higher (eg manager) role you see a link in manage sidebar for 'Delegate Moderators/Managers'
• - this lets you assign moderator roles to specific members or groups ( but no more powerful than your own roles )

... there are many other bits of how-to that need to be written ( KNotes is very full-featured :o)

... I'll try to get back to you with bits of documentation as soon as we get a chance to start writing them

cheers

Mike