Sidebar plugins exist to allow third party developers to easily extend Scribe and add content to the sidebar. Scribe also uses the plugin architecture to install some default functionality in the sidebar. The pre-packaged plugins are:
Sidebar plugins are used within the SIDEBAR_ITEMS preference. The preference defines a list of sidebar items to render and join together. Here’s an example:
SIDEBAR_ITEMS = ['tags', 'archives']
The sidebar object will automatically get the content that the tags plugin makes available and put it in place of 'tags' and will do the same for the archives plugin. The list will then be joined together.
Each plugin allows you to customize the look and feel of it. (It’s designed so that you have to, in fact.) You must define a template for each sidebar plugin. Let’s keep going with the tags plugin example. Since we’re using the tags plugin, we must create a template at sidebar/tags.html. Here’s an example of what that template might look like:
<h2>Tags</h2>
<ul>
{% for tag in tags %}
<li><a href="{{ tag.get_absolute_url }}">{{ tag.name }}</a></li>
{% endfor %}
</ul>
Each sidebar plugin will pass its template a content variable that has the same name as the plugin. In this case the variable is tags and is a list of Tag objects. In the case of the archives plugin, the variable is archives and it is a list of ArticleArchive objects. Consult the documentation for the plugins that you have installed for information about what the data they provide is.
If you obtain a plugin from a third party, you can simply put it into the plugins folder. The next time your code is reloaded, the plugin will be loaded.
The categories plugin is designed to display a list of all categories in your sidebar.
The categories object provided to the sidebar/categories.html template is a list of scribe.models.Category objects.
The tags plugin is designed to display a list of the most used tags in your sidebar. The tags plugin will limit the number of tags displayed to the preference SIDEBAR_TAGS_COUNT. The default value for SIDEBAR_TAGS_COUNT is 15.
The tags object provided to the sidebar/tags.html template is a list of scribe.models.Tag objects.
The tags plugin is designed to display a list of months in which you have written articles along with the number of articles that have been written in that month.
The archives object provided to the sidebar/archives.html template is a list of scribe.models.ArticleArchives objects.
The base class object is scribe.core.plugins.base.SidebarPlugin. You should create a plugin object that inherits from this object.
The info method is the only method you need to override. The return value of this method will be passed to the template in a variable corresponding to the name of the plugin.
For example, the tags plugin looks something like this:
from scribe.core.plugins.base import SidebarPlugin
from scribe.models import Tag
class TagsPlugin(SidebarPlugin):
def info(self):
return Tags.objects.all()
def expire_on(self):
return [Tag]
If you feel you need to, you can override the name method as well. By default this method simply takes the name of the class, strips off the Plugin part, and converts it to all lowercase. This should work fine for most plugin developers, and we encourage you do do this.
For performance reasons, the rendered result of the sidebar plugin is cached. Certain sidebar plugins may change more often than others. Whenever data within Scribe changes that would result in a change to your plugin’s content, the cache should expire.
The plugin provides a simple way to do this. You simply return an array of the things that your content relies on. The above example relies on any change to the Tag class. When tags are created or destroyed, your plugin’s content will be regenerated.
(This example is insufficient, though, if the rendered template includes the article count with the tag name, though. Realistically, the Article class should be included as well since this is something likely to happen.)
The more things you list, the more your plugin will slow down the overall performance of Scribe. There is no way (without creating a hack) to create a plugin that won’t have the content cached. The reason for pointing this out is that sidebar plugins with dynamic content will not be dynamic. You can however use other techniques to make content dynamic (javascript, iframes, etc).
You have the option of defining custom preferences for your plugin. Simply add a module called defaults to your module and define the default values for any preferences. When you want to use the preferences do the following:
from scribe.conf import settings settings.MY_PREFERENCE
This will retrieve the value that the user defined in his/her preferences.py file if it exists, and if not, it will use the default value that you defined in the defaults module.
You can include other python libraries by including a lib directory within your plugin. The lib directory will automatically be added to sys.path if it exists, so you can simply import modules from within lib. You should only use this if you’re using another author’s work that you don’t want to modify. Don’t put your own code in it.
Each plugin must be a module contained within a directory. It cannot simply be a .py file. Here is a sample plugin architecture:
sidebar_coolfeature/ __init__.py defaults.py lib/
Please don’t hesitate to use the built-in plugins as additional reference for creating new plugins.
If you notice errors with this documentation, please open a ticket and let us know!