[[PageOutline(2-5,Contents,pullout)]]
= Blogging system for Trac =

{{{
#!html
<div class="system-message">
There will be no 0.11 version.  For 0.11 blogs, use the <a href="http://trac-hacks.org/wiki/FullBlogPlugin">FullBlogPlugin</a>.
</div>
}}}

== Description ==

A blogging system for Trac.

TracBlogPlugin allows one to harness the power of TagsPlugin to generate blogs.  It provides a wiki macro so that blogs can be inserted in any wiki page.  It also provides a navigation component.

== Screenshots ==

[[Image(wiki:TracBlogPlugin/screenshots:blog_link.png,320,200)]]
[[Image(wiki:TracBlogPlugin/screenshots:blog_post.png,320,200)]]
[[Image(wiki:TracBlogPlugin/screenshots:blog_admin.png,320,200)]]

== Bugs/Feature Requests == 

Existing bugs and feature requests for TracBlogPlugin are [query:status!=closed&component=TracBlogPlugin&order=priority here].

If you have any issues, create a 
[/newticket?component=TracBlogPlugin&owner=pacopablo new ticket].

== Download ==

Download the zipped source from [download:tracblogplugin here].

== Source ==

You can check out TracBlogPlugin from [http://trac-hacks.org/svn/tracblogplugin here] using Subversion, or [source:tracblogplugin browse the source] with Trac.

Please do not use [source:/tracblogplugin/trunk trunk].  It is known to not work.  It is a work in progress.  When it is ready, it will be renamed.

== Installation ==
TracBlogPlugin should work with 0.9.x and 0.10.x.

=== Requirements ===
 * TagsPlugin >= 0.3 and < 0.5
 * [t:WebAdmin WebAdmin]

If using 0.9.x it may be necessary to install the TagsPlugin and the [t:WebAdmin WebAdmin] plugin globally instead of the project's plugin directory.  This is due to the need for those plugins to load before the TracBlogPlugin loads.  Unfortunately, 0.9.x does not support plugin dependencies, so the only way to get it to work properly is installing the above plugins globally via:
{{{
# python setup.py install
}}}
An indication that this may be the case is if a message similar to the following is displayed
{{{
...
resolve
    raise DistributionNotFound(req)  # XXX put more info here
DistributionNotFound: TracWebAdmin
}}}

Install in the same manner as any other Trac plugin:
{{{
# python setup.py bdist_egg
# cp dist/*.egg /srv/trac/env/plugins
}}}

If the TracBlogPlugin is installed system wide, then you will need to enable the plugin in your trac.ini:
{{{
[components]
tBlog.* = enabled
}}}

== Integration ==

If you want '''only''' the blog to be your frontpage '''instead''' of the wiki, in trac.ini:
{{{
[trac]
default_handler = TracBlogPlugin
}}}
nb: Using the TracBlogPlugin as the default_handler is a non supported, non recommended usage. But it has been known to work.


Otherwise, if you want to integrate the blog into your wiki, use the following examples in conjunction with regular WikiFormatting:

 {{{[[BlogShow]]}}}::
 Displays a blog based on tags
    
 The list of tags to be shown can be specified as arguments to the macro.
 If no tags are specified as parameters, then the default 'blog' tag is
 used.

 The following options can be specified:

 '''union''' - Specify whether the join for the tags listed should be a union or intersection(default).[[br]]
 '''num_posts''' - Number of posts to display.[[br]]
 '''year''' - Year for which to show posts.[[br]]
 '''month''' - Month for which to show posts.[[br]]
 '''day''' - Day of the month for which to show posts.[[br]]
 '''delta''' - How many days of posts should be shown.[[br]]
 '''mark_update''' - Specify whether to show "Updated on" for posts that have been updated.[[br]]
 '''hidecal''' - Hide the calendar (when set to true).[[br]]

 If specifying dates with {{{year}}}, {{{month}}}, and/or {{{day}}}, the
 current value is specified if missing.  For example, if {{{day}}} is 
 specified but {{{year}}} and {{{month}}} are not, then {{{year}}} will be
 filled in with the current year and {{{month}}} will be filled with the 
 current month.  If only {{{year}}} and {{{month}}} are specified, then that
 indicates the whole month is desired.                     

 The {{{num_posts}}} options is bounded by the date options if combined. For
 example, if {{{num_posts=5}}} and {{{month=4}}} is specified, it will show 
 up to 5 posts from the month of April.  If only 3 posts exist, then only 3 
 are shown.  If a date option is not specified, then it will show the last 
 {{{num_posts}}} posts.
{{{
[[BlogShow()]]
[[BlogShow(blog,pacopablo)]]
[[BlogShow(blog,pacopablo,union=True)]]
[[BlogShow(blog,pacopablo,num_posts=5)]]
[[BlogShow(blog,pacopablo,month=4,num_posts=5)]]
[[BlogShow(blog,pacopablo,year=2006,month=4)]]
[[BlogShow(blog,pacopablo,year=2006,month=4,day=12)]]
[[BlogShow(blog,pacopablo,delta=5)]]
[[BlogShow(blog,pacopablo,delta=5,mark_updated=False)]]
[[BlogShow(blog,pacopablo,num_posts=3,hidecal=true)]]
}}}

 {{{[[BlogPost]]}}}::
 Inserts a link to create a new blog post

 Accepts keyword arguments that specify default parameters. The macro will be hidden unless the user has {{{BLOG_POSTER}}} permissions.

 '''tag''' - Tag that populates the "Tag under" field. This key may be specified as a tuple or list to pass multiple values.[[br]]
 '''blogtitle''' - Default blog entry title.[[br]]
 '''text''' - Default entry body text.[[br]]
 '''pagename''' - Default wiki page name.[[br]]
 '''readonly''' - Default readonly page status.[[br]]
 '''link''' - Text to display as the link.[[br]]
{{{
[[BlogPost()]]
[[BlogPost(tag=(blog,pacopablo))]]
[[BlogPost(tag=blog,blogtitle="A Simple Title",text="Body Text")]]
[[BlogPost(tag=blog,pagename=blog/newpage,readonly=1)]]    
[[BlogPost(tag=(blog,pacopablo),link="A New Blog Post")]]  
}}}

== trac.ini Documentation ==
{{{
[blog]
date_format = %x %X              ; format string in strftime format
page_format = %Y/%m/%d/%H.%M     ; format string in strftime format
default_tag = blog               ; comma separated list of tags
post_size = 1024                 ; number of bytes to show before truncation
history_days = 30                ; number of days of blog entries to show
new_blog_link = New Blog Post    ; default value for new blog post link
}}}

= Users =
If you use [TracBlogPlugin TracBlog], please post a link to your blog:

 * [http://häcker.net/cgi-bin/trac.cgi DWTs Heavy Industries]
 * [http://www.phpunit.de/wiki/GSoC2007MutationTestingDevBlog PHPUnit GSoC '07 Dev Blog]
 * [https://pacopablo.com/ Casa de Pacopablo]
 * [http://dev-1.borgforge.net/castpodder CastPodder]
 * [https://kashmir.g33xnexus.com/projects/precursors/wiki The Seventh Game: Precursors]
 * [http://swapoff.org/blog SwapOff.org] Personal blog of Alec Thomas
 * [http://voidblog.de/ voidblog.de] Christian Aust
 * [http://www.trash-media.de/tim/blog betatim's blog] Personal blog of Tim Head, betatim
 * [http://opensysadmin.com/trac/blog OpenSysAdmin.com] Daniel Joseph Barnhart Clark
 * [http://www.maiamailguard.com Maia Mailguard]  Anti-spam software
 * [http://www.mocksoul.ru/trac/blog MockSoul Devblog] Vadim Burmakin personal blog
 * [http://plumi.org plumi.org] Video sharing plugin for [http://plone.org Plone].

== Recent Changes ==

[[ChangeLog(tracblogplugin, 3)]] 

== Author/Contributors ==

'''Author:''' [wiki:pacopablo] [[BR]]
'''Maintainer:''' [wiki:pacopablo] [[BR]]
'''Contributors:'''