View source for Cchost/concepts/Skins

[[Category:ccHost]]
[[Category:ccMixter]]
[[Category:Developer]]
[[Category:Software]]
[[Category:Technology]]
{{cchost_head}}
{{lowercase}}

=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 <nowiki><head></nowiki> 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 [[Cchost/How_User_Content_is_Displayed|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 [[Cchost/admin/config_customize|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 [[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''.

=Profile Compliant Skinning=
''body.tpl'' is responsible for the contents of the <nowiki><body></nowiki> 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:

   <nowiki><?</nowiki>      
       if( !empty($A['macro_names'] ) )
          while( $macro = array_shift($A['macro_names']) )
              $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%