[[PageOutline(2-5,Contents,pullout)]]

= Display a message of the day in Trac

== Description

This plugin allows the system-administrator to display a message of the day (MOTD) on ''every'' Trac page. Once the user acknowledges the message, it is no longer shown. It is similar to the NewsFlashMacro, with the difference that every page is affected instead of only the ones where the macro is embedded.

For a sysadmin it was always hard to inform every Trac user about upcoming system updates, maintenance periods, hardware changes or similar. With this plugin it is now possible to display such message(s) on every Trac page, even when having many projects, by simply editing one text file.

== Bugs/Feature Requests

Existing bugs and feature requests for MotdPlugin are 
[report:9?COMPONENT=MotdPlugin here].

If you have any issues, create a 
[/newticket?component=MotdPlugin new ticket].

[[TicketQuery(component=MotdPlugin&group=type,format=progress)]]

== Download

Download the zipped source from [export:motdplugin here].

== Source

Check out MotdPlugin from [/svn/motdplugin here] using Subversion, or [source:motdplugin browse the source] with Trac.

== Installation

General instructions on installing Trac plugins can be found on the [TracPlugins#InstallingaTracplugin TracPlugins] page.

== Configuration

MotdPlugin can be configured with the following options in your `trac.ini` file:
{{{#!ini
[motd]
message_file = /data/messag_of_the_day.ini
message_dir = /data/motd.d
date_format = <planned>
frame_width = <motd-frame width in pixel>
frame_height = <motd-frame height in pixel>
}}}

message_file
 * default: /data/motd.ini
 * location of the file containing the messages to display
message_dir
 * default: /data/motd.d
 * directory containing HTML-files with messages to display
date_format (planned)
 * default: %Y-%m-%d %H:%M
 * allows configuration of the date-format for parameter ''valid_until''. format is given in python 'datetime' format.
frame_width
 * default: 400px
 * sets the width of the MOTD-frame in pixel (range: 400-900)
frame_height
 * default: 300px
 * sets the height of the MOTD-frame in pixel (range: 300-800)

=== motd.ini file

MotdPlugin uses an ini-style file for configuring the messages that should be displayed:
{{{
[MsgName]
title = <message header>
message = <message text (in one line!)>
priority = <message priority, for future use>
valid_until = <expiration date for message>
repeat = n-i
}}}

The section name (!MsgName) has to be unique within the message file.
Format of the expiration date is (currently) "yyyy-mm-dd HH:MM", next version will have a configurable format.

''repeat'' specifies how often (n) and in which interval (i) the message should be displayed. ''n'' must be a positive integer and ''i''
must be in the range of: ''m'' for minutely, ''h'' for hourly, ''d'' for daily and ''w'' for weekly.

== Example

{{{
[Message1]
title = System Maintenance
message = Trac services will be unavailable next Friday from 4pm to 6pm!
valid_until = 2011-04-24 18:00

[Message2]
title = New version of xxx has been installed
valid_until = 2011-05-13 23:59
repeat = 3-d
}}}

The first example should be self explanatory. In the second example there is the ''message'' parameter missing! In that case MotdPlugin searches for a file named ''Message2.html'' in the directory specified by ''message_dir'' in `trac.ini` and displays the complete content of this file.
This message will be shown 3 times, interval is daily. If the expiration date is before the repeat period finishes, the message is no longer shown.

== Recent Changes

[[ChangeLog(motdplugin, 3)]]

== Author/Contributors

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