4.9.1 Options communes de représentation d'attribut

Les options de représentation indiquées dans la structure de la famille ne sont pas prises en compte dans les interfaces HTML5.

4.9.1.1 showEmptyContent

Cette option indique le texte à afficher dans le cas où la valeur de l'attribut est vide.

Dcp\Ui\CommonRenderOptions showEmptyContent(string $htmlText)

4.9.1.1.1 Restrictions

• Utilisable uniquement pour les rendus de consultation

4.9.1.1.2 Paramètres

L'argument en entrée est un fragment html affiché à la place de la valeur de l'attribut lorsque sa valeur est vide.

4.9.1.1.3 Cas particuliers

Aucun

4.9.1.1.4 Exemples

use Dcp\AttributeIdentifiers\My_contact;
class MyCustomRender extends \Dcp\Ui\DefaultView
{
    public function getOptions(\Doc $document)
    {
        $options = parent::getOptions($document);
 
        $options->commonOption()->showEmptyContent("Non communiqué");
        $options->commonOption(My_contact::zct_civility)
            ->showEmptyContent("Non communiquée");
        $options->commonOption(My_contact::zct_phone)
            ->showEmptyContent('<b class="my-nophone">Pas de téléphone</b>');
        $options->image(My_contact::zct_photo)
            ->showEmptyContent('<img src="MY/Images/my_nophoto.png"/>');
 
        return $options;
    }

4.9.1.2 setLink

Cette option ajoute un hyperlien sur la valeur de l'attribut si celui-ci est affiché.

Dcp\Ui\CommonRenderOptions setLink(Dcp\ui\htmlLinkOptions $linkOption)

4.9.1.2.1 Restrictions

• Utilisable uniquement pour les rendus de consultation
• Non applicable aux attributs de type array, frame, htmltext et tab

4.9.1.2.2 Paramètres

L'argument en entrée est un objet de type Dcp\Ui\htmlLinkOptions qui configure les différents paramètres du lien :

target

Nom de la fenêtre du navigateur vers laquelle le lien sera envoyé. * Si la valeur est _self (valeur par défaut), la fenêtre courante est utilisée. * Si la valeur est _dialog, une fenêtre de dialogue interne sera utilisée.

title

Message du tooltip du lien visible lorsque le pointeur de la souris est sur le lien. Ce titre est un fragment HTML et les variables de valeur d'attribut ({{value}} et {{displayValue}}) peuvent être utilisées.
Les parties variables du titre ne sont pas actualisées en cas de modification de la valeur.

url

Url d'accès à la page. L'url est composée lors du rendu de l'attribut et les variables de valeur d'attribut ({{value}} et {{displayValue}}) peuvent être utilisées. Ces valeurs sont encodées (au moyen de la fonction encodeUriComponent).
Les parties variables de l'url ne sont pas actualisées en cas de modification de la valeur.

urls

Tableau d'url d'accès à la page pour les attributs inclus dans un tableau.
Si l'url à l'index (0 étant la première rangée) de la rangée du tableau est présent, la valeur donnée par le tableau "urls" est utilisé à la place de l'url standard.

Si target est différente de _self les options suivantes sont prises en compte :

windowHeight

Hauteur de la fenêtre de dialogue. Si target est égal à _dialog, la dimension doit être une dimension css valable (c'est à dire un nombre suivi immédiatement de son unité). Sinon la dimension est un nombre entier exprimé en pixels.

windowWidth

Largeur de la fenêtre de dialogue. Si target est égal à _dialog, la dimension doit être une dimension css valable (c'est à dire un nombre suivi immédiatement de son unité). Sinon la dimension est un nombre entier exprimé en pixels.

windowTitle (seulement si target est égal à _dialog)

Titre de la fenêtre de dialogue. Si cet argument est vide, alors le titre de la page ciblée est utilisée si son accès est autorisé (même domaine). Le titre est composé dynamiquement et les variables définissant la valeur de l'attribut peuvent être utilisées ({{value}} et {{displayValue}} pour tous les types d'attribut).

De plus, lorsque windowHeight ou windowWidth est défini et que target est différent de _self et _dialog, la fenêtre ouverte ne possède ni menus ni barre d'adresse.

Dans le rendus de consultation par défaut ( Dcp\Ui\DefaultView), les liens sont affectés en fonction de la colonne link défini dans la définition de l'attribut.

4.9.1.2.3 Cas particuliers

Pour les attributs "multiple" (type docid, account et enum), les variables de valeurs d'attribut sont des tableaux. Ils doivent être adressés en Mustache par des répétables.

Exemple :

`<b>Voici les valeurs : <ul>{{#.}}<li>{{displayValue}}</li>{{/.}}</ul></b>`

Pour les attributs dans les tableaux, les variables {{value}} et {{displayValue}} sont remplacés par la valeur de l'attribut à la rangée (index) donnée.

Il possible d'utiliser des url différentes par index. Dans ce cas, il faut renseigner la variable "urls" afin de donner des urls spécifiques par rangée.

4.9.1.2.4 Exemples

Sur l'attribut "my_text", ajout d'un lien vers "http://www.example.net".

$linkOption = new \Dcp\ui\htmlLinkOptions();
$linkOption->target = "_dialog";
$linkOption->title = "Go to My page";
$linkOption->windowHeight = "300px";
$linkOption->windowWidth = "500px";
$linkOption->windowTitle = "Mon test {{value}} {{displayValue}}";
$linkOption->url = "http://www.example.net";
$options->text("my_text")->setLink($linkOption);

Sur les images affichage d'une plus grande miniature et affichage de l'image en taille "200px" dans une boite de "200px".

$linkOption = new \Dcp\ui\htmlLinkOptions();
$linkOption->target = "_dialog";
$linkOption->title = ' <h3><img src="{{thumbnail}}&size=100"/>{{displayValue}}</h3>';
$linkOption->url = "{{{url}}}&size=200";
$linkOption->windowHeight = "200px";
$linkOption->windowWidth = "200px";
$options->image()->setLink($linkOption);

Modifier le titre (tooltip) du lien de la relation "myRelation" :

/**
 * @var $link \Dcp\Ui\HtmlLinkOptions
 */
$link = $options->docid(myAttributes::myRelation)->getOption(\Dcp\Ui\CommonRenderOptions::htmlLinkOption);
if ($link) {
    $link->title = "Voir le document de <br/><b>\"{{displayValue}}\"<b>";
}

4.9.1.2.5 Css setLink

La couleur du tooltip généré par l'argument title  est surchargeable à l'aide des règles css suivantes :

Exemple : tooltip écrit en noir sur fond vert pour tous les attributs du cadre "my_frame"

.dcpFrame__content[data-attrid=my_frame]  .tooltip.dcpAttribute__linkvalue .tooltip-inner {
    background-color:  #f7f942; /* Green */
    color: #000000;
}
.dcpFrame__content[data-attrid=my_frame] .tooltip.dcpAttribute__linkvalue.tooltip.top .tooltip-arrow {
    border-top-color:  #f7f942;
}
.dcpFrame__content[data-attrid=my_frame] .tooltip.dcpAttribute__linkvalue.tooltip.bottom .tooltip-arrow {
    border-bottom-color:  #f7f942;
}

Exemple : tooltip écrit en noir sur fond rose pour l'attribut' "my_mail"

.dcpAttribute[data-attrid=my_mail]  .tooltip.dcpAttribute__linkvalue .tooltip-inner {
    background-color: #f99adf; /* Pink */
    color: #000000;
}
.dcpAttribute[data-attrid=my_mail] .tooltip.dcpAttribute__linkvalue.tooltip.top .tooltip-arrow {
    border-top-color:  #f99adf;
}
.dcpAttribute[data-attrid=my_mail] .tooltip.dcpAttribute__linkvalue.tooltip.bottom .tooltip-arrow {
    border-bottom-color:  #f99adf;
}

4.9.1.3 setLabelPosition

Cette option indique le placement du label par rapport à la valeur de l'attribut.

Dcp\Ui\CommonRenderOptions setLabelPosition(string $position)

4.9.1.3.1 Restrictions

• Non applicable aux attributs de type tab.
• Applicable de manière partielle aux attributs de type frame.

4.9.1.3.2 Paramètres

L'argument en entrée peut prendre les valeurs suivantes :

Dcp\Ui\CommonRenderOptions::autoPosition (valeur par défaut)

Le libellé est positionné à gauche de la valeur si la limite de largeur de page ("480px") n'est pas atteinte. Si la limite de largeur de page est atteinte le libellé est positionné au dessus de la valeur. La limite peut être modifiée lors de la définition d'un style personnalisé. Cette limite est indiquée dans la variable less (@grid-float-breakpoint)

Dcp\Ui\CommonRenderOptions::leftPosition

Le libellé est positionné systématiquement à gauche de sa valeur quelle que soit la largeur de la fenêtre. La largeur du libellé correspond à 2/12^ème de la largeur disponible.

Dcp\Ui\CommonRenderOptions::upPosition

Le libellé est positionné systématiquement au dessus de la valeur. La valeur et le libellé occupent chacun toute la largeur du document.

Dcp\Ui\CommonRenderOptions::nonePosition

Le libellé n'est pas visible. La valeur occupe toute la largeur du document.

Ces différentes positions sont définies comme des constantes de la classe Dcp\Ui\CommonRenderOptions.

4.9.1.3.3 Cas particuliers

Pour les cadres (type frame) :

• la valeur Dcp\Ui\CommonRenderOptions::autoPosition est équivalente à la valeur Dcp\Ui\CommonRenderOptions::upPosition.

• la valeur Dcp\Ui\CommonRenderOptions::leftPosition, n'est pas applicable.

• la valeur Dcp\Ui\CommonRenderOptions::nonePosition efface le libellé (header du cadre).

Pour les tableaux (type array) :

• pour la valeur "Dcp\Ui\CommonRenderOptions::autoPosition", la limite de largeur de page n'est pas la même que pour les attributs "normaux".
  Cette limite est par défaut à 1280px afin de représenter le tableau dans des conditions optimales. Elle peut être modifiée avec la méthode setResponsiveBreakpoints.

4.9.1.3.4 Exemples

$options->text("my_attribute")->labelPosition(Dcp\Ui\CommonRenderOptions::leftPosition);

4.9.1.4 setAttributeLabel

Cette option permet de modifier le texte d'un libellé d'attribut.

Dcp\Ui\CommonRenderOptions setAttributeLabel(string $label)

4.9.1.4.1 Restrictions

Aucune

4.9.1.4.2 Paramètres

L'argument $label est un texte brut (et non un fragment HTML) qui sera utilisé comme label de l'attribut.

4.9.1.4.3 Cas particuliers

Aucun

4.9.1.4.4 Exemples

$options->text("my_attribute")->setAttributeLabel("Mon nouveau texte");

4.9.1.5 setDescription

Cette option permet d'afficher une description détaillée pour un attribut.

Dcp\Ui\CommonRenderOptions setDescription(
                                        string $htmlTitle,
                                        string $position = Dcp\Ui\CommonRenderOptions::topPosition,
                                        string $htmlContent = "",
                                        bool   $collapsed = false)

4.9.1.5.1 Restrictions

Aucune

4.9.1.5.2 Paramètres

$htmlTitle

Description courte de l'attribut. Ce texte est en HTML, il convient au développeur d'échapper les éventuelles variables.

$position

Position du texte à afficher. La position du texte dépend aussi du type d'attribut. L'ensemble de ces positions ne sont pas reconnues pour tous les types d'attributs.

$htmlContent

Description longue de l'attribut. Ce texte est en HTML, il convient au développeur d'échapper les éventuelles variables. Ce texte est affiché en dessous du texte du titre. Il est escamotable via un bouton. Un ascenseur est affiché si la longueur de ce texte dépasse la limite. Cette limite ("10em" par défaut) est configurable par css.

$collapsed

Présentation de la description longue lors de l'affichage du document. Par défaut, cette description est affichée. Si le paramètre vaut true alors la description est escamotée. L'utilisateur doit alors cliquer sur le bouton présent sur le titre pour l'afficher.

4.9.1.5.3 Position de la description des attribut non structurant (hors tableau)

Attribut contenant une valeur : type "text", "int", "date", etc. Ne concerne pas ces attributs s'ils sont définis dans un tableau.

• Dcp\Ui\CommonRenderOptions::topPosition : Texte affiché au dessus du contenu de l'attribut (libellé et valeur)

  

  Figure 4. Placement "top"

• Dcp\Ui\CommonRenderOptions::bottomPosition :Texte affiché au dessous du contenu de l'attribut (libellé et valeur)

  

  Figure 5. Placement "top"

• Dcp\Ui\CommonRenderOptions::leftPosition : Texte affiché à gauche du contenu de l'attribut

  

  Figure 6. Placement "left"

• Dcp\Ui\CommonRenderOptions::rightPosition : Texte affiché à droite du contenu de l'attribut

  

  Figure 7. Placement "right"

• Dcp\Ui\CommonRenderOptions::topLabelPosition : Texte affiché au dessus du libellé de l'attribut

  

  Figure 8. Placement "topLabel"

• Dcp\Ui\CommonRenderOptions::topValuePosition : Texte affiché au dessus de la valeur de l'attribut

  

  Figure 9. Placement "topValue"

• Dcp\Ui\CommonRenderOptions::bottomLabelPosition : Texte affiché au dessous du libellé de l'attribut

  

  Figure 10. Placement "bottomLabel"

• Dcp\Ui\CommonRenderOptions::bottomValuePosition : Texte affiché au dessous de la valeur de l'attribut

  

  Figure 11. Placement "bottomValue"

• Dcp\Ui\CommonRenderOptions::clickPosition : Affiche une ancre  à gauche du libellé. Cette ancre affiche la description lorsque l'utilisateur clique dessus.

Figure 12. Placement "click"

4.9.1.5.4 Cas particuliers

Le positionnement dans les tableaux est propre à ce type. Voir la position dans les tableaux.

Le positionnement dans les cadres est propre à ce type. Voir la position dans les cadres.

Le positionnement dans les onglets est propre à ce type. Voir la position dans les onglets.

4.9.1.5.5 Variables utilisables dans les textes de descriptions.

Les variables suivantes sont utilisables comme variable "Mustache" dans la description courte ou la description longue.

• id : identifiant de l'attribut
• label : label de l'attribut (localisé)
• needed : (bool) Indique si l'attribut est obligatoire
• visibility: visibilité de l'attribut(W,R,H, ...)
• type: type de l'attribut (text, date, int, ...)
• attributeValue.value : valeur brute de l'attribut au moment du rendu (la description n'est pas mise à jour lors de la modification de l'attribut)
• attributeValue.displayValue : valeur affichée de l'attribut au moment du rendu
• renderOptions.description : définition de la description
  • collapsed : (bool) Valeur du paramètre $collapsed
  • htmlContent: Valeur du paramètre $htmlContent
  • htmlTitle: Valeur du paramètre $htmlTitle
  • position: Valeur du paramètre $position

4.9.1.5.6 Règles css applicables aux descriptions

Les descriptions sont identifiables grâce à la classe dcpAttribute__description.

La description d'un attribut donné peut être repéré en indiquant l'attribut HTML data-attrid sur la règle.

.dcpAttribute__description[data-attrid="tst_ban_etablissement"] {
    ...
}

Modifier la couleur de fond pour toutes les descriptions :

.dcpAttribute__description  {
    background-color:#F4FFBA;
}
/* Flèche vers la droite */
.dcpAttribute__description--left::after {
    border-left-color:#F4FFBA;
}
/* Flèche vers la gauche */
.dcpAttribute__description--right::after {
    border-right-color:#F4FFBA;
}
/* Flèche vers le bas */
.dcpAttribute__description--topLabel::after,
.dcpAttribute__description--topValue::after,
.dcpAttribute__description--top::after {
    border-top-color:#F4FFBA;
}
/* Flèche vers le haut */
.dcpAttribute__description--bottomLabel::after,
.dcpAttribute__description--bottomValue::after,
.dcpAttribute__description--bottom::after {
    border-bottom-color:#F4FFBA;
}

Modifier la couleur de la bordure pour toutes les descriptions :

.dcpAttribute__description {
    border-color:#BFAF00;
}
/* Flèche vers la droite */
.dcpAttribute__description--left::before {
    border-left-color:#BFAF00;
}
/* Flèche vers la gauche */
.dcpAttribute__description--right::before {
    border-right-color:#BFAF00;
}
/* Flèche vers le bas */
.dcpAttribute__description--topLabel::before,
.dcpAttribute__description--topValue::before,
.dcpAttribute__description--top::before {
    border-top-color:#BFAF00;
}
/* Flèche vers le haut */
.dcpAttribute__description--bottomLabel::before,
.dcpAttribute__description--bottomValue::before,
.dcpAttribute__description--bottom::before {
    border-bottom-color:#BFAF00;
}

Supprimer la flèche pour la description de l'attribut "tst_ban_etablissement" :

.dcpAttribute__description[data-attrid="tst_ban_etablissement"]::after,
.dcpAttribute__description[data-attrid="tst_ban_etablissement"]::before {
    display:none;
}

Modifier la hauteur maximale de la description longue :

.dcpAttribute__description__content {
    max-height: 10em; /* hauteur maximale à indiquer */
}

4.9.1.5.7 Exemples

Affichage de descriptions dans diverses positions :

$displayPosition='<b style="float:right;color:orange;border:solid 1px orange;margin-left:2px">{{renderOptions.description.position}}</b>';
 
$options->text(myAttribute::tst_ban_agence)->setDescription(
    $displayPosition."<p>Nom et localisation de l'agence bancaire</p>",
    \Dcp\Ui\CommonRenderOptions::leftPosition);
 
$options->text(myAttribute::tst_ban_etablissement)->setDescription(
    $displayPosition."<p>L'identifiant domestique du compte : code banque<p><b> (5 chiffres)</b>",
    \Dcp\Ui\CommonRenderOptions::topValuePosition);
 
$options->text(myAttribute::tst_ban_guichet)->setDescription(
    $displayPosition."<p>Le code guichet de la banque<p><b> (5 chiffres)</b>",
    \Dcp\Ui\CommonRenderOptions::topLabelPosition);
 
$options->text(myAttribute::tst_ban_numcompte)->setDescription(
    $displayPosition."<p>Numéro du compte bancaire<p><b> (11 chiffres ou lettres)</b>",
    \Dcp\Ui\CommonRenderOptions::bottomValuePosition);
 
$options->text(myAttribute::tst_ban_clecompte)->setDescription(
    $displayPosition."<p>Clé du relevé d'identité bancaire<p><b> (2 chiffres)</b>",
    \Dcp\Ui\CommonRenderOptions::rightPosition);
 
$options->text(myAttribute::tst_ban_iban)->setDescription(
    $displayPosition."<p>Le code IBAN <i>(International Bank Account Number)</i> représenté par une série de <b>27</b> chiffres et de lettres</p>",
    \Dcp\Ui\CommonRenderOptions::topPosition, "<p>Reprenant notamment (mais regroupés différemment) le code banque, le code guichet et le numéro de compte</p>",
    true);
 
$options->text(myAttribute::tst_ban_bic)->setDescription(
    $displayPosition."<p>Le code BIC <i>(Business Identifier Code)</i> représenté par une série de <b>11 ou 8</b> lettres .</p>",
    \Dcp\Ui\CommonRenderOptions::bottomPosition);

Figure 13. Différentes options de placement de la description

Ajout d'information complémentaire au libellé. Dans cet exemple, le libellé n'est pas affiché (utilisation de setLabelPosition - nonePosition) mais il est utilisé dans la description qui est affiché au dessus de chaque attribut.

$originalLabel='<p><b>{{label}}</b></p>';
 
$options->text(myAttribute::tst_ban_agence)->setDescription(
    $originalLabel."<p>Nom et localisation de l'agence bancaire</p>",
    \Dcp\Ui\CommonRenderOptions::topPosition)
    ->setLabelPosition(\Dcp\Ui\CommonRenderOptions::nonePosition);
 
$options->text(myAttribute::tst_ban_etablissement)->setDescription(
    $originalLabel."<p>L'identifiant domestique du compte : code banque <b> (5 chiffres)</b><p>",
    \Dcp\Ui\CommonRenderOptions::topPosition)
    ->setLabelPosition(\Dcp\Ui\CommonRenderOptions::nonePosition);
 
$options->text(myAttribute::tst_ban_guichet)->setDescription(
    $originalLabel."<p>Le code guichet de la banque<b> (5 chiffres)</b><p>",
    \Dcp\Ui\CommonRenderOptions::topPosition)
    ->setLabelPosition(\Dcp\Ui\CommonRenderOptions::nonePosition);
 
$options->text(myAttribute::tst_ban_numcompte)->setDescription(
    $originalLabel."<p>Numéro du compte bancaire<b> (11 chiffres ou lettres)</b><p>",
    \Dcp\Ui\CommonRenderOptions::topPosition)
    ->setLabelPosition(\Dcp\Ui\CommonRenderOptions::nonePosition);
 
$options->text(myAttribute::tst_ban_clecompte)->setDescription(
    $originalLabel."<p>Clé du relevé d'identité bancaire <b> (2 chiffres)</b></p>",
    \Dcp\Ui\CommonRenderOptions::topPosition)
    ->setLabelPosition(\Dcp\Ui\CommonRenderOptions::nonePosition);
 
$options->text(myAttribute::tst_ban_iban)->setDescription(
    $originalLabel."<p>Le code IBAN <i>(International Bank Account Number)</i> représenté par une série de <b>27</b> chiffres et de lettres</p>",
    \Dcp\Ui\CommonRenderOptions::topPosition, "<p>Reprenant notamment (mais regroupés différemment) le code banque, le code guichet et le numéro de compte</p>",
    true)->setLabelPosition(\Dcp\Ui\CommonRenderOptions::nonePosition);
 
$options->text(myAttribute::tst_ban_bic)->setDescription(
    $originalLabel."<p>Le code BIC <i>(Business Identifier Code)</i> représenté par une série de <b>11 ou 8</b> lettres .</p>",
    \Dcp\Ui\CommonRenderOptions::topPosition)
    ->setLabelPosition(\Dcp\Ui\CommonRenderOptions::nonePosition);

Figure 14. Libellé enrichi avec la description

Le même exemple avec de la css pour personnaliser l'aspect :

/* Positionnement 2 colonnes pour les attributs du cadre tst_f_dombancaire */
.dcpFrame__content[data-attrid="tst_f_dombancaire"] .dcpAttribute {
    float: left;
    display: inline-block;
    min-height: 34px;
    width: calc(50% - 1em);
    margin-left: 0.5em;
    margin-right: 0.5em;
}
 
/* Colorisation des descriptions d'attributs */
.dcpAttribute__description[data-attrid="tst_ban_agence"] {
    background-color: rgba(0, 128, 50, 0.2);
    border-color: #02bf54;
    background: linear-gradient(to right, #c9de96 0%,#8ab66b 44%, #47bc43 100%);
}
 
.dcpAttribute__description[data-attrid="tst_ban_etablissement"],
.dcpAttribute__description[data-attrid="tst_ban_guichet"],
.dcpAttribute__description[data-attrid="tst_ban_numcompte"],
.dcpAttribute__description[data-attrid="tst_ban_clecompte"] {
    background-color: rgba(15, 61, 128, 0.2);
    border-color: #0062bf;
    background: linear-gradient(to right, #e4f5fc 0%,#bfe8f9 34%,#2ab0ed 71%,#9fd8ef 100%);
}
.dcpAttribute__description[data-attrid="tst_ban_iban"],
.dcpAttribute__description[data-attrid="tst_ban_bic"] {
    background-color: rgba(128, 63, 13, 0.2);
    border-color: #bf7410;
    background: linear-gradient(to right, #fceabb 0%,#fccd4d 37%,#f8b500 70%,#fbdf93 100%);
}
 
/* Alignement des descriptions pour le mode 2 colonnes */
.dcpFrame[data-attrid="tst_f_dombancaire"] .dcpAttribute__description {
    min-height:6em;
}
/* Suppression de la flêche pour les description du cadre tst_f_dombancaire */
.dcpFrame[data-attrid="tst_f_dombancaire"] .dcpAttribute__description::after,
.dcpFrame[data-attrid="tst_f_dombancaire"] .dcpAttribute__description::before  {
    display:none;
}

Figure 15. Libellé enrichi avec css

4.9.1.6 setLinkHelp

Cette option permet d'associer un document d'aide avec un attribut.

Dcp\Ui\CommonRenderOptions setLinkHelp(string|int $documentIdentifier)

Un document d'aide est un document de la famille HELPPAGE. Ce document permet de fournir des descriptions statiques sur les attributs. À la différence de l'option setDescription, cette option va afficher un lien (indiqué par l'icone ) vers un document d'aide complet lié à la famille et non une description contextuelle.

Ce lien va afficher le document d'aide dans une fenêtre de dialogue en pointant vers le paragraphe lié à l'attribut.

Dans le rendu d'édition par défaut (classe Dcp\Ui\DefaultEdit), tous les attributs définis dans le document d'aide associé à la famille ont cette option.

Dans les rendus de consultation (classe Dcp\Ui\DefaultView) et d'édition par défaut un menu " Aide" est ajouté. Ce menu ouvre le document d'aide dans une fenêtre de dialogue.

Dans ces 2 classes de rendu, le document d'aide est fourni par la méthode :

protected function getDefaultHelpPageDocument(\Doc $document)

Cette méthode retourne le document de la famille HELPPAGE qui est associé avec la famille du document. Elle ne recherche pas une aide parmi les familles parentes si le document d'aide liés exactement à la famille n'existe pas. S'il y a plusieurs documents d'aide c'est le premier, ordonné par titre, qui est retourné.

Cette méthode peut être surchargée, dans la classe de rendu, pour utiliser un autre document d'aide ou pour simplement ne pas afficher l'aide par défaut.

4.9.1.6.1 Restrictions

Aucunes.

4.9.1.6.2 Paramètres

L'argument $documentIdentifier indique l'identifiant du document d'aide à ouvrir. Cet identifiant doit indiquer un document de la famille "HELP".

La méthode retourne une exception si l'identifiant ne correspond pas à un document de la famille HELPPAGE.

4.9.1.6.3 Cas particuliers

Aucun

4.9.1.6.4 Exemples

Lier l'attribut "my_attribute" avec le document d'aide qui a le nom logique "MY_SPECIAL_HELP".

$options->text("my_attribute")->setLinkHelp("MY_SPECIAL_HELP");

Utilisation du dernier document d'aide créé.

namespace My;
class MyViewRender extends \Dcp\Ui\DefaultView {
    protected function getDefaultHelpPageDocument(\Doc $document) {
        $s = new \SearchDoc("", "HELPPAGE");
        // Filtre sur les aides liés à la famille du document
        $s->addFilter("help_family='%d'", $document->fromid);
        $s->setOrder("id desc"); // L'id indique l'ordre de création
        $s->setSlice(1);
        $s->setObjectReturn();
        $helps = $s->search();
        if (count($helps) > 0) {
            return $helps->getNextDoc();
        }
        return null;
    }
}

4.9.1.7 displayDeleteButton

Cette option indique si le bouton de suppression doit être affiché ou non.

Dcp\Ui\CommonRenderOptions displayDeleteButton(bool $display)

4.9.1.7.1 Restrictions

• Utilisable uniquement pour les rendus de modification ou de création.
• Non applicable aux attributs de type array, frame et tab.

4.9.1.7.2 Paramètres

L'argument $display indique si le bouton de suppression doit être affiché. Le bouton de suppression est affiché par défaut.

4.9.1.7.3 Cas particuliers

Aucun

4.9.1.7.4 Exemples

$options->text("my_attribute")->displayDeleteButton(false);

4.9.1.8 setInputTooltip

Cette option indique un texte à afficher lorsque le champ de l'attribut à saisir a le focus. Le tooltip n'est pas affiché au survol (hover), mais lorsque le champ de saisie obtient le focus.

Dcp\Ui\CommonRenderOptions setInputTooltip(string $htmlText)

4.9.1.8.1 Restrictions

• Utilisable uniquement pour les rendus de modification ou de création.
• Non applicable aux attributs de type array, frame et tab.

4.9.1.8.2 Paramètres

L'argument htmlText est un fragment HTML qui sera utilisé pour le texte du tooltip.

4.9.1.8.3 Cas particuliers

Aucun

4.9.1.8.4 Exemples

4.9.1.8.5 Css setInputTooltip

La couleur de ce tooltip est surchargeable à l'aide des règles css suivantes :

Exemple tooltip écrit en noir sur fond jaune pour le cadre "my_frame"

.dcpFrame__content[data-attrid=my_frame]  .tooltip.dcpAttribute__editlabel .tooltip-inner {
    background-color:  #f7f942; /* Yellow */
    color: #000000;
}
.dcpFrame__content[data-attrid=my_frame] .tooltip.dcpAttribute__editlabel.tooltip.top .tooltip-arrow {
    border-top-color:  #f7f942;
}
.dcpFrame__content[data-attrid=my_frame] .tooltip.dcpAttribute__editlabel.tooltip.bottom .tooltip-arrow {
    border-bottom-color:  #f7f942;
}

4.9.1.9 setAutoCompleteHtmlLabel

Cette option permet d'afficher un tooltip lorsque la souris passe au dessus du bouton de déclenchement de l'aide à la saisie. Par défaut aucun tooltip n'est affiché.

Dcp\Ui\CommonRenderOptions setAutoCompleteHtmlLabel(string $htmlText)

4.9.1.9.1 Restrictions

• Utilisable uniquement pour les rendus de modification ou de création.
• Applicable uniquement aux attributs qui ont une aide à la saisie.

4.9.1.9.2 Paramètres

L'argument htmlText est un fragment HTML qui sera utilisé pour le texte du tooltip.

4.9.1.9.3 Cas particuliers

Aucun

4.9.1.9.4 Exemples

$options->text(My_family::my_workpostalcode)
{{Hello>setAutoCompleteHtmlLabel("Choisissez un code postal du <b>Gers</b>");

4.9.1.9.5 Css setAutoCompleteHtmlLabel

La couleur de ce tooltip est surchargeable à l'aide des règles css suivantes :

Exemple tooltip écrit en noir sur fond jaune pour le cadre "my_frame"

.dcpFrame__content[data-attrid=my_frame]  .tooltip.dcpAttribute__autocomplete .tooltip-inner {
    background-color:  #f7f942; /* Yellow */
    color: #000000;
}
.dcpFrame__content[data-attrid=my_frame] .tooltip.dcpAttribute__autocomplete.tooltip.top .tooltip-arrow {
    border-top-color:  #f7f942;
}
.dcpFrame__content[data-attrid=my_frame] .tooltip.dcpAttribute__autocomplete.tooltip.bottom .tooltip-arrow {
    border-bottom-color:  #f7f942;
}

4.9.1.10 addButton

Cette option ajoute un bouton à droite de la valeur.

En mode édition il est placé à gauche du bouton de suppression.

En mode consultation, il est placé à l'extrémité droite de la valeur.

Dcp\Ui\CommonRenderOptions addButton(Dcp\Ui\ButtonOptions $buttonOptions)

4.9.1.10.1 Restrictions

• Non applicable aux attributs de type array, frame et tab.

4.9.1.10.2 Paramètres

L'argument en entrée est un objet de type Dcp\Ui\ButtonOptions qui configure les différents paramètres du bouton.

target

Nom de la fenêtre du navigateur vers laquelle le lien sera envoyé. Si le nom est _dialog , une fenêtre de dialogue interne sera utilisée. Dans ce cas, les options suivantes sont prises en compte : windowHeight : Hauteur de la fenêtre de dialogue La dimension doit être une dimension css valable (c'est à dire un nombre suivi immédiatement de son unité). windowWidth : Largeur de la fenêtre de dialogue La dimension doit être une dimension css valable (c'est à dire un nombre suivi immédiatement de son unité). windowTitle : Titre de la fenêtre de dialogue. Si cet argument est vide alors le titre de la page ciblée est utilisé si son accès est autorisé (même domaine). Le titre est composé dynamiquement et les variables {{value}} et {{displayValue}} peuvent être utilisées.

title

Texte HTML du tooltip du bouton visible lorsque le pointeur de la souris est sur le lien. Ce texte est un fragment HTML et les variables de valeur d'attribut ({{value}} et {{displayValue}}) peuvent être utilisées.

url

Url d'accès à la page. L'url est composée dynamiquement et les variables de valeur d'attribut ({{value}} et {{displayValue}}) peuvent être utilisées. Ces valeurs sont encodées (au moyen de la fonction encodeUriComponent).

htmlContent

Texte du bouton (fragment HTML de contenu phrasé). Ce texte est un fragment HTML et les variables de valeur d'attribut ({{value}} et {{displayValue}}) peuvent être utilisées.

class

Classe css supplémentaire à mettre sur le bouton afin de personnaliser le bouton par css ou l'identifier par javascript.

4.9.1.10.3 Cas particuliers

Pour les attributs "multiple" (type docid, account et enum), les variables de valeurs d'attribut sont des tableaux. Ils doivent être adressés en Mustache par des répétables.

Exemple :

`<b>Voici les valeurs : <ul>{{#.}}<li>{{displayValue}}</li>{{/.}}</ul></b>`

4.9.1.10.4 Exemples

$buttonConfig = new ButtonOptions();
$buttonConfig->url = "?app=MYAPP&action=MY_SENDRESPONSE&myto={{value}}";
$buttonConfig->title = "Send a mail to response";
$buttonConfig->class = "myClass";
$buttonConfig->target = "_dialog";
$buttonConfig->htmlContent = "<b>Send it</b>";
$options->text("my_mail")->addButton($buttonConfig);

Afficher un bouton sur une relation pour avoir un aperçu du document.

$viewDoc=new \Dcp\Ui\ButtonOptions();
$viewDoc->htmlContent='<i class="fa fa-eye"></i>';
$viewDoc->url=sprintf("api/v1/documents/{{value}}.html" );
$viewDoc->target="_dialog";
$viewDoc->windowWidth="400px";
$options->docid("my_relation")->addButton($viewDoc);

4.9.1.11 setTemplate

Permet de définir le template à utiliser pour afficher la valeur de l'attribut.

Ce template ne s'applique qu'à la valeur et pas au label. Le label peut être effacé si nécessaire avec l'option de rendu setLabelPosition.

Dcp\Ui\CommonRenderOptions setTemplate(string $htmlText
                                        array $extraKeys = array()) )

4.9.1.11.1 Restrictions

En consultation, le template n'est pas appliqué si la valeur est vide. Dans ce cas, c'est l'option showEmptyContent qui est appliquée.

4.9.1.11.2 Exception

Si un des templates ajoutés n'existe pas alors l'exception suivante est déclenchée à l'exécution :

UI0004 = 'Render template file not found : %s'

4.9.1.11.3 Paramètres

L'argument $htmlText est un template Mustache.

L'argument $extraKeys est un tableau de clés additionnelles.

4.9.1.11.4 Déclaration d'un modèle

Exemple :

$options->frame("my_frame")->setTemplate('<div class="my">{{{attributes.my_firstattr.htmlContent}}}</div>');
 
$options->text("my_text")->setLabelPosition("none");
$options->text("my_text")->setTemplate(
    '<div class="my">{{attributes.my_text.label}}/{{attributes.my_text.id}}'.
                   ' {{attributes.my_text.attributeValue.value}}</div>');
 
// récupération du modèle dans un fichier (chemin relatif au répertoire d'installation)
$options->text("my_info")->setTemplate(file_get_contents("MYAPP/Templates/myInfo.mustache"));

Applicable à tous les types, y compris "array", même si ce dernier offre d'autres possibilités dans la déclaration d'un template spécifique comme cela est décrit dans les chapitres suivants.

La visibilité est applicable au contenu donc à l'ensemble du template d'attribut.

4.9.1.11.5 Clefs applicables au template

Le template est un template Mustache.

Pour les attributs multiples, la valeur de attribute.attributeValue ou attributes.<attrid>.attributeValue est un tableau de valeur.

Exemple pour ajouter une <div> autour d'un attribut :

$options->account(MyFamily::my_text)->setTemplate(
'<div style="outline:solid 1px red;padding:5px;">
        {{{attribute.htmlDefaultView}}}
  </div>');

On notera dans cet exemple, l'utilisation de htmlDefaultView et non htmlView afin d'indiquer explicitement qu'on utilise pas notre propre template personnalisé.

Exemple de modèle pour un attribut de type account multiple

$options->account(MyFamily::my_account_multiple)->setTemplate(
    '<div style="border:solid 1px grey;padding:5px;">
            <ol>
                 {{#attribute.attributeValue}}
                 <li><img src="{{icon}}"> {{displayValue}}</li>
                  {{/attribute.attributeValue}}
            </ol>
      </div>');

Si l'attribut a modifier est dans un tableau alors les clefs en attributes.<attrid>.* sont restreintes au seul attrid de l'attribut courant. Il n'est donc pas possible dans ce cas de représenter un autre attribut que l'attribut courant.

4.9.1.11.6 Modèle de tableau

Les clefs supplémentaires suivantes sont disponibles pour les tableaux.

Le template de tableau doit contenir une balise table avec la classe dcpArray__table pour indiquer le container qui sera utilisé pour représenter l'attribut.

Les classes de styles et les attributs nécessaires au fonctionnement du widget de tableau seront ajoutés au modèle pour disposer d'un comportement et d'un aspect similaire au tableau original.

Exemple de modèle de tableau :

<table class="dcpArray__table">
    <thead>
        <tr>
            <th class="special">Identification</th>
            <th>Deuxième et troisième cellules</th>
        </tr>
    </thead>
    <tbody>
    {{#attribute.rows}}
        <tr>
            <td>
                <b>{{content.my_firstcell.label}}</b>
                <br/>
                {{{content.my_firstcell.htmlContent}}}
            </td>
            <td>
                {{{content.my_secondcell.htmlContent}}}
                <br/>
                {{{content.my_thirdcell.htmlContent}}}
            </td>
        </tr>
    {{/attribute.rows}}
    </tbody>
</table>

Si le modèle de tableau n'est pas une balise table, il est nécessaire de préciser la classe dcpArray__content__line dans l'élement qui sera considéré comme la rangée (tr).

Exemple de modèle de tableau contenant un attribut image (my_photo) et un attribut relation (my_species) avec des balises div :

<div class="dcpArray__table">
      {{#attribute.rows}}
       <div class="dcpArray__content__line">
            {{#content.my_photo.attributeValue.value}}
               <img class="my__photo" src="api/v1/documents/{{properties.id}}/images/my_photo/{{index}}/sizes/60x60c.png" />
            {{/content.my_photo.attributeValue.value}}
            {{^content.my_photo.attributeValue.value}}
               <img class="my__nophoto" src="api/v1/images/assets/sizes/60x60c/zoo_nophoto.png" />
            {{/content.my_photo.attributeValue.value}}
            <div>{{{content.my_species.htmlContent}}} </div>
        </div>
    {{/attribute.rows}}
</div>

4.9.1.11.7 Complément pour la modification de tableau

En mode "modification", le modèle général de tableau n'affiche pas les boutons pour supprimer, sélectionner et ajouter des lignes.

Pour placer ces éléments d'interface il faut les insérer explicitement dans le modèle.

<table class="dcpArray__table">
    <thead>
        <tr>
            {{#attribute.toolsEnabled}}<th>Outils</th>{{/attribute.toolsEnabled}}
            <th class="special">
                Identification
            </th>
            <th>
                Deuxième et troisième cellules
            </th>
        </tr>
    </thead>
    <tbody>
    {{#attribute.rows}}
        <tr>
            {{#attribute.toolsEnabled}}<td>{{{rowTools}}}</td>{{/attribute.toolsEnabled}}
            <td>
                <b>{{content.my_firstcell.label}}</b>
                <br/>
                {{content.my_firstcell.htmlContent}}
            </td>
            <td>
                {{content.my_secondcell.htmlContent}}
                <br/>
                {{content.my_thirdcell.htmlContent}}
            </td>
        </tr>
    {{/attribute.rows}}
    </tbody>
</table>
<div>
    {{{attribute.tableTools}}}
</div>

 : Pour avoir un même modèle de tableau en consultation et en modification, il est possible d'afficher les boutons suivant la variable {{attribute.toolsEnabled}}.

Les modèles de tableau pour les formulaires doivent être basés sur des tableaux (balise table) HTML.

4.9.1.11.8 Modèle d'attribut contenu dans un tableau

Les attributs qui sont dans un tableau disposent des mêmes possibilités que les modèles classiques. La différence se situe au niveau de la clef {{attribute.attributeValue}}. Cette clef retourne la valeur de l'attribut en fonction de la rangée du tableau et non un tableau de valeurs.

Note : Pour les attributs "multiple" dans un tableau, la valeur est un tableau qui contient la liste de valeurs de l'attribut pour la rangée.

4.9.1.11.9 Ajouter des clefs de modification

En plus des clefs prédéfinies des clefs supplémentaires peuvent être fournies pour le modèle.

$options->docid(MyFamily::my_relation)->setTemplate(
    "<div style=\"border:inset 3px orange\">{{{Hello}}}<h1>{{attribute.id}}</h1> {{{attribute.htmlContent}}}</div>",
        array("Hello"=>"<h1>World</h1>")
);

Ces clefs sont des variables Mustache, elles peuvent aussi être utilisées dans un itérateur (valeur de type array) ou pour une condition.

$options->docid()->setTemplate("<div>{{{Hello}}}<ol>{{#NumberList}}<li>{{Number}}</li>{{/NumberList}}</ol>
                                    <h1>{{attribute.id}} / {{attribute.label}}</h1>
                                    {{{attribute.htmlContent}}}</div>",
        array("Hello"=>"<h1>World</h1>",
             "NumberList"=>array(array("Number"=>"One"),
                                 array("Number"=>"Two"),
                                 array("Number"=>"Three")))
        );

Pour ajouter des clefs dans les rangées d'un tableau, il faut utiliser "attributes.rows".

Exemple d'utilisation des clefs pour renseigner la composition de la dernière colonne d'un tableau.

$options->arrayAttribute("zoo_array_dates")->setTemplate('
         <table class="dcpArray__table"" rules="all" style="border:solid 3px orange; ">
            <thead>
                <tr>
                    <th class="special dcpArray__head__cell">
                        Identification : {{attributes.zoo_date_array.label}}
                    </th>
                    {{#attribute.isWriteMode}}
                        <th class="dcpArray__head__cell">
                            Tools
                        </th>
                    {{/attribute.isWriteMode}}
                    <th class="dcpArray__head__cell">
                        Deuxième et troisième cellules
                    </th>
                    <th class="dcpArray__head__cell">
                        Extra custom {{customTitle}}
                    </th>
                </tr>
            </thead>
            <tbody>
            {{#attribute.rows}}
                <tr>
                    <td>
                        <b>{{content.zoo_date_array.label}}</b>
                        <br/>
                        {{{content.zoo_date_array.htmlContent}}}
                    </td>
                    {{#attribute.isWriteMode}}
                        <td>
                            {{{rowTools}}}
                            <br/>
                            THE TOOLS IN THE MIDDLE
                        </td>
                    {{/attribute.isWriteMode}}
                    <td>
                        {{{content.zoo_time_array.htmlContent}}}
                        <br/>
                        {{{content.zoo_timestamp_array.htmlContent}}}
                    </td>
                    <td>
                        {{custom.foo}}/{{custom.bar}}/{{customTitle}}
                    </td>
                </tr>
            {{/attribute.rows}}
            </tbody>
        </table>
        <div style="border:solid 2px green; font-size:200%">
            The table tools
            {{#attribute.isWriteMode}}
                {{{attribute.tableTools}}}
            {{/attribute.isWriteMode}}
        </div>
     ', array(
        "customTitle" => "Titre personnalisé",
        "attribute" => array(
            "rows" => array(
                "custom" => array(
                    array(
                        "foo" => "One",
                        "bar" => "Uno"
                    ) ,
                    array(
                        "foo" => "Two",
                        "bar" => "Duo"
                    ) ,
                    array(
                        "foo" => "Three",
                        "bar" => "Trio"
                    ) ,
                )
            )
        )
    ));

4.9.1.12 setTranslations

Configuration des différents textes utilisés dans les interfaces des attributs. Ces textes sont par défaut configurés et sont modifiés suivant la locale de l'utilisateur connecté.

Dcp\Ui\CommonRenderOptions setTranslations(array $labels)

4.9.1.12.1 Restrictions

Les textes à traduire sont fonction des types d'attributs.

Les labels suivants sont communs à tous les types :

• deleteLabel: Tooltip affiché sur le bouton de suppression de valeur
• closeErrorMessage: Tooltip de fermeture du message d'erreur d'attribut

Suivant les types d'autres textes peuvent être traduits :

• type int
• type file

4.9.1.12.2 Paramètres

L'argument $labels est un tableau php contenant chacun des labels défini par sa clé.

4.9.1.12.3 Cas particuliers

4.9.1.12.4 Exemples

$options->commonOption("my_attribute")->setTranslations(
    array(
        "closeErrorMessage"=>___("Close error message","my"),
        "deleteLabel"=>___("Remove attribute value","my")
    )
);

4.9.1.13 setCustomWidgetAttributeFunction

Modification du widget utilisé pour rendre l'attribut

Dcp\Ui\CommonRenderOptions setCustomWidgetAttributeFunction(string $widgetFunctionName)

4.9.1.13.1 Restrictions

Le nom du widget doit être le nom d'un widget héritant de $.dcp.dcpAttribut qui est ajouté dans le contexte d'exécution du document avant le rendu du widget.

4.9.1.13.2 Paramètres

L'argument $widgetFunctionName est un nom de widget jquery ui héritant de $.dcp.dcpAttribut.

4.9.1.13.3 Cas particuliers

Aucun.

4.9.1.13.4 Exemples

Cet exemple associe le widget myCustomAttribute à l'attribut my_attribute.

Déclaration de l'option dans le options de rendu :

/**
 * L'attribut `my_attribute` utilisera le widget `myCustomAttribute`.
 */
public function getOptions(\Doc $document)
{
    $options = parent::getOptions($document);
    $options->text("my_attribute")->setCustomWidgetAttributeFunction("myCustomAttribute");
 
    return $options;
} 
/**
 * Ajout du fichier JS contenant le code du nouveau widget
 */
public function getJsReferences(\Doc $document = null)
{
    $js = parent::getJsReferences();
    $js["myWidget"] = "MY/Layout/myWidget.js";
    return $js;
}

Fichier "myWidget.js" de définition d'un nouveau widget d'attribut.

$.widget("myproject.myCustomAttribute",$.dcp.dcpAttribute, {
 
    /**
     * Init the dom of the attribute
     * @private
     */
    _initDom: function ()
    {
        this._super();
 
        if(this.getMode() === "write"){
            //Add code for write representation of the attribute
        }
        else{
            //Add code for consult representation of the attribute
        }
    },
 
    /**
     * Init the event of the attribute
     * @private
     */
    _initEvent: function () {
        //Add the custom event of the attribute
        this._super();
    },
 
    /**
     * Modify value to widget and send notification to the view
     * @param value
     */
    setValue: function wDcpViewTreeSetValue(objValue) {
        this._super(objValue);
        //Add code for the modification of the value of the attribute
    },
 
    /**
     * Return the value stored in the wiget
     *
     * @returns {*|number|.options.attributeValue}
     */
    getValue: function wDcpViewTreeGetValue() {
        let value = this._super();
        //Add code for the consultation of the value of the attribute
        return value;
    },
 
    getType: function wDcpViewTreegetType() {
        //return the type of the attribute
        return "myAttribute";
    }
});

Autre exemple :

$options->htmltext()->setCustomWidgetAttributeFunction("dcpText");

Dans ce cas, tous les attributs de type htmltext sont rendus comme des attributs de type text. Le résultat est que la valeur brute (texte avec les balises html) apparaitra à la place du texte formaté.