blog_index.cgi - A simple blog-style view of your archived list messages

- NAME
- DESCRIPTION
- USAGE

- Use it like a CGI script.
- As a Javascript Library
- As a Server Side Include
- By Itself
- By Copying the HTML/Javascript

- CONFIGURATION

- $Plugin_Config->{Default_List}

- DIAGNOSTICS
- CONFIGURATION AND ENVIRONMENT
- SEE ALSO
- DEPENDENCIES
- INCOMPATIBILITIES
- BUGS AND LIMITATIONS
- AUTHOR
- LICENCE AND COPYRIGHT

# NAME

blog_index.cgi - A simple blog-style view of your list's archived messages

# DESCRIPTION

This small extension script prints out the last, x archived messages, in a blog-style fashion, with the text of all the archived messages shown on one screen. You can then embed this into a page you may have on your site, either by calling the extension like a Javascript library, or calling it as an old-school Apache Server Side Include.

In a pinch, you can then use Dada Mail in a more blog-like manner, by creating new entries to your Dada Mail-powered blog by creating new archive messages:

In Dada Mail's, ``Send a List Message'' screen, there's a fieldset labeled, Archive Options. Expanding this fieldset will reveal options to, Archive, but DO NOT Send the message you're creating and also an option to Backdate the entry. This will allow you to add new entries to your list's archives, without having to send the messages out to your subscribers.

One thing I find useful is to have my blog powered by Dada Mail: I can make new entries more frequently, but just archive and not sending - much more frequently than I feel comfortable sending to my entire list, but have all the entries available on my blog. That way, my mailing list gets the more important messages sent and if I want to get a bit chatty, I can, without deluging my list with messages they may not want to have fill up their inbox.

This simple extension does not support some of the more familiar blog-like things, such as commenting on an entry, but does provide other features. Since Dada Mail already supports RSS/Atom feeds for its archived messages, your blog powered by Dada Mail does as well. The core of Dada Mail also supports full text searching of archived messages.

For a simple site where a blog is just one part of the entire site, such simplicity may be all you really need.

# USAGE

## Use it like a CGI script.

Put it in your, extensions directory (ala: cgi-bin/dada/extensions), chmod 755, visit it in your web browser.

## As a Javascript Library

To add this form to your HTML page, just add a line that looks like this:

            <script type="text/javascript" src="http://example.com/cgi-bin/dada/extensions/blog_index.cgi"></script>

Where, http://example.com/cgi-bin/dada/extensions/blog_index.cgi is the URL to this extension.

## As a Server Side Include

You can also call it as a server side include, like this:

      <!--#include virtual="/cgi-bin/dada/blog_index?mode=html" -->

Make sure to add the query string, `mode=html`

## By Itself

Not really a method, but you can view the HTML and Javascript produced by visiting the extension in your web browser, with the same query string you use for the Server Side Include:

http://example.com/cgi-bin/dada/blog_index.cgi

## By Copying the HTML/Javascript

You could also try just copying the source that this script produces from the URL above, and paste it into a page/script/etc that you'd like.

Probably not the best idea, but I'll throw that idea for ya.

# CONFIGURATION

There's no configuration that you are required to do, but there's many things that you can do. We'll try to cover everything:

## $Plugin_Config->{Default_List}

This extension currently shows one list's archives at one time - there's no collating of archive entries from different lists, or anything.

The, `Default_List` config variable holds what the default list can be. Set it to a list's shortname:

     $Plugin_Config->{Default_List}  = 'mylistshortname';

If no list is set, you will need to tack on a query string to the end of the script, when you call it:

     http://example.com/cgi-bin/dada/extensions/blog_index.cgi?list=mylistshortname

In this example, `mylistshortname` is your list's shortname and:

     ?list=mylistshortname

Is the entire query string you'll have to tack on.

If you've configured this variable incorrectly, you'll most likely receive an error in your web browser, so take care in setting it correctly.

# DIAGNOSTICS

None, really.

# CONFIGURATION AND ENVIRONMENT

There are a few variables at the top of the script that will need to be changed. They are:

- $Plugin_Config{Default_List}

  Required

  You'll need to set $Plugin_Config{Default_List} to a valid list shortname that you would like to use for your blog index.

- $Plugin_Config{Entries}

  Optional

  $Plugin_Config{Entries} holds the count of how many archived messages you'd like shown at once. If set to `undef` or a number below, 1, this extension will use the default value set in the Manage Archives - Archive Options - Advanced list control panel screen (which itself defaults to, 10.

- $Plugin_Config{Style}

  Optional

  Currently, there are two styles supported when showing the archived messages, full and, blurb

  If this variable is set to, full, the entire archived message will be shown.

  If this variable is set to, blurb, only the first few words (basically) will be shown and a link to the rest will be provided.

- $Plugin_Config{Template}

  Optional

  This variable holds the embedded template for the actual HTML to display. If you'd like to change the design of the HTML that's outputting, here's the place to do it.

  The Template is written in the HTML::Template system, just like much of the rest of Dada Mail.

  Some of the variables that are available:

  - archive_entries

    This holds all the archived entries that are to be displayed. You'll most likely want to call it in a loop:

         <!-- tmpl_loop archive_entries -->
            ...
         <!--/tmp_loop>

    You can also use it to check the existance of entries available:

         <!-- tmpl_unless archive_entries -->
            Currently, there are no archived entries!
         <!--/tmpl_unless-->

    When you're looping over all the archived messages, other variables will be available to you, inside the loop:

    - pretty_subject

      ``pretty-fied'' version of the subject. If you want the raw subject, use the `subject` variable.

    - pretty_date

      ``pretty-fied'' version of the date the message was posted on. Should be following the formatting options you've set in: Manage Archive - Archive Options - Advanced

    - blurb_style

      Is set to, 1 if you're using the, blurb style in, `$Plugin_Config-`{Style}>.

    - message

      Will hold the actual email message body. If you're using the, full style, the message will already be converted to HTML (if needed) and massaged in a way that it'll look really well without any help.

      If you're using the blurb style, the message will be a plaintext string, with all HTML encoding stripped.

    - PROGRAM_URL

      Holds the URL to your Dada Mail Installation

    - list

      Holds the value that you've set in, $List

    - message_id

      Holds the message_id that's associated with the archived message.

  - list

    Holds the value that you've set in, $List

    (This is also available to you, outside of the `archive_entries` loop.

  - PROGRAM_URL

    Holds the URL to your Dada Mail Installation

    (This is also available to you, outside of the `archive_entries` loop.

# SEE ALSO

Dada Mail also can share its archives using its built-in RSS/Atom feeds. In your list control panel, go to:

Manage Archive - Archive Options - Advanced

# DEPENDENCIES

# INCOMPATIBILITIES

# BUGS AND LIMITATIONS

Currently, this extension is simple, and only handles one list at a time.

If this extension becomes popular, I may give it the capability to handle all lists and at the same time, as well as have some of the more interesting archive capabilities support (embedded attachments, etc)

Please, let me know if you find any bugs.

# AUTHOR

Justin Simoni

See: http://mojo.skazat.com/contact

# LICENCE AND COPYRIGHT

Copyright (c) 2007-2008 Justin Simoni All rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.