How do I...Create a new skin?

 This page is meant to bring all of the "mumbo jumbo" together as a tutorial of how to skin Deki Wiki.  Please be warned this is sort of a "dummy's guide" so if you're tech savvy bear with me.

Table Of Contents

1. Getting Familiar with skinning

If you have any experience with Deki or Deki Wiki you are probably familiar with this section and can skip to section 2. There have been a lot developments in Deki Wiki "Hayes" related to skinning.   Allow me to introduce you to  the basics.  First lets navigate to the "Visual Appearance" page. 

• Control Panel > Visual Appearance 

On the visual appearance page see four different sections.  The first section is the "site logo" and it allows you to define which logo your wiki is going to display in the top left corner.  As you can see on on wiki.opengarden.org we have selected to show the opengarden.org logo.  The second section is the "customize site styles" section.  This section simply allows you to enter CSS in order to change the style of your wiki.  You will more than likely be using the customize site styles section a lot.  The third section is the "change your styles" section and it may be a misnomer but this section allows you to select between different templates and skins for those templates.  The fourth section is the "custom site HTML" section which allows you to inject custom HTML markup into each skin.

As you can see to the right I have included an image of the "change your styles" section.  Here we have two templates - ace and base.  Within ace we have three skins - blue, mindtouch, and neutral.  Within base we only have one skin - wireframe. 

Most skins will contain a preview image but please note that as you create skins you will need to create a image called screenshot.png for the preview function to work.

2. Copying an existing skin

1. Start Deki Wiki in VMware
2. Identify the ip/location of your wiki
   1. This can be accomplished using the ifconfig command in the VM
   2. Mine happens to be 192.168.111.128
3. Verify that you can navigate to \\ipaddress if you get any errors follow the setup instructions here
4. In your file system navigate to \\192.168.111.128\drive\var\www\deki-hayes\skins
   1. Here you will see the following folders.  Each folder represents a template php file.  Within each folder you then have different skins that work with that template file.
      
      
      1. ace - This is our original template.  It is extremely crisp and clean but doesn't lend itself to skinning/customizing very well.  For a quick out-of-the-box solution use the ace template.
          
      2. base - This is our custom skin template and it was designed to allow for standardized customization of skins.  We will be working with the base template throughout the remainder of this tutorial.

             

      3. fiesta - [needs info]. wiki.opengarden.org  uses the fiesta skin.
          
      4. common - This folder contains all of the shared files such as images and CSS.  You may need to change a couple files in here once you are doing extremely detailed skinning but for starters I wouldn't worry about the common folder.
          
      5. local - nothing
          
5. Open up the base folder.  Inside the base folder you will see the following:
   1. Folders - Each folder represents a different skin
       
   2. Stylesheets - You won't need to use these style sheets for now.  Perhaps later on when we get into more nitty gritty skinning.
       
   3. base.php  - This is the template file.  DO NOT make any changes to this file.  If you do, you are compromising the update ability and your wiki may not receive the necessary updates.
       
6. Our new skin is going to be based on the "wireframe" skin, so you can start off by copying and pasting the "wireframe" folder.  Give it a unique name so that it will represent the new skin and allow others to differentiate.  Don't just call it "red", call it something like "mindtouch_red_8_7_07".
7. Once you have created the skin you can open the folder and you will see the following
   
   1. CSS.php - This file is used to aggregate all of the necessary styles.  When we need to customize the stylesheet for IE6/IE7 you may be making changes to this file.
       
   2. Style.css- This file will become your best friend.  99.31% of changes you make to your wiki will be done in style.css.  I suppose this is a good time to mention that if you don't know CSS you should probably take a crash course on it and come back later.

3. Customizing My Skin

Intro / Things to keep in mind

Lets start by switching your wiki over to the new skin.  You should be familiar with this process because we already covered it in section1.  Go to Control Panel > Visual Appearance and scroll down to the "change your styles" section.  Under the base template you should now see your new skin.  Select your new skin and follow by pushing the "Set Style" button.

Ah ha, everything looks drastically different now doesn't it?  That's because your stylesheet only contains styles for the wireframe layout of the base template.  It should look very similar to the image on the right.  The wireframe is actually quite important and can be used to identify all the key areas of the template.  You will notice that everything on the wireframe skin is exposed.  You may find that later you hide some of these areas but for now it is good to see that they exist.

You will also see on the wireframe that there are duplicate areas.  You can see that the user login is placed in three different areas and that the search appears in two different areas.  The duplicates are there on purpose in order to provide flexibility to you.   If you want the user login to only appear in the top bar you can simply hide the other two user login sections in your css.

You should also notice the areas on the wireframe outlined in red.  These sections are designated for custom HTML and allow you to enter your own markup.  Whereas the markup of base.php cannot be changed, you can add your own html by using our custom HTML editor which I will discuss further later.  For now please keep in mind the location of the red/custom sections.

When considering how to make your skin look you have to be very creative.  Although items may appear as though they are already positioned you can manipulate the page very drastically with CSS and a little creativity.

Vital Functionality of a Wiki

As I mentioned earlier you can show and hide as many elements on the wiki as you desire. Although this approach does yield the most flexibility for our users when it come to skinning there are some fairly important suggestions we would like to make. 

Wikis are successful because of the nature of how people use them.  This is a lesson that MindTouch has spent many years perfecting and in turn we have altered and adapted by creating tools that encourage and foster successful wiki usage.  That being said we suggest/demand that you do not hide the following areas:

• Top Site Navigation - body div.global div.globalWrap div.header div.siteNav
  • This navigation contains links to: My Page, Control Panel, Recent Changes, Tools, Help
     
• Content Navigation/Tools - body div.global div.globalWrap div.body div.page div.pageBar
  • This navigation contains links to:  Edit Page, New Page, Restrict Access, AttachFile, Move Page, Delete Page, Table Of Contents, Print Page, More
  • Although it is recommended that you keep this navigation you can hide some buttons in order to preserve space.  We recommend that you always keep the Edit Page button shown in order to encourage users to contribute to the content. 
  • Also keep in mind that the more menu is a dropdown and provides the same links but in dropdown format.  So you can hide some of the less used items (Print Page, Table of Contents, Move Page) and keep the more menu.
     
• Wiki Navigation - body div.global div.globalWrap div.body div.siteNav
  • This navigation contains links to the entire wiki site allowing users to navigate from one page to another.

Custom HTML Editor

As mentioned earlier we have created a section for you to enter custom HTML.  The custom HTML editor is actually the tool that will give you the most flexibility/empowerment while designing your custom skin.  For instance you may use the custom HTML editor to add the header of your main website which will give users the feeling that your wiki is seamlessly integrated into your existing website.  Another application of the custom HTML may be to add advertisements to your wiki.  Perhaps you have sparked a hot topic and want to monetize your wiki community. With the custom HTML editor you can do so.  Another application may include inserting a custom footer to your template. 

Your custom HTML editor is also located on the "Visual Appearance" page:

• Control Panel > Visual Appearance 

The custom HTML editor doesn't strip or modify any code either which means that you can insert html, javascript, images, etc...  Perhaps you have a dropdown menu in your custom header and it requires javascript to work.  Simply place the script in the custom HTML editor and push save. 

However, please note that we really don't recommend using the custom HTML editor for CSS.  All of your CSS should be kept in style.css or in your "customize site styles" editor.

Start Making Changes

Ok, I know you're probably very eager to get started and I would be too after reading all the boring rules and recommendations but they are important to ensure a job well done.

In order to completely understand the element hierarchy of base.php we have constructed a hierarchical list of elements. 

Please open up your style.css files.  If you'll don't recall the location please refer to section 2.  Once you open it you will see that there are some styles that have been defined.  These are the styles that build the current wireframe skin you have loaded.  Feel free to make modifications to the wireframe style.  Ultimately you are going to wipe out all of the wireframe styles and replace them with your own but they certainly do help as a guide to styling the elements.

Skinning your wiki can be a fairly long process.  There are hundreds of elements and because we use reset.css you can often find yourself redefining styles for common HTML tags.  In an effort to streamline the process of skinning your wiki we have created a "skinning kick start" page that provides you will all the styles you need to get started.  The skinning kick start styles take care of the styles for your editor, content, dropdowns, and administrative section.  It also removes or dims down the wireframe styles which makes it easier to customize.

Once You're Done

Upload it to the Skin Gallery
Once you've completed you need to show it of.  In an effort to build a library of skins we're asking that users contribute their skin files and any documentation that goes along with the skin.  You can simply zip it up and upload it to our skin gallery.  Thanks for your help.