============================
Writing a skin in CPSDefault
============================

:Revision: $Id: howto-write_skin.txt 30254 2005-12-04 01:49:55Z dkuhlman $

.. sectnum::    :depth: 4
.. contents::   :depth: 4


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:

1. (cps_devel)

2. cps_styles/nuxeo

3. cps_styles

4. cps_images

5. cps_default


File naming
===========

We try to use the same file naming as CMF.

For any new file follow these rules:

1. For a page template or a python script that return an HTML page::

       object_action.p[ty]

   If the page is a form: object_action_form.p[ty].

   Examples::

       content_submit_form.pt
       content_create.py       # use request and redirect to html page
       dummy_view.pt

2. Python script::

       getSomething.py
       doSomething.py

   Examples::

       getContentInfo.py
       getFolderContents.py

   Note: It is very useful to make each python script work with a
   default value so that you can call them with a browser and you
   can bench mark it easily (cf. doc HOWTO.BENCHMARK).

3. 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 30254 2005-12-04 01:49:55Z dkuhlman $
    """ 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 parameter line.  Examples::

    ##parameters=REQUEST

or::

    REQUEST=None``.


Path and URL
============

Follow CPSCore/doc/virtual-hosting.txt documentation to see all
the ways to get url/path information about an object that will not
break using virtual hosting.

main_template defines:

- context_url -- This is the minimal url to your context, with a
  trailing slash like ``/cps/foo/``.  Example::

      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 returns ``/`` or ``/cps/`` or
  ``/name_of_the_cps/``.  You should use this for images or CSS
  URL::

      <img ... tal:attributes="src string:${base_url}foo.png" .../>


SVN
===

Follow these guidelines:

- Use "svn status" to see what is changed in your sandbox.

- Use "svn update" and run tests before committing.

- Do not use mass commit.

- Committing a file:

  1. TEST IT

  2. Perform a comparison -- ``svn 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 Step 1.

  4. Commit with a valid comment::

      svn ci -m "mandatory comment in ENGLISH" foo.py

- Remove unused files or code.  SVN will keep it for you.

The following section of the SVN manual is helpful:
http://svnbook.red-bean.com/en/1.1/svn-book.html#svn-ch-3-sect-5.


Macros
======

We try to use macros for any thing that appears twice or that
needs to be easily customized.  Macros are defined in a
``*_lib.pt`` file, for example ``content_lib`` or ``generic_lib``.
You should provide a test suite for each library.  These 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 heavy customization by rewriting
``*_lib`` files and maybe ``main_template``.  The goal is to keep
all other files unchanged.


Translation and caveats
=======================

See ``howto-i18n.txt|html`` for internationalization and
translation rules.

**A skin is finished only when it is fully i18n and l10n in en and
fr!**

