doc/refactoring-the-css-with-uiprops.rst
author Aurelien Campeas <aurelien.campeas@logilab.fr>
Wed, 03 Jul 2013 14:33:27 +0200
branchstable
changeset 9130 0f1504a9fb51
parent 5492 da983679fab5
child 10121 23af005426bf
permissions -rw-r--r--
[constraint] more robust unicity constraint failures reporting for end-users Postgres or Sqlserver have limits on the index names (around resp. 64 and 128 characters). Because `logilab.database` encodes the `unique together` constraint rtypes in the index names, we sometimes get truncated index names, from which it is impossible to retrieve all rtypes. In the long run, the way such index are named should be changed. In the short term, we try to reduce the end-user confusion resulting from this design flaw: * in source/native, the regex filtering ``IntegrityError`` message does not impose an `_idx` suffix, which indeed may be absent (the result being an UI message that resembles a catastrophic failure), * also we avoid including a trailing " (double quote) from the error message * in entities/adapters, the well-named ``IUserFriendly`` adapter is made a bit smarter about how to handle missing rtypes. * the adapter also always produces a global message explaining the issue (and the fact that sometimes, the user is not shown all the relevant info) * i18n is updated Closes #2793789

=========================================
Refactoring the CSSs with UI properties
=========================================

Overview
=========

Managing styles progressively became difficult in CubicWeb. The
introduction of uiprops is an attempt to fix this problem.

The goal is to make it possible to use variables in our CSSs.

These variables are defined or computed in the uiprops.py python file
and inserted in the CSS using the Python string interpolation syntax.

A quick example, put in ``uiprops.py``::

  defaultBgColor = '#eee'

and in your css::

  body { background-color: %(defaultBgColor)s; }


The good practices are:

- define a variable in uiprops to avoid repetitions in the CSS
  (colors, borders, fonts, etc.)

- define a variable in uiprops when you need to compute values
  (compute a color palette, etc.)

The algorithm implemented in CubicWeb is the following:

- read uiprops file while walk up the chain of cube dependencies: if
  cube myblog depends on cube comment, the variables defined in myblog
  will have precedence over the ones in comment

- replace the %(varname)s in all the CSSs of all the cubes

Keep in mind that the browser will then interpret the CSSs and apply
the standard cascading mechanism.

FAQ
====

- How do I keep the old style?

  Put ``STYLESHEET = [data('cubicweb.old.css')]`` in your uiprops.py
  file and think about something else.

- What are the changes in cubicweb.css?

  Version 3.9.0 of cubicweb changed the following in the default html
  markup and css:

  ===============  ==================================
   old              new
  ===============  ==================================
   .navcol          #navColumnLeft, #navColumnRight
   #contentcol      #contentColumn
   .footer          #footer
   .logo	    #logo
   .simpleMessage   .loginMessage
   .appMsg	    (styles are removed from css)
   .searchMessage   (styles are removed from css)
  ===============  ==================================

  Introduction of the new cubicweb.reset.css based on Eric Meyer's
  reset css.

  Lots of margin, padding, etc.