# Blosxom Plugin: excludez # Author: Stu MacKenzie # Based on "exclude" 0+3i plugin by: Breyten Ernsting and # "hide" 0.1 plugin by: Fletcher T. Penney # Version: v0.5 2005-04-08 # License: MIT/Public Domain # excludez home: http://www.enilnomi.net/download.html # Documentation: See the bottom of this file or type: perldoc excludez package excludez; # = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = # # Configuration Section # # = = = = = = = = = = = = = = = = # # What will your "exclude" file(s) be named? # To exclude whole categories and/or specific files from displaying, # you'll list them in files at one or more spots in your directories; # this is the name that this/these file(s) will use. # ex: $excludez_filename = 'exclude'; (default) my $excludez_filename = 'exclude'; # # Should the Find or Wikieditish plugins have access to excluded items? # 0 = no; 1 = yes (normal is 1) # If you may want items that are excluded from display to still be # searchable or editable, set this to 1; if not, set it to 0 my $allow_find = 1; # # NOTE: For info about setting up your "exclude" files, and about a # small "exception" to $allow_find, read the "Usage" section below. # # = = = = = = = = = = = = = = = = use strict; use CGI qw/:standard :netscape/; my($fp, $dd, @ignores); sub start { $fp = $blosxom::path_info; $fp &&= "/$fp"; $dd = $blosxom::datadir; $excludez_filename ||= 'exclude'; 1; } sub filter { my ($pkg, $files_ref) = @_; $allow_find &&= param('plugin') eq ('find' or 'wikieditish') or param('find'); # check the current path and plugins state directory # for an "exclude.flavour" or "exclude" file my $flag = 0; if (! $allow_find) { foreach ("$dd$fp", $blosxom::plugin_state_dir) { foreach ("$_/$excludez_filename.$blosxom::flavour", "$_/$excludez_filename") { if ( open (IGNORE, " < $_") ) { while () { chomp; m/^\s*#/ and next; # skip commented lines s/^\/+//; # remove leading "/"s; add trailing "/" to dirs m/\.$blosxom::file_extension$/ or s/\/*$/\//; push (@ignores, "$dd$fp/$_"); } close (IGNORE); $flag++; # stop looking after first success } $flag and last; } $flag and last; } } if (! $flag) { while () { # if no exclude files were found, check last if /^(__END__)?$/; # the DATA section of this plugin chomp; m/^\s*#/ and next; s/^\/+//; m/\.$blosxom::file_extension$/ or s/\/*$/\//; push (@ignores, "$dd$fp/$_"); } } foreach my $ignore (@ignores) { foreach (keys %$files_ref) { $_ =~ m/^$ignore/ and delete $files_ref->{$_}; } } 1; } 1; __DATA__ __END__ =head1 NAME Blosxom Plug-in: excludez =head1 SYNOPSIS Users can specify individual files and/or entire directories to exclude from display on a per-flavour, per-category basis. Exclude-ing can be suspended for the "find" or "wikieditish" plugins. Migration from the orignal "exclude" and "hide" plugins is seamless; new features include standard path notation, more options for where exclude info is stored, and the ability to "comment out" path info in exclude files. =head1 INSTALLATION Enter configuration info as instructed, then drop this file into your blosxom plugins folder. Blog on. =head1 CONFIGURATION With any luck, the instructions in the "Configuration Section" at the top of this file are sufficient; if more information is needed, see the documentation at: http://www.enilnomi.net/dltext/excludez.dl Setting up your "exclude" files is discussed below. =head1 USAGE =head2 Info Formats There are two formats available for specifying the directories and/or files to exclude from display in your blog: =over 2 =item Original -- The original "exclude" plugins (exclude, hide) required directory and file specifications like this: dir1/dir2/ entry_file.txt dir1/entry_file.txt And that method works here, so if you're migrating, you can still use your existing exclude files. =item Standard -- New users may prefer a more-standard notation, like this: /dir1/dir2 /entry_file.txt /dir1/entry_file.txt And that works, too. =back =head2 exclude Info Locations There are three ways to save exclude info: =over 2 =item Method #1 -- Situate exclude files on a per-flavour, per-directory basis, as in the original "exclude" plugins (exclude, hide). So again, if you're migrating, all your old files will still work. Given this directory structure: /blosxom /sekrit_stuff /dir1 /dir2 /sub2 /sub_sub2 /sekrit_entry.txt /dir3 we would locate these exclude files: /blosxom /exclude_file containing: /sekrit_stuff /dir2/sub2/sub_sub2/sekrit_entry.txt /sekrit_stuff /dir1 /dir2 /exclude_file containing: /sub2/sub_sub2/sekrit_entry.txt /sub2 /exclude_file containing: /sub_sub2/sekrit_entry.txt /sub_sub2 /exclude_file containing: /sekrit_entry.txt /sekrit_entry.txt /dir3 Very efficient for the plugin, but potentially many exclude files to keep track of. =item Method #2 -- Situate one per-flavour exclude file in your plugins "state" directory (the $plugins_state_dir configuration variable). Given the above directory structure, an exclude file in the plugins state directory would look like this: /sekrit_stuff /dir2/sub2/sub_sub2/sekrit_entry.txt /sub2/sub_sub2/sekrit_entry.txt /sub_sub2/sekrit_entry.txt /sekrit_entry.txt More work for the plugin, but only one file to deal with. =item Method #3 -- Store exclude info in the DATA section of the plugin (generic only; applies to all flavours). Just paste lines of exclude info between DATA and END; reading stops at a blank line. For an example, see Method #2 above. =back =head2 Putting It All Together It makes no difference which format you use ("/dir" vs. "dir/"), so don't worry about it. It *does* make a difference where your exclude files are located: the plugin follows a sequence as it looks for info, and stops looking as soon as it finds a file. The precedence of exclude file locations is: 1) current directory, flavour-specific file ("exclude.flavour") 2) current directory, generic file ("exclude") 3) plugins state directory, flavour-specific file 4) plugins state directory, generic file 5) DATA section, generic info (applies to all flavours) So, if you absoposilutely have to keep a file or directory from being displayed, record it in the DATA section of the plugin as a safety net against lost exclude files. (But see the next note about exceptions for Find.) =head2 Special Case for Find, Wikieditish When $allow_find is set to 1, and the Find or Wikieditish plugins are active (finding or editing), things are a little different. In this case, all your exclude *files* are ignored, allowing the plugins to access any file. However, you may still have items you don't want exposed to finding or editing. Exclude info entered into the DATA section of the plugin *is not* ignored during finding or editing. So, in terms of finding -- 1) if you never want your excluded items to be "find-able", (or "wikieditish-able") set $allow_find to 0 (zero) 2) to allow *all* your excluded items to be "find-able", set $allow_find to 1 and use only exclude *files* to store exclude info 3) to allow find-ing in some excluded items, but not all, use exclude files to hold exclude info about find-able items, and use the DATA section of the plugin to hold info about "non-find-able" items. =head1 VERSION 2005-05-08 (v0.5) - it's alive =head1 LICENSE this Blosxom Plug-in Copyright 2005, Stu MacKenzie Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.