Preface: Work in Progress
This manual is not complete. It needs in particular to be augmented with the Block API information that Shimon posted to his weblog around 4 Nov 2004.
Using and Extending the Frassle Publisher
Frassle is designed to give its users a lot of power over how they view or publish content. This is made available through the frassle publisher, a system for developing custom, dynamic pages. The publisher lets you use all the content and organizational knowledge in frassle, and can be used entirely through the web. Though pages can be extensively customized by frassle users, they never have to edit files.
For certain specialized site designs, frassle’s publisher may not ship with built-in support for the styles you require. Frassle is designed to easily accomodate these kinds of extensions when required. A programmer with knowledge of HTML coding and basic Perl can develop or customize a block style in about an hour.
If you develop a block style that you think will be useful to other users of the Frassle Community System, please consider licensing it under the GPL or donating your copyright to the frassle authors so that other users can also benefit from your work.
Overview of the Publisher
Frassle contains a lot of diverse, but interrelated content. The frassle weblog reader and aggregator provide standard interfaces to this content. When you wish to view frassle content in a different format, you can use the publisher to build custom views. For example, you can use the publisher to:
1. Present latest content, grouped by subject area, from a variety of sources. Backed by frassle’s inter-category relationship tracking, you can build your own Google news.
2. Group weblogs. Blend content published to a certain category name from several blogs to offer a group weblog. Because frassle can just as easily take content from aggregated feeds as locally-published feeds, authors who are already used to one blogging system don’t need to switch.
3. Combination RSS feeds. Blend several feeds together in a block, and subscribe to that block’s RSS feed in your favorite aggregator. It’s easy because each block can be viewed via RSS.
4. Books and serials. Are you publishing a book in parts, or a series of related entries? Use the publisher to present them together, along with specialized navigation, sidebar content, and visual style.
5. All time favorites. If you’ve found a group of postings that deserve to be preserved together forever, put them all on a single publisher page. Share this page with your friends or colleagues.
Sites, Pages, and Blocks
The frassle publisher allows you to create dynamic pages, grouped within sites. To start, you create a site rooted at a location you specify, such as http://frassle.rura.org/shimon. You can then create pages within that site, with their own distinct locations such as http://frassle.net/shimon/blog or http://frassle.net/shimon/about. If you’ve created a site but that site contains no pages, visiting that site will take you to a page where you can edit site settings and create new pages. Other users will simply see a message that this site is under construction.
Pages within a site are composed of blocks. These are reusable elements that can contain a variety of information: they can display a single piece of content, such as a title or “about this site” blurb; they can show a list of notes, based on a search, in a variety of formats; or they can contain other static or dynamic content. Once you’ve created a block, you can reuse it on other pages. This makes it easy to share navigation links among pages within a site.
Frassle Plugin ArchitectureM
The frassle studio allows users to build and customize dynamic websites without any programming. But what if the options the studio gives you don’t meet your needs? Frassle provides a plugin API so that you can build custom page elements.
There are currently three kinds of plugins in frassle:
- block display styles, which define a format for a set of notes. The content of each block comes from a content stream specified by the user, and the block display style controls how the query results are displayed: headlines, full text, etc.
- widgets, which are programmatic elements that do not necessarily display a set of notes. A widget may display the current time, or some user’s category tree, or just a static piece of text.
- themes, which provide a Cascading Style Sheet (CSS) for use in studio pages and sites.
Although these plugin types serve different purposes, they have some common structure:
- Don’t call us, we’ll call you. When it’s time to render a page that includes your plugin, frassle loads your files and invokes the appropriate functions.
- Drop-in deployment. Simply put plugin files into the appropriate frassle/plugins directory, and you’re ready to start using them. No need to restart your server.
- Separate code and template files. Each plugin has a template file, interpreted using the HTML::Template system, and optionally a program code file written in Perl.
- Full API access. Because your plugin code runs within the same Perl environment as frassle itself, you have full access to frassle’s Perl interfaces and the attached database. This is powerful but dangerous; because a plugin can potentially harm your data or expose security vulnerabilities, you should not run untrusted plugins.
- Automatic options interface. You specify what configuration options are available for your plugin, and frassle automatically generates the interface for users to edit these options. When your plugin is called to render, frassle tells you what options apply.
- [coming soon] Caching. Concisely specify caching options for the output of your plugin. Frassle handles the mechanics of storing and serving the cached output, as well as expiring the cache as soon as it is invalidated.