ikiwiki/doc/todo/color_plugin.mdwn

183 lines
6.3 KiB
Markdown

Recently I've wanted to colour some piece of text on my Ikiwiki page.
It seems that Markdown can do it only using HTML tags, so I used
`<span class="color">foo bar baz</span>`.
However, in my opinion mixing Markdown syntax and HTML tags is rather ugly,
so maybe we should create a new color plugin to add more color to Ikiwiki ;)
I know that another Wikis have similar plugin, for example
[WikiDot](http://www.wikidot.com/).
I've noticed that htmlscrubber plugin strips `style` attribute, because of
security, so probably we need to use `class` attribute of HTML. But then
we have to customize our `local.css` file to add all color we want to use.
It's not as easy in usage like color name or definition as plugin argument,
but I don't have a better idea right now.
What do you think about it? --[[Paweł|ptecza]]
> Making a plugin preserve style attributes can be done, it just has to add
> them after the sanitize step, which strips them. The general method is
> adding placeholders first, and replacing them with the real html later.
>
> The hard thing to me seems to be finding a syntax that is better than a
> `<span>`. A preprocessor directive is not really any less ugly than html
> tags, though at least it could play nicely with nested markdown: --[[Joey]]
>
> \[[!color red,green """
> Xmas-colored markdown here
> """]]
>> I'm glad you like that idea. In my opinion your syntax looks good.
>> Out of curiosity, why did you used 2 colors in your example? What is HTML
>> result for it? ;)
>>> I was thinking one would be foreground, the other background. Don't
>>> know if setting the background makes sense or not.
>> I can try to create that plugin, if you are too busy now. I'm not Perl
>> hacker, but I wrote a lot of Perl scripts in my life and color plugin
>> doesn't seem to be very hard task. --[[Paweł|ptecza]]
>> Yes, it's a good intro plugin, have at it! --[[Joey]]
---
This is a RC1 of my `color` plugin. It works for me well, but all your
comments are very welcome. --[[Paweł|ptecza]]
> Sure, I have a couple.
>
> The preprocess function is passed named parameters. The hack you have of
> hardcoding use of `$_[0]` and `$_[2]` can fail at any time.
>
> `replace_preserved_style` is passed a single parameter, so its prototype
> should be `($)`, not `(@)`. Ditt `preserve_style`, it should have
> `($$)`.
>
> The sanitize hook is always passed `$params{content}`, so there should be
> no reason to check that it exists. Also, it shouldn't be done in a
> sanitize hook, since html sanitization could run _after_ that santize
> hook. It should use a format hook.
>
> The preprocess hook needs to call `IkiWiki::preprocess` on the content
> passed into it if you want to support nesting other preprocessor
> directives inside the color directive. See `preprocess_toggleable` in the
> toggle plugin, for example.
>
> I'm not a big fan of the dummy text `COLORS { ... } SROLOC;TEXT { ... TXET }`
> The method used by toggle of using two real `<div>`s seems slightly
> better. --[[Joey]]
--- /dev/null 2008-07-24 09:38:19.000000000 +0200
+++ color.pm 2008-07-25 14:43:15.000000000 +0200
@@ -0,0 +1,75 @@
+#!/usr/bin/perl
+# Ikiwiki text colouring plugin
+# Paweł Tęcza <ptecza@net.icm.edu.pl>
+package IkiWiki::Plugin::color;
+
+use warnings;
+use strict;
+use IkiWiki 2.00;
+
+sub import { #{{{
+ hook(type => "preprocess", id => "color", call => \&preprocess);
+ hook(type => "sanitize", id => "color", call => \&sanitize);
+} #}}}
+
+sub preserve_style(@) { #{{{
+ my ($colors, $text) = @_;
+ $colors = '' unless $colors; # foreground and background colors
+ $text = '' unless $text; # text
+
+ # Check colors
+ my ($color1, $color2) = ();
+ $colors = lc($colors); # Regexps on lower case strings are simpler
+ if ($colors =~ /,/) {
+ # Probably defined both foreground and background color
+ ($color1, $color2) = ($colors =~ /(.*),(.*)/);
+ }
+ else {
+ # Probably defined only foreground color
+ ($color1, $color2) = ($colors, '');
+ }
+
+ # Validate colors. Only color name or color code are valid.
+ my ($fg, $bg) = ();
+ $fg = $color1 if ($color1 &&
+ ($color1 =~ /^[a-z]+$/ || $color1 =~ /^#[0-9a-f]{3,6}$/));
+ $bg = $color2 if ($color2 &&
+ ($color2 =~ /^[a-z]+$/ || $color2 =~ /^#[0-9a-f]{3,6}$/));
+
+ my $preserved = '';
+ if ($fg || $bg) {
+ $preserved .= 'COLORS {';
+ $preserved .= 'color: '.$fg if ($fg);
+ $preserved .= '; ' if ($fg && $bg);
+ $preserved .= 'background-color: '.$bg if ($bg);
+ $preserved .= '} SROLOC;TEXT {'.$text.'} TXET';
+ }
+
+ return $preserved;
+
+} #}}}
+
+sub replace_preserved_style(@) { #{{{
+ my $content = shift;
+
+ if ($content) {
+ $content =~ s/COLORS {/<span style="/;
+ $content =~ s/} SROLOC;TEXT {/">/;
+ $content =~ s/} TXET/<\/span>/;
+ }
+
+ return $content;
+} #}}}
+
+sub preprocess (@) { #{{{
+ return preserve_style($_[0], $_[2]);
+} #}}}
+
+sub sanitize (@) { #{{{
+ my %params = @_;
+
+ return replace_preserved_style($params{content})
+ if (exists $params{content})
+} #}}}
+
+1
--- /dev/null 2008-07-24 09:38:19.000000000 +0200
+++ color.mdwn 2008-07-25 14:50:19.000000000 +0200
@@ -0,0 +1,31 @@
+\[[!template id=plugin name=color core=0 author="[[Paweł Tęcza|ptecza]]"]]
+
+This plugin can be used to color a piece of text on Ikiwiki page.
+It's possible setting foreground and/or background color of the text.
+
+The plugin syntax is very simple. You only need to type name (e.g. `white`)
+or HTML code of colors (e.g. `#ffffff`) and a text you want to color.
+The colors should by separated using a comma character.
+
+Below are a few examples:
+
+ \[[!color white,#ff0000 "White text on red background"]]
+
+Foreground color is defined as a word, background color is defined as HTML
+color code.
+
+ \[[!color white "White text on default color background"]]
+
+Foreground color is default color if only one color was typed and a comma
+character is missing.
+
+ \[[!color white, "White text on default color background"]]
+
+Background color is missing, so the text is displayed on default background.
+
+ \[[!color ,#ff0000 "Default color text on red background"]]
+
+Foreground is missing, so the text has default color.
+
+This plugin is not enabled by default. You can do that in [[ikiwiki.setup]]
+file (hint: `add_plugins` variable).