Difference between revisions of "Cchost/concepts/Skins"

From Creative Commons
Jump to: navigation, search
(New page: Category:ccHost Category:ccMixter Category:Developer Category:Software Category:Technology {{cchost_head}} {{lowercase}} =Components of Skin= A skin is a composite of ...)
 
(→‎Compliant Layout)
 
(3 intermediate revisions by the same user not shown)
Line 99: Line 99:
 
When your skin executes on a page request, the [[cchost/concepts/Templates|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 [[Cchost/concepts/Templates#Searching_for_Files|finds templates]]. The template engine then executes your ''page.tpl'' which should call ''body.tpl''.
 
When your skin executes on a page request, the [[cchost/concepts/Templates|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 [[Cchost/concepts/Templates#Searching_for_Files|finds templates]]. The template engine then executes your ''page.tpl'' which should call ''body.tpl''.
  
−
===body.tpl===
+
=Profile Compliant Skinning=
 
''body.tpl'' is responsible for the contents of the <nowiki><body></nowiki> section of the page.
 
''body.tpl'' is responsible for the contents of the <nowiki><body></nowiki> section of the page.
  
−
A properly authored body.tpl will respect the expectations of the various Skin Profile attributes. For example the ''tab_pos'' variable which suggests where the navigator tabs are to be positioned. Another example would be keeping to the CSS selectors in the ''color_scheme'' template. Perhaps the most important of these are the position selectors in the ''page_layout'' attribute in order to honor the admin's layout preferences.
+
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:
  
−
The content section of the page is filled by executing the ''macro_names'' array. In order to allow templates to dynamically add items to the end of the content list you should the array_shift function in case the list changes during execution:
+
  <nowiki><?</nowiki>     
−
 
+
      if( !empty($A['macro_names'] ) )
−
      if( !empty($A['macro_names'] ) )
 
 
           while( $macro = array_shift($A['macro_names']) )
 
           while( $macro = array_shift($A['macro_names']) )
 
               $T->Call($macro);
 
               $T->Call($macro);
 +
  <nowiki><?</nowiki>     
 +
 +
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:
 +
 +
  <nowiki><div id="wrapper"></nowiki>
 +
    <nowiki><div id="content"></nowiki>
 +
    <nowiki></div></nowiki>
 +
  <nowiki></div></nowiki>
 +
  <nowiki><div id="navigation"></nowiki>
 +
  <nowiki></div></nowiki>
 +
  <nowiki><div id="extras"></nowiki>
 +
  <nowiki></div></nowiki>
 +
  <nowiki><div id="footer"></nowiki>
 +
  <nowiki></div></nowiki>
 +
 +
If you do need your own positioning that isn't one of the pre-canned ones, you should still use the layout above and [[Cchost/admin/config_customize#Page_Layout|create your own layout]] sytle.
 +
==Compliant Color Scheme==
 +
Instead of hard coding colors into your style sheets and templates you should use the following selectors:
 +
 +
.light_bg
 +
.light_border
 +
.light_color
 +
.dark_bg
 +
.dark_border
 +
.dark_color
 +
.med_dark_bg
 +
.med_dark_color
 +
.med_dark_border
 +
.med_bg
 +
.med_color
 +
.med_border
 +
.med_light_bg
 +
.med_light_color
 +
.med_light_border
 +
 +
If you want specific color you should definitely [[Cchost/admin/config_customize#Creating_a_new_color_scheme|make it into a color scheme]]. See '''ccskins/shared/colors/color_mono.php''' for that looks like.
 +
==Compliant Font Family and Style==
 +
Instead of hard coding font family and sizes into your skin should use leave that to the profile's font settings. If what you're looking for isn't there, you should [[Cchost/admin/config_customize#Creating_font_schemes|create your own font schemes]].
 +
 +
==Compliant Navigation Tab Positions==
 +
The admin can control where the [[Cchost/customize/Navigation_Tabs|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:
 +
 +
    <nowiki><div id="wrapper"></nowiki>
 +
      <nowiki><div id="content"></nowiki>
 +
 +
        %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:
 +
 +
    <nowiki><div id="navigation"></nowiki>
 +
 +
      %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%

Latest revision as of 16:51, 17 November 2008


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="wrapper">
    <div id="content">
    </div>
 </div>
 <div id="navigation">
 </div>
 <div id="extras"> 
 </div>
 <div id="footer">
 </div>

If you do need your own positioning that isn't one of the pre-canned ones, you should still use the layout above and create your own layout sytle.

Compliant Color Scheme

Instead of hard coding colors into your style sheets and templates you should use the following selectors:

.light_bg
.light_border
.light_color
.dark_bg
.dark_border
.dark_color
.med_dark_bg
.med_dark_color
.med_dark_border
.med_bg
.med_color
.med_border
.med_light_bg
.med_light_color
.med_light_border

If you want specific color you should definitely make it into a color scheme. See ccskins/shared/colors/color_mono.php for that looks like.

Compliant Font Family and Style

Instead of hard coding font family and sizes into your skin should use leave that to the profile's font settings. If what you're looking for isn't there, you should create your own font schemes.

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%
Retrieved from "https://wiki.creativecommons.org/index.php?title=Cchost/concepts/Skins&oldid=19940"