17.1 Gestion des styles

17.1.1 Description des styles

17.1.1.1 Éléments de style

Un style est composé de :

• Un fichier de description,
• un fichier css (optionnel)
• des images (optionnel)

Soit le style MONSTYLE. Les fichiers doivent être publiés sur le serveur avec cette arborescence :

• STYLE
  • MONSTYLE
    • MONSTYLE.sty
    • Layout
      • MONSTYLE.css
    • Images
      • monimage1.png
      • monimage2.png

Le fichier de style est MONSTYLE.sty, le fichier css est MONSTYLE.css.

17.1.1.2 Fichier de style

Un fichier de style .sty est un fichier php, déclarant les variables :

$sty_desc (obligatoire)

La description du style.

C'est un tableau contenant les entrées :

name (obligatoire)

Le nom du style.

description

La description du style

parsable (déprécié)

conservé pour compatibilité avec l'ancien système.

$sty_colors (obligatoire)

Les couleurs de base du style.

C'est un tableau contenant les entrées :

• A (obligatoire)
• B (obligatoire)
• C (obligatoire)

Ces variables seront utilisées pour générer les paramètres de couleur (de COLOR_A0 à COLOR_A9, de COLOR_B0 à COLOR_B9 et de COLOR_C0 à COLOR_C9).

$sty_inherit

le chemin vers un fichier de style parent.

Si défini, alors le style parent sera utilisé comme base, et ses valeurs seront les valeurs par défaut des éléments du style courant.

$sty_const

Les paramètres propres au style.

C'est un tableau contenant les entrées :

• COLOR_BLACK : couleur du noir
• COLOR_WHITE : couleur du blanc
• CORE_BGIMAGE : image de fond de page
• CORE_BGCOLOR : couleur du fond d'éléments
• CORE_TEXTFGCOLOR : couleur du texte
• CORE_TEXTBGCOLOR : couleur de texte contrasté (pour la mise en évidence)
• CORE_BGCOLORALTERN : couleur de fond secondaire
• CORE_FGCOLOR: couleur de fond utilisé pour le texte contrasté
• CORE_BGCOLORHIGH : couleur utilisée pour la mise en évidence (généralement onmouseover)
• CORE_ACOLOR: couleur de hyperliens (ancres)
• CORE_BGCELLCOLOR: couleurs des cellules de tableaux
• CORE_ERRORCOLOR : couleur des messages d'erreurs

$sty_local

Les variables à utiliser pour le parsing initial du style.

C'est un tableau. Les clés sont enregistrées comme paramètres volatiles le temps de l'initialisation du style.

$sty_rules

Les règles de style permettant la génération des fichiers css finaux.

17.1.1.3 Règles de style css

Les règles d'un style définissent comment sont produits les fichiers d'un style. Ces fichiers peuvent, par exemple, être la simple copie d'un fichier existant, la concaténation de plusieurs fichiers, la minification d'un fichier, le résultat du parsing d'un fichier, une génération complète, etc.

Les règles sont définies au moyen d'un tableau à plusieurs niveaux.

Par exemple :

array(
    'css' => array(
 
        // copie simple
        'dcp/raw/modern.css' => array(
            'src' => 'STYLE/MODERN/Layout/MODERN.css'
        ),
 
        // concaténation simple
        'dcp/raw/ext-adapter.css' => array(
            'src' => array(
                "extsystem"=>'STYLE/MODERN/Layout/EXT-ADAPTER-SYSTEM.css',
                "extuser"=>'STYLE/MODERN/Layout/EXT-ADAPTER-USER.css'
            )
        ),
 
        // concaténation avec parsing
        'dcp/parse_on_copy/ext-adapter.css' => array(
            'src' => array(
                "extsystem"=>'STYLE/MODERN/Layout/EXT-ADAPTER-SYSTEM.css',
                "extuser"=>'STYLE/MODERN/Layout/EXT-ADAPTER-USER.css'
            ),
            "deploy_parser" => array(
                "className" => '\Dcp\Style\dcpCssTemplateParser'
            )
        ),
 
        // concaténation simple - 
        // le parsing se fait à la volée lors de la requête
        'dcp/parse_on_load/ext-adapter.css' => array(
            'src' => array(
                "extsystem"=>'STYLE/MODERN/Layout/EXT-ADAPTER-SYSTEM.css',
                "extuser"=>'STYLE/MODERN/Layout/EXT-ADAPTER-USER.css'
            ),
            'flags' => Style::RULE_FLAG_PARSE_ON_RUNTIME
        ),
 
        // concaténation avec parsing - 
        // un autre parsing se fait à la volée lors de la requête
        'dcp/parse_twice/ext-adapter.css' => array(
            'src' => array(
                 "extsystem"=>'STYLE/MODERN/Layout/EXT-ADAPTER-SYSTEM.css',
                "extuser"=>'STYLE/MODERN/Layout/EXT-ADAPTER-USER.css'
            ),
            "deploy_parser" => array(
                "className" => '\Dcp\Style\dcpCssTemplateParser'
            ),
            'flags' => Style::RULE_FLAG_PARSE_ON_RUNTIME
        )
 
    )
);

• L'index de premier niveau correspond au type de fichier produit, parmi :

  • css

    Tous les fichiers produits seront placés dans le répertoire css à la racine du répertoire d'installation.

• L'index de second niveau définit le fichier à produire, au moyen de son chemin relatif à la racine pour ce type de fichier (par exemple, pour mypath/myfile.css, cela correspond à <document root>/css/mypath/myfile.css).

  Le tableau correspondant à cet index définit comment sera générée la cible. Les clés significatives de ce tableau sont :

  src

  le ou les fichier(s) source(s), définis par leur chemin relatif au documentroot ;

  flags

  un masque binaire indiquant des options de génération.

  les flags actuellement disponibles sont :

  Style::RULE_FLAG_PARSE_ON_DEPLOY

  Indique que les sources seront envoyées à un parser lors de leur déploiement

  Style::RULE_FLAG_PARSE_ON_RUNTIME

  Indique que les sources seront envoyées à un parser lors de leur téléchargement par le client

  deploy_parser

  La configuration du parser à utiliser pour le déploiement (voir les parsers).

  C'est un tableau contenant :

  • à l'index className le nom de la classe (namespaces inclus) à utiliser pour produire le fichier

    en l'absence de valeur, c'est la classe \Dcp\Style\dcpCssConcatParser qui est utilisée.

  • à l'index options un tableau d'options qui sera envoyé au parser.

  runtime_parser

  La configuration du parser à utiliser pour le déploiement (voir les parsers).

  Pour le moment, le parsing au runtime ne supporte pas de classe personnalisée.
  Si Style::RULE_FLAG_PARSE_ON_RUNTIME est positionné, le fichier sera parsé par le moteur de template de Dynacase.
  Aussi, positionner une valeur autre que null à l'index className lèvera une erreur.

  C'est un tableau contenant :

  • à l'index className le nom de la classe (namespaces inclus) à utiliser pour produire le fichier.

  • à l'index options un tableau d'options qui sera envoyé au parser.

17.1.1.3.1 Règles locales

Les règles locales sont définies dans la variable $sty_rules du fichier de définition de style.

17.1.1.3.2 Surcharge de règles pour un style

Lors de son déploiement, le style récupère également toutes les règles définies dans les fichiers contenus dans le répertoire rules.d placés à la racine du style. Ces fichiers sont chargés par ordre alphabétique, et seule leur variable $sty_rules est utilisée, afin de surcharger les règles locales.

Cela permet notamment

• de rajouter des règles à un style déjà déployé,
• d'altérer les règles d'un style déjà déployé.

17.1.1.3.3 Surcharge de règles pour plusieurs styles

3.2.19

Les styles installée par défaut sont ajoutés dans le répertoire STYLE de la racine du répertoire d'installation. Chacun des styles dispose de son propre répertoire.

./STYLE
       DEFAULT/
              DEFAULT.sty
              Images/*.png
       MODERN/
              MODERN.sty
              Images/*.png

Comme indiqué au paragraphe précédent, il est possible d'ajouter des surcharges pour des styles déjà définis.

Exemple :

./STYLE
       DEFAULT/
              DEFAULT.sty
              Images/*.png
              rules.d/
                      CUSTOM1.sty
                      CUSTOM2.sty
       MODERN/
              MODERN.sty
              Images/*.png
              rules.d/
                      CUSTOM1.sty

Afin d'éviter d'ajouter la même règle sur tous les styles existants, il faut déposer le fichier de règles dans le répertoire global-rules.d situé au dessus des répertoires des styles.

L'exemple précédent peut être redéfini avec l'arborescence suivante : La régle CUSTOM1.sty sera ajouté au style courant quel qu'il soit.

./STYLE
       DEFAULT/
              DEFAULT.sty
              Images/*.png
              rules.d/
                      CUSTOM2.sty
       MODERN/
              MODERN.sty
              Images/*.png
       global-rules.d/
              CUSTOM1.sty

Cela permet notamment :

• d'ajouter des règles à tous les styles déployés et à venir
• d'altérer les règles pour le style courant sans l'affecter directement

17.1.1.4 Parsers

Les parsers sont des classes implémentant l'interface Dcp\Style\IParser et celle correspondant au type de fichier produit (pour les css, Dcp\Style\ICssParser).

Ils implémentent donc

• un constructeur prenant en entrée le(s) fichier(s) source(s), un tableau d'options, ainsi que la configuration complète du style.
• une méthode gen prenant en paramètre le chemin du fichier à produire.

Les parsers fournis par défaut sont :

Dcp\Style\dcpCssConcatParser

un parser faisant uniquement la concaténation de css

Dcp\Style\dcpCssTemplateParser

un parser faisant la concaténation de css, puis les parsant au moyen du moteur de template de Dynacase.

Les parsers étant chargés au moyen de l'autoloader, il est parfaitement possible de définir de nouvelles classes de parser, tant qu'elles implémentent les interfaces correspondantes.

Dcp\Style\dcpCssCopyDirectory

un parser permettant de copier le contenu d'un répertoire. Ceci est utilisé notamment pour copier un ensemble d'images liées à la css.

3.2.19 Un parser less (Dcp\Style\dcpLessParser) est aussi disponible en installant le module dynacase-less-installer.

17.1.2 Créer un nouveau style à partir du style par défaut

Le module "Dynacase-core" livre 3 styles situé dans le répertoire STYLE :

• DEFAULT : Le style de référence
• MODERN : Le style installé par défaut. Il hérite de DEFAULT
• ORIGINAL : Ancien style gardé pour compatibilité. Il hérite de DEFAULT

Il est recommandé d'installer votre répertoire contenant vos règles de styles dans le répertoire STYLE afin que votre style puisse être surchargé par des règles globales.

17.1.2.1 Définition des règles par défaut

Les règles par défaut sont celles décrites dans le style DEFAULT.

17.1.2.1.1 Règles interfaces initiales

Les interfaces standards de dynacase utilisent les css suivantes :

'dcp/main.css'

Cette css est utilisée dans la plupart des interfaces documentaires de haut niveau fournies par le module dynacase-core.
Elle est utilisée pour les interfaces web de documents (consultation et modification) et pour les listes de documents.

Elle est composée des éléments suivants :

• core => "CORE/Layout/core.css",
• fdl => "FDL/Layout/freedom.css",
• size => "WHAT/Layout/size-normal.css",
• style => "STYLE/DEFAULT/Layout/DEFAULT.css"

dcp/core.css

Cette css est utilisée par défaut sur les interfaces si le template utilisé possède la clef [CSS:REF].
Elle est utilisée sur les interfaces de core d'importation et de gestion des droits.

Elle est composée des éléments suivants :

• core => "CORE/Layout/core.css",
• size => "WHAT/Layout/size-normal.css",
• style => "STYLE/DEFAULT/Layout/DEFAULT.css"

'dcp/document-view.css'

Cette css est utilisée sur les vues standards de consultation des documents. La vue de consultation utilise aussi la css dcp/main.css.

Elle est composée des éléments suivants :

• document => "FDL/Layout/document.css"

dcp/document-edit.css

Cette css est utilisée sur les vues standards de modification des documents

Elle est composée des éléments suivants :

• edit => "FDL/Layout/editdoc.css",
• autocompletion => "FDL/Layout/autocompletion.css",
• popup => "FDL/Layout/popup.css",
• document => "FDL/Layout/document.css",
• jscalendar => "jscalendar/Layout/calendar-win2k-2.css"

dcp/system.css

Cette css est utilisée par défaut sur les interfaces si le template utilisé possède la clef [CSS:REF]. Elle est utilisée sur les anciennes interfaces de core.

Elle est composée des éléments suivants :

• size => "WHAT/Layout/size-normal.css",
• style => "STYLE/DEFAULT/Layout/DEFAULT.css"

Toutes ces règles utilisent le parser dcpCssTemplateParse.

17.1.2.1.2 Règles interfaces jquery-ui

Le module dynacase-jqueryui-installer ajoute aussi deux autres règles au style DEFAULT :

dcp/jquery-ui.css

Cette css est utilisée dans les interfaces utilisant jquery-ui sauf dans l'interface GENERIC_LIST (liste de documents de ONEFAM) qui utilise une autre version de jquery-ui.

Elle est composée des éléments suivants :

• jqueryui => "lib/jquery-ui/css/smoothness/jquery-ui.css"

Cette règle n'utilise pas de parser.

dcp/images

Cette règles permet de copier les images utiles à jquery-ui Elle utilise les images suivantes :

• jqueryimages => "lib/jquery-ui/css/smoothness/images"

Cette règle utilise le parser dcpCssCopyDirectory

17.1.2.1.3 Description du fichier css

Le fichier css de style est utilisable dans les règles.

En l'absence de parser, ce fichier doit être autonome.

Il doit être composé uniquement de règles css valides.

Les url d'accès aux images doivent être définies par rapport à la cible (par exemple, si la cible est mypath/mycss.css le fichier produit sera placé dans le répertoire css/mypath/mycss.css).

Si le parser employé est dcpCssTemplateParser alors les variables définies dans $sty_const et $sty_local seront utilisables.

Voici un exemple de production de css avec le fichier de style suivant :

$sty_const = array(
    "COLOR_BLACK" => "#000000",
    "COLOR_WHITE" => "#FFFFFF"
);
// style color variable to compute colors
// COLOR_A0 -> COLOR_A9
// COLOR_B0 -> COLOR_B9
// COLOR_C0 -> COLOR_C9
$sty_colors = array(
    "A" => '#4D4D4D', // gray
    "B" => '#126ab5',  //blue
    "C" => "#cbc11f"// gold
); 
// local variable for compose style css
$sty_local = array(
    "input-text-normal-color" => "COLOR_BLACK",
    "input-text-hover-color" => "yellow",

De plus les 10 nuances de couleurs COLOR_A, COLOR_B et COLOR_C peuvent aussi être utilisées.

Pour un fichier css comme décrit ci-dessous :

input : {
    color: [input-text-normal-color];
    background-color: [COLOR_WHITE];
}
input:hover : {
    color: [input-text-hover-color];
    background-color: [COLOR_C5];
}

Le fichier css produit sera :

input : {
    color: #000000;
    background-color: #ffffff;
}
input:hover : {
    color: yellow;
    background-color: #EDE787;
}

17.1.2.1.4 Fichier css avec flag RULE_FLAG_PARSE_ON_RUNTIME

Si la règle utilise le flag Style::RULE_FLAG_PARSE_ON_RUNTIME alors la css peut aussi utiliser les variables suivantes :

• "ISIE" : vrai si le navigateur est Internet Explorer
• "ISIE6", vrai si le navigateur est une version 6 d'Internet Explorer
• "ISIE7", vrai si le navigateur est une version 7 d'Internet Explorer
• "ISIE8", vrai si le navigateur est une version 8 d'Internet Explorer
• "ISIE9", vrai si le navigateur est une version 9 d'Internet Explorer
• "ISIE10",vrai si le navigateur est une version 10 d'Internet Explorer
• "ISAPPLEWEBKIT": vrai si le navigateur est basé sur Apple Web Kit (Chrome et Safari entre autre)
• "ISSAFARI" : vrai si le navigateur est basé sur Safari
• "ISCHROME" : vrai si le navigateur est basé sur Google Chrome

Ces variables sont basées sur le User-Agent envoyé par le navigateur.

Le fichier css peut avoir des parties conditionnelles :

input : {
    color: [input-text-normal-color];
    background-color: [COLOR_WHITE];
    [IF ISIE]padding:10px;[ENDIF ISIE]
    [IFNOT ISCHROME]margin:10px;[ENDIF ISCHROME]
}

Les règles suivantes :

• dcp/main.css,
• dcp/core.css,
• dcp/document-edit.css,
• dcp/system.css,

utilisent le flag RULE_FLAG_PARSE_ON_RUNTIME.

17.1.2.2 Surcharge de DEFAULT

17.1.2.2.1 Définir son fichier de style avec héritage

Pour surcharger le style DEFAULT il faut dans le fichier de style .sty l'héritage :

MONSTYLE.sty

$sty_inherit = "STYLE/DEFAULT/DEFAULT.sty";

Ensuite il faut créer son fichier MONSTYLE.css qui doit être dans le répertoire STYLE/MONSTYLE/Layout.

Les règles de surcharge de style sont :

$sty_rules = array(
    'css' => array(
        'dcp/main.css' => array(
            "src" => array(
                "style" => "STYLE/MONSTYLE/Layout/MONSTYLE.css"
            )
        ) ,
        'dcp/core.css' => array(
            "src" => array(
                "style" => "STYLE/MONSTYLE/Layout/MONSTYLE.css"
            )
        ) ,
        'dcp/document-edit.css' => array(
            "src" => array(
                "jscalendar" => "STYLE/MONSTYLE/Layout/calendar.css"
            )
        ) ,
        'dcp/system.css' => array(
            "src" => array(
                "style" => "STYLE/MONSTYLE/Layout/MONSTYLE.css"
            )
        )
    )
);

L'exemple remplace le fichier DEFAULT.css par MONSTYLE.css en réutilisant l'index style des sources. Il remplace aussi la css du calendrier utilisé dans la modification de documents.

Il est aussi possible d'ajouter et non de remplacer des éléments de css :

$sty_desc = array(
    "name" => "SKYBLUE", //Name
    "description" => N_("Blue Style") , //long description 
);
 
$sty_inherit = "STYLE/MODERN/MODERN.sty";
 
$sty_rules = array(
    'css' => array(
        'dcp/jquery-ui.css' => array(
            "src" => array(
                "blue"=>"STYLE/SKYBLUE/Layout/jquery-blue.css"
            )
        ) ,
        'dcp/main.css' => array(
            "src" => array(
                "blue"=>"STYLE/SKYBLUE/Layout/main-blue.css"
            )
        )
    )
);

Cette exemple reprend le style MODERN (fourni par dynacase-core) qui hérite lui-même de DEFAULT. Dans ce dernier exemple la règle dcp/jquery-ui.css sera composée de :

• jqueryui => "lib/jquery-ui/css/smoothness/jquery-ui.css"
• blue=>"STYLE/SKYBLUE/Layout/jquery-blue.css"

17.1.3 Créer un nouveau style sans héritage

Pour créer un style sans héritage il est nécessaire de déclarer l'ensemble des règles nécessaires aux différentes interfaces :

• dcp/core.css
• dcp/document-edit.css
• dcp/document-view.css
• dcp/jquery-ui.css
• dcp/main.css
• dcp/system.css

17.1.4 Surcharger les templates

Au delà des css, le style peut aussi surcharger les templates des interfaces des actions de Dynacase. Les templates doivent se trouver dans le répertoire Layout du style.

Par exemple, l'interface de connexion utilise l'action AUTHENT:LOGINFORM.

Cette action utilise le template AUTHENT/Layout/loginform.xml. Si le style MONSTYLE publie le fichier STYLE/MONSTYLE/Layout/loginform.xml alors l'action AUTHENT:LOGINFORM utilisera le template du style pour l'interface de connexion si le style MONSTYLE est installé.

17.1.5 Surcharger les images

De même, les images peuvent être surchargées. Pour cela il faut publier des images de même nom dans le répertoire Images du style.

Par exemple la famille Groupe d'utilisateurs utilise l'image igroup.png comme icone. Si le style MONSTYLE publie l'image STYLE/MONSTYLE/Images/igroup.png, alors l'icone de la famille sera changée.

La surcharge d'image ne fonctionne que si les templates ont utilisé la balise [IMG] ou la méthode Action::getImageUrl().

Attention : Le cache du navigateur peut conserver les anciennes images.

17.1.6 Installer un style

Une fois l'arborescence de fichiers installée sur le serveur, il faut utiliser la commande setStyle depuis la console.

$ ./wsh.php --api=setStyle --style=./STYLE/MONSTYLE/MONSTYLE.sty

Cette commande permet d'appliquer les règles définies dans le style. Les fichiers css sont alors produits dans le répertoire css à la racine du répertoire d'installation.

L'option --verbose=yes permet de voir quelles sont les règles prises en compte.

Si le paramètre style n'est pas indiqué, alors la commande setStyle va régénérer les fichiers composants le style courant.