template docu reorg

Remove wikitemplates page; fold its contents into templates page.
Update all backlinks. Document new ability to put templates inside srcdir.
master
Joey Hess 2010-04-23 16:10:46 -04:00
parent 83703d2f4a
commit 7e79da7633
22 changed files with 111 additions and 141 deletions

View File

@ -10,7 +10,7 @@ If I have a <--#include virtual="foo" --> in some file, it gets stripped,
> 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

View File

@ -36,7 +36,7 @@ If you want to keep it as one form, then perhaps using some javascript to disabl
> 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]]
@ -44,4 +44,4 @@ If you want to keep it as one form, then perhaps using some javascript to disabl
> 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]]
>> Looks good, thanks! :-) -- [[AdamShand]]

View File

@ -72,7 +72,7 @@ you would care to syndicate.
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]]

View File

@ -4,7 +4,7 @@ ikiwiki, and this documentation wiki, are licensed under the terms of the
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

View File

@ -43,7 +43,7 @@ An example crontab:
# TEMPLATES
This command uses two [[template|wikitemplates]] to generate
This command uses two [[templates]] to generate
the pages, `calendarmonth.tmpl` and `calendaryear.tmpl`.
# AUTHOR

View File

@ -21,7 +21,7 @@ something like:
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.

View File

@ -1,17 +1,13 @@
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"]]

View File

@ -1,7 +1,11 @@
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.

View File

@ -3,5 +3,5 @@
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.

View File

@ -1,7 +1,7 @@
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

View File

@ -3,8 +3,4 @@
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.

View File

@ -3,5 +3,5 @@
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.

View File

@ -297,7 +297,7 @@ value is ignored.
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
@ -313,7 +313,7 @@ a new custom parameter to the template.
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 (relative to the
template directory), or undef if it doesn't want to change the default

View File

@ -1,17 +1,88 @@
[[!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.
These templates can be filled out and inserted into other pages in the
wiki using the directive.
"""]]
[[!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.
* `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.
[[!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"]]

View File

@ -6,5 +6,5 @@ add a feed that contains all the comments posted to any page. Here's how:
\[[!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.

View File

@ -17,7 +17,7 @@ The new tag file is then complied during the change phase.
*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"]]

View File

@ -6,7 +6,7 @@ This would allow setting:
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.

View File

@ -1,6 +1,6 @@
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]] ..)

View File

@ -1,4 +1,4 @@
> 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.

View File

@ -120,10 +120,11 @@ also be configured using a setup file.
* --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

View File

@ -1,52 +0,0 @@
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.

View File

@ -1,46 +0,0 @@
## 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.