properly encode and decode from/to utf8 when sending rpc to ikiwiki
[ikiwiki.git] / doc / todo / Option_linktext_for_pagestats_directive.mdwn
1 [[!meta title="Option disp for pagestats directive"]]
2
3 [[!toggle id=old text="Old, outdated, monologue"]]
4
5 [[!toggleable id=old text="""
6 Hello,    
7 here is a proposal to add a new option to [[ikiwiki/directive]]
8 [[ikiwiki/directive/pagestats]] (from plugin [[plugins/pagestats]]).
9
10 This adds global option `pagestats_linktext` (and directive option `linktext`) to specify whether directive `pagestats` should use the page name or the [[title|ikiwiki/directive/meta]] of tags.
11
12 Here is a [[patch]], for both code and documentation.
13
14     diff --git a/IkiWiki/Plugin/pagestats.pm b/IkiWiki/Plugin/pagestats.pm
15     index 17b26f7..a65fd7a 100644
16     --- a/IkiWiki/Plugin/pagestats.pm
17     +++ b/IkiWiki/Plugin/pagestats.pm
18     @@ -29,11 +29,31 @@ sub getsetup () {
19                         rebuild => undef,
20                         section => "widget",
21                 },
22     +           pagestats_linktext => {
23     +                   type => "string",
24     +                   example => "title",
25     +                   description => "Set link text to be whether page title (page) or meta title (title).",
26     +                   safe => 1,
27     +                   rebuild => 1,
28     +           },
29     +}
30     +
31     +sub linktext ($$) {
32     +   # Return the text of the link to a tag, depending on option linktext.
33     +   use Data::Dumper;
34     +   my $page = $_[0];
35     +   my $linktype = $_[1];
36     +   if (($linktype eq "title") and (exists $pagestate{$page}{meta}{title})) {
37     +           return $pagestate{$page}{meta}{title};
38     +   } else {
39     +           return undef;
40     +   }
41      }
42      
43      sub preprocess (@) {
44         my %params=@_;
45         $params{pages}="*" unless defined $params{pages};
46     +   $params{linktext} = $config{pagestats_linktext} unless defined $params{linktext};
47         my $style = ($params{style} or 'cloud');
48         
49         my %counts;
50     @@ -78,7 +98,7 @@ sub preprocess (@) {
51                 return "<table class='".(exists $params{class} ? $params{class} : "pageStats")."'>\n".
52                         join("\n", map {
53                                 "<tr><td>".
54     -                           htmllink($params{page}, $params{destpage}, $_, noimageinline => 1).
55     +                           htmllink($params{page}, $params{destpage}, $_, noimageinline => 1, linktext => linktext($_, $params{linktext})).
56                                 "</td><td>".$counts{$_}."</td></tr>"
57                         }
58                         sort { $counts{$b} <=> $counts{$a} } keys %counts).
59     @@ -101,8 +121,8 @@ sub preprocess (@) {
60                         
61                         $res.="<li>" if $style eq 'list';
62                         $res .= "<span class=\"$class\">".
63     -                           htmllink($params{page}, $params{destpage}, $page).
64     -                           "</span>\n";
65     +                                                   htmllink($params{page}, $params{destpage}, $page, linktext => linktext($page, $params{linktext})).
66     +                                                   "</span>\n";
67                         $res.="</li>" if $style eq 'list';
68      
69                 }
70     diff --git a/doc/ikiwiki/directive/pagestats.mdwn b/doc/ikiwiki/directive/pagestats.mdwn
71     index 8d904f5..56970e6 100644
72     --- a/doc/ikiwiki/directive/pagestats.mdwn
73     +++ b/doc/ikiwiki/directive/pagestats.mdwn
74     @@ -37,4 +37,6 @@ links:
75      The optional `class` parameter can be used to control the class
76      of the generated tag cloud `div` or page stats `table`.
77      
78     +The optional `linktext` parameter can be used to control the text that is displayed for each tag. It can be `page` (the name of the page is used) or `title` (the title, according to the [[ikiwiki/directive/meta]] [[ikiwiki/directive]], is used). This option can be set globally in the setup using option `pagestats_linktext`; default is `page`.
79     +
80      [[!meta robots="noindex, follow"]]
81     diff --git a/doc/plugins/pagestats.mdwn b/doc/plugins/pagestats.mdwn
82     index 347e39a..6a72a9a 100644
83     --- a/doc/plugins/pagestats.mdwn
84     +++ b/doc/plugins/pagestats.mdwn
85     @@ -4,3 +4,7 @@
86      This plugin provides the [[ikiwiki/directive/pagestats]]
87      [[ikiwiki/directive]], which can generate stats about how pages link to
88      each other, or display a tag cloud.
89     +
90     +Their is one global option for the setup file:
91     +
92     +* `pagestats_linktext` controls the text that is displayed for each tag. If `page` (the default), the name of the page is used; if `title`, its title (according to the [[ikiwiki/directive/meta]] [[ikiwiki/directive]]) is used.
93
94 -- [[Louis|spalax]]
95
96 > Hello,    
97 > do not accept my patch: it is an ugly hack that works for me, but its too narrow to be merged in IkiWiki:
98
99 >   - it assumes the [[ikiwiki/directive/pagestats]] directive only deals with tags, which is wrong;
100 >   - such a feature (allowing displaying tags using their title), if enabled, should be enabled for the [[plugins/tag]] plugin (and maybe other plugins [[I have in mind|users/spalax]]) as well.
101
102 > I cannot manage to find a solution to my problem that suits me.
103
104 > # My problem
105
106 > On two sites I maintain using IkiWiki, I have tags that:
107
108 > - have special characters in it (like [[ยท|http://en.wikipedia.org/wiki/Interpunct]]) that generate ugly URLs;
109 > - have subtags (e.g. `math/calculus`, `math/algebra`, `physics/mechanic` etc.).
110
111 > That is, having [[ikiwiki/directive/taglink]] or [[ikiwiki/directive/pagestats]] displaying tags using the pagename (that is something derived from the basename of the URL) is not sufficient for me. I would like to be able to display them using their title, their full name (from the `tagbase` parameter), or both.
112
113 > # Solution?
114
115 > A solution would be to provide a `tagtext` config option, set to one of `page` (use pagename), `title` (use [[ikiwiki/directive/meta]] title), `path` (use path, since the tagbase), `pathtitle` (use path, and use title for each of the subtags); or a boolean `display_tagtitle` and `display_tagpath`, which would handle the way tags are displayed.
116
117 > I see at least two drawbacks to this solution:
118
119 > - I do not know what would be the default of these options, not to break backward compatibility: [[ikiwiki/directive/taglink]] would suggest `page`, whereas the footer would suggest `path`.
120 > - The [[ikiwiki/directive/pagestats]] directive would need an optional boolean parameter `tag`, to specify whether to use these options or not.
121
122 > # *My* problem ?
123
124 > I actually wonder if someone else also have this problem: as far as I can see on other sites using IkiWiki and tags, I would not be surprised if others are satisfyed with the current way tags are displayed: I do not remember having seen subtags, or tags in non-English language with weird characters in them.
125
126 > So, I wonder whether this discussion would benefit IkiWiki, or if I should just go on with my hack (or maybe a plugin, but I think it would be quite difficult to do, given that the very same function is used to display tags and to uniquely identify them).
127
128 > -- [[Louis|spalax]]
129 """]]
130
131 I eventually managed to get something that suits me, for the problem described above (I want [[ikiwiki/directive/pagestats]] directive to display [[title|ikiwiki/directive/meta]] rather than page name).
132
133 Here is a [[patch]] that adds an option `disp` for the [[ikiwiki/directive/pagestats]], acting exactly the same as option `show` for the [[ikiwiki/directive/map]] directive (but parameter `show` was already used for something else). That is, if one wants its tags displayed using their [[title|ikiwiki/directive/meta]] rather than their page name, she can use param `disp`, is in:
134
135     \[[!pagestats  pages="tags/*" disp=title]]
136
137 [[!toggle id=patch text="Patch"]]
138 [[!toggleable id=patch text="""
139     diff --git a/IkiWiki/Plugin/pagestats.pm b/IkiWiki/Plugin/pagestats.pm
140     index 17b26f7..8a5e100 100644
141     --- a/IkiWiki/Plugin/pagestats.pm
142     +++ b/IkiWiki/Plugin/pagestats.pm
143     @@ -31,6 +31,19 @@ sub getsetup () {
144                 },
145      }
146      
147     +sub linktext ($%) {
148     +   # Return the text of the link to a tag, depending on option linktext.
149     +   my ($page, %params) = @_;
150     +  if (exists $params{disp} && 
151     +      exists $pagestate{$page} &&
152     +      exists $pagestate{$page}{meta}{$params{disp}}) {
153     +    return $pagestate{$page}{meta}{$params{disp}};
154     +  }
155     +  else {
156     +    return undef;
157     +  }
158     +}
159     +
160      sub preprocess (@) {
161         my %params=@_;
162         $params{pages}="*" unless defined $params{pages};
163     @@ -78,7 +91,7 @@ sub preprocess (@) {
164                 return "<table class='".(exists $params{class} ? $params{class} : "pageStats")."'>\n".
165                         join("\n", map {
166                                 "<tr><td>".
167     -                           htmllink($params{page}, $params{destpage}, $_, noimageinline => 1).
168     +                           htmllink($params{page}, $params{destpage}, $_, noimageinline => 1, linktext => linktext($_, %params)).
169                                 "</td><td>".$counts{$_}."</td></tr>"
170                         }
171                         sort { $counts{$b} <=> $counts{$a} } keys %counts).
172     @@ -101,7 +114,7 @@ sub preprocess (@) {
173                         
174                         $res.="<li>" if $style eq 'list';
175                         $res .= "<span class=\"$class\">".
176     -                           htmllink($params{page}, $params{destpage}, $page).
177     +                                                   htmllink($params{page}, $params{destpage}, $page, linktext => linktext($page, %params)).
178                                 "</span>\n";
179                         $res.="</li>" if $style eq 'list';
180  
181 """]]
182
183 Regards,  
184 -- [[Louis|spalax]]