$Id: howto-write_skin.txt 6552 2004-09-16 15:24:04Z sfermigier $

Writing skin in CPSDefault
==========================
skin directories:

skins:
  |-- cps_default    all needed skin for CPSDefault
  |-- cps_devel      skin for benchmarking or debuging
  |-- cps_images     images only no icons
  `-- cps_styles     a plone_styles folder
      `-- nuxeo      a customization of the plone.css

skin order:
(cps_devel), cps_styles/nuxeo, cps_styles, cps_images, cps_default


File naming
===========
we try to use same file naming as CMF,
for any new file follow this rules:

For a page template or a python script that return an html page:
  object_action.p[ty]
if the page is an form
  object_action_form.p[ty]
ex:
  content_submit_form.pt
  content_create.py       # use request and redirect to html page
  dummy_view.pt

Python script:
  getSomething.py
  doSomething.py
ex:
  getContentInfo.py
  getFolderContents.py

it is very usefull to make python script working with default value
so that you can call them with a browser and you can bench it easily
(cf doc HOWTO.BENCHMARK)

macro library:
  object_lib.pt


Generic names
=============
Folder:  a folderish object
Content: what is inside a folder
items:   a list of objects
proxy:   the cps proxy object
doc:     a cps document in the portal_repository
info:    a dictionary of information about an object
..path:  a list of item that represent a path like physical path
..url:   a /string/like/this that resolve

Python Script
=============
mandatory header:

##parameters=only_ids=0
# $Id: howto-write_skin.txt 6552 2004-09-16 15:24:04Z sfermigier $
""" A description of what the script does, param and return if
it is not obvious """

Do not use context.REQUEST in a python script !
You should pass it through the parameters line like:
##parameters=REQUEST

or REQUEST=None


Path and URL
============
main_template defines
- context_url:
  this is the minimal url to your context like /cps/foo
  ex: url: http://server/cps/foo/bar/foo/bar/cps/foo/bar/bar/bar
      context_url = /cps/foo/bar

- base_url:
  this is the base url taking into account the apache redirection
  it return / or /cps/ or /name_of_the_cps/
  you should use this for images or css url like:
  <img ... tal:attributes="src string:${base_url}foo.png" .../>

note: replace all portal_url by context_url in you zpt
for python script you can call
  context.getContextUrl()
  or context.getBaseUrl()


CVS
===
- use the alias 'needs' as much as possible
  needs is a 'cvs -qnz6 up'
  this tell you what cvs will do if you run 'cvs up' without doing anything
  before working on a product you should run needs and check that
  you are uptodate
- do not use mass commit
- commiting a file:
  1/ TEST IT
  2/ cvs diff file
      because you will know exactly what to put in the comment
      and it gives you a last chance to remove some stupid code
      REMOVE unused code or commented code
  3/ if you have changed something goto 1/
  4/ commit with a valid comment
      cvs commit -m"mandatory comment in ENGLISH" foo.py
- remove unused file or code, cvs will keep it for you


Macros
======
we try to use macros for any thing that appear twice,
or that need to be easily customized.
Macros are define in *_lib.pt file like content_lib or generic_lib
you should provide a test suite for each library
they are located in cps_devel like test_content_lib or test_generic_lib
each time you add a macro you should add a test


About CSS XXX deprecated
=========
- we are using the plone css definition
- we provide a customization nuxeo/ploneCustom.css and a new ploneNS4.css
- we can use any plone customization
- plone can use our nuxeo css customization


Customization
=============
We should be able to make light customization by adding custom css
We should be able to make eavy customization by rewriting *_lib files
 and maybe main_template, the goal is to keep all other files unchanged


Translation and caveats
=======================
See HOWTO.i18n for internationalisation and translation rules.

A SKIN IS FINISH ONLY WHEN IT IS FULLY I18N AND L10N IN en AND fr !!!

