egroupware/doc/README-dirs-less-css

/**
 * How EGroupware loads images and style-sheets
 *
 * @link http://www.egroupware.org
 * @license http://opensource.org/licenses/gpl-license.php GPL - GNU General Public License
 * @author Ralf Becker <rb@stylite.de>
 * @package phpgwapi
 * @version $Id$
 */

EGroupware uses following directory structure:
=============================================

Applications:
------------

$appname/
        +- inc/        directory containing PHP classes (class.$appname_$something.inc.php)
        +- lang/       directory with translations egw_*.lang
        +- js/         directory containing JavaScript
        |    +- app.js get automatically loaded by eTemplate and should extend phpgwapi/js/jsapi/app_base.js
        |
        +- setup/      information about installing (setup.inc.php, tables_(current|update).inc.php, ...
        +- templates/
                    +- default/           directory containing templates eg. eTemplate *.xet files
                    |         +- images/  directory with app specific images, used by all templates not incl. image in own directory
                    |         |        +- navbar.png  application icon shown in navigation bar
                    |         +- app.css  app specific styles automatic loaded, if template does not include own one
                    |         +- app.less (optional) source for CSS preprocessor less, from which app.css is generated
                    |
                    +- $template/           directory containing template-set specific templates
                                +- images/  template-set and app specific images, overwriting these in default, incl. navbar.png
                                +- app.css  template specific CSS file, get prefered over default/app.css NOT loaded additinal
                                +- app.less (optional) soucre for above app.css
API:
---

api/                      (basic layout as for an application)
        +- src/           directory containing PHP classes in PSR-4 autoloadable structure
        +- js/
        |    +- jsapi/    JavaScript clientside API
        |    +- jquery/   directory with jQuery, jQuery-UI and jQuery plugins
        |    +- etemplate/ eTemplate2 javascript files
        |    +- ...       other Javascript modules like ckEditor, dhtmlxtree, ...
        |
        +- setup/         information about installing (setup.inc.php, tables_(current|update).inc.php, ...
        +- templates/
                    +- default/          containing templates files for all template-sets
                              +- images/ containing images automatic found by all apps and template-sets

Old phpgwapi:
------------

phpgwapi/                 (basic layout as for an application)
        +- inc/           directory containing PHP classes (new ones should use class.egw_$something.inc.php)
        |     +- $module/ directory containing external modules
        +- js/
        |    +- ...       old Javascript modules like jscalendar, all current stuff is in api/js
        |
        +- setup/         information about installing (setup.inc.php, tables_(current|update).inc.php, ...
        +- templates/
                    +- default/          containing templates files for all template-sets
                    |         +- images/ containing images automatic found by all apps and template-sets
                    +- idots/            old idots template (new templates can use different structure, see below)
                            +- class.jdots_framework.inc.php extending egw_framework class
                            +- images/   images specific of idots template-set, overwriting the ones in default
                            +- css/      themes for idots template file (automatic detected by preferences)

New template-sets:
-----------------

$template/
         +- inc/                                    contains PHP files
         |     +- class.$template_framework.inc.php required PHP class extending egw_framework class
         |
         +- js/     Javascript files of template
         +- images/ template specific images for all apps, overwriting images in phpgwapi/templates/default/images
         +- css/    themes of template
         |     +- $template.css  required default theme of template, get automatically loaded, if no other theme specified in prefs
         |     +- $template.less (optional) source of $template.css
         +- less/   (optional) directory containing files for CSS preprocessor less included by .less files in $template/css/

Automatic image loading order:
=============================
1. Instance specific directory defined configuration
2. app's template specific directory, eg. addressbook/templates/$template/images/navbar.png
3. app's default image directory, eg. addressbook/templates/default/images
4. templates image directory, eg. phpgwapi/idots/images or for newer templates $template/images
5. API default image directory phpgwapi/templates/default/images

Images lower down in above hierarchy are NOT to be copied to more specific directories, unless they should be overwritten!

Automatic loading of CSS styles:
-------------------------------
a) theme from template, eg. phpgapi/templates/idots/css/idots.css
b) etemplate/templates/default/(app|etemplate2).css (only for eTemplate applications)
c) either:
   - apps template specific app.css eg. $appname/templates/$template/app.css or
   - apps default $appname/templates/default/app.css

CSS preprocessor less:
=====================
More information about syntax can be found under http://lesscss.org/
EGroupware requires at least version 1.4 as we use @include (require) syntax to fetch just definitions
from phpgwapi/templates/default/def_*.less.

Currently commiter is responsible to generate all CSS files depending on a changed .less file
and also to modify .less files not .css files, if a .less file exits.

One way to do so is automatic with NetBeans 7.4:
-----------------------------------------------
1. install a current node.js and npm (node package manager) follwoing this tutorial

      https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager

   a) for Mac OS X using port: port install node npm
      You need to symlink node to default location: ln -s /opt/local/bin/node /usr/bin/

   b) for Mac OS X using installer from http://nodejs.org/download/
      You need to symlink node as follows: ln -s /usr/local/bin/node /usr/bin/

   c) Ubuntu 13.10 still includes too old node version (at least for less v. 1.5.0),
      so follow above tutorial using Chris Lea's node repository

2. install lessc via npm: npm install -g less

3. Got to: NetBeans preferences >> Miscellanceous >> CSS Preprocessor and set:
   Less path: /usr/bin/lessc, /opt/local/bin/lessc or /usr/local/bin/lessc depending
   on your way of installing lessc
   Uncheck "Generate extra information (debug)"

4. Open EGroupware project configuration in NetBeans (right click on project >> properties)
   >> CSS Preprocessor
   >> LESS
   - check "Compile LESS Files on Save"
   - Watch: change default "css/" "less/" to "." "." (generate css file in same directory)
   - no compile options used currently

--> after that NetBeans compiles LESS files automatic to CSS files (you have to commit both!)