Modele de contenu

Tout est serialise via uSync sous src/Web/uSync/v17/. Les modeles C# correspondants sont generes par ModelsBuilder dans src/Web/umbraco/Models/*.generated.cs (ne pas editer). Le modele livre est volontairement minimal (gabarit) avec des exemples a adapter.

Document types (uSync/v17/ContentTypes/)

Alias	Nom	Role
homePage	Page d'accueil	Racine de site. Compose cookiesSettings, exampleSection, genericSection (+ autres compositions). Template homePage.
pageSettings	Page Settings	Composition SEO/sitemap partagee par les pages (meta description, masquage sitemap...).
notFoundPage	Page 404	Page d'erreur 404 par site (resolue par NotFoundContentFinder). Compose pageSettings.
internalServerErrorPage	Page 500	Page d'erreur 500 (cible de ErrorController). Compose pageSettings.
genericSection	Section generique	Bloc de layout (conteneur de blocs).
exampleSection	Section d'exemple	Section de demonstration (titre + elements).
exampleElement	Element d'exemple	Element de bloc de demonstration (contenu + titre).
titleBlock	Titre	Bloc titre (texte + taille via DropdownHeadingSizes).
cookiesSettings	Cookies Settings	Composition : textes/labels du popup de consentement cookies.
marketingSettings	Marketing Settings	Composition : ID Google Analytics 4.

Les example* et titleBlock sont des exemples a adapter/supprimer dans un projet aval.

DataTypes (uSync/v17/DataTypes/)

Les 46 DataTypes sont ranges dans des conteneurs (dossiers) cote backoffice via l'element <Folder> de chaque .config (les fichiers restent a plat sur le disque ; Level="2"). uSync recree les conteneurs a l'import (au demarrage, groupe Settings). Dossiers : Dropdowns, DatePickers, Pickers, Media, Uploads, Labels, ListViews, Fields, Blocks. Pour deplacer un DataType, changer son <Folder> (ou le glisser dans le backoffice, ExportOnSave re-serialise).

Bibliotheque d'editeurs preconfigures, prete a l'emploi :

• Pickers media : MediaPicker, ImageMediaPicker, MultipleMediaPicker, ImageCropper, variantes legacy.
• Pickers contenu/URL : ContentPicker, MemberPicker, SingleURLPicker, MultiURLPicker.
• Champs : Textstring, Textarea, RichtextEditor, Numeric, Decimal/DecimalPositiveOnly, Truefalse, Dropdown/DropdownMultiple, DropdownHeadingSizes, Radiobox, CheckboxList, Tags, DatePicker/DatePickerWithTime, ApprovedColor.
• BlockGrid / BlockList : CustomBlockGridsBase, CustomBlocListExampleElement.
• Labels (lecture seule) : LabelString, LabelInteger, LabelBigint, LabelDecimal, LabelDatetime, LabelTime, LabelBytes, LabelPixels.
• ListViews : ListViewContent, ListViewMedia, ListViewMembers.
• Uploads media : UploadFile, UploadArticle, UploadAudio, UploadVideo, UploadVectorGraphics.
• seo : Umbraco.TextBox configure (maxChars 20).

Property editors custom (App_Plugins/)

Editeurs de propriete maison, reutilisables pour creer des DataTypes dans le backoffice (voir aussi modules/backoffice.md) :

• ButtonPicker (App_Plugins/ButtonPicker/) - property editor UI Spektrum.PropertyEditorUi.ButtonPicker (schema Umbraco.TextBox) : un groupe de boutons single-select ou la valeur stockee est la classe CSS du bouton choisi (emise par les vues de blocs). La liste des boutons ({ label, value }), la defaultValue et l'option "boutons compacts" se configurent sur le DataType via l'editeur de config Spektrum.PropertyEditorUi.ButtonPickerConfig (repeater libelle / classe). 100 % frontend (aucun backend C#). Aucun DataType prelivre : creer un Data Type base sur "Button Picker" et y definir les boutons.

MediaTypes / MemberTypes / Templates

• MediaTypes : image, file, folder, umbracoMediaArticle, umbracoMediaAudio, umbracoMediaVideo, umbracoMediaVectorGraphics.
• MemberTypes : member (standard).
• Templates : homepage, notfoundpage, internalservererrorpage.

Langues (uSync/v17/Languages/)

• fr (French) : langue par defaut (IsDefault=true).
• en-US : marquee Change="Delete" dans uSync (en cours de suppression) - ne pas considerer comme active.
• Le backoffice est en fr-FR (DefaultUILanguage, appsettings.json).

Dictionnaire (uSync/v17/Dictionary/)

Cles d'interface multilingues, surtout pour le consentement cookies (cookies.*, cookiespopup*), le footer (footer.*), l'accessibilite (accessibility.skiptocontent, accessibility.noscript...) et des cles generiques. Le handler Dictionnaire uSync est en CreateOnly (n'ecrase pas les traductions existantes a l'import).

Libellés dynamiques de blocs - UFM, plus AngularJS

Le champ Label d'un bloc (Block List et Block Grid) affiche un résumé de l'élément dans la liste du backoffice. Il peut afficher la valeur d'une propriété du bloc.

La syntaxe a changé avec le backoffice v14. Umbraco 13 et avant utilisaient AngularJS, donc {{alias}}. Depuis la v14, le backoffice est en Lit et le champ utilise UFM (Umbraco Flavored Markdown). {{alias}} n'est plus interprété : il s'affiche littéralement dans la liste des blocs.

Symptôme : les blocs de la liste s'intitulent tous {{title}} au lieu du titre saisi. Rien ne casse par ailleurs, ce qui rend le défaut facile à laisser passer.

La syntaxe UFM

Forme générale : {<prefixe>: <contenu>}.

Usage	Syntaxe	Exemple
Valeur d'une propriété	{umbValue: alias}	{umbValue: headline}
Idem, forme courte a privilegier	{=alias}	{=title}
Clé de traduction	{umbLocalize: cle} ou {#cle}	{#general_name}
Nom du contenu pointé par un picker	{umbContentName: alias}	{umbContentName: page}
Titre du lien d'un picker de liens	{umbLink: alias}	{umbLink: ctaLink}
Expression JavaScript	${ ... }	${ title.toUpperCase() }

Filtres

Ils s'enchaînent avec | :

{umbValue: bodyText | stripHtml | wordLimit:15}
{=title | fallback:"Sans titre"}
{=name | uppercase}

Disponibles : bytes, fallback, lowercase, stripHtml, titleCase, truncate, uppercase, wordLimit.

Expressions JavaScript

${ ... } évalue une expression dans un bac à sable : accès aux propriétés, opérateurs logiques et conditionnels, arithmétique, méthodes natives.

${ title }
${ title.length > 0 ? title : "Sans titre" }
${ link[0].name }
${ navMenuTitle || (navMenuLink && navMenuLink[0] && navMenuLink[0].name) || '' }

Le dernier exemple est le patron à retenir pour les pickers de liens (MultiUrlPicker) : la valeur est un tableau, il faut donc garder chaque niveau pour ne pas casser quand le champ est vide. Le || '' final évite d'afficher undefined.

Pour ce cas précis, {umbLink: navMenuLink} fait la même chose de façon déclarative. Préférer le composant quand il existe, et réserver ${ ... } aux cas qu'il ne couvre pas (repli sur une autre propriété, condition, mise en forme).

Choisir la forme

1. {=alias} par défaut. C'est court et ça couvre la majorité des blocs.
2. {=alias | fallback:"..."} dès qu'un bloc peut exister sans que la propriété soit remplie.
3. {umbLink:} / {umbContentName:} pour les pickers.
4. ${ ... } seulement pour la logique que les trois précédents ne savent pas exprimer.

Détecter l'ancienne syntaxe

À lancer après toute reprise d'un projet v13, ou après un copier-coller depuis un ancien dépôt. Retour vide = conforme.

grep -rn '{{' src/Web/uSync/*/DataTypes/ || echo "aucun label AngularJS"

Référence

Documentation officielle : docs.umbraco.com, section Model your content -> Property editors -> Umbraco Flavored Markdown. Le champ Label du Block List y renvoie explicitement.

Icônes de blocs et de document types - toujours vérifier qu'elles existent

Chaque document type porte une icône (<Icon> dans son .config uSync). Pour un element type exposé dans une Block Grid ou une Block List, c'est l'icône que l'éditeur voit dans le sélecteur de blocs.

Une icône inventée ne casse rien de visible côté dev : la solution compile, l'import uSync passe, le site rend normalement. Le seul symptôme est une case vide dans le sélecteur de blocs du backoffice. Le défaut n'apparaît donc qu'en ouvrant l'éditeur, souvent après la livraison.

Règle : ne jamais écrire un nom d'icône de mémoire. Toujours le vérifier contre le registre Umbraco avant de créer ou de modifier un bloc.

Format

<Icon>icon-home color-black</Icon>

Le premier segment est le nom de l'icône, le second (optionnel) sa couleur (color-black, color-red, color-amber, ...). Seul le premier segment doit exister dans le registre.

Où est le registre

Le backoffice v14+ n'utilise plus un fichier SVG par icône. Les noms vivent dans un manifeste JavaScript livré par le paquet Umbraco.Cms.StaticAssets :

~/.nuget/packages/umbraco.cms.staticassets/<version>/staticwebassets/umbraco/backoffice/packages/core/icons-<hash>.js

Le hash change à chaque version d'Umbraco, donc on résout le fichier au lieu de le coder en dur. Umbraco 17.6.0 expose 713 icônes.

Vérifier une icône

# Toutes les icones disponibles, triees
M=$(find ~/.nuget/packages/umbraco.cms.staticassets/17.6.0 -name 'icons-*.js' ! -name '*.map')
LC_ALL=C grep -o 'name: "icon-[a-z0-9-]*"' "$M" | sed 's/name: "//; s/"//' | sort -u

# Chercher par mot-cle
LC_ALL=C grep -o 'name: "icon-[a-z0-9-]*"' "$M" | sed 's/name: "//; s/"//' | grep align

Valider tout le dépôt d'un coup

À lancer après avoir ajouté ou modifié des blocs. Retour vide = conforme.

M=$(find ~/.nuget/packages/umbraco.cms.staticassets/17.6.0 -name 'icons-*.js' ! -name '*.map')
LC_ALL=C grep -o 'name: "icon-[a-z0-9-]*"' "$M" | sed 's/name: "//; s/"//' | sort -u > /tmp/icons.txt

grep -rho "<Icon>[^< ]*" src/Web/uSync/ | sed 's/<Icon>//' | sort -u | while read -r i; do
  grep -qx "$i" /tmp/icons.txt || echo "INCONNUE  $i"
done

Le cas qui a motivé la règle

Un bloc richIntro a été livré dans un projet aval avec <Icon>icon-align-left</Icon>. Cette icône n'existe pas : le registre v17 nomme la famille icon-text-align-left / -center / -right / -justify. Le nom paraissait évident, il ne l'était pas. Résultat : bloc sans icône dans le sélecteur, découvert bien après coup.

Icônes usuelles pour des blocs

Vérifiées présentes en 17.6.0, à utiliser comme point de départ plutôt que d'inventer :

Usage	Icône
Bloc générique, section	icon-block, icon-item-arrangement
Texte, intro, citation	icon-font, icon-article, icon-blockquote
Alignement de texte	icon-text-align-left, icon-text-align-center
Image, galerie	icon-picture, icon-pictures-alt-2, icon-thumbnail-list
Vidéo, audio	icon-video, icon-sound-waves
Carrousel, diaporama	icon-slideshow, icon-billboard
Grille, liste	icon-grid, icon-list, icon-split
Personnes, équipe	icon-user, icon-users, icon-users-alt
Lien, bouton, partage	icon-link, icon-share
Formulaire, contact	icon-mailbox, icon-message
Carte, localisation	icon-map-location
Agenda, date	icon-calendar
Code, embed	icon-code
Navigation, réglages	icon-navigation, icon-settings

Après une montée de version d'Umbraco

Le registre change entre majeures : des icônes disparaissent, d'autres sont renommées. Rejouer la validation complète ci-dessus fait partie de la procédure de montée de version (voir ../architecture/build-deploy.md).

Ajouter / modifier un document type

Backoffice -> uSync exporte (ExportOnSave="Settings") ; les modeles se regenerent (SourceCodeAuto). Voir ../architecture/patterns.md.

Avant de valider : vérifier l'icône (section ci-dessus) et respecter les conventions de rédaction pour les libellés vus par l'éditeur (../domain/conventions-redaction.md).

Contributors

No contributors

Changelog

No recent changes