ROT13 and Hello

ROT13 and Hello are simple example plugins by Hans Nowak. They illustrate creating plugins, and accessing mainframe attributes through them.

FireSpell Manual

FireSpell is a spell checker for Firedrop2. It uses the PyEnchant module by Ryan Kelly. It needs version 1.1.2 or more recent.

FireSpell probably comes enabled by default. In case it doesn't, see Installing Plugins for the steps to install it. Even if your version of Firedrop comes with the FireSpell files, you may need to add the following line to either 'firedrop.ini' or 'build.ini' :

To use FireSpell, select the entry you want to spell check and hit the SpellCheck button. This activates FireSpell, which should be straightforward to use. Any words you Add to Dict will be saved in a plain text file called 'pwl.txt' in the plugins directory.

PyEnchant comes with dictionaries for several languages. The default is 'en_US', meaning US English. You can choose any of the alternatives from the drop down list on FireSpell. Choosing a new language will cause this language to be the default next time FireSpell is started. For more dictionaries, follow the instructions for PyEnchant.

FireMail Manual

FireMail is a plugin that allows you to email your current post. This is a feature of Blogger that I missed [2], so I've implemented it as a plugin. It is capable of sending HTML emails or text. When sent as HTML the text version of the post is also embedded so that people who don't like (or can't receive) HTML emails will see the text version.

FireMail generates the HTML using a file called 'firemail_template.html'. The mail server configuration should be done in a file called 'firemail.ini'. It first looks for these files in the site directory, if it doesn't find them there it looks in the plugin directory. This allows you to have different settings for each blog, or one setting that applies to all your blogs.

Editing the config file causes the changes to be saved. You will need to give it the name of your mail server. If you need to log in, it will need your username and password.

The 'to address' can be a single email address, or a comma separated list. Some email servers won't allow you to send email if you don't supply a 'from' address.

The template file uses the normal Firedrop2 template system. If you correctly set <base href=".... in the head of your template, then local references in the generated HTML ought to be resolved correctly when the email is received.

InteractiveGUI Manual

InteractiveGUI is a plugin for programmers. It gives you an interactive shell into Firedrop2.

This means that all the attributes of mainframe are available as local variables. The mainframe itself is present as self.

A useful value to inspect is active_entry, which is the currently selected entry [3]. You can access the main editor pane as editor. It's fully dynamic - try changing entry and watch editor.Value change.

It's particularly useful when creating new plugins.

For a complete and sorted list of attributes available - try the following

:

OutBox Manual

Another plugin is called 'OutBox'. It's aimed at programmers. It is only useful for Windows users who run firedrop.pyw.; it will run on Mac OS X, but only for displaying errors (see below).

Once activated, it displays output from sys.stdout and sys.stderr (that would normally be lost) in a display box. This is useful for debugging - you can still see the output of print statements without having to have a console box hanging around.

Once activated for the first time it caches all output, even when closed. It's not enabled by default, of course.

Note that if you enable it, you should always put it last in the list of plugins :

plugins = 'InteractiveGUI', 'FireSpell', 'OutBox'

That's because if you have turned on debugging, as soon as OutBox is activated it will grab all of the debug print statements you would normally see.

Themes Manual

New in Firedrop2 version 0.2.2 is the Themes plugin. This provide a choice of several different looks for your site. It's useful for new users who don't have a detailed knowledge of CSS stylesheets, or templates, but still would like to be able to vary the look of their site.

Each theme lives in the Themes folder inside the Firedrop folder. Each theme is comprised of a stylesheet and some templates, as described above. To select a Theme, click on the Themes plug-in button on the lower toolbar. You'll get the following dialog (as seen in Ubuntu Linux).

If you click on the name of a theme in the pull-down list, you'll see the description for that theme, and below it, a screen capture of a blog page using the theme.

When you select a theme, a couple of things happen :

• you will be prompted as to whether you want to proceed. This is your last chance to change your mind.

  

• Any existing templates you have are backed up once. If you apply another theme, your previous backup

  will be overwritten.

• The type of Firedrop site you are editing will be determined. It presently can be one of three types: Article Collection,

  Item List, or Weblog, with the latter being most common.

• The appropriate templates for your site type will be copied into your site folder. If all went well, you'll get a confirmation of success:

  

• When you build your site, and then preview it, you'll see the new theme at work! If you don't like what you see, just

  invoke the Themes plugin again and choose a different look. Or go back to the default whitey-whites look.

Adding themes

If you would like to add a theme to the Firedrop project, by all means make a submission. Here's how :

• Make a copy of one of the existing themes (but not the default theme), and save it under your desired name, e.g. rocketman.
• In the rocketman folder, there will be a .css file and a theme.ini file. Delete the existing .css file and replace it with your own, or edit the existing file. Either way, save it as rocketman.css.
• Now edit the theme.ini file. It's self-documenting, but you'll need to edit the values for the three parameters: name, description and stylesheet. name should be set to rocketman. Think up some appealing description for your theme.
• In the "images" subfolder, place a copy of any logo files or other graphic elements your theme requires. Also make up a screen capture of your theme in action so we can see how it looks without having to apply it to our blog. For best results, your screen capture should be 550 pixels wide and 250 pixels high, so you may need to scale down your image if it was larger to start with; save it as theme.png.
• Now make any edits required to the templates; oftentimes, no edits at all are needed: most of the themes supplied with Firedrop have identical templates. For best results, and compatibility with other existing themes, try to use the same <div> names as the existing themes; e.g. "banner", "mainbody", "sidebar", "entry", "bloganchor", etc. Do NOT change any of the namespace names; these are the ones described in Templating, and include such items as <% page_ext %>, <% entry_body %>, <% body %> and several others.
• If you edit or delete any of the javascript in the templates, then the comments system will no longer work with your blog.
• Last thing to do is to test your theme by applying it to your blog, and pressing the Preview button. Hopefully it will all work nicely for you, but if not, just send a note to the Firedrop developer's list and we'll get you some help right away. Note that we are not CSS experts, so we'll be unlikely able to help with questions like "why does my theme work in Firefox but not in MS Internet Explorer?"

The Plugin Class

Every plugin must have a plugin class, which will be imported by Firedrop2.

This class should be named pluginnamePlugin. 'pluginname' is the plugin filename without the '.py', and the same name that should appear in build.ini/firedrop.ini for Firedrop2 to use the plugin.

This class should have an OnClick method, which will be called when the plugin button is used. OnClick receives one argument in addition to the usual self - this is mainframe which is actually the main Firedrop instance. Through this you (as a programmer) have access to all the entries and functions in the currently opened Firedrop.

This is easily illustrated with a basic example :

class SillyExamplePlugin:
    button_text = 'Silly Example'
    def OnClick(self, mainframe):
            print mainframe.editor.Value

Save the above code as SillyExample.py, put it in the plugin directory, and add 'SillyExample' to your 'firedrop.ini'. When you run Firedrop you'll see a new button 'Silly Example' on the plugin toolbar. Pressing this causes the contents of the main editor window to be dumped on stdout [5].

button_text

You'll notice the 'magic' class variable button_text. If this is present then its value is used for the plugin button.

Mainframe Attributes

Beyond this, writing plugins is simply a case of knowing the attributes of mainframe. You probably also want to know Wax : both to understand the methods available for elements of mainframe, and to construct a GUI for your plugin.

Attributes of mainframe include :

• mainframe.editor - the main editor window. A Wax TextBox.
• mainframe.active_entry - the currently active entry (or None).
• mainframe.textmanipulator - this has several methods for manipulating text, including just the selected text.
• mainframe.fd2manager.get_entries() - this returns a list of all entries
• mainframe.fd2manager.dir - is the current site directory
• mainframe.fd2manager.get_options() - gets you the options dictionary for this site
• mainframe.fd2manager.getter() returns the currently selected text.
• mainframe.fd2manager.setter(new_text) will replace the currently selected text with whatever you give it.

See the InteractiveGUI Manual for a way to explore these objects live.

mainframe.editor in particular is the wax TextBox that forms the main display. You can get and set its value through mainframe.editor.Value = 'something' and this_entry = mainframe.editor.Value. Note that setting Value directly like this won't mark the entry as modified. If the user navigates away from this entry without saving, the changes will be lost. You'll need to call mainframe.editor.Modified = True to do this.

A GUI For Your Plugin

Most plugins (but not all) will have their own GUIs. It makes sense to do this using Wax, with mainframe as the parent frame.

There are basically three possible techniques :

1. Code Your Plugin Without a GUI
2. Plugin as Child Window
3. Plugin as Dialog