| |
| TEMPLATES |
| ========= |
| |
| 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. |
| |
| *Skins* are modifications on the basic templates. Each template may |
| have one or many skins available, and these are chosen by the user. |
| These are based on stylesheets, and some templates might not support |
| any skins 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 "skin". |
| |
| |
| Rolling your own |
| ================ |
| |
| To make your own template, just make an another subdirectory in |
| "templates", copy all the files from the "default" -template, and |
| modify them at your will. |
| |
| To specify which template your site should use, just change the |
| definition of "jspwiki.templateDir" in jspwiki.properties. |
| |
| |
| More details |
| ============ |
| |
| 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. |
| |
| Each template MUST have both of these files, or else there will be |
| trouble. |
| |
| |
| View pages: ViewTemplate.jsp, EditTemplate.jsp |
| ---------------------------------------------- |
| |
| ViewTemplate.jsp gets all requests from Wiki.jsp, Preview.jsp, |
| PageInfo.jsp, etc. Modify this file 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. |
| |
| |
| OK. 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 files depending on the Page Request |
| Context. The Page Request Context basically tells you whether you're |
| asking for "info", or "diff", or whatever. The default template uses |
| the CheckRequestContext tag to see which context you're in at the moment, |
| and includes then a proper "Content" -file. |
| |
| For example, in an excerpt from the default template: |
| |
| <wiki:CheckRequestContext context="view"> |
| <wiki:Include page="PageContent.jsp" /> |
| </wiki:CheckRequestContext> |
| |
| 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 "ViewTemplate.jsp" to see |
| what kind of different request contexts there are, and how to handle |
| them. |
| |
| |
| |
| "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. |
| |
| |
| Explanation of the different tags |
| ================================= |
| |
| JSPWiki templates are heavily based on JSP tags. An explanation on |
| them will be shortly coming, but in the mean time, just run "ant |
| javadoc" and see what kind of stuff appears in "docs/". |
| |
| You could alternatively just look at the default template, since it |
| basically uses all of the tags. They're not that hard to figure out. |