doc/templates.mdwn

   1 [[Ikiwiki]] uses many templates for many purposes. By editing its templates,
   2 you can fully customise its appearance, and avoid duplicate content.
   3
   4 Ikiwiki uses the HTML::Template module as its template engine. This
   5 supports things like conditionals and loops in templates and is pretty
   6 easy to learn. All you really need to know to modify templates is this:
   7
   8 * To insert the value of a template variable, use `<TMPL_VAR variable>`.
   9 * To make a block of text conditional on a variable being set use
  10   `<TMPL_IF variable>text</TMPL_IF>`.
  11 * To use one block of text if a variable is set and a second if it's not,
  12   use `<TMPL_IF variable>text<TMPL_ELSE>other text</TMPL_IF>`
  13
  14 [[!if test="enabled(template) or enabled(edittemplate)" then="""
  15 ## template pages
  16
  17 Template pages are regular wiki pages that are used as templates for other
  18 pages.
  19 """]]
  20
  21 [[!if test="enabled(template)" then="""
  22 The [[!iki ikiwiki/directive/template desc="template directive"]] allows
  23 template pages to be filled out and inserted into other pages in the wiki.
  24 """]]
  25
  26 [[!if test="enabled(edittemplate)" then="""
  27 The [[!iki ikiwiki/directive/edittemplate desc="edittemplate directive"]] can
  28 be used to make new pages default to containing text from a template
  29 page, which can be filled out as the page is edited.
  30 """]]
  31
  32 [[!if test="(enabled(template) or enabled(edittemplate))
  33 and enabled(inline)" then="""
  34 These template pages are currently available:
  35
  36 [[!inline pages="templates/* and !*.tmpl and !templates/*/* and !*/discussion"
  37 feeds=no archive=yes sort=title template=titlepage
  38 rootpage=templates postformtext="Add a new template page named:"]]
  39 """]]
  40
  41 ## template files
  42
  43 Template files are unlike template pages in that they have the extension
  44 `.tmpl`. Template files are used extensively by Ikiwiki to generate html.
  45 They can contain html that would not normally be allowed on a wiki page.
  46
  47 Template files are located in `/usr/share/ikiwiki/templates` by default;
  48 the `templatedir` setting can be used to make another directory be
  49 searched first. Customised template files can also be placed inside the
  50 "templates/" directory in your wiki's source -- files placed there override
  51 ones in the `templatedir`.
  52
  53 Here is a full list of the template files used:
  54
  55 * `page.tmpl` - Used for displaying all regular wiki pages. This is the
  56   key template to customise to change the look and feel of Ikiwiki.
  57   [[!if test="enabled(pagetemplate)" then="""
  58   (The [[!iki ikiwiki/directive/pagetemplate desc="pagetemplate directive"]]
  59   can be used to make a page use a different template than `page.tmpl`.)"""]]
  60 * `rsspage.tmpl` - Used for generating rss feeds for blogs.
  61 * `rssitem.tmpl` - Used for generating individual items on rss feeds.
  62 * `atompage.tmpl` - Used for generating atom feeds for blogs.
  63 * `atomitem.tmpl` - Used for generating individual items on atom feeds.
  64 * `inlinepage.tmpl` - Used for displaying a post in a blog.
  65 * `archivepage.tmpl` - Used for listing a page in a blog archive page.
  66 * `titlepage.tmpl` - Used for listing a page by title in a blog archive page.
  67 * `microblog.tmpl` - Used for showing a microblogging post inline.
  68 * `blogpost.tmpl` - Used for a form to add a post to a blog (and rss/atom links)
  69 * `feedlink.tmpl` - Used to add rss/atom links if `blogpost.tmpl` is not used.
  70 * `aggregatepost.tmpl` - Used by the aggregate plugin to create
  71   a page for a post.
  72 * `searchform.tmpl`, `googleform.tmpl` - Used by the search plugin
  73   and google plugin to add search forms to wiki pages.
  74 * `searchquery.tmpl` - This is a Omega template, used by the
  75   search plugin.
  76 * `comment.tmpl` - Used by the comments plugin to display a comment.
  77 * `change.tmpl` - Used to create a page describing a change made to the wiki.
  78 * `recentchanges.tmpl` - Used for listing a change on the RecentChanges page.
  79 * `autoindex.tmpl` - Filled in by the autoindex plugin to make index pages.
  80 * `autotag.tmpl` - Filled in by the tag plugin to make tag pages.
  81 * `calendarmonth.tmpl`, `calendaryear.tmpl` - Used by ikiwiki-calendar to
  82   make calendar archive pages.
  83 * `editpage.tmpl`, `editconflict.tmpl`, `editcreationconflict.tmpl`,
  84   `editfailedsave.tmpl`, `editpagegone.tmpl`, `pocreatepage.tmpl`,
  85   `editcomment.tmpl` `commentmoderation.tmpl`, `renamesummary.tmpl`,
  86   `passwordmail.tmpl`, `openid-selector.tmpl`, `revert.tmpl` - Parts of ikiwiki's user
  87   interface; do not normally need to be customised.
  88
  89 [[!meta robots="noindex, follow"]]
  90
  91 here is a list of variables used in various tmpl files:
  92 ACTION
  93 ACTIONS
  94 ADDCOMMENTURL
  95 ATOMCOMMENTSURL
  96 ATOMURL
  97 ATTACHMENTS-CLASS
  98 AUTHOR
  99 AUTHORURL
 100 BACKLINKS
 101 BASEURL
 102 BROKENLINKS
 103 BROKENLINKS_CHECKED
 104 CATEGORIES
 105 CATEGORY
 106 CDATE_3339
 107 CDATE_822
 108 CGIURL
 109 COMMENTAUTHOR
 110 COMMENTAUTHORURL
 111 COMMENTID
 112 COMMENTIP
 113 COMMENTOPENID
 114 COMMENTS
 115 COMMENTSLINK
 116 COMMENTSURL
 117 COMMENTUSER
 118 COMMITDATE
 119 COMMITTYPE
 120 CONTENT
 121 COPYRIGHT
 122 CTIME
 123 DEST
 124 DIFF
 125 DIFFURL
 126 DISCUSSIONLINK
 127 DYNAMIC
 128 EDITURL
 129 ENCLOSURE
 130 ERROR
 131 ERROR_MESSAGE
 132 EXTRAFOOTER
 133 FAVICON
 134 FEEDDATE
 135 FEEDDESC
 136 FEEDLINKS
 137 FEEDURL
 138 FIELD-ATTACHMENT
 139 FIELD-DO
 140 FIELD-EDITCONTENT
 141 FIELD-EDITMESSAGE
 142 FIELD-FROM
 143 FIELD-LINK
 144 FIELD-NEWFILE
 145 FIELD-PAGE
 146 FIELD-RCSINFO
 147 FIELD-REMOVE
 148 FIELD-RENAME
 149 FIELD-REV
 150 FIELD-REVERTMESSAGE
 151 FIELD-SELECT
 152 FIELD-SID
 153 FIELD-SUBJECT
 154 FIELD-TYPE
 155 FIELD-UPLOAD
 156 FIRST
 157 FIXEDLINKS
 158 FORCEBASEURL
 159 FORCEBASEURL
 160 form-cancel
 161 FORM-END
 162 FORM-START
 163 FORM-SUBMIT
 164 GETSOURCEURL
 165 GUID
 166 HAVE_ACTIONS
 167 HELPONFORMATTINGLINK
 168 HISTORYURL
 169 HTML5
 170 ID
 171 ISTRANSLATION
 172 JAVASCRIPT
 173 LANG
 174 LANGUAGE
 175 LAST
 176 LENGTH
 177 LICENSE
 178 LINE
 179 LINK
 180 LOCAL_CSS
 181 MASTER
 182 MDATE_3339
 183 MESSAGE
 184 META
 185 MONTH
 186 MORE_BACKLINKS
 187 MTIME
 188 NAME
 189 NAME="ATTACHMENT_LIST"
 190 NAME="ATTACHMENT_LIST"
 191 NAME="CAN_COMMIT"
 192 NAME="FIELD-ATTACHMENT"
 193 NAME="FORM-END"
 194 NAME="PAGE_DIFF"
 195 NAME="PAGE_PREVIEW"
 196 NAME="PAGE_PREVIEW"
 197 NAME="PAGE_SELECT"
 198 NAME=ALLOWAUTHOR
 199 NAME=FIELD-AUTHOR
 200 NAME=FIELD-URL
 201 NAME=USERNAME
 202 NONOPENIDFORM
 203 OPENID_URL
 204 OTHERLANGUAGES
 205 PAGE
 206 PAGE_DIFF
 207 PAGE_PREVIEW
 208 PAGES
 209 PAGESPEC
 210 PAGEURL
 211 PARENTLINKS
 212 PASSWORDURL
 213 PERCENT
 214 PERCENTTRANSLATED
 215 PERMALINK
 216 POSTFORMTEXT
 217 PREFSURL
 218 RECENTCHANGESURL
 219 RELVCS
 220 REMOTE_ADDR
 221 REMOVEURL
 222 REV
 223 REVERTURL
 224 ROOTPAGE
 225 RSSURL
 226 SEARCHACTION
 227 SEARCHFORM
 228 SID
 229 SIDEBAR
 230 SIGNINURL
 231 SIZE
 232 SRC
 233 TAG
 234 TAGNAME
 235 TAGS
 236 TITLE
 237 TYPE
 238 URL
 239 USER
 240 USER_NAME
 241 VERSION
 242 VIEW
 243 WIKINAME
 244 WIKIURL
 245 WMD_PREVIEW
 246 YEAR
 247