KNotations

Which RDBMS? :: PostgreSQL, MYSQL

Knotes was built for speed, that's why it's been built using a RDBMS. During the development stages we used Postgresql throughout, this has led to some small non-standard, or shall I say 'non-MYSQL' code sneaking into some of the pre defined queries. This isn't a big issue and we already have a 'MYSQL friendly' version available. This just needs some thorough testing before being merged into the product.

Support for Plone 2.1

KNotes stores all related data (attachments,links...) in the RDBMS. To enable links and attachments to get their data storerd in the RDBMS, we created special versions of the standard 'Link' & PloneExFile products. The version of PloneExFile used for subclassing is now quite old and newer versions are not supported, this old version will *not* install in Plone 2.1. We will therfore drop PloneExFile as a dependency from any future release.

ZAttachmentAttribute is required by PloneExFile, even when the dependency on PloneExFile has been removed we still need ZAttachmentAttribute for our own KNExFile. The version of ZAttachmentAttribute used at the moment (2.3) does not install without a few minor hacks to the installer script. Altough these are *very* minor, they are still of some concern.

Apart from the problems outlined above, KNotes versions 0.7 alpha and above *will" install and work in Plone 2.1

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

I've been meaning to do something about providing a sandbox in which guests cvan try usinhg and managing KNotes for themselves. We've finally done it!

We have owned the knotes.net domain for some time, intending that it becomes the centre for hosting and discussing KNotes development and releases. There is now a sandbox for KNotes there. If you join the knotes site, you can create and manage KNotes weblogs and discussion items in your home folder. On request, we can make a folder in the sandbox area for you, so you can also try knownet's indexFolder context for plone content. (We will at some time make indexFolder the default for a member folder in this site, but that requires a bit of work :o)

Making the knotes.net site ready for using KNotes was informative about a few remaining installer issues:

ZAAPlugins required

The ZAAPlugins product must be installed in order for attachments to work in blog entries and discussion items

[temporary] main_template hack for nowrap editing

I still have not propagated the changes entailed by the plone-skins-cookie technique for delivering 'unwrapped' plone content/forms. Until I do - sometime next week - it is necessary to have a simple customisation of main_template

Default style for weblogs expects a banner image

Another long-pending little to-do: When Knotes is installed, the default style expects a banner image which is missing from the distribution. Making a knotes_banner.jpg and placing it in your portal_skins/custom folder corrects this. I'll have to think about how best to tackle this problem - we're planning to have a good long look at improving skinnability soon. -- UPDATE - I made a 'base banner' and added it to the skin folder for the weblog type..

The version of KNotes on sourceforge had fallen behind the version we deploy in our own production portals. Steve has updated it and fixed the problem that had prevented it being updated automatically. Somehow we'd removed CVS information from the product filespace during a big synch-with-experimental version changes in May.

Sorry to say we've been neglecting the sourceforge area; we'll be paying more attention again now. For instance, Steve just discovered that there were more than 190 downloads during the period of my illness. Scary! If anyone reading this has downloaded the tarball and not been able to get anything sensible working, please contact me (contact link in the navigation bar at top of page).

Steve is just back from a refreshing holiday touring the Canadian Rockies in a big campervan with Rachel, Jade and Elle. I missed him. Already in the past day and a bit he's eliminated some nasty API bugs that had snuck in during a feature-push just before he left.

I think we're spotting bugs pretty quickly now, thanks to the volume of activity in our own project blogs and discussions. And when it comes to the subtleties of the XML-RPC API we're getting much better at predicting and avoiding issues. The date of a safe release is getting closer and closer!