%autofiles};
use Exporter q{import};
-our @EXPORT = qw(hook debug error template htmlpage deptype
- add_depends pagespec_match pagespec_match_list bestlink
+our @EXPORT = qw(hook debug error htmlpage template template_depends
+ deptype add_depends pagespec_match pagespec_match_list bestlink
htmllink readfile writefile pagetype srcfile pagename
displaytime will_render gettext ngettext urlto targetpage
add_underlay pagetitle titlepage linkpage newpagefile
safe => 0, # path
rebuild => 1,
},
- templatedirs => {
- type => "internal",
- default => [],
- description => "additional directories containing template files",
- safe => 0,
- rebuild => 0,
- },
underlaydir => {
type => "string",
default => "$installdir/share/ikiwiki/basewiki",
}
sub template_file ($) {
- my $template=shift;
+ my $name=shift;
+
+ my $tpage=($name =~ /^\//) ? $name : "templates/$name";
+ if ($name !~ /\.tmpl$/ && exists $pagesources{$tpage}) {
+ $tpage=$pagesources{$tpage};
+ $name.=".tmpl";
+ }
+
+ my $template=srcfile($tpage, 1);
+ if (! defined $template) {
+ $name=~s:/::; # avoid path traversal
+ foreach my $dir ($config{templatedir},
+ "$installdir/share/ikiwiki/templates") {
+ if (-e "$dir/$name") {
+ $template="$dir/$name";
+ last;
+ }
+ }
+ }
- foreach my $dir ($config{templatedir}, @{$config{templatedirs}},
- "$installdir/share/ikiwiki/templates") {
- return "$dir/$template" if -e "$dir/$template";
+ if (defined $template) {
+ return $template, $tpage if wantarray;
+ return $template;
}
return;
}
-sub template_params (@) {
- my $filename=template_file(shift);
-
- if (! defined $filename) {
- return if wantarray;
- return "";
+sub template_depends ($$;@) {
+ my $name=shift;
+ my $page=shift;
+
+ my ($filename, $tpage)=template_file($name);
+ if (defined $page && defined $tpage) {
+ add_depends($page, $tpage);
}
- my @ret=(
+ return unless defined $filename;
+
+ require HTML::Template;
+ return HTML::Template->new(
filter => sub {
my $text_ref = shift;
${$text_ref} = decode_utf8(${$text_ref});
},
- filename => $filename,
loop_context_vars => 1,
die_on_bad_params => 0,
- @_
+ filename => $filename,
+ @_,
+ no_includes => 1,
);
- return wantarray ? @ret : {@ret};
}
sub template ($;@) {
- require HTML::Template;
- return HTML::Template->new(template_params(@_));
+ template_depends(shift, undef, @_);
}
sub misctemplate ($$;@) {
my $title=shift;
my $pagebody=shift;
- my $template=template("misc.tmpl");
- $template->param(
+ my $template=template("misc.tmpl",
title => $title,
indexlink => indexlink(),
wikiname => $config{wikiname},
action => $config{cgiurl},
header => 0,
table => 0,
- template => scalar IkiWiki::template_params('editcomment.tmpl'),
+ template => template('editcomment.tmpl'),
);
IkiWiki::decode_form_utf8($form);
action => $config{cgiurl},
header => 0,
table => 0,
- template => scalar template_params("editpage.tmpl"),
+ template => template("editpage.tmpl"),
);
decode_form_utf8($form);
my $template_page=shift;
my $page=shift;
- my $template_file=$pagesources{$template_page};
- if (! defined $template_file) {
- return;
- }
-
my $template;
eval {
- $template=HTML::Template->new(
- filter => sub {
- my $text_ref = shift;
- $$text_ref=&Encode::decode_utf8($$text_ref);
- chomp $$text_ref;
- },
- filename => srcfile($template_file),
- die_on_bad_params => 0,
- no_includes => 1,
- );
+ # force page name absolute so it doesn't look in templates/
+ $template=template("/".$template_page);
};
if ($@) {
# Indicate that the earlier preprocessor directive set
# up a template that doesn't work.
- return "[[!pagetemplate ".gettext("failed to process")." $@]]";
+ return "[[!pagetemplate ".gettext("failed to process template:")." $@]]";
+ }
+ if (! defined $template) {
+ return;
}
$template->param(name => $page);
# Add search box to page header.
if ($template->query(name => "searchform")) {
if (! defined $form) {
- my $searchform = template("googleform.tmpl", blind_cache => 1);
+ my $searchform = template_depends("googleform.tmpl", $page, blind_cache => 1);
$searchform->param(url => $config{url});
$form=$searchform->output;
}
(exists $params{postform} && yesno($params{postform}))) &&
IkiWiki->can("cgi_editpage")) {
# Add a blog post form, with feed buttons.
- my $formtemplate=template("blogpost.tmpl", blind_cache => 1);
+ my $formtemplate=template_depends("blogpost.tmpl", $params{page}, blind_cache => 1);
$formtemplate->param(cgiurl => $config{cgiurl});
$formtemplate->param(rootpage => rootpage(%params));
$formtemplate->param(rssurl => $rssurl) if $feeds && $rss;
}
elsif ($feeds && !$params{preview} && ($emptyfeeds || @feedlist)) {
# Add feed buttons.
- my $linktemplate=template("feedlink.tmpl", blind_cache => 1);
+ my $linktemplate=template_depends("feedlink.tmpl", $params{page}, blind_cache => 1);
$linktemplate->param(rssurl => $rssurl) if $rss;
$linktemplate->param(atomurl => $atomurl) if $atom;
$ret.=$linktemplate->output;
}
if (! $feedonly) {
- require HTML::Template;
- my @params=IkiWiki::template_params($params{template}.".tmpl", blind_cache => 1);
- if (! @params) {
- error sprintf(gettext("nonexistant template %s"), $params{template});
+ my $template;
+ if (! $raw) {
+ # cannot use wiki pages as templates; template not sanitized due to
+ # format hook hack
+ eval {
+ $template=template_depends($params{template}.".tmpl", $params{page},
+ blind_cache => 1);
+ };
+ if ($@) {
+ error gettext("failed to process template:")." $@";
+ }
+ if (! $template) {
+ error sprintf(gettext("template %s not found"), $params{template}.".tmpl");
+ }
}
- my $template=HTML::Template->new(@params) unless $raw;
my $needcontent=$raw || (!($archive && $quick) && $template->query(name => 'content'));
foreach my $page (@list) {
my $url=URI->new(encode_utf8(urlto($page,"",1)));
- my $itemtemplate=template($feedtype."item.tmpl", blind_cache => 1);
+ my $itemtemplate=template_depends($feedtype."item.tmpl", $page, blind_cache => 1);
my $content="";
my $lasttime = 0;
foreach my $p (@pages) {
$lasttime = $pagemtime{$p} if $pagemtime{$p} > $lasttime;
}
- my $template=template($feedtype."page.tmpl", blind_cache => 1);
+ my $template=template_depends($feedtype."page.tmpl", $page, blind_cache => 1);
$template->param(
title => $page ne "index" ? pagetitle($page) : $config{wikiname},
wikiname => $config{wikiname},
# Add search box to page header.
if ($template->query(name => "searchform")) {
if (! defined $form) {
- my $searchform = template("searchform.tmpl", blind_cache => 1);
+ my $searchform = template_depends("searchform.tmpl", $page, blind_cache => 1);
$searchform->param(searchaction => $config{cgiurl});
$form=$searchform->output;
}
use warnings;
use strict;
use IkiWiki 3.00;
-use HTML::Template;
use Encode;
sub import {
error gettext("missing id parameter")
}
- my $template_page="templates/$params{id}";
- add_depends($params{page}, $template_page);
-
- my $template_file;
- if (exists $pagesources{$template_page}) {
- $template_file=srcfile($pagesources{$template_page});
- }
- else {
- $template_file=IkiWiki::template_file("$params{id}.tmpl")
- }
- return sprintf(gettext("template %s not found"),
- htmllink($params{page}, $params{destpage}, "/".$template_page))
- unless defined $template_file;
-
+ # The bare id is used, so a page templates/$id can be used as
+ # the template.
my $template;
eval {
- $template=HTML::Template->new(
- filter => sub {
- my $text_ref = shift;
- $$text_ref=&Encode::decode_utf8($$text_ref);
- chomp $$text_ref;
- },
- filename => $template_file,
- die_on_bad_params => 0,
- no_includes => 1,
- blind_cache => 1,
- );
+ $template=template_depends($params{id}, $params{page},
+ blind_cache => 1);
};
if ($@) {
- error gettext("failed to process:")." $@"
+ error gettext("failed to process template:")." $@";
+ }
+ if (! $template) {
+ error sprintf(gettext("%s not found"),
+ htmllink($params{page}, $params{destpage},
+ "/templates/$params{id}"))
}
$params{basename}=IkiWiki::basename($params{page});
safe => 0,
rebuild => 1,
},
- add_templates => {
- type => "string",
- example => ["$ENV{HOME}/.ikiwiki/templates"],
- description => "extra template directories to add",
- advanced => 1,
- safe => 0,
- rebuild => 1,
- },
}
sub checkconfig () {
add_underlay($dir);
}
}
- if ($config{add_templates}) {
- push @{$config{templatedirs}}, @{$config{add_templates}};
- }
}
1;
$templatefile=$file;
}
});
- my $template=template(defined $templatefile ? $templatefile : 'page.tmpl', blind_cache => 1);
+ my $template;
+ if (defined $templatefile) {
+ $template=template_depends($templatefile, $page,
+ blind_cache => 1);
+ }
+ else {
+ # no explicit depends as special case
+ $template=template('page.tmpl',
+ blind_cache => 1);
+ }
my $actions=0;
if (length $config{cgiurl}) {
foreach my $file (@$new, @$del) {
render_linkers($file);
}
-
- if (@$changed || @$internal_changed ||
+
+ if ($rendered{"templates/page.tmpl"}) {
+ foreach my $f (@$files) {
+ next if $f eq "templates/page.tmpl";
+ render($f, sprintf(gettext("building %s, which depends on %s"), $f, "templates/page.tmpl"));
+ }
+ }
+ elsif (@$changed || @$internal_changed ||
@$del || @$internal_del || @$internal_new) {
1 while render_dependent($files, $new, $internal_new,
$del, $internal_del, $internal_changed,
rm -f *.man $(outprogs) ikiwiki.setup plugins/*.pyc
$(MAKE) -C po clean
+# Joey uses this before committing.
+myclean: clean
+ git checkout po ikiwiki.spec
+
underlay_install:
install -d $(DESTDIR)$(PREFIX)/share/ikiwiki
for dir in `cd underlays && find . -follow -type d ! -regex '.*\.svn.*'`; do \
This version of ikiwiki has a lot of changes that you need to know about.
+ Now you can include customised versions of templates in the source
+ of your wiki. (For example, templates/page.tmpl.) When these templates
+ are changed, ikiwiki will automatically rebuild pages that use them.
+
+ Allowing untrusted users to upload attachments with the ".tmpl"
+ extension is not recommended, as that allows anyone to change
+ a wiki's templates.
+
The --getctime switch is renamed to --gettimes, and it also gets the
file modification time. And it's a lot faster (when using git). But
the really important change is, you don't have to remember to use this
switch. Now ikiwiki will do it when it needs to.
- Starting from this version, the "tagged()" pagespec only matches tags,
- not regular wikilinks. If your wiki accidentially relied on the old,
- buggy behavior, you might need to change its pagespecs to use "link()".
+ At last, the "tagged()" pagespec only matches tags, not regular wikilinks.
+ If your wiki accidentially relied on the old, buggy behavior, you might
+ need to change its pagespecs to use "link()".
+
+ Many of your wishes have been answered: Now tag pages can automatically be
+ created when new tags are used. This feature is enabled by default if you
+ have configured a tagbase. It can be turned on or off using the
+ tag_autocreate setting.
+
+ These changes may also affect some users:
+
+ * The title_natural sort method (as used by the inline directive, etc)
+ has been moved to the new sortnaturally plugin, which is not enabled
+ by default since it requires the Sort::Naturally perl module.
- Now tag pages can automatically be created as new tags are used. This
- feature is enabled by default if you have configured a tagbase. It
- can be turned on or off using the tag_autocreate setting.
+ * TMPL_INCLUDE is no longer supported in any template used by ikiwiki.
+ It used to be allowed in certian templates, but not in others.
- The title_natural sort method (as used by the inline directive, etc)
- have been moved to the new sortnaturally plugin, which is not enabled
- by default since it requires the Sort::Naturally perl module.
+ * The add_templates option has been removed from the underlay plugin.
+ If you used this option, you can instead use templates/ subdirectories
+ inside underlay directories added by the add_underlays option.
Due to the above and other changes, all wikis need to be rebuilt on
upgrade to this version. If you listed your wiki in /etc/ikiwiki/wikilist
[ Joey Hess ]
* tag: Automatic creation of tag pages can now be enabled using
the tag_autocreate setting. (David Riebenbauer)
+ * Customised templates can now be included in the source of wikis
+ (and also in underlays), and dependencies on them are tracked.
+ * TMPL_INCLUDE is no longer supported in any template.
+ * underlay: Removed the add_templates option.
+ * Add template_depends function to plugin API.
* bzr: Fix bzr log parsing to work with bzr 2.0. (liw)
* comments: Fix missing entity encoding in title.
* txt: Add a special case for robots.txt.
> Anyway, it makes sense for the htmlscrubber to strip server-side
> includes because otherwise your wiki could be attacked
> by them being added to it. If you want to use both the htmlscrubber and
-> SSI together, I'd suggest you modify the [[wikitemplates]]
+> SSI together, I'd suggest you modify the [[templates]]
> and put the SSI on there.
>
> Ie, `page.tmpl` has a
> that allows modifying that form, but does not allow creating a separate
> form. The best way to make it obvious how to use it currently is to just
> disable password auth, then it's nice and simple. :-) Javascript is an
-> interesting idea. It's also possible to write a custom [[signin.tmpl wikitemplates]] that
+> interesting idea. It's also possible to write a custom [[templates]] that
> is displayed instead of the regular signin form, and it should be
> possible to use that to manually lay it out better than FormBuilder
> manages with its automatic layout. --[[Joey]]
> I've improved the form, I think it's more obvious now that the openid
> stuff is separate. Good enough to call this [[done]]. I think. --[[Joey]]
->> Looks good, thanks! :-) -- [[AdamShand]]
\ No newline at end of file
+>> Looks good, thanks! :-) -- [[AdamShand]]
Ikiwiki aims to produce
[valid XHTML 1.0](http://validator.w3.org/check?url=referer). Ikiwiki
-generates html using [[templates|wikitemplates]], and uses [[css]], so you
+generates html using [[templates]], and uses [[css]], so you
can change the look and layout of all pages in any way you would like.
## [[Plugins]]
GNU [[GPL]], version 2 or later.
The parts of ikiwiki that become part of your own wiki (the [[basewiki]]
-pages (but not the smilies) and the [[templates|wikitemplates]]) are licensed
+pages (but not the smilies) and the [[templates]]) are licensed
as follows:
> Redistribution and use in source and compiled forms, with or without
# TEMPLATES
-This command uses two [[template|wikitemplates]] to generate
+This command uses two [[templates]] to generate
the pages, `calendarmonth.tmpl` and `calendaryear.tmpl`.
# AUTHOR
* [[ikiwiki/markdown]]
* [[ikiwiki/openid]]
* [[ikiwiki/searching]]
+* [[templates]]
Details:
The template page can also contain [[!cpan HTML::Template]] directives,
-similar to other ikiwiki [[templates]]. Currently only one variable is
+like other ikiwiki [[templates]]. Currently only one variable is
set: `<TMPL_VAR name>` is replaced with the name of the page being
created.
The `pagetemplate` directive is supplied by the [[!iki plugins/pagetemplate desc=pagetemplate]] plugin.
-This directive allows a page to be displayed using a different template than
-the default `page.tmpl` template.
+This directive allows a page to be displayed using a different
+[[template|templates]] than the default `page.tmpl` template.
The page text is inserted into the template, so the template controls the
overall look and feel of the wiki page. This is in contrast to the
[[ikiwiki/directive/template]] directive, which allows inserting templates
_into_ the body of a page.
-This directive can only reference templates that are already installed
-by the system administrator, typically into the
-`/usr/share/ikiwiki/templates` directory. Example:
-
\[[!pagetemplate template="my_fancy.tmpl"]]
[[!meta robots="noindex, follow"]]
The `template` directive is supplied by the [[!iki plugins/template desc=template]] plugin.
-[[Templates]] are files that can be filled out and inserted into pages in the
-wiki, by using the template directive. The directive has an `id` parameter
+The template directive allows wiki pages to be used as templates.
+These templates can be filled out and inserted into other pages in the
+wiki using the directive. The [[templates]] page lists templates
+that can be used with this directive.
+
+The directive has an `id` parameter
that identifies the template to use. The remaining parameters are used to
fill out the template.
attachments will be accepted, via the `allowed_attachments`
configuration setting.
-For example, to limit arbitrary files to 50 kilobytes, but allow
-larger mp3 files to be uploaded by joey into a specific directory, and
-check all attachments for viruses, something like this could be used:
+For example, to limit most users to uploading small images, and nothing else,
+while allowing larger mp3 files to be uploaded by joey into a specific
+directory, and check all attachments for viruses, something like this could be
+used:
- virusfree() and ((user(joey) and podcast/*.mp3 and mimetype(audio/mpeg) and maxsize(15mb)) or (!ispage() and maxsize(50kb)))
+ virusfree() and ((user(joey) and podcast/*.mp3 and mimetype(audio/mpeg) and maxsize(15mb)) or (mimetype(image/*) and maxsize(50kb)))
The regular [[ikiwiki/PageSpec]] syntax is expanded with the following
additional tests:
This plugin searches for [[SubPages|ikiwiki/subpage]] with a missing parent
page, and generates the parent pages. The generated page content is
-controlled by the `autoindex.tmpl` [[template|wikitemplates]], which by
+controlled by the `autoindex.tmpl` [[template|templates]], which by
default, uses a [[map]] to list the SubPages.
I'm wanting a [[map]] (with indentation levels) showing page _titles_
instead of page 'names'. As far as I can see, this is not an option with
existing plugins - I can get a list of pages using [[inline]] and
-appropriate [[wikitemplates]], but that has no indentation and therefore
+appropriate [[templates]], but that has no indentation and therefore
doesn't show structure well.
The quick way is to modify the map plugin to have a 'titles' option. The
This plugin provides the [[ikiwiki/directive/pagetemplate]]
[[ikiwiki/directive]], which allows a page to be displayed
-using a different [[template|wikitemplates]] than the default.
-
-This plugin can only use templates that are already installed in
-`/usr/share/ikiwiki/templates` (or wherever ikiwiki is configured to look for
-them). You can choose to use any .tmpl files in that directory.
+using a different [[template|templates]] than the default.
This plugin provides the [[ikiwiki/directive/template]] [[ikiwiki/directive]].
With this plugin, you can set up templates, and cause them to be filled out
-and inserted into pages in the wiki. It's documented and existing templates
-are listed in the [[templates]] page.
+and inserted into pages in the wiki. Existing templates are listed in the
+[[templates]] page.
Directories in `add_underlays` should usually be absolute. If relative,
they're interpreted as relative to the parent directory of the basewiki
underlay, which is probably not particularly useful in this context.
-
---
-
-This plugin also adds an `add_templates` option to the setup file.
-Its value is a list of template directories to look for template files in,
-if they are not present in the `templatedir`.
hook(type => "pagetemplate", id => "foo", call => \&pagetemplate);
-[[Templates|wikitemplates]] are filled out for many different things in
+[[Templates]] are filled out for many different things in
ikiwiki, like generating a page, or part of a blog page, or an rss feed, or
a cgi. This hook allows modifying the variables available on those
templates. The function is passed named parameters. The "page" and
hook(type => "templatefile", id => "foo", call => \&templatefile);
-This hook allows plugins to change the [[template|wikitemplates]] that is
+This hook allows plugins to change the [[template|templates]] that is
used for a page in the wiki. The hook is passed a "page" parameter, and
-should return the name of the template file to use, or undef if it doesn't
-want to change the default ("page.tmpl"). Template files are looked for in
-/usr/share/ikiwiki/templates by default.
+should return the name of the template file to use (relative to the
+template directory), or undef if it doesn't want to change the default
+("page.tmpl").
### sanitize
### `template($;@)`
Creates and returns a [[!cpan HTML::Template]] object. The first parameter
-is the name of the file in the template directory. The optional remaining
-parameters are passed to `HTML::Template->new`.
+is the name of the template file. The optional remaining parameters are
+passed to `HTML::Template->new`.
+
+Normally, the template file is first looked for in the templates/ subdirectory
+of the srcdir. Failing that, it is looked for in the templatedir.
+
+Wiki pages can be used as templates. This should be done only for templates
+which it is safe to let wiki users edit. Enable it by passing a filename
+with no ".tmpl" extension. Template pages are normally looked for in
+the templates/ directory. If the page name starts with "/", a page
+elsewhere in the wiki can be used.
+
+### `template_depends($$;@)`
+
+Use this instead of `template()` if the content of a template is being
+included into a page. This causes the page to depend on the template,
+so it will be updated if the template is modified.
+
+Like `template()`, except the second parameter is the page.
### `htmlpage($)`
## HTML::Template security
-If the [[plugins/template]] plugin is enabled, users can modify templates
-like any other part of the wiki. This assumes that HTML::Template is secure
+If the [[plugins/template]] plugin is enabled, all users can modify templates
+like any other part of the wiki. Some trusted users can modify templates
+without it too. This assumes that HTML::Template is secure
when used with untrusted/malicious templates. (Note that includes are not
-allowed, so that's not a problem.)
+allowed.)
----
-[[!meta robots="noindex, follow"]]
-[[!if test="enabled(template)"
-then="This wiki has templates **enabled**."
-else="This wiki has templates **disabled**."
-]]
+[[Ikiwiki]] uses many templates for many purposes. By editing its templates,
+you can fully customise this site.
-Templates are files that can be filled out and inserted into pages in the
-wiki.
+[[!if test="enabled(template)" then="""
+## The template directive
+The template directive allows wiki pages to be used as templates,
+filled out and inserted into other pages in the wiki.
+"""]]
[[!if test="enabled(template) and enabled(inline)" then="""
-
-These templates are available for use with the template directive.
-
[[!inline pages="templates/* and !*/discussion" feeds=no archive=yes
sort=title template=titlepage
rootpage=templates postformtext="Add a new template named:"]]
"""]]
+
+[[!if test="enabled(edittemplate)" then="""
+## The edittemplate directive
+
+The edittemplate directive can be used to make new pages default to
+containing text from a template, which can be filled as out the page is
+edited.
+"""]]
+
+## Wiki templates
+
+These templates are used to build the wiki. The aim is to keep almost all
+html out of ikiwiki and in the templates.
+
+* `page.tmpl` - Used for displaying all regular wiki pages.
+* `misc.tmpl` - Generic template used for any page that doesn't
+ have a custom template.
+* `rsspage.tmpl` - Used for generating rss feeds for blogs.
+* `rssitem.tmpl` - Used for generating individual items on rss feeds.
+* `atompage.tmpl` - Used for generating atom feeds for blogs.
+* `atomitem.tmpl` - Used for generating individual items on atom feeds.
+* `inlinepage.tmpl` - Used for displaying a post in a blog.
+* `archivepage.tmpl` - Used for listing a page in a blog archive page.
+* `titlepage.tmpl` - Used for listing a page by title in a blog archive page.
+* `microblog.tmpl` - Used for showing a microblogging post inline.
+* `blogpost.tmpl` - Used for a form to add a post to a blog (and a rss/atom links)
+* `feedlink.tmpl` - Used to add rss/atom links if `blogpost.tmpl` is not used.
+* `aggregatepost.tmpl` - Used by the aggregate plugin to create
+ a page for a post.
+* `searchform.tmpl`, `googleform.tmpl` - Used by the search plugin
+ and google plugin to add search forms to wiki pages.
+* `searchquery.tmpl` - This is a Omega template, used by the
+ search plugin.
+* `comment.tmpl` - Used by the comments plugin to display a comment.
+* `change.tmpl` - Used to create a page describing a change made to the wiki.
+* `recentchanges.tmpl` - Used for listing a change on the RecentChanges page.
+* `autoindex.tmpl` - Filled in by the autoindex plugin to make index pages.
+* `autotag.tmpl` - Filled in by the tag plugin to make tag pages.
+* `calendarmonth.tmpl`, `calendaryear.tmpl` - Used by ikiwiki-calendar to
+ make calendar archive pages.
+* `editpage.tmpl`, `editconflict.tmpl`, `editcreationconflict.tmpl`,
+ `editfailedsave.tmpl`, `editpagegone.tmpl`, `pocreatepage.tmpl`,
+ `editcomment.tmpl` `commentmoderation.tmpl`, `renamesummary.tmpl`,
+ `passwordmail.tmpl` - Parts of ikiwiki's user interface; do not
+ normally need to be customised.
+
+[[!if test="enabled(pagetemplate)" then="""
+## The pagetemplate directive
+
+The pagetemplate directive can allow individual pages to use a
+different template than `page.tmpl`.
+"""]]
+
+## Template locations
+
+Templates are located in `/usr/share/ikiwiki/templates` by default;
+the `templatedir` setting can be used to make another directory be
+searched first. Customized templates can also be placed inside the
+"templates/" directory in your wiki's source.
+
+## Template syntax
+
+Ikiwiki uses the HTML::Template module as its template engine. This
+supports things like conditionals and loops in templates and is pretty easy
+to learn. All you really need to know are a few things:
+
+* To insert the value of a template variable, use `<TMPL_VAR variable>`.
+* To make a block of text conditional on a variable being set use
+ `<TMPL_IF NAME="variable">text</TMPL_IF>`.
+* To use one block of text if a variable is set and a second if it's not,
+ use `<TMPL_IF NAME="variable">text<TMPL_ELSE>other text</TMPL_IF>`
+
+[[!meta robots="noindex, follow"]]
\[[!inline pages="internal(*/comment_*)" template=comment]]
The special [[ikiwiki/PageSpec]] matches all comments. The
-[[template|wikitemplates]] causes the comments to be displayed formatted
+[[template|templates]] causes the comments to be displayed formatted
nicely.
*see git history of this page if you want the patch --[[smcv]]*
-This uses a [[template|wikitemplates]] called `autotagpage.tmpl`, here is my template file:
+This uses a [[template|templates]] called `autotagpage.tmpl`, here is my template file:
\[[!inline pages="link(<TMPL_VAR TAG>)" archive="yes"]]
templatedir => "$srcdir/templates",
-.. and then the [[wikitemplates]] are managed like other wiki files; and
+.. and then the [[templates]] are managed like other wiki files; and
like other wiki files, a change to them automatically updates dependent
pages.
>>>>>>> many templates, so the clutter is small. (Especially when
>>>>>>> compared to the other clutter the basewiki always puts in destdir.)
>>>>>>> This could be revisted later. --[[Joey]]
+
+[[done]]
Create some nice(r) stylesheets.
Should be doable w/o touching a single line of code, just
-editing the [[wikitemplates]] and/or editing [[style.css]].
+editing the [[templates]] and/or editing [[style.css]].
[[done]] ([[css_market]] ..)
-> Another useful feature might be to be able to choose a different [[template|wikitemplates]]
+> Another useful feature might be to be able to choose a different [[template|templates]]
> file for some pages; [[blog]] pages would use a template different from the
> home page, even if both are managed in the same repository, etc.
* --templatedir dir
- Specify the directory that the page [[templates|wikitemplates]] are stored in.
+ Specify the directory that [[templates|templates]] are stored in.
Default is `/usr/share/ikiwiki/templates`, or another location as configured at
build time. If the templatedir is changed, missing templates will still
- be searched for in the default location as a fallback.
+ be searched for in the default location as a fallback. Templates can also be
+ placed in the "templates/" subdirectory of the srcdir.
Note that if you choose to copy and modify ikiwiki's templates, you will need
to be careful to keep them up to date when upgrading to new versions of
+++ /dev/null
-ikiwiki uses the HTML::Template module as its template engine. This
-supports things like conditionals and loops in templates and is pretty easy
-to learn.
-
-The aim is to keep almost all html out of ikiwiki and in the templates.
-
-It ships with some basic templates which can be customised. These are
-located in `/usr/share/ikiwiki/templates` by default; the `templatedir`
-setting can be used to make another directory be searched first.
-
-* `page.tmpl` - Used for displaying all regular wiki pages.
-* `misc.tmpl` - Generic template used for any page that doesn't
- have a custom template.
-* `editpage.tmpl` - Create/edit page.
-* `change.tmpl` - Used to create a page describing a change made to the wiki.
-* `passwordmail.tmpl` - Not a html template, this is used to
- generate a mail with an url the user can use to reset their password.
-* `rsspage.tmpl` - Used for generating rss feeds for [[blogs|blog]].
-* `rssitem.tmpl` - Used for generating individual items on rss feeds.
-* `atompage.tmpl` - Used for generating atom feeds for blogs.
-* `atomitem.tmpl` - Used for generating individual items on atom feeds.
-* `inlinepage.tmpl` - Used for adding a page inline in a blog
- page.
-* `archivepage.tmpl` - Used for listing a page in a blog archive page.
-* `microblog.tmpl` - Used for showing a microblogging post inline.
-* `blogpost.tmpl` - Used for a form to add a post to a blog (and a rss/atom links)
-* `feedlink.tmpl` - Used to add rss/atom links if blogpost.tmpl is not used.
-* `aggregatepost.tmpl` - Used by the [[plugins/aggregate]] plugin to create
- a page for a post.
-* `searchform.tmpl` - Used by the [[plugins/search]] plugin to add a search
- form to wiki pages.
-* `searchquery.tmpl` - This is an omega template, used by the
- [[plugins/search]] plugin.
-* `comment.tmpl` - This template is used to display a comment
- by the [[plugins/comments]] plugin.
-* `editcomment.tmpl` - This template is the comment post form for the
- [[plugins/comments]] plugin.
-* `commentmoderation.tmpl` - This template is used to produce the comment
- moderation form.
-* `recentchanges.tmpl` - This template is used for listing a change
- on the RecentChanges page.
-
-The [[plugins/pagetemplate]] plugin can allow individual pages to use a
-different template than `page.tmpl`.
-
-The [[plugins/template]] plugin also uses templates, though those
-[[templates]] are typically stored as pages in the wiki, and are inserted
-into pages.
-
-The [[plugins/edittemplate]] plugin is used to make new pages default to
-containing text from a template, which can be filled as out the page is
-edited.
+++ /dev/null
-## Place for local templates
-Where does one put any locally modified templates for an individual ikiwiki? --Ivan Z.
-
-> You can put them whereever you like; the `templatedir` controls
-> where ikiwiki looks for them. --[[Joey]]
-
-Thank you for your response! My question arose out of my intention to make
-custom templates for a wiki--specifically suited for the kind of content
-it will have--so, that would mean I would want to distribute them through
-git together with other content of the wiki. So, for this case the
-separation of conceptually ONE thing (the content, the templates, and the
-config option which orders to use these templates) into THREE separate
-files/repos (the main content repo, the repo with templates, and the config
-file) is not convenient: instead of distributing a single repo, I have to
-tell people to take three things if they want to replicate this wiki. How
-would you solve this inconvenience? Perhaps, a default location of the
-templates *inside* the source repo would do?--Ivan Z.
-
-> I would avoid putting the templates in a subdirectory of the ikiwiki srcdir.
-> (I'd also avoid putting the ikiwiki setup file there.)
-> While it's safe to do either in some cases, there are configurations where
-> it's unsafe. For example, a malicious user could use attachment handling to
-> replace those files with their own, bad versions.
->
-> So, two ideas for where to put the templatedir and ikiwiki setup.
-
-> * The easiest option is to put your wiki content in a subdirectory
-> ("wiki", say) and point `srcdir` at that.
-> then you can have another subdirectory for the wikitemplates,
-> and put the setup file at the top.
-> * Another option if using git would be to have a separate branch,
-> in the same git repository, that holds wikitemplates and the setup file.
-> Then you check out the repository once to make the `srcdir` available,
-> and have a second checkout, of the other branch, to make the other stuff
-> available.
->
-> Note that with either of these methods, you have to watch out if
-> giving other direct commit access to the repository. They could
-> still edit the setup file and templates, so only trusted users should
-> be given access. (It is, however, perfectly safe to let people edit
-> the wiki via the web, and is even safe to configure
-> [[tips/untrusted_git_push]] to such a repository.) --[[Joey]]
-
-Thanks, that's a nice and simple idea: to have a subdirectory! I'll try it. --Ivan Z.
-
-A [[!taglink wish|wishlist]]: the ikiwiki program could be improved so that it follows the same logic as git in looking for its config: it could ascend directories until it finds an `.ikiwiki/` directory with `.ikiwiki/setup` and then uses that configuration. Now I'm tired to always type `ikiwiki --setup path/to/the/setup --refresh` when working in my working clone of the sources; I'd like to simply type `ikiwiki` instead, and let it find the setup file. The default location to look for templates could also be made to be a sibling of the setup file: `.ikiwiki/templates/`. --Ivan Z.
--- /dev/null
+#!/usr/bin/perl
+use warnings;
+use strict;
+use Test::More 'no_plan';
+
+$/=undef;
+open(IN, "doc/templates.mdwn") || die "doc/templates.mdwn: $!";
+my $page=<IN>;
+close IN;
+
+foreach my $file (glob("templates/*.tmpl")) {
+ $file=~s/templates\///;
+ ok($page =~ /\Q$file\E/, "$file documented on doc/templates.mdwn");
+}
sipb-www / ikiwiki.git / commitdiff
