doc/todo/progressbar_plugin.mdwn

   1 I would like to add next plugin to Ikiwiki. It's `progressbar` or simply `progress`.
   2 I'm not sure what plugin name better is, probably that shorter ;) I know that
   3 [DokuWiki](http://wiki.splitbrain.org/plugin:progressbar) has similar plugin,
   4 so I think it can be useful also for Ikiwiki users.
   5
   6 Here is proposition of the plugin syntax:
   7
   8     \[[!progress done=50]]
   9
  10 Of course, `done` argument is integer from 0 to 100.
  11
  12 A here is its HTML result:
  13
  14     <div class="progress">
  15       <div class="progress-done" style="width: 50%">50%</div>
  16     </div>
  17
  18 Note: I was trying with `<span>` tags too, but that tag is inline, so I can't
  19 set `width` property for it.
  20
  21 Default CSS styles for the plugin can be like below:
  22
  23     div.progress {
  24             border: 1px solid #ddd;
  25             /* border: 2px solid #ddd; */
  26             width: 200px;
  27             background: #fff;
  28             padding: 2px;
  29             /* padding: 0px; */
  30             border: 2px solid #aaa;
  31             background: #eee;
  32     }
  33     div.progress-done {
  34             height: 14px;
  35             background: #ff6600;
  36             font-size: 12px;
  37             text-align: center;
  38             vertical-align: middle;
  39     }
  40
  41 You can use alternative, commented CSS code for `div.progress` if you dislike
  42 padding around done strip.
  43
  44 Any comments? --[[Paweł|ptecza]]
  45
  46 > This looks like a nice idea.  If I could add one further suggestion: Allow your
  47 > ratio to be a pair of pagespecs.  Then you could have something like:
  48
  49     \[[!progress totalpages="bugs/* and backlink(milestoneB)" donepages="bugs/* and backlink(milestoneB) and !link(bugs/done)"]]
  50
  51 > to have a progress bar marking how many bugs were compete for a
  52 > particular milestone.  -- [[Will]]
  53
  54 >> Thanks a lot for your comment, Will! It seems very interesting for me.
  55 >> I need to think more about improving that plugin. --[[Paweł|ptecza]]
  56
  57 >> Attached is a [[patch]] (well, source) for this.  You also need to add the proposed CSS above to `style.css`.
  58 >> At the moment this plugin interacts poorly with the [[plugins/htmlscrubber]] plugin.
  59 >> HTMLScrubber plugin removes the `style` attribute from the `progress-done` `div` tag, and so it defaults
  60 >> to a width of 100%. -- [[Will]]
  61
  62 >>> Thank you for the code! I know how to fix that problem, because I had
  63 >>> the same issue while writing [[todo/color_plugin]] :) --[[Paweł|ptecza]]
  64
  65 >>>> Ahh - good idea.  Patch updated to work with HTMLScrubber. --[[Will]]
  66
  67     #!/usr/bin/perl
  68     package IkiWiki::Plugin::progress;
  69
  70     use warnings;
  71     use strict;
  72     use IkiWiki 2.00;
  73
  74     my $percentage_pattern = qr/[0-9]+\%/; # pattern to validate percentages
  75
  76     sub import { #{{{
  77         hook(type => "getsetup", id => "progress", call => \&getsetup);
  78         hook(type => "preprocess", id => "progress", call => \&preprocess);
  79         hook(type => "format",     id => "progress", call => \&format);
  80     } # }}}
  81
  82     sub getsetup () { #{{{
  83         return
  84                 plugin => {
  85                         safe => 1,
  86                         rebuild => undef,
  87                 },
  88     } #}}}
  89
  90     sub preprocess (@) { #{{{
  91         my %params=@_;
  92
  93         my $fill;
  94
  95         if (defined $params{percent}) {
  96                 $fill = $params{percent};
  97                 ($fill) = $fill =~ m/($percentage_pattern)/; # fill is untainted now
  98         }
  99         elsif (defined $params{totalpages} and defined $params{donepages}) {
 100                 add_depends($params{page}, $params{totalpages});
 101                 add_depends($params{page}, $params{donepages});
 102
 103                 my @pages=keys %pagesources;
 104                 my $totalcount=0;
 105                 my $donecount=0;
 106                 foreach my $page (@pages) {
 107                         $totalcount++ if pagespec_match($page, $params{totalpages}, location => $params{page});
 108                         $donecount++ if pagespec_match($page, $params{donepages}, location => $params{page});
 109                 }
 110
 111                 if ($totalcount == 0) {
 112                         $fill = "100%";
 113                 } else {
 114                         my $number = $donecount/$totalcount*100;
 115                         $fill = sprintf("%u%%", $number);
 116                 }
 117         }
 118         else {
 119                 error("Missing parameters to progress plugin.  Need either `percent` or `totalpages` and `donepages` parameters.");
 120         }
 121
 122         return <<EODIV
 123     <div class="progress">
 124       <div class="progress-done" style="width: $fill">$fill</div>
 125     </div>
 126     EODIV
 127
 128     } # }}}
 129
 130     sub format(@) { #{{{
 131         my %params = @_;
 132
 133         # If HTMLScrubber has removed the style attribute, then bring it back
 134
 135         $params{content} =~ s!<div class="progress-done">($percentage_pattern)</div>!<div class="progress-done" style="width: $1">$1</div>!g;
 136
 137         return $params{content};
 138     } #}}}
 139
 140     1
 141
 142 Here is a potential documentation page:
 143
 144 -----
 145
 146 [[!template id=plugin name=progress author="[[Will]]"]]
 147 [[!tag type/meta]]
 148
 149 Provides a \\[[!progress ]] [[ikiwiki/PreProcessorDirective]] that is
 150 replaced with a progress bar.
 151
 152 There are two possible parameter sets.  The first is a single parameter
 153 `percent` which holds a percentage figure for how complete the progress bar is.
 154
 155 The second possible set of parameters is a pair of [[ikiwiki/PageSpec]]s,
 156 `totalpages` and `donepages`.  The progress plugin counts the number of
 157 pages in each pagespec and shows the percentage of the total pages that are
 158 done.
 159
 160 This plugin is included in ikiwiki, but is not enabled by default.
 161
 162 If it is turned on it can show what percentage of pages have discussion pages:
 163
 164 [[!progress totalpages="* and !*/Discussion" donepages="*/Discussion"]]