README for BlogFace 1.1 About The BlogFace product is meant to be a simple weblog interface. It provides those features that I think are essential in a weblog, and allows other weblogish features to be added if desired. The BlogFace provides a weblog-style interface to a cataloged collection of objects, without requiring that the catalog or entries be modified, or even know about the BlogFace at all. It will work with any catalog and collection of entry objects, so long as the catalog provides an ISO format date attribute for each entry record. Status This is a stable release. Features The BlogFace is a web interface to a ZCatalog that provides navigation and display features. The blog entries themselves are instances of separate Zope products. Navigation is date-based, with each step in the path corresponding to an element of the date. The page returned will start with the latest entry before that date. For example, blog/2001/10/31 will show entries starting with the last entry on October 31, 2001, while blog/2001/10 will start with the last entry on October, 2001. The maximum resolution is to the day. The BlogFace doesn't know anything about the entries, only about the catalog. The entries are responsible for providing their own add and edit methods, and for cataloging themselves. Requirements The calendar feature requires the "Calendar":http://www.zope.org/Members/jdavid/Calendar tag. If you don't have that installed, BlogFace will work without displaying it. Installation If you are upgrading from BlogFace 0.3b or earlier: save the files in the dtml directory of your BlogFace installation to a temporary location. Unpack the BlogFace tarball in the Products directory of your Zope installation. Rename the unpacted BlogFace-1.1 directory to "BlogFace". Restart Zope. If you are upgrading from BlogFace 0.3b or earlier: you will need to manually add the DTML methods through the web (because they were filesystem based DTMLFiles earlier). From the Contents tab of the BlogFace, add DTML methods named "index_htmlPage", "entries", "blogCalendar", "rss", and "URLFmtError", with source from the corresponding files saved from the earlier BlogFace installation. You will need a content object type to use as blog entries - BlogFace only provides the interface. I recommend using CMF products as blog entries. I use a toy entry object that I created, "STXDocumentEntry":http://www.zope.org/Members/karl/STXDocumentEntry/STXDocumentEntry. Usage Add a BlogFace instance. Check "Create Catalog" if you don't want to use an existing catalog. If you are using an existing catalog, enter its path in the "path to catalog" entry on the main view of the blogFace, and see Customization below. Tell the BlogFace what property or attribute of the entry objects represents the blogged date. This is done with the "Date index" field of the main view. This must be an attribute or method that returns a string readable as an ISO date format. For CMFy objects using the Dublin Core metadata, this is usually "date". For STXDocumentEntry objects, this is "ISODate". Since the entries are Zope products, you can add them in whatever ways that they support. They need to be added where they will be cataloged by the ZCatalog that the BlogFace instance is reading. If you are using the catalog created on install, then CatalogAware entry types such as STXDocumentEntry can be added anywhere within the BlogFace or a subcontainer. If you're using the CMF portal catalog, any location within the CMF site should work. Subobjects can't be added to the BlogFace itself via FTP or DAV, but they can be added to a subfolder that was added from the web management page. I recommend adding a BTreeFolder to the BlogFace and putting entries in there, to make management easier. The default view page shows the most recent blog entries. Pages starting at other entries have URLs based on their dates. Look at the links provided to entries, or append some gibberish to the blog URL to see a descriptive error page. Customization The attributes of an entry that can be displayed come from the catalog entries. To change this, change the indexes and metadata of the catalog using the standard ZCatalog management tabs. Selection attributes must be in the index, display attributes must be in the metadata. If you had the BlogFace create its own catalog, you can reach it from the "Contents" tab. If you are using an existing catalog, its indices and metadata will have to contain the entry information. If the catalog catalogs objects of types other than blog entries, you will have to narrow the search to include only your entry meta_type. Other customization is described in the help page of the main tab. The default view is sparse and meant to be configured to taste. The views supplied with the blog are filesystem DTML methods, which aren't editable through the web. That's just my personal preference, but it's easy to get around. If you want a RSS image and description, add objects within the BlogFace called "rssImage" and "rssDescription" that provide an image and description when rendered. If the image is missing it is not provided, and if the description is missing the title or ID is used. The BlogFace will work with any entry types that are in the catalog that it looks at. The entry types must have the attributes to be displayed cataloged, and must store their date attributes as ISO date strings. I recommend using the CMF and its types, such as NewsItem - CMFy features such as workflow and Dublin Core metadata are perfect for blog features. I currently use STXDocumentEntry, however. To use a BlogFace with CMF News Items: install the BlogFace within your CMF instance. Use "portal_catalog" as the path to the catalog, and "Date" as the date index. Add a default search criterion with a search term of "meta_type" and a criterion of "News Item". Edit entries.dtml to suit how you want to display the content of the news items (the date display should work out of the box). For a slashdotty format like the one ZopeZen uses, show the "Description" attribute as structured text and include a link to the article itself. To use a BlogFace with a ZWiki, see wikiblog.txt. Bugs No cacheing or cacheability yet. BlogFace is a very efficient product if you use the catalog and don't access the entry object directly, but returning a cached result that is only updated when the catalog is written to would be better. And the calendar display isn't very nice, it queries the catalog for every day displayed! Improper date URLs get the info page, but not a 404. Nonexistent pages get a 500 with an attribute error page, not a 404. This is a bug in the Zope WebDAV support. A relative link in an entry gets the blog URL *including the date* prepended to it. The link will still work because of acquisition, but it makes many URLs for the same object, which makes cacheing less useful. This isn't a BlogFace bug really, it's a drawback of using paths to connotate information. To do CMF skin integration, preferably by somebody else. Searching. Motivation Why yet another blog product? I wanted my personal peeves fulfilled. The features that I think every blog needs are understandable date-based navigation and a URL for every entry that points to the blog page starting at that entry. That URL should be expressed as a path, so that spiders aren't afraid to crawl to it. These features are important because the linear reading of the most recent entries of a blog is only part of its interface. A blog is also an archive of ideas, and each blog entry should be an entry point to that idea and the rest of the blog. I also want to own the blog and it's data, which means running it on my Zope server. Finally, I want the act of writing entries to be natural and as effortless as possible, which means treating entries like text files so I can edit them with Emacs. Now that there's a Python interface to the XML-RPC API exposed by Blogger and Manila/Radio/Frontier, these last two points are reachable with those services. A Python librarian program that keeps those remote servers in synch with a local directory of entries shouldn't be too hard to whip together. The Zope CMF has some reasonable blogging features out of the box. The only thing missing for me is the navigation and entry points listed above, and that's what this product is meant to provide. Author Karl Anderson, kra@monkey.org, http://www.monkey.org/~kra. Copyright 2002 Karl Anderson, released under the LGPL - see LICENSE.txt.