Cchost/concepts/Skins

From Creative Commons
Revision as of 16:09, 17 November 2008 by Fourstones (talk | contribs)
Jump to: navigation, search


Docs Home Install Upgrade Troubleshoot Customize Admins Devs Content Query Templates Commands Skins


Components of Skin

A skin is a composite of several template components. The main controlling file for a skin is a profile file that specifies what the different pieces are. For examples of skin profiles see ccskins/shared/profiles

Attribute Description Example
skin-file The main skin template which initializes any skin specific variables. ccskins/commons/skin.tpl
head-type Generates the <head> section of a page. ccskins/shared/head.tpl
string_profile Determines strings to use for forms, prompts, page titles, etc. ccskins/shared/strings/audio.php
list_file Template to use for an upload page. ccskins/shared/formats/upload_page_wide.php
list_files Template to use for query results. ccskins/shared/formats/upload_list_wide.tpl
form_fields Template (macro) to use for laying out single column form fields. ccskins/shared/form_fields.tpl/form_fields
grid_form_fields Template (macro) to use for laying out multiple column form fields. ccskins/shared/form_fields.tpl/grid_form_fields
tab_pos Template with tab position settings and styling. ccskins/shared/layouts/tab_pos_header.php
box_shape Template that controls box shape and styling. ccskins/shared/layouts/box_round.php
page_layout CSS template that determines position and size of content area, menus, extras (widgets) and footer. ccskins/shared/layouts/layout024.php
font_scheme CSS template that controls font family. ccskins/shared/colors/font_verdana.php
font_size CSS template that controls font size. ccskins/shared/colors/fontsize_px11.php
color_scheme CSS template that controls color selectors. ccskins/shared/colors/color_mono.php

Create a Skin Profile

You can create a new Skin Profile composed of existing skin components. To new create a new custom skin profile:

  • Log in as admin (if not already)
  • Click on Manage Site then Skin (or browse to admin/skins)
  • Select options in the Basic Settings, Layouts, and Color, Font, Text size sections.
  • Click on Save this Skin Profile (or browse to admin/skins/profile/save)
  • Fill out the form and click the Save this Skin Profile button.

Customizing Components

You can create customized version of the Upload Page and Upload Listing as described in the How User Content is Displayed section of this documentation.

You can create customized versions of many of the skin components like color schemes, string profiles and page layouts as described here. The other components (like tab_pos, font_scheme, etc.) follow the same model as the components mentioned in that section.

Customizing skin.tpl and body.tpl

In order to customize the raw CSS for body.tpl template you'll need to generate a new skin template based on an existing one.

  • Log in as admin (if not already)
  • Click on Manage Site, then Skin, then Create Skin Template (or browse to admin/skins/create)
  • Fill out the form
    • Select the skin to clone
    • Select a target directory (really, this should be <local_files>/skins
    • Enter name (NOTE: Because of a little, er, anomaly in 5.x only use lower case letters for you name. Trust us.)
  • Click on the Create a new skin button

This process creates a clone of a skin in <local_files>/skins directory.

In order to get you going, a new Skin Profile file was also created in <local_files>/skins/profiles and automatically selected as the current profile.

When your skin executes on a page request, the template engine is initialized with your skin.tpl. This is your chance to initialize any skin specific variables or mappings. (This would be a good time to get a deep understanding of how the template engine finds templates. The template engine then executes your page.tpl which should call body.tpl.

Profile Compliant Skinning

body.tpl is responsible for the contents of the <body> section of the page.

Before you start hacking at body.tpl you have decide whether your skin will be compliant with the profile settings that an admin can make. In other words, you can easily create a page that does nothing else but display the contents:

  <?      
      if( !empty($A['macro_names'] ) )
         while( $macro = array_shift($A['macro_names']) )
             $T->Call($macro);
  <?      

And wrap that in any HTML and CSS you desire. This might be the most efficient (or even likely) way that your pages will come out the way you desire. Whenever possible, however, you should seriously consider using the methods outlined below to give admins the most flexibility when using your skin.

Compliant Layout

There are 40 pre-canned layouts the admin can choose from at admin/skins/layouts. The control the content area, the menus and extras area.

In order to comply you should (at least) respect the following element IDs:

 wrapper
 content
 navigation
 extra
 footer

Ideally you should maintain the following layout after your header section:

 <div id="extras" 

Compliant Navigation Tab Positions

The admin can control where the navigation tabs and subtabs are laid out at admin/skins/tabs.


There are three macros to help you with the standard formats:

  • tabs.tpl/print_tabs - print main tabs
  • tabs.tpl/print_sub_tabs - print free standing subtabs
  • tabs.tpl/print_nested_tabs - print subtabs nested in main tabs

You can remap these to your own versions, but to be profile compliant you should check the tab_pos variable for these boolean values:

  • in_header Main tabs are in the header
  • floating Main tabs in with the menus
  • subclient Subtabs are in the content area
  • nested Main tabs in with menus, subtabs nested within

in_header means calling putting the in your header section (above div#wrapper). Here's how to check and print there using TPL macros:

   %if_not_empty(tab_pos/in_header)%
       %call('tabs.tpl/print_tabs')%
   %end_if%

If you're body template is in PHP the equivalent would be:

   <?
       if( !empty($A['tab_pos']['in_header']) )
       {
           $T->Call('tabs.tpl/print_tabs');
       }
   ?>

You should do you check just inside div#content to see if the subtabs go there:

   <div id="wrapper">
     <div id="content">
       %if_not_empty(tab_pos/subclient)%
         %call('tabs.tpl/print_sub_tabs')%
       %end_if%
 
       ...

Finally, inside div#navigation you should check and display the other options:

   <div id="navigation">

     %if_not_empty(tab_pos/floating)%
         %call('tabs.tpl/print_tabs')%
     %end_if%

     %if_not_empty(tab_pos/nested)%
         %call('tabs.tpl/print_nested_tabs')%
     %end_if%