src/wikipages/WikiTemplates.txt - jspwiki - Git at Google

 This page describes the Wiki v2 template system, which lets you adjust the
 appearance of your JSPWiki installation without worrying about losing your
 changes the next time you update JSPWiki.

 If you're looking for ready-made templates, please go to [JSPWiki:ContributedTemplates].  If you on the other hand are looking for ideas to implement in your templates, go to [JSPWiki:WantedTemplates].

 [{TableOfContents title='Table of Contents'}]

 ----

 !!!Introduction

 JSPWiki v2 now supports the concept of "templates" and "skins".  These
 are actually two different things:

 * ''Templates'' are set by the site administrator.  They are a core set
   of HTML and JSP files, that define how your site looks.  All
   templates are located in the JSPWiki/templates/<template name>
   directory.

 * ''Styles'' are modifications on the basic templates.  Each template may
   have one or many styles available, and these are chosen by the user.
   These are based on stylesheets, and some templates might not support
   any styles at all.

 JSPWiki comes currently with a single template, called "default".
 This is also the template that gets used if no template has been
 defined.  Unfortunately, the default template has only one "style".

 !!!Templates

 !!A very simple example

 This very simple example allows you to create the simplest possible template.

 __First, create your own template directory__

 Go to the JSPWiki installation directory, then go to "templates".  Make a new subdirectory, called "example".

 __Create your own ~ViewTemplate__

 Put the following example in the "example" directory, and call the file "~ViewTemplate.jsp":
 {{{
 <%@ taglib uri="/WEB-INF/jspwiki.tld" prefix="wiki" %>

 <h1><wiki:PageName/></h1>

 <wiki:Content/>
 }}}

 __Modify the {{jspwiki.properties}} file__

 Now find the {{jspwiki.properties}}-file, which is located under the WEB-INF subdirectory of your JSPWiki installation.  Open it in an editor, and find the line which says
 {{{
 jspwiki.templateDir=default
 }}}
 and change it into
 {{{
 jspwiki.templateDir=example
 }}}

 __Restart JSPWiki__

 Restart JSPWiki (for example, in Tomcat you can use the manager UI to do this, so you don't have to restart the entire Java Virtual Machine), or you can just restart the entire container.

 !!More details, aka "OK, here's how it works"

 !Main JSP pages: Wiki.jsp, Edit.jsp, Preview.jsp, PageInfo.jsp, etc.

 JSPWiki has a bunch of main JSP pages.  These work as the "Controller" - they basically control the processing of the request.  They take
 care of saving your document, or making sure that there are no concurrent changes, etc.  You can modify these files, if you want - they're written as JSP pages to make your modifications easier. However, when you upgrade to a new JSPWiki version, you'll need to
 modify these pages again.

 The main JSP pages will then figure out which template to use, and will include the appropriate template file, which decides what the "View" is going to be like.

 There are two basic templates: ViewTemplate and EditTemplate. ViewTemplate gets all requests from any page that does not have to care about changing the page contents, and EditTemplate gets all those requests that do.

 Any template should have at least ''one'' of the two files, or else it's essentially useless.

 !A word about the "default" template

 If JSPWiki cannot find a template file, it will use the one in the "default" template.  This allows you to just copy a single file from the default template in your own template and modify it.  You can even keep the ~ViewTemplate and ~EditTemplate from the default directory and change any of the *Content -files.

 Note that this does __not__ include the CSS -files. You have to still manually specify their location.  The "commonheader.jsp" file in the default template will include whatever css files you have in the local directory.

 !View pages: ViewTemplate.jsp, EditTemplate.jsp

 Basically, all you ever need to do is to modify two files to change the look of your Wiki:

 __ViewTemplate.jsp__ gets all requests from Wiki.jsp, Preview.jsp,
 PageInfo.jsp, etc.  Create a copy to change the visual outlook of your Wiki site, as your average browsing user would see it.

 __EditTemplate.jsp__ on the other hand gets all Edit.jsp requests.  Modify this file so that people who edit it get to see stuff.

 !The <wiki:Content> -tag and the request context

 OK, so far so good.  But we still have a problem: Displaying Page Info is totally different from showing the rendered text - yes?  The other one has plenty of lists and items, and the other one has nice HTML text.  But they are both handled by ViewTemplate.jsp!

 Here's where it gets complicated:  The "default" template handles this by including different ''content pages'' depending on the Page Request
 Context.  The Page ~RequestContext basically tells you whether you're asking for "info", or "diff", or whatever. Each context has a specific string representation - view is "view" etc.  You can use the [CheckRequestContextTag] to change JSPWiki's behaviour depending on the context - to show different text for example.

 However, there's a JSP tag called [ContentTag], which takes care most of the dirty work for you.  Just drop it wherever you would like, and it will include the proper content page.

 For example, the "view" context means that a page called "PageContent.jsp" is included.  You may override this by using the "view" argument of the [ContentTag].  (See for more information).

 This basically means that "if the request context is 'view', i.e. someone just wanted to see the rendered HTML content, then
 include a JSP page called 'PageContent.jsp'".  The PageContent.jsp then just basically says that:
 {{{
       <wiki:InsertPage />

       <wiki:NoSuchPage>
            This page does not exist.  Why don't you go and
            <wiki:EditLink>create it</wiki:EditLink>?
       </wiki:NoSuchPage>
 }}}

 That is: "insert the page content in HTML.  If there is no such page, display a simple note to the user, requesting him to fix this."

 So, it's not that difficult.  Take a look at the [list of request contexts|WikiTemplates#ListOfRequestContexts] to see what kind of different request contexts there are, and how they're handled by default.

 Note that this is just the way the default template does things.  Your own template is free to do anything it wants; as long as you provide EditTemplate.jsp and ViewTemplate.jsp, you should be set.

 !"Content" pages

 These are the different "content" pages that are included by "ViewTemplate.jsp".  For example, "PageContent.jsp" displays HTML,
 "DiffContent.jsp" displays the diff, etc.  You can just easily reuse these, or do something else.

 !A clarifying picture
 {{{

      Wiki.jsp, PageInfo.jsp, etc.
         ==>   templates/<name_of_template>/ViewTemplate.jsp


      Edit.jsp
         ==>   templates/<name_of_template>/EditTemplate.jsp
 }}}

 !Structure of the "default" template
 {{{
      ViewTemplate.jsp
         (Provide basic layout, incl. SearchBox.jsp)
         (Include proper content page)
         ==> PageContent.jsp   (If request was for Wiki.jsp)
         ==> InfoContent.jsp   (If request was for PageInfo.jsp)
         etc.

      EditTemplate.jsp
         (Provide edit page layout)
         (Includes only SearchBox.jsp)

 }}}

 !!Explanation of the different tags

 JSPWiki templates are heavily based on JSP tags.  A full explanation of them is available at [JSPWikiTags].

 For further examples, just look at the default template, since it
 basically uses all of the tags.  They're not that hard to figure out.

 ----
 !!!Styles

 ''This section needs to be written''

 ----

 !!!A few Frequently Asked Questions

 !Problem: Setting CSS classes to change the appearance of links, etc. on page parts

 Something I noticed while playing around with templates: if you want a clear contrast between
 wiki controls (LeftMenu, the top bar...) and page content, you'd want to be able to make text and links
 in various locations use different CSS classes. For example, you might want to render the control areas
 with darkish, earthy tones and light text/links, and normal dark-on-white on the content area.

 This doesn't seem like a trivial change at the face of it. How could we indicate what css styles to
 use in the template files?

 __Answer__

 Trivial.  In the template file, wrap the LeftMenu inside a <div class="leftmenu"> ... </div> block, then use a CSS selector to transform all anchors in that div to something else.  Like thus:

 {{{
 DIV.leftmenu A { font-size: 200px }
 }}}

 CSS is cool :-).

 ----

 !!!List of request contexts

 Here's a clarifying lists of which request contexts are available, and which content page handles what by default:

 ||  Context      ||  Handling JSP page
 | "view"|  PageContent.jsp
 | "diff"  | DiffContent.jsp
 | "info" | InfoContent.jsp
 | "preview" | PreviewContent.jsp
 | "conflict" | ConflictContent.jsp
 | "find" | FindContent.jsp
 | "prefs" | PreferencesContent.jsp
 | "error" | DisplayMessage.jsp
 | "edit" | EditContent.jsp
 | "comment" | CommentContent.jsp
	This page describes the Wiki v2 template system, which lets you adjust the
	appearance of your JSPWiki installation without worrying about losing your
	changes the next time you update JSPWiki.

	If you're looking for ready-made templates, please go to [JSPWiki:ContributedTemplates]. If you on the other hand are looking for ideas to implement in your templates, go to [JSPWiki:WantedTemplates].

	[{TableOfContents title='Table of Contents'}]

	----

	!!!Introduction

	JSPWiki v2 now supports the concept of "templates" and "skins". These
	are actually two different things:

	* ''Templates'' are set by the site administrator. They are a core set
	of HTML and JSP files, that define how your site looks. All
	templates are located in the JSPWiki/templates/<template name>
	directory.

	* ''Styles'' are modifications on the basic templates. Each template may
	have one or many styles available, and these are chosen by the user.
	These are based on stylesheets, and some templates might not support
	any styles at all.

	JSPWiki comes currently with a single template, called "default".
	This is also the template that gets used if no template has been
	defined. Unfortunately, the default template has only one "style".

	!!!Templates

	!!A very simple example

	This very simple example allows you to create the simplest possible template.

	__First, create your own template directory__

	Go to the JSPWiki installation directory, then go to "templates". Make a new subdirectory, called "example".

	__Create your own ~ViewTemplate__

	Put the following example in the "example" directory, and call the file "~ViewTemplate.jsp":
	{{{
	<%@ taglib uri="/WEB-INF/jspwiki.tld" prefix="wiki" %>

	<h1><wiki:PageName/></h1>

	<wiki:Content/>
	}}}

	__Modify the {{jspwiki.properties}} file__

	Now find the {{jspwiki.properties}}-file, which is located under the WEB-INF subdirectory of your JSPWiki installation. Open it in an editor, and find the line which says
	{{{
	jspwiki.templateDir=default
	}}}
	and change it into
	{{{
	jspwiki.templateDir=example
	}}}

	__Restart JSPWiki__

	Restart JSPWiki (for example, in Tomcat you can use the manager UI to do this, so you don't have to restart the entire Java Virtual Machine), or you can just restart the entire container.

	!!More details, aka "OK, here's how it works"

	!Main JSP pages: Wiki.jsp, Edit.jsp, Preview.jsp, PageInfo.jsp, etc.

	JSPWiki has a bunch of main JSP pages. These work as the "Controller" - they basically control the processing of the request. They take
	care of saving your document, or making sure that there are no concurrent changes, etc. You can modify these files, if you want - they're written as JSP pages to make your modifications easier. However, when you upgrade to a new JSPWiki version, you'll need to
	modify these pages again.

	The main JSP pages will then figure out which template to use, and will include the appropriate template file, which decides what the "View" is going to be like.

	There are two basic templates: ViewTemplate and EditTemplate. ViewTemplate gets all requests from any page that does not have to care about changing the page contents, and EditTemplate gets all those requests that do.

	Any template should have at least ''one'' of the two files, or else it's essentially useless.

	!A word about the "default" template

	If JSPWiki cannot find a template file, it will use the one in the "default" template. This allows you to just copy a single file from the default template in your own template and modify it. You can even keep the ~ViewTemplate and ~EditTemplate from the default directory and change any of the *Content -files.

	Note that this does __not__ include the CSS -files. You have to still manually specify their location. The "commonheader.jsp" file in the default template will include whatever css files you have in the local directory.

	!View pages: ViewTemplate.jsp, EditTemplate.jsp

	Basically, all you ever need to do is to modify two files to change the look of your Wiki:

	__ViewTemplate.jsp__ gets all requests from Wiki.jsp, Preview.jsp,
	PageInfo.jsp, etc. Create a copy to change the visual outlook of your Wiki site, as your average browsing user would see it.

	__EditTemplate.jsp__ on the other hand gets all Edit.jsp requests. Modify this file so that people who edit it get to see stuff.

	!The <wiki:Content> -tag and the request context

	OK, so far so good. But we still have a problem: Displaying Page Info is totally different from showing the rendered text - yes? The other one has plenty of lists and items, and the other one has nice HTML text. But they are both handled by ViewTemplate.jsp!

	Here's where it gets complicated: The "default" template handles this by including different ''content pages'' depending on the Page Request
	Context. The Page ~RequestContext basically tells you whether you're asking for "info", or "diff", or whatever. Each context has a specific string representation - view is "view" etc. You can use the [CheckRequestContextTag] to change JSPWiki's behaviour depending on the context - to show different text for example.

	However, there's a JSP tag called [ContentTag], which takes care most of the dirty work for you. Just drop it wherever you would like, and it will include the proper content page.

	For example, the "view" context means that a page called "PageContent.jsp" is included. You may override this by using the "view" argument of the [ContentTag]. (See for more information).

	This basically means that "if the request context is 'view', i.e. someone just wanted to see the rendered HTML content, then
	include a JSP page called 'PageContent.jsp'". The PageContent.jsp then just basically says that:
	{{{
	<wiki:InsertPage />

	<wiki:NoSuchPage>
	This page does not exist. Why don't you go and
	<wiki:EditLink>create it</wiki:EditLink>?
	</wiki:NoSuchPage>
	}}}

	That is: "insert the page content in HTML. If there is no such page, display a simple note to the user, requesting him to fix this."

	So, it's not that difficult. Take a look at the [list of request contexts\|WikiTemplates#ListOfRequestContexts] to see what kind of different request contexts there are, and how they're handled by default.

	Note that this is just the way the default template does things. Your own template is free to do anything it wants; as long as you provide EditTemplate.jsp and ViewTemplate.jsp, you should be set.

	!"Content" pages

	These are the different "content" pages that are included by "ViewTemplate.jsp". For example, "PageContent.jsp" displays HTML,
	"DiffContent.jsp" displays the diff, etc. You can just easily reuse these, or do something else.

	!A clarifying picture
	{{{

	Wiki.jsp, PageInfo.jsp, etc.
	==> templates/<name_of_template>/ViewTemplate.jsp


	Edit.jsp
	==> templates/<name_of_template>/EditTemplate.jsp
	}}}

	!Structure of the "default" template
	{{{
	ViewTemplate.jsp
	(Provide basic layout, incl. SearchBox.jsp)
	(Include proper content page)
	==> PageContent.jsp (If request was for Wiki.jsp)
	==> InfoContent.jsp (If request was for PageInfo.jsp)
	etc.

	EditTemplate.jsp
	(Provide edit page layout)
	(Includes only SearchBox.jsp)

	}}}

	!!Explanation of the different tags

	JSPWiki templates are heavily based on JSP tags. A full explanation of them is available at [JSPWikiTags].

	For further examples, just look at the default template, since it
	basically uses all of the tags. They're not that hard to figure out.

	----
	!!!Styles

	''This section needs to be written''

	----

	!!!A few Frequently Asked Questions

	!Problem: Setting CSS classes to change the appearance of links, etc. on page parts

	Something I noticed while playing around with templates: if you want a clear contrast between
	wiki controls (LeftMenu, the top bar...) and page content, you'd want to be able to make text and links
	in various locations use different CSS classes. For example, you might want to render the control areas
	with darkish, earthy tones and light text/links, and normal dark-on-white on the content area.

	This doesn't seem like a trivial change at the face of it. How could we indicate what css styles to
	use in the template files?

	__Answer__

	Trivial. In the template file, wrap the LeftMenu inside a <div class="leftmenu"> ... </div> block, then use a CSS selector to transform all anchors in that div to something else. Like thus:

	{{{
	DIV.leftmenu A { font-size: 200px }
	}}}

	CSS is cool :-).

	----

	!!!List of request contexts

	Here's a clarifying lists of which request contexts are available, and which content page handles what by default:

	\|\| Context \|\| Handling JSP page
	\| "view"\| PageContent.jsp
	\| "diff" \| DiffContent.jsp
	\| "info" \| InfoContent.jsp
	\| "preview" \| PreviewContent.jsp
	\| "conflict" \| ConflictContent.jsp
	\| "find" \| FindContent.jsp
	\| "prefs" \| PreferencesContent.jsp
	\| "error" \| DisplayMessage.jsp
	\| "edit" \| EditContent.jsp
	\| "comment" \| CommentContent.jsp