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