Raible's Wiki: WikiTemplates

-       Raible's Wiki




    Raible Designs

Wiki Home

News

Recent Changes

AppFuse
Homepage

  -  Korean

  -  Chinese

  -  Italian

  -  Japanese

QuickStart Guide

  - Chinese
 
  - French

  - German

  - Italian

  - Korean

  - Portuguese

  - Spanish

  - Japanese


User Guide

  - Korean

  - Chinese
 

Tutorials

  -  Chinese

  -  German

  -  Italian

  -  Korean

  -  Portuguese

  -  Spanish


FAQ

  -  Korean


Latest Downloads

Other Applications
Struts Resume

Security Example

Struts Menu



    




    

    
         
        Set your name in

        UserPreferences
            
    





       
       
       
       




    

Referenced by

InsertPageTag
JSPWikiFAQ
JSPWikiTags



    




   



   
   JSPWiki v2.2.33 
   



       
           

           

           
           
           


           Hide Menu
+            WikiTemplates
            



  
    Search Wiki:
    
    
  



         
         
            Your trail: 
         
      

      


      

      
         



      
          Difference between 
          current version 
          and 
          current version:
          

          
At line 1 added 199 lines.
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].

----

!!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, 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.

Each template MUST have both of these files, or else there will be
trouble.


!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.  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.

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.


----

!!A few Frequently Asked Questions

!Problem: Style Sheets

The default template directory contains a small JavaScript file, ''cssinclude.js'', 
which attempts to load the right CSS definitions for client browsers. Notice
that this file is __template specific__; you will need to modify it to use
''your'' template directory, if you have template-specific CSS. Modify this
line (around 28):

{{{
document.write("<link rel=\"stylesheet\" href=\"templates/default/"+sheet+"\">");
}}}

and replace ''default'' with your template dir name.

--[ebu]

!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? 

--[ebu]

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 :-).

--JanneJalkanen



          

      

      

      
      Back to WikiTemplates,
       or to the Page History.
       

      

      

      

      

      

      

      

      Show Menu
-WikiTemplates
+    Search Wiki:
 At line 1 added 199 lines.
+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].
+----
+!!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, 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.
+Each template MUST have both of these files, or else there will be
+trouble.
+!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.  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.
+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.
+----
+!!A few Frequently Asked Questions
+!Problem: Style Sheets
+The default template directory contains a small JavaScript file, ''cssinclude.js'',
+which attempts to load the right CSS definitions for client browsers. Notice
+that this file is __template specific__; you will need to modify it to use
+''your'' template directory, if you have template-specific CSS. Modify this
+line (around 28):
+{{{
+document.write("<link rel=\"stylesheet\" href=\"templates/default/"+sheet+"\">");
+}}}
+and replace ''default'' with your template dir name.
+--[ebu]
+!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?
+--[ebu]
+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 :-).
+--JanneJalkanen