Introduction What's New Installation Upgrading Using Habari Developer Introduction

Introduction

These documents are intended for basic information on installing, upgrading and base use. As development continues, additional information will be added. For more comprehensive documentation, visit the main Habari wiki.

About Habari

Habari intends to represent a fresh start to the idea of blogging. The system will be fast, easy to use, and easy to modify. New users should have no problem using and enjoying Habari. Advanced users should have no problem tweaking Habari to do exactly what they need it to do.

What Does Habari Mean?

"Habari" is a Swahili word that means "what's the news?" It's similar to the English "What's up?" or the Spanish "Qué pasa?" The typical response is "mzuri sana", which means "very good."

How Will it be Different?

Habari is being written with a firm understanding of the current state of blogging. Most other blogging packages have been around long enough that their responses to things like comment spam and Digg site overloads are bolted on after the fact; whereas Habari is being written from the beginning to take these things -- and more -- into account.

Habari strongly favors open, standard, and documented protocols. Atom, being both open and documented, is the prefered syndication format, and the Atom Publishing Protocol is the prefered means of remote communication with your site. This is a core feature, and not a plugin.

Habari is being written specifically for modern web hosting environments, and uses modern object-oriented programming techniques. Using these recent but well-established additions to the PHP language allows Habari to make use of PDO, enabling prepared statements for all interactions with the database. This greatly reduces the system's vulnerability to SQL injection attacks. This is just one of many benefits of modern object-oriented techniques.

Those are just a few of the technical differences, but a major component of what makes Habari different is its community participation model. Users who demonstrate a consistent level of quality contributions to the project are granted more privileges within the project.

Our Process

Meritocracy

Following the meritocracy model advocated by the Apache Software Foundation, the Habari project rewards contributors with decision making privilege in the project. Regular participants should be able to influence the direction of the project to which they dedicate their time and talent. The requirement for participation will be something of a moving target over time, but the barrier to entry should never be so high that dedicated people are excluded.

Transparency

A fundamental aspect of successful open source projects is transparency. Decisions are made in the public's eye, and discussion and deliberation takes place in the open. The Habari project pursues transparency by using the Google issues tracker to maintain a record of proposed changes, and discussion associated with those changes. All proposals -- whether for code, documentation, visual style, etc -- are logged through the issues tracker for public scrutiny and input.

Licensing

All contributions to Habari will acquire the Apache License, which is a modified version of the Apache License. For those unfamiliar with this license, the Apache License FAQ page should answer most of your questions.

Developers contributing to the Habari project itself should note that, unless explicitly stated otherwise, any contribution intentionally submitted for inclusion shall be under the terms and conditions of the Habari license, without any additional terms or conditions. However, plugins and themes designed to work with Habari are not required to have the same license as Habari itself.

You can find our license included in the source, and in our code repository.

What's New

Introduction

Welcome to Habari Version 0.6.4!

This latest release of Habari contains some major improvements and feature changes.

Known Bugs

Almost 1100 bug fixes and improvements have been made since the last release, but as with any piece of software issues and enhancement requests remain. For full details see Habari's change management system.

Credits

These release notes were compiled by the Habari Community.

On behalf of the community, we give our warmest thanks to the developers and contributors who made this Habari release possible.

Upgrading

Before You Upgrade

Before making any major change in your Habari installation, it would be prudent to create a backup of your database and your installation, in particular all the files in your Habari /user directory. The /user directory should contain all files which you have customized - plugins you have installed, themes you have installed, class files you may have modified, or locale files you have installed.

The Upgrade Process

  1. Download the new version of Habari that you will be installing. Unzip it into the location of your choice.
  2. Deactivate your active plugins. Some of the system plugins may have been changed. Some of the plugins you got in other places may not be compatible with the new version of Habari.
  3. Delete the following directories
    1. /3rdparty
    2. /scripts
    3. /doc
    4. /system
  4. Delete the index.php, LICENSE, and NOTICE files from the root of your installation. Do not delete your config.php file if it is in the root of your Habari installation, or the .htaccess file.
  5. Copy the new version of Habari to the same location as the old version.
  6. Using your web browser, navigate to your site. If there are any database changes that need to be made, they will be made automatically at this time.
  7. Log into your Habari administrative area. Navigate to the plugins page and reactivate the plugins one by one.
  8. Celebrate and enjoy the new features of your latest version of Habari!

Upgrading from Version 0.5.2 to Version 0.6.4

Version 0.6.4 incorporates many changes from the previous version, both in bug fixes and new features. For details see the release notes.

Habari's upgrade process is designed to be transparent, with the only indication that an upgrade is happening being a slightly longer page load time the first time the site is visited after the software is updated.

One major change that affects the upgrade process in this release is in how Habari stores it's configuration details. Habari 0.5.2 and earlier stored site configuration details in global variables. Habari 0.6.x marks the move to using a config class, so the variables aren't globally available, a change that was made to improve security. These details are stored in the site's config.php file, which is located either in the root of the site's directory, or, for multisite users, in Habari's /user/sites/site_name directory.

For users who have left their config.php file writable, the necessary changes to the configuration file will be handled by the upgrade process transparently. For users who have made their configuration file read only, some manual changes will have to be made before the upgrade process can begin.

Manually Updating The Configuration File

The config.php file for Habari version 0.5.2 and below looks like this:

For MySQL 

<?php
$db_connection= array(
	'connection_string'=>'mysql:host={$db_host};dbname={$db_schema}',
	'username'=>'{$db_user}',
	'password'=>'{$db_pass}',
	'prefix'=>'{$table_prefix}'
);

?>

For SQLite 

<?php
$db_connection= array(
	'connection_string'=>'sqlite:{$db_file}',
	'username'=>'',
	'password'=>'',
	'prefix'=>'{$table_prefix}'
);

?>

With version 0.6.x the config file looks like this:

For MySQL 

<?php
Config::set( 'db_connection', array(
	'connection_string'=>'mysql:host={$db_host};dbname={$db_schema}',
	'username'=>'{$db_user}',
	'password'=>'{$db_pass}',
	'prefix'=>'{$table_prefix}'
));

?>

For SQLite 


<?php
Config::set( 'db_connection', array(
	'connection_string'=>'sqlite:{$db_file}',
	'username'=>'',
	'password'=>'',
	'prefix'=>'{$table_prefix}'
));

?>

The easiest thing to do is, before upgrading, make the configuration file writable. Perform the upgrade, then make the file read only again.

If you don't wish to do that, open the configuration file in a text editor and make the changes shown above, save your changes, then navigate to your site so the upgrade process can proceed.

Upgrading Other Versions of Habari

For specific upgrade instructions for earlier versions of Habari, see the full upgrade notes on the wiki.

Using Habari

Introduction

Welcome to Habari, the next-generation online publishing platform!

Habari was built from the ground-up with a firm understanding of the current state of blogging, and with a strong eye toward the future of internet publishing. Habari strives to make it as easy as possible to publish your content. It stays out of your way as much as it can, and lends a hand where it's needed.

The word "Habari" is Swahili for "news", as in "What's the news?" We feel this is an appropriate name for a blogging package not just because of the clever tagline, but because blogs are so often used to tell others what's the news in your life or your business.

As a Free Software project, Habari's most valuable asset is the community of users and developers who collaborate to improve the product. Habari is built by people just like you: folks with an interest in blogging and internet publishing.

Installation

Habari has a few Server Requirements, which you will need to meet to be able to run Habari. If you have what is required, (or better), you are good to go! As Habari is still in development, no guarantees are made that these are fully stable versions, or that updating won't break the current database structure.

To install the latest stable version of Habari:

The Habari installer initially presents you with a choice of languages that it will use for the interface. Select the correct locale code from the list for your language of choice. The default selection is "en-us", which is English, United States.

Clicking the question mark at the top of any section of the installer will reveal more information about each field in that section.

Depending on the Database Type you set, you may need to enter some of the following information:

The Site Configuration settings you will need to set are:

The installer recommends several plugins upon initial install. These plugins are checked in the next section, Plugin Activation. Additional optional plugins are included in the core installation, but these plugins are not checked by default. If there are additional plugin present in addition, Habari will list these here as well. Choose the plugins that should be activated upon installation by checking the box next to each.

Conclude the installation process by clicking the "Install Habari" button. When Habari completes processing, installation is complete.

The End! Habari should now be installed.

Full Installation Instructions are available, including some details of how to adjust your settings for different web servers and specific configuration information for several popular hosting companies.

If you are happy to use the current development version of Habari, the full instructions explain how to access the Habari subversion repository; however, for most normal users you will need to download the latest stable version of Habari.

Using Habari

After you have installed Habari, go to http://example.com/admin/. You will be taken to a login page. Enter your user name and password to open up Habari's administration interface. You will be greeted by the Dashboard. This page provides a snapshot of useful information, such as the total number of posts and comments on your site, the number of posts you've made, and more. Later you can install plugins to add new modules to the dashboard, greatly expanding its usefulness.

The primary way you will interact with Habari is through the main menu. The main menu is accessed by placing your mouse at the top left of the window. The menu should automatically drop down, to reveal to you the available choices. The menu items users see will be controlled by the permissions assigned to them by the site administrator. Clicking on any menu item will take you to the corresponding page within the administrative interface. For details on each menu item, see the corresponding section of this manual.

It should be noted that the main menu can also be accessed by keyboard shortcuts. If you press the Q key on your keyboard, the menu should expand. Press the Q key again to hide the menu. When the menu is displayed, each menu item has a keyboard shortcut displayed to the right. Using the keyboard shortcuts you can quickly navigate through Habari. Want to create a new entry? Press Q, then the 1 key. Want to change your site's theme? Press Q, then T. Want to add a new user? Q U.

Your First Post

You can create your first post by clicking on the main menu, then selecting "Create Entry".

You are now looking at the publish entry page, by default you have three fields into which to enter information.

Create Entry admin page

Pressing the Save button will save your work into the Habari database. The post will still be a Draft, which means it is not available for the public to read. You can edit and save drafts as many times as you like, to make sure you get the post just right before letting the world read it. When you are satisfied with your post, click the Publish button. This will make the post visible to the world on your front page, as well as in your Atom syndication feed. Congratulations, you've posted your first entry!

You also have an additional button between the Tag box and the Save/Publish buttons, the Settings button. It contains optional extras you may wish to use. Clicking it opens a pagesplitter (so called because it splits the page).

Key Terms and Ideas

Content Types

As a tool for managing content, Habari defines two default types of content.

Plugins have the ability to add additional content types.

NOTE: When discussing Habari, the term "post" will frequently be used to mean any kind of content. If the content type matters for documentation or example purposes, a specific content type will be used. Entries and Pages are both Posts.

Content Statuses

Out of the box Habari maintains three post statuses - draft, published, and scheduled. Plugins have the option of adding further statuses to this list. The Undelete plugin that comes with Habari, for example, adds the deleted status.

Tags

Tagging is a non-hierarchical way to categorize your content. When you create a post, you label it with one or more tags to show readers what other posts on your site it is related to. Tags have only a general semantic meaning, because the context of a label can change it's meaning, and this context isn't a part of the tag. Tags do, however, allow you to show the general categories of your work without forcing it into a hierarchical system of categories.

Comments

Readers can add feedback to published posts via comments. Habari requires all comments to be moderated before they are displayed on the site. Plugins can change this situations so that comments from frequent commenters are automatically approved, or comments left as spam are automatically marked as spam.

Out of the box Habari maintains three comment statuses - approved,unapproved and spam.

Feeds

The term feed indicates a stream of data which is "consumed" by a special application called a feed reader or aggregator. Your blog's feed contains the same data that is presented to visitors viewing your site, but it is formatted in a way that is suitable for machine-to-machine communication, as opposed to machine-to-human communication. There are several formats for this machine-to-machine transmission, with the two most popular being RSS and Atom. Out of the box, Habari only speaks the Atom format.

RSS and Atom allow users to subscribe to your web site in their aggregator, like Bloglines or Google Reader. Their aggregator will periodically poll your website (usually once every couple of hours), checking to see if you've published any new content. If you have, your Habari installation will transmit that new content to the aggregator using the Atom format, and your posts will show up in the aggregator's list of new items.

Your main Atom feed can be located by appending /atom/1 to your site's URL. Separate feeds are also available for comments, posts with the same tag, and the comments for an individual post.

Themes

Themes allow you to customize the look and feel of the site for your readers. Habari includes several themes to choose from after installation, and many more are available from the community.

Plugins

By design, Habari by itself has a basic set of capabilities. Plugins add functionality, new capabilities, or additional content types to Habari. Habari includes several out of the box...

Timeline and Loupe

The timeline and loupe

On certain administration pages, the loupe is a sliding, expandable window that operates on the timeline of a group of data. The default position for the loupe is the far right: the most recent items of the collection. The default width of the loupe encompasses 20 items. You can click inside the loupe and drag it left and right across the timeline: this will change the items shown beneath the loupe based on the date range highlighted by the loupe. On the left and right of the loupe are handlebars, which you can click to drag left or right to expand or shrink the size of the loupe: this will increase or decrease the number of items shown below.

The loupe makes it extremely easy to display and select specific timelines of data. You can drag and expand the loupe to display all the items from June of last year to June of this year. Or you can narrow the loupe to only display items from last month, or yesterday.

Administration

The Dashboard

The Dashboard is the first page you see after you log in to Habari's administrative interface. The dashboard can be reached from any page of Habari's administrative interface by choosing Dashboard from the main menu, or by typing Q followed by D.

Dashboard admin page with default modulesDashboard admin page with default modules

The dashboard provides a summary of useful information for your site. The top section contains a couple of sentences telling you how long your site has been active, a series of high level statistics about your site, how many drafts you have awaiting completion, how many scheduled posts you have, and how many comments you have awaiting moderation.

Next is a series of modules. Modules are small sub-blocks that focus on specific details about your site. Habari comes with modules that contain lists of your recent published posts, recent comments on your blog, and recent activity that has been logged. Plugins can add various other modules dedicated to specific purposes. A plugin that redirects your feeds through the Feedburner service, for example, may use a module to let you know how many subscribers you have, while a plugin that tracks links to your site may use a module to show you the recent links.

Modules can be moved and rearranged, added, and hidden, so they stay in the positions that is most logical to you and show you the information you want to see. If you don't care about recent log activity, click the x in the upper left corner of the log module to hide it. If the first thing you want to see is any recent comments on your site, move the recent comments module to the top left of the modules section by clicking on the grey rectangle in the upper right of the module and dragging the module .

After all the visible modules, the dashboard has a dropdown list of all the modules that are available to show. To show a module you don't currently have displayed, choose the module then click the button with a + on it to the right of the list to display the module.

Managing Content

To manage your content -- draft or published, entry or page -- select one of the Manage links from the main menu. Habari creates a main Manage menu item, which has a submenu listing each type of content in your system, providing a convenient way to access a specific type of content. The destination for each of these menu links is, in fact, the same page: the menus merely provide a shortcut to filter the display by the specified content type.

Manage Posts page

Habari strives to make it as easy as possible to find and manage your content. The first thing to note when visiting the "Manage Content" page is the timeline.

Beneath the timeline are the posts returned by the current filters. Beside the timeline are the filter controls, and additional navigation controls. By default, 20 posts will be presented beneath the timeline in reverse chronological order (newest first). If you have more than 20 items that satisfy the filters, you can page forward and backward to see the next or previous set of 20 posts using the "Older" and "Newer" links at the top left and right, respectively. To the right of the "Older" link is a report of the number of posts that match the current filter, and where your current display falls within that set.

Above the timeline on the Manage Content page is the search box. You can use this box to type in search terms to find content. To find all posts that include the word "Habari", simply type "Habari" into the search box and wait a moment. The list of posts below will be updated, and the quantity indicator to the left of the filter box will be updated. Beside the search box are several links that provide shortcut filter controls. To see only entries, click the "Entry" link: this will add type:entry into the search box, restricting the list of posts to only those of type Entry. Click the "Entry" link again to remove that filter from the list. Using these buttons, you can quickly drill down to see all your content. Click the "Entry" link and the "Draft" link to see all your unpublished entries. Click the "Entry" link again to see all draft posts, regardless of content type.

Additional filters are available for manual entry. To see all posts authored by Scott, type "author:scott" into the search box. There is no shortcut link for these other filters because it's possible that a single site might have, for example, a sufficiently large number of authors as to make the links dominate the screen.

You can combine the filter links with manual search words. To see all drafts about pizza, click the "Draft" button, and then type in "pizza". Or, manually type in "status:draft pizza".

The loupe will update for the current set of filtered posts. The combination of filter controls and timeline provide for extremely flexible content navigation.

Beneath the timeline is the list of posts that match the current filters. The post title, status, author, and date are displayed above a brief snippet of the post. This snippet should provide a bit of context about the post if you can't remember it from the title. The title of the post is a hyperlink, allowing you to click it to view that post on the publish page. The status, author, and date are also hyperlinks that show you similar items (same status, same author, or same publication date). To the right of the post is a "drop button". This is a special control mechanism that acts like both a button and a drop-down list. If you place your mouse over the drop button it will expand to reveal all of the options available to you. The first item -- the one displayed before you placed your mouse over the drop button -- is the default action that will occur if you click your mouse. You may select one of the other items from the list, though, if you don't want to take the default action. When managing content, the usual values of the drop buttons will be "Delete" and "Edit".

To the left of each post is a checkbox. You can tick the boxes to mark one or more posts, allowing you to delete a group of posts. The number of posts marked will be indicated above and below the list of posts. The posts you select will be remembered, allowing you to page through all the posts that match the current filter. The number shown will remind you that you have posts selected that might not be displayed on the current page. Next to the number of selected posts (which says "None selected" if you've not yet selected any) is another checkbox. If you tick this box, all posts on the current page will be selected. Once you do so, another link will appear which allows you to select all posts which match the current filter, even those not visible.

Once you have some group of posts selected, you can delete the entire group at once by clicking the Delete Selected button to the right.

Managing Comments

To manage your comments select the Comments link from the main menu, or type Q, then C.

As with posts, the first thing to note when visiting the Comments page is the timeline and the loupe at the top of the page. The timeline works with comments the same way as it does with posts.

The Manage Comments page

Beneath the timeline are the comments returned by the current filters. Above the timeline are the search and filter controls, and additional navigation controls. By default, 20 comments will be presented beneath the timeline in reverse chronological order (newest first). If you have more than 20 items that satisfy the filters, you can page forward and backward to see the next or previous set of comments using the "Older" and "Newer" links at the top left and right, respectively. To the right of the "Older" link is a report of the number of comments that match the current filter, and where your current display falls within that set.

In the top center of the Comments page is the search box. You can use this box to type in search terms to find comments. To find all comments that include the word Habari, simply type Habari into the search box and wait a moment. The list of comments will be updated, and the quantity indicator to the left of the search box will be updated. Beside the search box are several links that provide shortcut filter controls to the different statuses and types a comment may have. To see only Approved comments, click the Approved link: this will add status:Approved to the search box, restricting the list of comments to only those which are approved. Click the Approved link again to remove that filter from the list. Using these , you can quickly drill down to see all your comments. Click the Unapproved link and the Pingback link to see all your unapproved pingbacks. Click the Unapproved link again to remove the Unapproved filter and see all pingbacks, regardless of status.

You can combine the filter links with manual filter controls and search words. To see all approved comments containing the word terrific, click the Approved link, and then type in terrific. Or, manually type in status:Approved terrific.

The timeline will update for the current set of filtered posts. The combination of filter controls, timeline and loupe provide for extremely flexible content navigation.

Beneath the timeline are the comments that match the current filters, with a set of buttons and a checkbox located above and below the comments. Each comment shows the commenter's name, url, and email address ( if they left them ), the title of the post the comment was made on, the time and date of the comment, and the text of the comment. The commenter's url serves as direct link to the commenter's site, the email address serves as a link to send them an email, and the post title serves as a link to the comment and the post on which it was made.

To the right of each comment is a drop button, as seen with on the Manage Posts pages. The default action for comments on the drop button is Unapprove - to unapprove the comment. You may select one of the other items from the list, though, if you don't want to take the default action. These other actions are Spam - to mark the comment as spam, Approve - to approve the comment, Delete - to delete a comment completely, and Edit - to take you to a new page where you can modify a comment.

To the left of the comment is a checkbox. You can tick the boxes to mark one or more comments, allowing you to execute actions against groups of comments. The number of comments marked will be indicated above and below the list of comments. The comments you select will be remembered, allowing you to page through all the comments that match the current filter. The number will remind you that you have comments selected that might not be displayed on the current page. Next to the number of selected comments (which says "None selected" if you've not yet selected any) is another checkbox. If you tick this box, all comments on the current page will be selected. Once you do so, another link will appear which allows you to select all comments which match the current filter, even those not visible.

Once you have some group of comments selected, you can execute a single action against them. Just click the button at the top or bottom of the page for the action you wish to perform. As with the drop button, your choices are to Delete the comment, mark the comments as Spam, Unapprove previously approved comments, and Approve unapproved comments.

If you hover your mouse over the snippet of text from a comment, note that the background color will change. Click on the text when it does so, and the comment will become available for in-place editing. You can modify any of the fields shown on the Manage Comments page - the text of the comment, the commenter's name, their email address, and their url. The drop-button will also change to contain the options to Update and save any changes you may have made, and Cancel to abandon any changes you made. Clicking either of these options will cause Habari to take the indicated action and return the comment to read only mode with the standard options contained in the drop-button.

Managing Tags

To manage your site's tags, select Tags from the main menu, or type Q, then A.

The Manage Tags page

At the very top of the tags page is a search box. After your site has been in use for a period of time, you can have quite a few tags. Use the search box to narrow the number of tags which you are viewing.

Below the search box you will see the tags which you have used on your site. These will be of various heights, as a visual cue to how frequently they have been used, and each one will have a superscript number to the right of it denoting the exact number of posts on which it has been used.

Select tags by clicking on them. A second click on a tag de-selects it.

To rename a tag, click on it, type the new name in the text box below the tags, then click the Rename button.

To merge multiple tags into one tag, click on each tag you want to merge together, type the name you want to give the tags in the text box below the tags, then click the Rename button.

To delete one or more tags, click on each tag you want to delete, then click the Delete Selected button beneath the tags.

Options

Options admin page

Options for your site include such things as the site title, tagline, number of posts per page, time zone, etc.

To edit your site's options, either select Options from the main menu, or type Q, then O.

Options are searchable by using the search form at the top right of the page.

Themes

Themes admin page

To change your theme select Themes from the main menu, or type Q, then T. This will take you to the Themes page.

The Themes page is divided into two sections. The top section contains one item, your current active theme. The bottom section contains all the themes that are available for you to use.

Each theme will show several pieces of information. To the far left is the name of the theme, its developer, and a screenshot of what it looks like in use. In the middle is a short description of the theme. For inactive themes, to the right is a dropbutton containing available actions for the theme. Your active theme will not have a dropbutton.

If a theme is inactive, the only available action is to Activate it. Clicking on an inactive theme's dropbutton automatically deactivates the theme that is currently active, and activates the theme you selected.

Plugins

Plugins admin page

To manage your plugins, select Plugins from the main menu, or type Q, then P. You will be taken to your Plugins page.

The plugins page is divided into two main sections. At the top of the page is a list of the plugins you have activated. The bottom of the page contains a list of the plugins you have installed, but have not yet activated. Even if you have not added any plugins yourself, this section will contain the plugins that come with Habari.

To the right of each plugin is a dropdown button containing the actions that it is possible for you to perform with the plugin. For inactive plugins, the only possible action is Activate, which you may do by clicking on the dropdown button. Once you do so, the plugin is removed from the list of inactivate plugins and transferred to the list of active plugins.

Active plugins can have several actions associated with them. The most common are Configure, which opens an inline form in which you can set the configuration options for that plugin, and Deactivate, which removes the plugin from the list of active plugins and returns it to the list of inactive plugins. If there is no configuration possible for a plugin, the only action you will be able to perform with it is to deactivate it. Depending on what it does, plugins may add other options to the drop-button.

Each plugin that needs to be configured will have different options, but they all work the same general way. There will be a series of fields to fill in, then a Save and a Close button. After setting the plugin options to your satisfaction, click the Save button to save the changes to the database. Click the Close button to close the configuration dialog.

Some active plugins will have a question mark (?) to the right of their name. Clicking on the question mark will open an inline frame containing usage instructions for that plugin.

Users and Groups

Habari supports multiple users, each of which can be assigned to groups with different permissions within the system. Some users can have phenomenal cosmic powers (over the blog, that is) while some users can be restricted to simply writing new posts depending on their groups.

Users can be members of one or more groups. Groups are assigned permissions. The combined permissions assigned to all the groups to which a user belongs define the things that user is permitted to do within the blog.

When we talk about "what a user can do", what we're really saying is "things that can be done by one of the groups to which this user belongs". It's important to remember that users don't have any permission on their own. Users can only do stuff based on the permissions assigned to the groups to which they blog. But it's awkward to keep saying "This user belongs to a group with permission to do Foo", so for brevity we'll simply say "Users who can do Foo".

Users

Users with the "add, remove, and edit users" permission can, obviously, add, remove, and edit users. A user with this permission can access the Users page from the main menu. Here is presented a list of all the user accounts in the system, and a brief report on their activity within the system. Above the user list is a form to create a new user: simply supply a username, email address, and password.

If there are many users on the system, the display can be filtered by searching for part of a user name.

To the left of each user is a checkbox. This is only used when deleting a user account. Select the user(s) to be deleted, select whether to reassign that user's posts to a different user or to delete the posts from the system, and press the delete button.

Clicking on any user will display that user's details page.

User

From a user's details page one may specify additional information about a user or they may specify their own information, if they're viewing their own user detail page. Most of the data displayed on this page is purely informational, and not really used by Habari anywhere.

The Apply button is used to save any changes made on the user page. A user can also be deleted directly for their page by using the delete button. Choose whether you want to reassign posts to another users or not before using the delete button on the page.

Note that plugins can modify this page to add new fields.

Groups

Users with the "manage groups and permissions" permission can access the Groups page from the main menu. By default, all groups defined within the system are displayed. You may modify a single group's details by selecting it from the drop-down list at the top of the page, by clicking on the group's name in the main list, or by clicking the "Edit" option from the drop-button to the right of that group.

To add a new group, simply supply a group name in the field at the bottom of the page and click the "Add Group" button. Newly created groups will have no permissions, by default.

When editing a group, you are first presented with the list of users that are members of that group. You may add additional members from the drop-down list and then clicking the "Add" button. IMPORTANT: changes to the list of users are not saved to the database until you click the "Apply" button at the bottom of the page!

Beneath the user listing is a list of all of the defined permissions within the system, with controls to enable or disable access to these permissions for the group.

Group admin page showing permissions granted to 'admins' group.
Permissions

There are two kinds of permissions within Habari: binary and CRUD:

Binary Permissions

Binary permissions are either/or: a group may either do the thing, or not do the thing. For example, the "add, remove, and edit users" permission is either/or. Either a user can add and edit users, or they cannot.

There's a subtle distinction for binary permissions between "not assigned" and "denied". In either case, the group is not permitted to do the thing defined by the permission. The distinction comes into play when a user belongs to multiple groups. Let's look at a practical example to illustrate the point.

User Scott is assigned to the "Content Managers" group, which has been granted permissions to "Manage comments on all posts", "Manage comments on one's own posts", and "Manage tags". The specific assignment of these permissions allows Scott to manage the content on the blog. The "Content Managers" group is neither granted nor denied the "Change theme" permission. Since the "Change theme" permission is not specifically granted, Scott may not change the site theme.

Scott is next added to the "Site Managers" group, which has been granted permission to "Manage options" and "Change theme". Since Scott is in a group that specifically grants permission for "Change theme", Scott may now change the current theme.

After some time, the blog owner decides that he really likes the current theme, and doesn't want anyone changing it. Rather than go through each of the groups to manually remove any previously granted permission to "Change theme" the site owner makes a new group called "No Theme Changes", and assigns all the users to this group. The only permission setting for this group is to specifically deny access to the "Change theme" permission. The deny permission overrides any specifically granted permission for the same thing. Scott is now a member of the "Site Managers" and "No Theme Changes" groups. The former specifically grants him permission to change the theme, but the latter specifically revokes permission to change the theme. Denied permissions always override granted permissions.

CRUD Permissions

CRUD stands for "Create, Read, Update, Delete" and indicates that there are several related actions for that permission. For example, "Permissions on one's own posts" is CRUD. A user might be permitted to create new posts, but not update or delete posts they had previously created.

As with binary permissions, there is a difference for CRUD permissions between "not assigned" and "denied". A particular permission not assigned to one group may be assigned to another group. A user that was a member of both groups would have the permission, because one of the groups to which they belong was assigned that permission. Any CRUD permissions that are specifically denied to a group will deny that permission to all members of the group, regardless of other group membership that might grant that permission.

Using the cascading nature of groups and permissions, it is possible to create robust group assignments to enforce granular permissions. You can create "Content Managers" who have access to modify the content of the site without changing site settings or managing users. You could then create a "Users Managers" group that only has permission to manage users. As members of the "Content Managers" group gain experience and prove their trustworthiness, you can add their user accounts to the "User Managers" group so that they can begin adding new users, and managing current ones.

Default Permissions

Habari creates a set of permissions to enable managing access to its different areas. Plugins can add their own permissions to control access to their added functionality. The default permissions are listed below.

Logs

Habari keeps records of most of the interesting things about which it knows. It records each time someone logs in, each time a new item is posted, and the like. By selecting Logs from the main menu (shortcut: Q L), you can review the recent activity on your site.

At the top of the page is the familiar loupe and filter input box, allowing you to control what log messages to display. At the top of each column of data is a drop-down allowing you to filter the logs by specific elements. For example, you can select all the log entries generated by a specific IP address, or all logs generated by a specific user. You can apply multiple filter controls, allowing you to drill down to all authentication messages from a specific IP address and a specific user.

To the left of each log entry is a checkbox, allowing you to select one or more log entries. Selected entries can be manually deleted.

It is important to note that these logs are not permanent, and will expire after some time (usually a few weeks).

Importing Content

Habari is able to import post, comment, category/tag, and user data from a growing list of importable platforms. To import content, first activate the corresponding Importer plugin on the plugins page (Q P in the Main Menu) and then follow the steps detailed on the Import page.

Once the import process is complete your old data has been copied and can be managed through Habari, and can be deleted from the other platform if desired.

Important Note: Deactivate any spamchecking plugins or plugins that contact outside sites (such as pingback) before beginning to import your data. If active, these will greatly slow down, or even prevent, the successful completion of the import process. In the case of spamchecking plugins, comments may incorrectly be marked as unapproved if a spamchecker plugin is active.

After you have completed the import process, remember to reactivate the plugins you deactivated.

Extending Habari

By design, Habari is built with the basic set of capabilities needed by everyone to create and maintain a blog or simple website. It is, however, also designed to be highly extensible through the use of plugins and themes other than those with which it ships.

Themes

Your site's theme is its basic look and feel as seen by your visitors. Habari comes with several themes.

You aren't limited to these themes in your choices. There are many more themes listed in Habari's theme repository at Habari's wiki

Plugins

Habari comes packaged with several plugins. These are intended to serve as examples of best practices in plugin creation for developers, and to provide useful functionality to everyone.

Miscellaneous Plugins
Media Plugins
Importers

In addition to the plugins that are packaged with Habari, dozens of other plugins have been created to extended the software's functionality. These cover everything from WYSIWYG editors, to contact forms, to plugins to allow you to implement custom URLs for your site. Your can find an extensive list on the wiki plugin page, and even more at the Habari Distribution Directory.

Getting Help

Forums and Mailing Lists

There exist two mailing lists for Habari, one focused on end-user support, and the other focused on nitty-gritty development and programming issues.

habari-users is entirely focused on Habari end-user support. This is the first place to ask for help. When reporting problems, please provide as much information as you can. Be sure to accurately copy any specific error messages you receive. If you can reliably reproduce a problem, describe in detail the steps necessary to do so. It is often helpful to provide a link to your site, so that others can see the problem first-hand, but at the least please indicate who your hosting provider is.

habari-dev is focused on Habari development: programming, plugin design, and the like. All of Habari's long-term development takes place on this list, and ideas and suggested, debated, and revised. If you're interested in helping Habari programming, this is the list for you.

There is also a forum at The forums are focused on Habari user to user support.

Reporting Bugs / Suggesting Improvements

Habari succeeds because people like you help improve it every day. One of the easiest ways to contribute to the success of Habari is to report problems. The habari-users mailing list is the first place that problems should be reported: if the issue is known, you'll be provided with confirmation of that fact and hopefully some information to help you work around the problem until it is fixed. If you identify a new problem, you may be asked to file a bug report. It's easy to do!

Habari Trac is the place to file bug reports. Before you can file bugs, you need to register an account with the system. Click the Register link at the far right of the screen. Once you've created an account you can log in by clicking on the Login link. Once logged in, you can file a new ticket!

Creating a New Ticket

The first thing you need to provide is a succinct summary of the problem. Be concise, but don't be vague: the summary you provide is the first thing people will read when reviewing bugs to be fixed, so make sure that the developers get a jumpstart on your problem by supplying them with a meaningful summary. If you see an HTTP 500 error page every time you try to log in, a good summary might be 

HTTP 500 error every time I try to log in

This immediately indicates the specific error and the action that produces it. A poor summary for this problem would be 

Can't log in!

This does not indicate the specific error you see.

Summaries are important! Please try hard to provide a meaningful summary.

Next you indicate whether your ticket is due to a defect with Habari, or if you're simply making a suggestion for enhancement. The Habari developers love to see suggestions for enhancements because they help steer the long-term growth of Habari.

Below this you enter a full description of the problem or suggestion. Be as verbose as possible. If you have a specific error message, paste it here. If you have log data, paste it here. If you can reproduce the problem in one or more ways, describe in detail each of the ways to do so. The more information you can provide, the greater the chance of a developer fixing the problem! You can also upload screenshots if that helps to describe the problem: click the checkbox labeled "I have files to attach to this ticket". This will allow you to upload files that will be attached to your report. The version of Habari you are using, the browser and its version, and the database backend ( MySQL, SQLite, Postgres, etc. ) are also very helpful in diagnosing and fixing issues that you report.

In the section labeled Ticket Properties you can fine-tune some details about your ticket. If you're not sure what any of these mean, leave them all at the default values.

When you're all done, click "Submit ticket". This will add your ticket to the system, and a Habari developer will eventually review it. You might want to bookmark your ticket, and come back to check on it periodically: the Habari developers might ask you questions in comments to your ticket, seeking additional information or asking you to try a proposed fix to confirm that it works for you.

Please keep in mind when filing tickets for bug reports or feature enhancements that the list of tickets is completely public. DO NOT post any passwords or other sensitive information.

A note about security issues

As mentioned above, all items filed in the Habari Trac are public. If you are reporting a security problem, or a potential security problem, we respectfully ask that you first contact security@habariproject.org so that we can review the situation with you without jeopardizing our users' sites. If you open a ticket with details of how to execute an attack against a Habari installation, someone somewhere will see that information and exploit it.

Developer Introduction

To learn more about Habari internals and developing for Habari, listed are some useful starting points: