view release on metacpan or  search on metacpan

MiniWiki.pm  view on Meta::CPAN

  # URI that the user sent contains "(function)" as an element,
  # otherwise, call the default, view_function.
  my $function = "view_function";
  $uri =~ m{^\(([a-z]*)\)/?(.*)} and $function = "$1_function";

  my %args = $r->args;
  my $revision = $args{rev};
  my $page = $2 || $uri;

  # all dot files are hidden and forbidden
  if ($page =~ /^\./) {
    return &pretty_error($r, "All dot files are hidden", FORBIDDEN);
  }

  my $retval;
  eval {
    no strict 'refs';
    $retval = &$function($r, $page || "index", $revision);
  };

  if ($@) { return fatal_error($r, "Unknown function $function called: $@"); }
  else { return $retval; }
}

# This function converts an URI to a filename. It does this by simply
# replacing all forward slashes with an underscore. This means that all
# files, regardless of URI, finds themselves in the same directory.
# If you don't want this, you can always modify this function.
sub uri_to_filename {
    my ($uri) = @_;

	$uri =~ s/(\/)$//g;
    $uri =~ tr/\//_/;
    return $uri;
}


# this function creates an instance of an Rcs object using the
# provided page name. It handles file names with spaces. The new
# Rcs object is returned, ready to be used for rcsdiff, etc.
# locking must be handled by the calling function.
sub rcs_open {
  my ($r, $file) = @_;
  	
  delete @ENV{qw(PATH IFS CDPATH ENV BASH_ENV)};

  if ($file =~ /^([0-9a-zA-Z\ \_\:\.\-]+)$/) {
    $file = $1;
  } else {
    die "Bad page name: $file!";
  }

  my $obj = Rcs->new;
  $obj->rcsdir($datadir);
  $obj->workdir($datadir);
  $obj->file($file);

  return $obj;
}

# This function allows the user to change his or her password, if
# the perl variable "authen" is configured in the Apache configuration
# and points to a valid htpasswd file which is writeable by the user
# executing MiniWiki.
sub newpassword_function {
  my ($r, $uri) = @_;

  if ($authen eq -1) {
    return &pretty_error($r, "Authentication has been disabled in Apache::MiniWiki.");
  }

  my $q = new CGI;
  my $text;

  if ($q->param() && ($q->param('password1') eq $q->param('password2'))) {
    my $pass1 = $q->param('password1');
    $pass1 =~ s/\r//g;
    eval {
      my $htp = new Apache::Htpasswd($authen);
      $htp->htpasswd($r->connection->user, $pass1, 1);
    };
    if ($@) {
      return fatal_error($r, "$@");
    }
    $text = "Password changed.\n";
  } elsif ($q->param() && ($q->param('password1') ne $q->param('password2'))) {
    $text = "The passwords doen't match each other.\n";
  } else {
    $text = <<END;
<form method="post" action="${vroot}/(newpassword)">
<fieldset>
 New password: <input type="password" name="password1"><br/>
 Again: <input type="password" name="password2"><p>
 <input type="submit" name="Change">
 </fieldset>
</form>
END
  }
  
  $template->param('vroot', $vroot);
  $template->param('title', 'New Password');
  $template->param('body', $text);
  
  $r->send_http_header('text/html');
  print $template->output;

  return OK;
}

# This function saves a page submitted by the user into an RCS file.
sub save_function {
  my ($r, $uri) = @_;
  my $fileuri = uri_to_filename($uri);
  
  if ($r->method() ne "POST") {
    return fatal_error($r, "Invalid save, POST required.");
  }

  my $q = new CGI;

  my $text;
  # is this an uploaded binary file? If so, shlurp the data from
  # the file handle provided by CGI.pm.
  if (my $fh = $q->upload('text')) {
    local undef $/;
    $text = <$fh>;
  } else {
    $text = $q->param('text');
    $text =~ s/\r//g;
  }

  if ($q->param("Save") =~ /preview/i) {
    return &edit_function($r, $uri, $text);
  }

  my $comment = $q->param('comment');
  my $user = $r->connection->user || "anonymous";

  chomp ($comment);
  $comment =~ s/^\s*//g if $comment;
  $comment =~ s/\s*$//g if $comment;

  if (length($text) < 5) {
    return &pretty_error($r, "Not enough page text was provided.");
  }

  if (length($comment) < 3) {
    return &pretty_error($r, "A longer comment is required.");
  }

  my $file = &rcs_open($r, $fileuri);

  if (-f "${datadir}/${fileuri},v" && $file->lock) {

MiniWiki.pm  view on Meta::CPAN

	finish:

	$changes .= "<br/>\n";
	$changes .= "Current date: <b>" . `/bin/date` . "</b><br/>\n";

	return $changes;
}

# If enabled as a PerlAccessHandler, allows public viewing of
# a Wiki, but leaves existing authentication in place for editing
# content.
sub access_handler {
  my $r = shift;

  return OK unless $r->some_auth_required;

  my $uri = $r->uri;
  unless ($uri =~ /\((edit|save|revert)\)/) {
    $r->set_handlers(PerlAuthenHandler => [\&OK]);
    $r->set_handlers(PerlAuthzHandler => [\&OK])
      if grep { lc($_->{requirement}) ne 'valid-user' } @{$r->requires};
  }

  return OK;
}

## is the link a binary upload?
## are file uploads enabled?
sub is_binary {
  my $uri = shift;
  return 0 if $uploads =~ /^n/i;
  return ($uri =~ /\.(.+)$/ && grep /$1/i, @binfmts);
}

## is the link really an inline image?
## are file uploads enabled?
sub is_img {
  my $uri = shift;
  return 0 if $uploads =~ /^n/i;
  return ($uri =~ /\.(.+)$/ && grep /$1/i, @imgfmts);
}

1;

__END__

=head1 NAME

Apache::MiniWiki - Miniature Wiki for Apache

=head1 DESCRIPTION

Apache::MiniWiki is a simplistic Wiki for Apache. It doesn't have 
much uses besides very simple installations where hardly any features
are needed. What is does support though is:

  - storage of Wiki pages in RCS
  - templates through HTML::Template
  - text to HTML conversion with HTML::FromText
  - basic authentication password changes
  - uploading of binary (pdf, doc, gz, zip, ps)
  - uploading of images (jpg, jpeg, gif, png)
  - automatic thumbnailing of large using ImageMagick
  - sub directories
  - view any revision of a page
  - revert back to any revision of the page
  - basic checks to keep search engine spiders from deleting 
    all the pages in the Wiki

=head1 DEPENDENCIES

This module requires these other modules:

  Apache::Htpasswd
  Apache::Constants
  CGI
  Date::Manip
  Image::Magick (Optional)
  HTML::FromText
  HTML::Template
  Rcs

=head1 SYNOPSIS

Add this to httpd.conf:

  <Location /wiki>
     PerlAddVar datadir "/home/foo/db/wiki/"
     PerlAddVar vroot "/wiki"
     SetHandler perl-script
     PerlHandler Apache::MiniWiki
  </Location>

=head1 AUTHENTICATION EXAMPLES

  Require a password to read/write any page:
  
  <Location /wiki>
     PerlAddVar datadir "/home/foo/db/wiki/"
     PerlAddVar vroot "/wiki"
     PerlAddVar authen "/home/foo/db/htpasswd"
     SetHandler perl-script
     PerlHandler Apache::MiniWiki

     AuthType Basic
     AuthName "Sample Wiki"
     AuthUserFile /home/foo/db/htpasswd 
     Require valid-user
  </Location>

  Public can read, but need password to edit/save/revert a page:
  
  <Location /wiki>
     PerlAddVar datadir "/home/foo/db/wiki/"
     PerlAddVar vroot "/wiki"
     PerlAddVar authen "/home/foo/db/htpasswd"
     SetHandler perl-script
     PerlHandler Apache::MiniWiki

     Require valid-user # or group foo or whatever you want
     PerlAccessHandler Apache::MiniWiki::access_handler

     AuthType Basic
     AuthName "Sample Wiki"
     AuthUserFile /home/foo/db/htpasswd 
     Require valid-user
  </Location>

=head1 USE AS A CGI SCRIPT

Apache::MiniWiki can also be called by an Apache::Registry CGI script. By 
running it in this manner, absolutely no changes need to be made to the
web server's httpd.conf, as long as Apache has mod_perl built in, and the 
Apache::Registry (or a module that emulates it) is available.

Copy the example wiki.cgi into your CGI directory and assign it the 
appropriate permissions. Edit wiki.cgi and add the required options, such as
the datadir and vroot variables:

 $r->dir_config->add(datadir => '/home/foo/db/wiki/');
 $r->dir_config->add(vroot => '/perlcgi/wiki.cgi');

Note #1: This may be a great way of integrating Apache::MiniWiki into
an existing site that already has it's own header/footer template system.

Note #2: This method assumes that the site administrator is already
using Apache::Registry to speed up CGI's on the site. If they aren't,
have them set up mod_perl as it was meant to be. See the mod_perl guide,
or try this:

  ScriptAlias /perlcgi /path/to/your/cgi-bin/
  <Location /perlcgi>
    SetHandler perl-script
    PerlHandler Apache::Registry
    Options ExecCGI
  </Location>

=head1 CONFIGURATION

If you want to use your own template for MiniWiki, you should place the
template in the RCS file template,v in the C<datadir>. Upon execution,
MiniWiki will check out this template and use it. If you make any
modifications to the RCS file, a new version will be checked out.

You can modify the template from within MiniWiki by visiting the URL
http://your.server.name/your-wiki-vroot/(edit)/template

If you don't install a template, a default one will be used.

The C<datadir> variable defines where in the filesystem that the RCS
files that MiniWiki uses should be stored. This is also where MiniWiki
looks for a template to use.

The C<vroot> should match the virtual directory that MiniWiki runs under.

If this variable is set, it should point to a standard htpasswd file
which MiniWiki has write access to. The function to change a users password
is then enabled.
  
(Optional) The default timezone is GMT-8 (PST). To change to a different timezone, 
use the C<timediff> variable. Eg, to change to Amsterdam / Rome:

  PerlAddVar timediff 1

(Optional) By default, only the template called template is used. This becomes 
the default template for every page. Use the C<templates> variable to specify
more then one template:
  
  PerlAddVar templates fvlug linux

By doing this, pages that contain those words will use the matching template.
For example, the /your-wiki-vroot/LinuxDatabases page will then use the template-linux page,
instead of template. You will need to create the template by going to
/wiki/your-wiki-vroot/(edit)/template-<the_template> first.

(Optional) To disable file uploads such as binary attachments and inline images,
set uploads to no. By default it is yes. Note that inline images requires the
Image::Magick module to be installed for generating thumbnails.

  PerlAddVar uploads no

(Optional) Pre-caching can be done by a periodic (eg every 5 minutes) cronjob
to refresh the cached version of the .list* pages (see below) in the background,
rather then when Apache::Miniki discovers that the cache is old when a request is
done. To eanble:

  PerlAddVar precaching yes

If you create the pages 'list' or 'listchanges' or 'listlinks', the following will
automatically get appended to them:

 - list:        A simple line deliminated list of 
                all the pages in the system

 - listchanges: Ordered by date, gives a list of all pages 
                including the last comment, the number of lines 
                added or removed, and the date of the last change

 - listlinks:   Creates a list of all the inner/outer HTML links on the site,
                grouped by page name. By using CSS and some JavaScript in your
				template, it can become very easy to navigate around this way.

The master 'template' page does not show up in any of these three page
listings.

=head1 MULTIPLE WIKIS

Multiple wiki sites can easily be run on the same server. This can be done
by setting up multiple <Location> sections in the httpd.conf, with the
appropriate settings.

For an example of automating this using perl, see conf/httpd-perl-startup.pl 
in the MiniWiki distribution for a sample mod_perl startup file.

=head1 TEMPLATE VARIABLES

These variables are passed by Apache::MiniWiki to HTML::Template: