Modifier le fichier

Documentation K-Sup version master

Bienvenue sur le site de documentation du produit K-Sup pour la version master. Vous pouvez consulter les autres versions ici :

• Documentation de la version 6.7

Ce site présente l'ensemble de la documentation. Vous y trouverez :

• La documentation fonctionnelle
• La documentation technique
• Guide de développement sur le produit
• Licence : Les informations liées à la licence du produit
• Guide de contribution au produit
• Guide de contribution à la documentation

Cette documentation est vivante. Si jamais vous constatez un manque ou une erreur, il faut :

• Soit modifier directement la documentation (cf le guide de contribution)
• Soit créer un ticket doctech

Modifier le fichier

Documentation fonctionnelle

L'organisation de la documentation fonctionnelle reproduit l'organisation de la cartograhie des composants du produit K-Sup (cf cartographie sur Confluence).
La documentation est ainsi organisée en 3 catégories :

• Les composants Socle : Composant bas-niveau du produit K-Sup
• Les contenus : Les différentes fiches composant le CMS
• Les modules : Les composants métiers n'étant pas des fiches

Cartographie des composants

Les composants sont classés en 4 criticité : bloquants, critiques, majeurs, simples

Composants Bloquants

• Actualité
• Carte
• Connecteur CAS
• Connecteur LDAP
• Cycle de vie d'une fiche (B)
• Datagrid
• Editeur de contenus (toolbox)
• Eléments de contribution : multiselect ...
• Formation
• Formulaires
• Groupes
• Import / Export XML
• Inscription
• Liste dynamique
• Page d'accueil
• Recherche fulltext
• Recherche SQL
• Restriction d'accès
• RGPD
• Rubriques
• Scripts automatisés
• Sites
• Statistiques
• Urls
• Utilisateur

Composants Critiques

• Annuaire
• Article
• Cartographie
• Comparaison de fiches
• Document
• E-privacy
• Elément pédagogique
• Libellés
• Liste manuelle
• Mediathèque
• Multilingue
• Newsletter
• Page libre
• Panier
• Parcours
• Référencement (SEO)
• Rôles
• Sécurité
• Structure
• Structures (arbre)
• Workflow de validation d'une fiche

Composant Majeurs

• Accueil module d'administration
• Agenda
• Aperçu
• Cours
• Création de compte
• Encadrés
• Espaces collaboratifs
• HAL
• Laboratoire
• Lien
• Profils
• Services externes
• Supervision

Composants Simples

• Ancien étudiant
• API
• Arbre
• Association étudiante
• Billet de blog
• Blog
• CDM-fr
• Commentaire
• Connecteur PHP
• Construction de parcours
• Etudiant
• Gestionnaire d'extensions
• Indexation sites externes
• Lieu
• Offre stage / emploi
• Petite annonce
• Rebonds entre fiches
• Social
• Taglink

Modifier le fichier

Module de statistiques

Présentation

Le module Statistiques a pour objet de publier des indicateurs afin d'aider au pilotage du produit et des applications déployées. Ces indicateurs transversaux aux différentes fonctionnalités de l'application, permettront de vérifier si un composant est utilisé et comment il l'est. Les données générées par ce module ont pour vocation d'être intégrées dans un système tiers afin de les exploiter (compilation dans le temps, génération de graphiques ...). Ces données doivent être le plus générique possible et ne pas contenir de données personnelles ou trop précises (on mesure qu'un tag est utilisé, pas ce qu'il contient).

Fonctionnalités

Plusieurs indicateurs sont générés :

• North Star
• Indicateur d'usage
  • Indicateur de volume : Indicateur statique généré par des requêtes réalisées en base de données (Combien de fiche formations en ligne au mois de mars ?)
  • Indicateur d'action : Indicateur généré par l'écoute en temps réel de certaines méthodes de l'applicatif (Combien d'action de création de fiche formation au mois de mars)
• Indicateur de performance

Ces données seront extraites dans des fichiers présents par défaut dans le répertoire statistics du storage :

• Les indicateurs d'usage et North Star sont extraits mensuellement par un traitement planifié dans un fichier horodaté au format jsonl (json ligne à ligne https://jsonlines.org/).
• L'indicateur de performance est écrit dans un fichier de log (fichier avec rotation)

Cohorte d'utilisateurs

Certains indicateurs indiquent une cohorte d'utilisateurs dans le message généré. Cette cohorte permet d'identifier la typologie d'utilisateur utilisant le produit. Pluisuers cohortes sont identifiées par défaut de la produit :

• anonyme : Utilisateur non connecté navigant sur l'application.
  • Nom du profil : ANONYMOUS
• utilisateur connecté : Utilisateur connecté mais n'ayant aucune permission sur l'application.
  • Nom du profil : CONNECTEDUSER
• contributeur de contenu : Utilisateur ayant des droits sur des fiches (hors fiches de l'extension offre de formation).
  • Nom du profil : CONTENTMANAGER
• webmaster : Utilisateur avec la permission Webmaster.
  • Nom du profil : WEBMASTER
• contributeur de site: Utilisateur avec la permission Edition de rubrique (création, modification ou suppression).
  • Nom du profil : SITEMANAGER
• contributeur de formation : Utilisateur avec la permission de modification sur la fiche formation.
  • Nom du profil : PROGRAMMMANAGER
• contributeur : Utilisateur avec des permissions sur l'application (sans autorisation sur les fiches).
  • Nom du profil : CONTRIBUTOR

Cette liste de cohortes est extensible et il est possible d'en ajouter pour des extensions ou un besoin spécifique à un projet.

North Star

Indicateur de type action rendant compte de l'utilisation globale du produit. Cet indicateur mesure le taux de rafraîchissement des données visibles d'une application. Cela mesure donc :

• Le passage en ligne d'une fiche
• La modification d'une fiche en ligne
• Le dépublication d'une fiche en ligne

Cet indicateur est disponible par type de fiche et cohorte d'utilisateurs.

Indicateurs d'usage

Chaque composant du produit K-Sup va publier des indicateurs afin de suivre son utilisation. La description de chacun des indicateurs est disponible dans la documentation propre à chaque composant.

Le marqueur HTTP

Présentation

Cet indicateur permet de journaliser tout ou partie des appels HTTP.

Il est composé d'un filtre HTTP qui recueille des informations techniques sur l'exécution de la requête HTTP.

Les informations collectées sont :

1. le temps total passé pour la génération de la page
2. le temps total passé pour l'exécution des requêtes SQL
3. le nombre de requêtes SQL exécutées
4. le temps de la requête SQL la plus longue

Deux marqueurs différents sont implémentés à partir de ce marqueur HTTP.

Le marqueur HTTP de performance

Marqueur technique permettant de signaler les requêtes anormalement longues de l'application. L'écriture dans le journal de statistiques est déclenchée lorsque deux critères sont respectés :

1. la requête fait partie des requêtes à auditer
2. le temps total de la requête HTTP dépasse un seuil de déclenchement

• Le seuil de déclenchement est porté par la propriété statistics.http.duration.threshold (cf core-statistics.properties). La valeur -1 permet de désactiver le seuil
• Le filtrage des requêtes est réalisé par un ensemble de filtre (cf com/kosmos/statistics/marker/http/requestfilter) permettant de ne traiter que les URLs des contenus (pages et médias).
  • Un filtre d'exclusion de type "l'URI commence par".
    Par défaut, le filtre refuse les URL commençant par "/static/,/jsp/styles/,/jsp/images/,/jsp/scripts/"
    La propriété statistics.performance.exclude.uri.start.with permet de surcharger le comportement par défaut.
  • Un filtre d'exclusion de type "l'URI NE finit PAS par".
    Par défaut, le filtre refuse les URL finissant par ".js,.css.map,.css,.ttf,.woff,.json,.png"
    La propriété statistics.performance.exclude.uri.end.with permet de surcharger le comportement par défaut.

Les filtres par défaut sont définis dans le fichier core-statistics-http.xml.

Le marqueur HTTP d'usage

Marqueur fonctionnel permettant de tracer certaines URL de l'application. L'écriture dans la table des évènements est déclenchée si l'URL courante correspond à certains motifs prédéfinis:

• Le filtrage des requêtes est réalisé par un ensemble de filtre (cf com/kosmos/statistics/marker/http/requestfilter) permettant de ne traiter que les URLs des contenus (pages et médias). Les différents filtres sont spécifiques à chaque indicateur.

Les différentes extensions peuvent pousser leurs propres filtres à l'aide d'un bean "ListToAddBean"

Accueil BO

Bandeau alerte

Modifier le fichier

Module Groupes

Modifier le fichier

Statistiques du composant Groupes

Statistique d'usage

Indicateur de type compteurs

Modifier le fichier

Module Liste dynamique

Modifier le fichier

Statistique du composant Liste dynamique

Statistique d'usage

Indicateur de type compteurs

Modifier le fichier

Module Médiathèque

Le module Médiathèque permet de gérer les médias insérés dans les sites K-Sup.

Fonctionnalités

• Recherche par URL

Modifier le fichier

Recherche par URL

La recherche par URL permet de rechercher n'importe quel média inséré dans un site à partir de son URL et de consulter les utilisations de ce média au sein de K-Sup.

L'écran de recherche comporte un unique champ URL du média dans lequel l'utilisateur doit saisir l'URL du média qu'il souhaite rechercher (URL interne ou externe).

Une fois l'URL saisie, l'utilisateur doit cliquer sur le bouton Rechercher pour lancer la recherche.

Si le média est trouvé, l'utilisateur est redirigé vers une page affichant les résultats de la recherche.

Cette page affiche la vignette du média et son titre (l'URL du média si le titre n'est pas renseigné). Un bouton Voir les utilisations permet d'afficher la liste des références du média.

La liste des références du média est affichée sous forme de tableau.

Chaque ligne du tableau correspond à une référence du média.

Un lien Modifier permet d'accéder à la page d'édition de la référence. Si la référence est une fiche et que celle ci est en ligne, un lien Voir en ligne permet d'accéder à la page de consultation de la fiche.

Modifier le fichier

Module Profils

Modifier le fichier

Statistiques du composant Profils

Statistique d'usage

Indicateur de type compteurs

Modifier le fichier

Module Rubriques

Modifier le fichier

Statistiques du composant Rubriques

Statistique d'usage

Indicateur de type compteurs

Modifier le fichier

Module Scripts automatisés

Modifier le fichier

Statistiques du composant Scripts automatisés

Statistique d'usage

Indicateur de type compteurs

Indicateurs d'actions

Chaque script exécuté sera tracé avec le profil utilisateur renseigné. Le nombre de scripts exécutés manuellement devra être déterminé en compilant toutes les lignes de cette indicateur et en excluant les lignes avec le profil BATCH.

Modifier le fichier

Module Services externes

Modifier le fichier

Statistiques du composant Services externes

Statistique d'usage

Indicateur de type compteurs

Modifier le fichier

Module Utilisateurs

Modifier le fichier

Statistique du composant Utilisateurs

Statistique d'usage

Indicateur de type compteurs

Modifier le fichier

Module Agenda

Modifier le fichier

Statistique du composant agenda

Ce fichier présente les statistiques du composant agenda (cf ).

Indication d'installation / d'utilisation

North Star

Statistique d'usage

Indicateur de type compteurs

Indicateurs d'actions

Modifier le fichier

Extension Arbre

Modifier le fichier

Statistique de l'extension Arbre

Ce fichier présente les statistiques de l'extension Arbre

Indication d'installation / d'utilisation

Statistique d'usage

Indicateur de type compteurs

Modifier le fichier

Extension CatalogueLien

Modifier le fichier

Statistique de l'extension CatalogueLien

Ce fichier présente les statistiques de l'extension CatalogueLien

Indication d'installation / d'utilisation

North Star

Statistique d'usage

Indicateur de type compteurs

Modifier le fichier

Composant Espaces collaboratifs

Modifier le fichier

Statistique du composant Espaces collaboratifs

Ce fichier présente les statistiques du composant espaces collaboratifs (cf ).

Indication d'installation / d'utilisation

North Star

Statistique d'usage

Indicateur de type compteurs

Modifier le fichier

Extension FicheLink - Rebonds

Modifier le fichier

Statistique de l'extension FicheLink

Ce fichier présente les statistiques de l'extension FicheLink

Indication d'installation / d'utilisation

Statistique d'usage

Indicateur de type compteurs

Indicateurs d'actions

Modifier le fichier

Extension Formulaire

Modifier le fichier

Statistique de l'extension Formulaire

Ce fichier présente les statistiques de l'extension Formulaire.

Indication d'installation / d'utilisation

Statistique d'usage

Indicateur de type compteurs

Modifier le fichier

Module Import / Export XML

Modifier le fichier

Statistique de l'extension Import / Export XML

Ce fichier présente les statistiques de l'extension Import / Export XML (Gestion électronique des Documents).

Indication d'installation / d'utilisation

Statistique d'usage

Indicateurs d'actions

Modifier le fichier

Extension OFIN

Modifier le fichier

Statistique de l'extension OFIN

Ce fichier présente les statistiques de l'extension OFIN.

Indication d'installation / d'utilisation

Modifier le fichier

Module Supervision

Modifier le fichier

Statistique du composant supervision

Ce fichier présente les statistiques du composant supervision (cf ).

Indication d'installation / d'utilisation

Statistique d'usage

Indicateurs d'actions

Evolution du nombre d'accès à chaque sous menu :

Modifier le fichier

Import des évènements

Afin de faciliter la création des évènements en masse, une fonctionnalité d'import est disponible. La fonctionnalité est disponible depuis la page de liste des évènements, en cliquant sur le bouton "Import"

Importer un fichier

Le fichier à importer est un fichier ZIP composé de deux fichiers csv, un pour les évènements et un pour les créneaux. Les deux fichiers de données sont des fichiers CSV, avec séparateur ",".

Le fichier des évènements

Le fichier est composé de 21 colonnes, avec une ligne d'entête. Si une donnée contient des sauts de ligne ou des virgules, il est nécessaire d'encadrer la valeur par des guillemets. ex:

valeur 1,"Valeur 2,
avec un saut de ligne",valeur3

Si la donnée contient des guillemets, la valeur doit être encadrée par des guillements et les guillements de texte doublés.

valeur 1,"Valeur 2, avec ""des guillements""",valeur3

Exemple :

Code,Nom de l'évènement,Rubrique,Structure,Catégorie,Type,Lieu,Date de début,Heure de début,Date de fin,Heure de fin,Date d'ouverture des inscriptions,Heure d'ouverture des inscriptions,Date de fermeture des inscriptions,Heure de fermeture des inscriptions,Description,Intitulé de la place / article,Nombre de places / articles par inscription,Texte de confirmation,Adresse de l'expéditeur,Attacher le fichier calendaire,Adresse mail de contact KSMS-191022-A,Découerte du module inscription,RUBRIQUE1,,KSUP,WEBINAR,"Kosmos - 8 rue Kervegan - 44000 Nantes Rendez-vous place du Commerce, 15 à 30 minutes avant le début",01/11/2022,10:00:00,01/11/2022,12:00:00,15/10/2022,08:00:00,,,,Présentation du module inscription,2,"Vous êtes bien inscrit à la présentation du module inscription. Rendez-vous place du Commerce, 15 à 30 minutes avant le début. Merci de vous désinscrire si vous ne pouvez pas venir.",evenement@kosmos.fr,,jpatin@kosmos.fr

Le fichier des créneaux

Le fichier est composé de 16 colonnes, avec une ligne d'entête.

Exemple :

Code de l'évènement de rattachement,Code du créneau,Intitulé du créneau,Structure,Catégorie,Type,Date de début,Heure de début,Date de fin,Heure de fin,Lieu,Description,Nombre de places disponibles,Gestionnaire 1,Gestionnaire 2,Gestionnaire 3 KSMS-191022-A, KSMS-1,Créneau 1234,,,,01/11/2022,08:00:00,01/11/2022,09:00:00,,,5,jpatin,,

Fichier d'exemple

Modifier le fichier

Formulaires personnalisés

Lors de son inscription à un évènement, il est possible de demander des informations complémentaires au participant. C'est la notion de "Question" dans pretix.

Création d'un nouveau formulaire

Les formulaires sont des fichiers JSON contenant la définition des questions.

Le fichier de définition doit respecter la syntaxe exacte de pretix.
En effet, le fichier est envoyé directement via l'API sur le endpoint pretix dédié.

Actuellement, le moyen le plus simple de générer un nouveau formulaire est d'utiliser l'IHM pretix native. Une fois le formulaire construit, il suffit de l'appeler via le endpoint d'API GET /api/v1/organizers/(organizer)/events/(event)/questions/ Dans la réponse, extraire la section results et la copier dans un fichier ".json"

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [{
        "id": 1,
        "question": {"en": "T-Shirt size"},
        "help_text": {"en": "Choose your preferred t-shirt-size"},
        "type": "C",
        ...
        },{
        ...
    }]
}

Selon le besoin, le fichier généré peut être stocké dans trois emplacements différents:

1. Dans les ressources de l'extension inscription v2
   C'est le cas des questionnaires "produit" qui seront communs à tous les clients. Le fichier doit etre déposé dans le répertoire src/main/resources/form/templates de l'extension.
2. Dans les ressources du projet
   C'est le cas des questionnaires "projet" spécifiques à un client. Le fichier doit etre déposé dans le répertoire src/main/resources/form/templates du projet.
3. Dans le répertoire /inscription/templates/ du storage
   C'est le cas des questionnaires "projet" urgents, spécifiques à un client. En déposant le formulaire dans le storage il est immédiatement disponible, sans avoir besoin de procéder à une livraison et un déploiement.

Les fichiers issus du storage sont toujours prioritaires par rapport aux fichiers embarqués.
Si un fichier existe dans le storage et dans les ressources, c'est le fichier du storage qui fera foi.

Afin d'activer un formulaire pour le rendre disponible dans la création /modification d'un évènement, le fichier doit être associé à un libellé K-Sup dont le code est le nom (hors extension) du fichier JSON. Par exemple, pour un fichier de question nommé lorem.json, il faut créer un libellé de type "(Évènement) Type de formulaire" dont le code et "lorem".

Cela implique que les formulaires produit ou projet doivent être accompagnés d'un script flyway pour créer le libellé associé.

Modifier le fichier

Extension Lieu

Modifier le fichier

Statistique du module Cartographie

Ce fichier présente les statistiques du module Cartographie

Indication d'installation / d'utilisation

Statistique d'usage

Indicateur de type compteurs

Modifier le fichier

Article

La fiche "Article" est la fiche la plus simple. Elle sert à présenter un contenu en différents chapitre, mettre en place des guides pratiques, des procédures, diffuser des brèves...

"Contenus" > "Article"

Tous les champs ne sont pas obligatoires, seuls ceux précédés d'un astérisque (*) doivent obligatoirement être renseignés. Les champs non renseignés n'apparaîtront pas dans l'article sur le site.

La fiche article est découpée en 7 onglets :

Onglet Contenu principal

• Langue : Sélectionnez une langue dans le menu déroulant.
• Titre : Champ libre.
• Sous-titre : Champ libre.
• Date de l'article : format JJ/MM/AAAA
• Rubrique : Cliquez sur le bouton "Sélectionner" et recherchez dans l'arborescence la rubrique de rattachement de l'article. Le rattachement à une rubrique permet de positionner une page dans l'arborescence des contenus et de définir un contexte de navigation.
• Structure : Cliquez sur le bouton "Sélectionner" et recherchez dans l'arbre des structures. Le rattachement à une structure permet de définir des autorisations de modification sur la fiche en fonction des droits des utilisateurs, de rechercher une fiche ou de la faire remonter dans une liste de fiches.
• Thématique : Liste mutlivaluée. Les libellés sont paramétrables depuis le menu "Administration" du module d'adminsitration
• Résumé : Texte simple, qui sera affiché dans les listes d'articles si le style d'affichage sélectionné est par exemple : titre + sous-titre + résumé
• Description : Contenu de l'article. Dans ce champ vous pouvez copier/coller du texte et insérer des liens et des médias.
• Photo : Cliquez sur Parcourir pour aller chercher une image dans la médiathèque ou ajouter une nouvelle image. La photo sera affichée dans les listes d'articles, si le style d'affichage sélectionné est par exemple : date + titre + sous-titre + vignette + résumé

Onglet Informations complémentaires

• Ordre d'affichage : Saisissez un nombre entre 1 et 100 pour forcer l'ordre d'affichage des articles dans une liste de fiches.
• Fichier(s) joint(s) : Pour proposer en téléchargement un visuel ainsi que des fichiers. Attention : l'image et les fichiers ne seront pas intégrés dans la médiathèque il seront enregistrés sur la fiche article.
• Forum : Activer ou Fermer un forum de discussion.

Onglet Encadré

La zone d'encadré s'affiche habituellement à droite dans la fiche. Elle permet de faire des zooms et/ou des rebonds vers d'autres contenus. Le rédacteur peut y insérer des documents à télécharger, des liens vers des pages internes ou vers des sites externes... Pour insérer un nouvel encadré de fiche, cliquez sur "Modèles" situé dans l'éditeur de contenus.

Modifier le fichier

Statistique du composant Article

Ce fichier présente les statistiques du composant article (cf ).

Indication d'installation / d'utilisation

North Star

Statistique d'usage

Indicateur de type compteurs

Modifier le fichier

Page Libre

Créez des pages d'accueil de rubrique, des pages éditoriale

Le contributeur peut organiser une page libre en plusieurs "blocs de contenus" et y appliquer les "modèles" souhaités. En cela, elle est idéale pour créer des pages d'accueil de rubriques, des pages éditoriales par exemple.

"Contenus" > "Page Libre"

La page libre permet de faire des mises en page de façon souple et illimitée :

• d'ajouter autant de blocs de contenus que l'on souhaite
• d'organiser ces blocs et de les répartir librement
• exemple : double colonage, triple colonage...
• d'appliquer des modèles graphiques qui ne sont pas laisser à disposition dans les autres types de fiches
• d'appliquer des encadrés de recherche sur les contenus souhaités (Exemple : encadré de recherche dans l'annuaire)

Organisation des zones de contenus

Un bloc de contenus est caractérisé par :

• Une ligne
• Une colonne
• Une largeur (en %)

L'administration de ces 3 critères permet d'avoir une mise en page spécifique à sa page.

Les onglets de la fiche

Tous les champs ne sont pas obligatoires, seuls ceux précédés d'un astérisque (*) doivent obligatoirement être renseignés. Les champs non renseignés n'apparaîtront pas dans le site.

Comme les autres fiches, la page libre est découpée en 6 onglets.

Onglet Contenu Principal

• Langue : Sélectionnez une langue dans le menu déroulant.
• Titre : Champ libre.
• Rubrique : Cliquez sur le bouton "Sélectionner" et recherchez dans l'arborescence la rubrique de rattachement de la page. Le rattachement à une rubrique permet de positionner une page dans l'arborescence des contenus et permet de définir un contexte de navigation.
• Structure : Cliquez sur le bouton "Sélectionner" et recherchez dans l'arbre des structures. Le rattachement à une structure permet de définir des autorisations de modification sur la fiche en fonction des droits des utilisateurs.
• Bloc de contenu : Correspond à un paragraphe de votre page. Dans ce champ vous pouvez copier/coller du texte et insérer des liens, des médias...

Afin d'organiser votre page vous pouvez ajouter des blocs de contenu, changer l'ordre des blocs de contenu dans la page en modifiant le numéro de ligne, définir des colonnes.

Onglet Informations complémentaires

Informations complémentaires : Ajoutez ici les informations complémentaires qui apparaîtront généralement en bas de votre page libre

Onglet Encadré

Encadré de fiche

La zone d'encadré s'affiche habituellement à droite dans la fiche. Elle permet de faire des zooms et/ou des rebonds vers d'autres contenus. Le rédacteur peut y insérer des documents à télécharger, des liens vers des pages internes ou vers des sites externes... Pour insérer un nouvel encadré de fiche, cliquez sur "Modèles" dans l'éditeur de contenus.

Encadré de recherche

Vous pouvez ajouter deux formulaires de recherche de fiches au choix :

• Encadré recherche : sélectionnez un type dans le menu déroulant
• Encadré recherche (2) : sélectionnez un type dans le menu déroulant

Modifier le fichier

Module Accueil

Modifier le fichier

Statistique du composant accueil

Ce fichier présente les statistiques du composant accueil (cf ).

Indication d'installation / d'utilisation

North Star

Statistique d'usage

Indicateur de type compteurs

Modifier le fichier

Module Actualite

Modifier le fichier

Documentation Fonctionnelle : Carte "Dernières actualités"

Description

La carte "Dernières actualités" est un composant d'interface utilisateur qui permet d'afficher les actualités récentes et à venir, organisées par type d'actualité. Cette carte peut être intégrée dans différentes pages du portail pour offrir aux utilisateurs un accès rapide aux informations récentes.

Fonctionnalités

Affichage des actualités par type

• La carte affiche les actualités regroupées par type (événements, annonces, communiqués, etc.)
• Les types d'actualités sont présentés sous forme d'onglets, permettant à l'utilisateur de naviguer facilement entre les différentes catégories
• Un onglet "Dernières actualités" est toujours présent et affiche toutes les actualités, tous types confondus

Chargement dynamique du contenu

• Le contenu des actualités est chargé dynamiquement lorsque l'utilisateur clique sur un onglet
• Pendant le chargement, un indicateur visuel (skeleton loader) est affiché pour informer l'utilisateur que le contenu est en cours de chargement
• L'onglet "Dernières actualités" est chargé automatiquement à l'ouverture de la page

Filtrage des actualités

• La carte affiche uniquement les actualités actuelles et à venir (les actualités passées ne sont pas affichées)
• Le nombre d'actualités affichées par onglet est configurable
• Les types d'actualités affichés sont configurables

Lien vers toutes les actualités

• Un lien optionnel "Voir toutes les actualités" peut être affiché en bas de la carte, permettant à l'utilisateur d'accéder à la page complète des actualités

Configuration de la carte

La carte "Dernières actualités" peut être configurée par les administrateurs du portail avec les options suivantes :

Options de configuration

• Titre : Le titre principal de la carte
• Sous-titre : Un texte descriptif optionnel affiché sous le titre
• Types d'actualité : Sélection des types d'actualités à afficher dans la carte
• Nombre d'actualités par onglet : Définit combien d'actualités sont affichées dans chaque onglet
• Style d'affichage : Définit le style de liste à utiliser pour l'affichage dans la carte et dans les résultats "voir toutes les actualités"
• Contexte d'affichage de la recherche : Permet de filtrer les actualités selon un contexte spécifique (par exemple, une rubrique particulière)
• Intitulé du lien "voir toutes les actualités" : Personnalise le texte du lien vers la page complète des actualités

Cas d'utilisation

Pour les visiteurs du portail

• Consulter rapidement les dernières actualités de l'établissement
• Filtrer les actualités par type pour trouver rapidement l'information recherchée
• Accéder à la page complète des actualités pour voir plus de détails

Pour les administrateurs du portail

• Mettre en avant les actualités importantes sur la page d'accueil ou d'autres pages du portail
• Configurer les types d'actualités à afficher selon les besoins spécifiques
• Personnaliser l'apparence et le comportement de la carte pour s'adapter au contexte d'utilisation

Modifier le fichier

Statistique du composant actualité

Ce fichier présente les statistiques du composant actualité (cf ).

Indication d'installation / d'utilisation

North Star

Statistique d'usage

Indicateur de type compteurs

Indicateurs d'actions

Modifier le fichier

Module AnnuaireSup

Modifier le fichier

Statistique du composant annuairesup

Ce fichier présente les statistiques du composant annuairesup (cf ).

Indication d'installation / d'utilisation

North Star

Statistique d'usage

Indicateur de type compteurs

Indicateurs d'actions

Modifier le fichier

Fiche structure

Recherche

Une fiche structure est recherchable en front office si :

• elle est au statut "En ligne"
• elle est publiée ou multipubliée dans une rubrique d'un site actif OU est utilisée en page de tête d'une rubrique visible
• la case à cocher "Ne pas afficher dans le moteur de recherche" n'est pas cochée dans l'onglet "Publication" de saisie de la fiche
• la case "Visible en front-office" est cochée dans l'onglet "Suivi" de saisie de la fiche

Modifier le fichier

Statistique du composant structure

Ce fichier présente les statistiques du composant structure (cf ).

Indication d'installation / d'utilisation

North Star

Statistique d'usage

Indicateur de type compteurs

Indicateurs d'actions

Modifier le fichier

Module Application

La fiche "Application" sert à présenter une application, un service, un outil, un logiciel, une application mobile...

"Etablissement" > "Application"

Tous les champs ne sont pas obligatoires, seuls ceux précédés d'un astérisque (*) doivent obligatoirement être renseignés.

La fiche application est découpée en 6 onglets :

Onglet Contenu principal

• Code : Champ libre.
• Titre : Champ libre.
• Sous-titre : Champ libre.
• Fiche consultable : Case à cocher.
• Structure : Cliquez sur le bouton "Sélectionner" et recherchez dans l'arbre des structures. Le rattachement à une structure permet de définir des autorisations de modification sur la fiche en fonction des droits des utilisateurs, de rechercher une fiche ou de la faire remonter dans une liste de fiches.
• Application : Radio bouton Externe ou Interne. Lorsque Externe est sélectionné, un champ URL est affiché pour saisir l'url de l'application.
• Catégories : Liste multivaluée. Les libellés sont paramétrables depuis le menu "Administration" du module d'adminsitration
• Types : Liste multivaluée. Les libellés sont paramétrables depuis le menu "Administration" du module d'adminsitration
• Description : Toolbox. Dans ce champ vous pouvez copier/coller du texte et insérer des liens et des médias.
• Photo : Cliquez sur Parcourir pour aller chercher une image dans la médiathèque ou ajouter une nouvelle image. La photo sera affichée lors de la consultation de la fiche application.

Recherche elastic

La fiche remonte dans les résultats de recherche.

Si la case "Fiche consultable" est cochée, le lien du résultat de recherche renvoie vers la fiche application. Sinon, le lien renvoie vers l'URL de l'application.

Affichage front

• Les catégories sont affichées en haut de la fiche application sous la forme de cartouches.
• La date de publication est affichée sous les catégories. Si la fiche a été modifiée, la date de modification est également affichée.
• Si l'application est interne, un bouton "Accéder" est affiché pour ouvrir l'application dans un nouvel onglet. Si l'application est externe, un bouton "Accéder" est affiché pour ouvrir l'URL de l'application dans un nouvel onglet.

Carte Application

Carte permettant d'afficher une mosaïque des applications

Cette carte contient les champs de saisie suivants :

La carte application affiche :

• Un titre
• Un sous-titre
• Les catégories d'applications
  • Les 3 premières catégories d'applications
  • Un menu "Plus d'apps" permettant de sélectionner une autre catégorie d'application
• Le filtre "rechercher une application" qui permet de filtrer les applications de la catégorie courante directement dans l'onglet (filtre sur le titre ou le sous-titre ou l'url de l'application)
• Les aperçus des applications accessibles à l'utilisateur (pas de restriction d'accès) avec pour chaque appli :
  • Le sous-titre de l'application : affiché sous la forme d'un texte d'aide
  • La photo de l'application
  • Le titre de l'application

Au clic sur le bloc application : l'utilisateur est redirigé vers l'url de l'application ou vers la fiche application (selon ce qui a été défini dans la fiche application) => en V1 si le front de la fiche application n'existe pas on redirigera vers l'URL Lorsque l'utilisateur est connecté

Utilisateur connecté

Si l'utilisateur est connecté il voit apparaître un onglet "Mes apps" et il a la possibilité :

• Depuis les onglets catégories :
  • D'épingler des applications dans les différentes catégories qui seront ensuite disponibles dans "Mes apps" => les applications déjà ajoutées présentent une épingle de couleur
  • De supprimer l'appli de "Mes apps" depuis l'onglet de la catégorie
• Depuis "Mes apps"
  • De retrouver toutes les applis épinglées
  • De supprimer les applis épinglées de l'onglet "Mes apps"

Modifier le fichier

Statistique du composant Application

Ce fichier présente les statistiques du composant application.

Indication d'installation / d'utilisation

North Star

Statistique d'usage

Indicateur de type compteurs

Modifier le fichier

Extension Blog

Modifier le fichier

Statistique de l'extension Blog

Ce fichier présente les statistiques de l'extension blog (cf ).

Indication d'installation / d'utilisation

Modifier le fichier

Module Article de blog

Modifier le fichier

Statistique du composant Article de blog

Ce fichier présente les statistiques du composant article de blog (cf ).

Indication d'installation / d'utilisation

North Star

Statistique d'usage

Indicateur de type compteurs

Modifier le fichier

Module Blog

Modifier le fichier

Statistique du composant Blog

Ce fichier présente les statistiques du composant blog (cf ).

Indication d'installation / d'utilisation

North Star

Statistique d'usage

Indicateur de type compteurs

Modifier le fichier

Module Commentaire

Modifier le fichier

Statistique du composant commentaire

Ce fichier présente les statistiques du composant commentaire (cf ).

Indication d'installation / d'utilisation

North Star

Statistique d'usage

Indicateur de type compteurs

Indicateurs d'actions

Modifier le fichier

Extension étudiant et alumni

Modifier le fichier

Statistique de l'extension étudiant alumni

Ce fichier présente les statistiques de l'extension étudiant alumni (cf ).

Indication d'installation / d'utilisation

Modifier le fichier

Module Annuaire Anciens Etudiants

Modifier le fichier

Statistique du composant annuaire anciens etudiants

Ce fichier présente les statistiques du composant annuaire anciens etudiants (cf ).

Indication d'installation / d'utilisation

North Star

Statistique d'usage

Indicateur de type compteurs

Indicateurs d'actions

Module étudiant

Modifier le fichier

Statistique du composant annuaire étudiants

Ce fichier présente les statistiques du composant annuaire étudiants (cf ).

Indication d'installation / d'utilisation

North Star

Statistique d'usage

Indicateur de type compteurs

Indicateurs d'actions

Modifier le fichier

Module association étudiant

Modifier le fichier

Statistique du composant association étudiant

Ce fichier présente les statistiques du composant association étudiant (cf ).

Indication d'installation / d'utilisation

North Star

Statistique d'usage

Indicateur de type compteurs

Indicateurs d'actions

Modifier le fichier

Extension GED

Modifier le fichier

Statistique de l'extension GED

Ce fichier présente les statistiques de l'extension GED (Gestion électronique des Documents).

Indication d'installation / d'utilisation

North Star

Statistique d'usage

Indicateur de type compteurs

Modifier le fichier

Messages

Diffusion de messages ciblés aux utilisateurs de K-Sup

"Gestion éditoriale" > Message"

Les onglets de saisie de message

Tous les champs ne sont pas obligatoires, seuls ceux précédés d'un astérisque (*) doivent obligatoirement être renseignés.

La saisie du message est découpée en 3 onglets.

Onglet Contenu Principal

• Etat : Case à cocher permettant d'activer ou de désactiver le message.
• Intitulé : Champ texte. L'intitulé du message dans le back office.
• Rubrique : Cliquez sur le bouton "Sélectionner" et recherchez dans l'arborescence la rubrique de rattachement de la page. Le rattachement à une rubrique permet de positionner une page dans l'arborescence des contenus et permet de définir un contexte de navigation.
• Structure : Cliquez sur le bouton "Sélectionner" et recherchez dans l'arbre des structures. Le rattachement à une structure permet de définir des autorisations de modification sur la fiche en fonction des droits des utilisateurs.
• Langue : Sélectionnez une langue dans le menu déroulant.
• Date de début : Sélectionner une date de début d'affichage du message dans le date-picker.
• Date de fin : Sélectionner une date de fin d'affichage du message dans le date-picker.
• Heure de début : Saisir une heure de début d'affichage du message (format HH:mm).
• Heure de début : Saisir une heure de fin d'affichage du message (format HH:mm).
• Fermeture : Sélectionner "oui" ou "non" pour définir si le message peut être fermé.
• Notification : Sélectionner "oui" ou "non" pour définir si le message est doublé d'une notification.
• Ordre : Champ texte. Permet de définir l'ordre d'affichage du message.

Onglet Périmètres d'affichage

Application à une rubrique:

• Rubrique : Cliquez sur le bouton "Sélectionner" et recherchez dans l'arborescence la rubrique de périmètre.
• Appliquer aux sous-rubriques : Sélectionner la case à cocher pour que les sous-rubriques de la rubrique sélectionnée soit prises en compte dans le périmètre.
• Groupes : Sélectionner les groupes du périmètre dans l'arborescence des groupes.

Application à une page

• Type de fiche : Sélectionner dans la liste le type de fiche à appliquer au périmètre.
• Groupes : Sélectionner les groupes du périmètre dans l'arborescence des groupes.

Onglet Contenu

• Choix du type de message : Sélectionner le type d'affichage du message.
• Titre : Champ libre. Titre du message affiché en front.
• Contenu : Toolbox. Contenu du message affiché en front.

Modifier le fichier

Règles de gestion de visibilité des messages par date

RG1

Un message est visible uniquement s'il est actif.

RG2

Un message est visible si la date de début est dans le passé ou égale à la date courante.

RG3

Si une heure de début est définie. Un message est visible si l'heure de début est dans le passé ou égale à l'heure courante (l'heure de début s'applique sur la date de début).

RG4

Un message est visible s'il n'y a pas de date de fin ou si la date de fin est dans le futur.

RG5

Si une heure de fin est définie. Un message est visible si l'heure de fin est dans le futur (l'heure de fin s'applique sur la date de fin).

Modifier le fichier

Règles de gestion de visibilité des messages par périmètre

RG1

Un message est visible s'il n'a pas de périmètre d'affichage.

RG2

Si un périmètre de rubrique est renseigné. Un message est visible si la rubrique du périmètre est la rubrique du contexte courant.

RG3

Si un périmètre de rubrique est renseigné. Si les sous-rubriques sont incluses dans le périmètre. Un message est visible si la rubrique du contexte courant est la rubrique du périmètre ou une de ses sous-rubriques.

RG4

Si un groupe est présent sur le périmètre. Si l'utilisateur ne possède pas de groupe, le message n'est pas visible.

RG5

Si un groupe est présent sur le périmètre. Si l'utilisateur possède un ou plusieurs groupes, le message est visible si le groupe du périmètre est présent dans les groupes de l'utilisateur.

RG6

Si plusieurs groupes sont présents sur le périmètre. Si l'utilisateur possède un ou plusieurs groupes, le message est visible si un des groupes du périmètre est présent dans les groupes de l'utilisateur.

RG7

Si un groupe est présent sur le périmètre. Si l'utilisateur possède un ou plusieurs groupes, le message est visible si un des sous-groupes des groupes du périmètre est présent dans les groupes de l'utilisateur.

RG8

Si un périmètre d'objet est renseigné. Un message est visible si l'objet présent dans le contexte courant est l'objet défini sur le périmètre.

Modifier le fichier

Module Formation

Modifier le fichier

Statistique du composant Formation

Ce fichier présente les statistiques du composant Formation

Indication d'installation / d'utilisation

North Star

Statistique d'usage

Indicateur de type compteurs

Modifier le fichier

Module Parcours

Modifier le fichier

Statistique du composant Parcours

Ce fichier présente les statistiques du composant Parcours.

Indication d'installation / d'utilisation

North Star

Statistique d'usage

Indicateur de type compteurs

Modifier le fichier

Module Elément Pédagogique

Modifier le fichier

Statistique du composant Element Pédagogique

Ce fichier présente les statistiques du composant Element Pédagogique.

Indication d'installation / d'utilisation

North Star

Statistique d'usage

Indicateur de type compteurs

Modifier le fichier

Module Cours

Modifier le fichier

Statistique du composant Cours

Ce fichier présente les statistiques du composant Cours.

Indication d'installation / d'utilisation

North Star

Statistique d'usage

Indicateur de type compteurs

Modifier le fichier

Extension Offre Stage Emploi

Modifier le fichier

Statistique de l'extension OffreStageEmploi

Ce fichier présente les statistiques de l'extension OffreStageEmploi

Indication d'installation / d'utilisation

North Star

Statistique d'usage

Indicateur de type compteurs

Modifier le fichier

Extension Petite Annonce

Modifier le fichier

Statistique de l'extension Petite Annonce

Ce fichier présente les statistiques de l'extension Petite Annonce

Indication d'installation / d'utilisation

North Star

Statistique d'usage

Indicateur de type compteurs

Modifier le fichier

Extension Recherche et Labo

Modifier le fichier

Statistique de l'extension Recherche et Labo

Ce fichier présente les statistiques de l'extension Recherche et Labo

Indication d'installation / d'utilisation

North Star

Statistique d'usage

Indicateur de type compteurs

Modifier le fichier

Extension Lieu

Modifier le fichier

Statistique de l'extension Lieu

Ce fichier présente les statistiques de l'extension Lieu

Indication d'installation / d'utilisation

North Star

Statistique d'usage

Indicateur de type compteurs

Modifier le fichier

Documentation technique

La documentation technique décrit le fonctionnement de l'ensemble du produit K-Sup.
Celle-ci est organisée en modules techniques (calqués sur l'organisation du code, c'est à dire par repository git).
Si nécessaire, vous pourrez trouver pour chaque module :

• Une description du fonctionnement
• La liste des propriétés exposées pour configurer le module
• Un guide à destination des intégrateurs pour implémenter le module sur le projet

Modifier le fichier

Paramétrage des messages d'alerte

Le paramétrage des messages d'alerte est réalisé dans le fichiers core.properties et dans Core_fr.properties/Core_en.properties.

Surcharge

La surcharge des propriétés peut se faire dans le fichier :

• application_xxx.properties dans les sources d'un projet
• env.properties dans le répertoire de configuration d'un environnement (référencé par la propriété conf.dir)
• Message_xxx.properties dans le répertoire de configuration d'un environnement (référencé par la propriété conf.dir, xxx étant la langue)

Propriétés

1 les couleurs CSS s'expriment de plusieurs manières : documentatiton Mozilla sur les couleurs en css

Modifier le fichier

Les bandeaux d'actions

Un bandeau d’action permet d’afficher un ensemble de boutons regroupés dans une zone dédiée, généralement positionnés côte à côte. Chaque bouton représente une action utilisateur (par exemple : ajout aux favoris, export PDF, notification...).

La configuration des actions du bandeau est entièrement personnalisable :

• Une action peut être désactivée via une propriété dans le projet.
• L’ordre d’affichage des actions est configurable.
• De nouvelles actions peuvent être ajoutées directement depuis le projet, sans modifier le code de l’extension d’origine.

Définition du bandeau

Voici un exemple de définition de bandeau :

<bean id="defaultActionsBandeauFicheViewPreparer" class="com.kosmos.actionsbandeau.bandeau.ActionsBandeauFicheViewPreparer">
<property name="type" value="bandeau-action-fiche" />
<property name="view" value="/WEB-INF/jsp/actionsbandeau/actionsBandeau.jsp" />
<property name="expectedViewTypes">
<list>
<value>action-fiche</value>
</list>
</property>
</bean>

Tout bandeau doit étendre AbstractActionsBandeauViewPreparer. Pour utiliser ce bandeau au sein d'une fiche, il est nécessaire, dans la page en question de rajouter le type du preparer dans les expectedViewTypes.

Le bandeau prépare ici des actions de type "action-fiche".

Actions de bandeau

Voici un exemple d'action, ici un bouton d'ajout/retrait des favoris, qui sera ajouté au bandeau si son preparer l'accepte et que l'action est active (non désactivé).

<bean id="favorisActionFicheViewPreparer" class="com.kosmos.panier.actionsbandeau.preparer.FavorisActionFicheViewPreparer">
<property name="type" value="action-fiche" />
<property name="view" value="/extensions/panier/WEB-INF/jsp/buttonContentPanier.jsp" />
<property name="actionActive" value="${front.actionbandeaufiche.favoris.active:true}" />
<property name="actionPosition" value="${front.actionbandeaufiche.favoris.order:3}" />
<property name="typeFicheAutorise" value="${panier.FAVORIS.included.contents:}"/>
<property name="typeFicheExclu" value="${panier.FAVORIS.excluded.contents:}"/>
</bean>

Tout préparer d'action de bandeau doit étendre AbstractActionViewPreparer.

@startuml skinparam class { BackgroundColor White BorderColor #2C3E50 FontColor #2C3E50 FontSize 14 FontName Arial AttributeFontColor #34495E AttributeFontSize 12 AttributeFontName Arial StereotypeFontColor #8E44AD StereotypeFontSize 12 StereotypeFontName Arial } abstract class AbstractActionViewPreparer{ -actionActive -actionPosition +accept(frontContext : FrontContext) : Boolean +setActionActive() : Void +setActionPosition() Void }

class ActionsBandeauViewModel{ }

abstract class AbstractActionsBandeauViewPreparer { -typeAction //On acepte queles actions actionFiche ou actioncard ou ... +accept(frontContext : FrontContext) : Boolean +prepare(frontContext : FrontContext, Map<String, preparers : List>) : V //Prepare toutes les actions du type typeAction +setTypeAction() : Void } AbstractActionsBandeauViewPreparer --* ActionsBandeauViewModel abstract class AbstractActionViewModel{ -icon : String -label : String -order : Integer }

class ActionsBandeauFicheViewPreparer extends AbstractActionsBandeauViewPreparer{ } class AccueilActionsBandeauFicheViewPreparer extends ActionsBandeauFicheViewPreparer{ +accept(frontContext : FrontContext) : Boolean +prepare(frontContext : FrontContext, Map<String, preparers : List>) : V }

note left of ActionsBandeauFicheViewPreparer action-fiche

 main.jsp va attendre un bandeau-action-fiche

end note

class ActionsBandeauCardViewPreparer extends AbstractActionsBandeauViewPreparer{ }

note right of ActionsBandeauCardViewPreparer action-card

FavorisPanierCardViewBuilder va avoir une liste de ActionsBandeauCardViewPreparer.
Il va rechercher un preparer de type bandeau-action-card. et en preparer un pour chaque card.

end note

ActionsBandeauCardViewPreparer --* ActionsBandeauViewModel

abstract class AbstractFavorisActionViewPreparer { +prepare(frontContext : FrontContext, Map<String, preparers : List>) : V }

AbstractFavorisActionViewPreparer -right-|> AbstractActionViewPreparer class FavorisActionViewModel extends AbstractActionViewModel{ }

class FavorisActionFicheViewPreparer extends AbstractFavorisActionViewPreparer{

} note bottom of FavorisActionFicheViewPreparer Dans le core-front-sitetemplates, le preparer : end note

FavorisActionFicheViewPreparer --* FavorisActionViewModel

class FavorisActionCardViewPreparer extends AbstractFavorisActionViewPreparer{ } note bottom of FavorisActionCardViewPreparer Dans le core-front-sitetemplates, le preparer : end note

FavorisActionCardViewPreparer --* FavorisActionViewModel

ActionsBandeauFicheViewPreparer --* ActionsBandeauViewModel AbstractFavorisActionViewPreparer --* FavorisActionViewModel

ActionsBandeauViewModel --*"1..n" AbstractActionViewModel : actions @enduml

Modifier le fichier

Gestion des cookies par K-Sup

La version 7.0 de K-Sup introduit une nouvelle fonctionnalité sur les cookies.

Les cookies, notamment le cookie de session, sont générés par le serveur d'application (tomcat) afin de faire un lien entre un utilisateur et le serveur applicatif.

Les cookies sont ajoutés dans les entêtes de réponse par le serveur d'application via un composant nommé CookieProcessor".
Par défaut, le CookieProcessor de tomcat retourne un cookie sans domaine ni attribut samesite. Le navigateur remplit alors les blancs avec des valeurs par défaut.

• Le cookie est associé au site courant (et seulement au site courant, sans les sous-domaine)
• Le coolie est limité au site courant et ses sous-domaine (aka "LAX")

Afin de simplifier la connexion des utilisateurs et de permettre un SSO compatible avec les règles CORS (Cross-Origin Resource Sharing), un CookieProcessor modifié est injecté par le K-Sup au démarrage de la webapp.
Une notion de filtre a été ajoutée afin de n'appliquer ce CookieProcessor spécialisé que sur certains cookies. Par défaut, seul le cookie nommé KSUP-SSO-UUID est pris en charge. Il est possible d'ajouter d'autres cookies en valorisant la propriété cookie.processor.filter avec la liste des cookies concernés sous forme d'une chaine séralisée avec "," comme séparateur (NAME1,NAME2,...)

cookie.processor.filter=KSUP-SSO-UUID

Le nouveau CookieProcessor apporte les fonctionnalités suivantes :

• L'attribut SameSite est forcé à None sur tous les cookies pris en charge
  L'attribut "SameSite=None" autorise le navigateur à envoyer le cookie vers le domaine du cookie, y compris si l'appel est réalisé depuis un site d'un autre domaine. Depuis le site www.acme.com, si un script réalise un appel XmlHttpRequest vers le site www.acme.fr, le cookie sera envoyé avec la requête. Le SSO K-Sup est basé sur ce fonctionnement.
  
  
• Le drapeau "Secure" est forcé sur tous les cookies pris en charge
  Le drapeau "Secure" doit obligatoirement être positionné dans l'entête de réponse Set-Cookie si l'attribut "SameSite" est valorisé à "None".
  Pour être accepté par le navigateur, le cookie devra donc transiter via un canal sécurisé (HTTPS) ou être interrogé sur le site localhost.
  
  
• Le drapeau "HttpOnly" est forcé sur tous les cookies pris en charge
  Cette fonctionnalité n'est pas obligatoire, mais elle améliore la sécurité en empêchant la lecture en javascript des cookies.

A noter, une particularité des navigateurs permet d'ignorer le drapeau "Secure" des cookie si le domaine courant est "localhost" ou "xxxxx.localhost". Il est donc possible, sous certaines conditions sur les domaines de conserver le fonctionnement standard du CookieProcessor (true + None) dans un environnement local

Modifier le fichier

Les filtres HTTP

Les filtres HTTP permettent d'effectuer des traitements avant (pre-filter) ou après (post-filter) le traitement de la requête HTTP par le code applicatif (processus / controleur, etc... )

Ordre des filtres HTTP

L'ordre des filtres HTTP est géré via l'ajout de l'annotation @Order. (cf la classe FilterDeclarationManager) Lors de l'ajout des filtres, il convient de bien vérifier la fonction de chaque filtre. Par exemple, il ne faut pas insérer votre filtre avant le ContexteFilter si vous utilisez des données du contexte.

Liste des filtres standard apportés par le produit

Le produit apporte en standard un certain nombre de filtres.

• Filtres sur le répartiteur (dispatcher) REQUEST

• Filtres sur le répartiteur (dispatcher) FORWARD

• Filtres sur le répartiteur (dispatcher) ERROR

• Filtres spécifiques à la servlet JSP, dispatcher REQUEST + FORWARD + ERROR

Ajout d'un filtre HTTP

1. Créer une classe qui implémente ExtensionFilter

...
public class AcmeFilter implements ExtensionFilter {
    ...
}

2. Ajouter les annotations Spring

@Component
@CoreContext
@Order(Ordered.HIGHEST_PRECEDENCE + 35000)
@WebFilter(urlPatterns = FILTER_PATTERN_DEFAULT, filterName = "acme-filter")
public class AcmeFilter implements ExtensionFilter {
    ...
}

Modifier le fichier

Envoi d'e-mail

Présentation

L'applicatif K-Sup offre la possibilité d'envoyer des e-mails aux utilisateurs.
Il peut s'agir d'e-mails techniques liés au cycle de vie des fiches ou d'e-mails fonctionnels liès à de la communication (lettres d'information) ou à la gestion du compte utilisateur (activation de compte, réinitialisation de mot de passe, etc...).

Pour réaliser cette opération, le système s'appuie sur un serveur de messagerie externe.

Configuration

Modifier le fichier

Extension

Packaging

Une extension peut-être packagée en différents modules :

• Un module contenant les mécanismes java (exemple : actualite-core);
• Un module contenant les écrans de contribution back-office (exemple : actualite-webapp-contrib);
• Un module contenant les écrans utilisés en front-office (exemple : actualite-webapp-front);
• Un module pour l'API si l'extension expose des données via l'API K-Sup (exemple : actualite-api).

Chargement et déclaration

L'extension est chargée dans l'application via les mécanismes liés à Spring en créant un contexte dédié. Afin d'isoler les différents projets et extensions, le chargement des contextes doit toujours respecter une relation parent / enfant avec l'extension "Core" qui est l'extension de plus bas niveau. Toutes les extensions ont accès aux fonctionnalités et objets de ce contexte Core. En revanche, le Core ne doit pas référencer de fonctionnalités des extensions et les extensions ne doivent pas se référencer entres elles.

Chaque déclaration d'extension est matérialisée comme étant un bean de type {@link com.kportal.extension.IExtension}, qui est porté par ce contexte fils qui est initialisé dans la classe {@link com.kportal.extension.ExtensionConfigurer}. Ce traitement est responsable de la découverte des différents contextes Spring d'extensions (par convention : /extensions/idextension/ExtensionContext.xml). Pour le module Core, la déclaration est présente dans le fichier CoreContext.xml.

Ajoute de contrôleurs Spring MVC

Les extensions peuvent déclarer leurs propres contrôleurs afin d'exposer des fonctionnalités. Ces contrôleurs sont alors chargés dans le contexte propre de l'extension afin de pouvoir utiliser les fonctionnalités de l'extension (service java par exemple). Afin d'identifier les différents modules dans les URLs, les contrôleurs de chaque extension seront préfixées par un identifiant propre à l'extension (par exemple : www.univ-kosmos.fr/mon-extension/url-controller).

Activation et configuration

L'activation et la configuration des contrôleurs se fait via l'édition d'objet héritant de IExtensionServlet. Il est alors possible d'éditer les propriétés suivantes :

Pour chaque extension, il faut également qu'il y ait la configuration d'un objet implémentant org.springframework.web.servlet.HandlerMapping associé. Cela peut être configuré de plusieurs manières :

• Ajouter l'annotation @EnableWebMvc sur une classe ayant l'annotation @Configuration scannée dans le contexte de l'extension;
• Une @Configuration scannée dans l'extension peut étendre la classe org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport.

Chaque extension peut également étendre son comportement MVC en important dans le contexte des Configurations étendant l'interface org.springframework.web.servlet.config.annotation.WebMvcConfigurer. Il est ainsi possible de configurer Tiles avec l'import de com.kosmos.context.CommonTilesConfig.

@Configuration
@Import(CommonTilesConfig.class)
@EnableWebMvc
public class MonExtensionConfig {
    //
}

Modifier le fichier

Gestion des logs

Logback

Ajout de logger dans l'appender

Modification du niveau de logs

Sentry

Prérequis

Afin d'utiliser sentry, les projets doivent ajouter les dépendances suivantes dans leur pom.xml Les versions sont gérées en dependencyManagement dans le pom parent des projets.

<!-- Fournie le support Logback pour Sentry en utilisant un appender pour envoyer les exceptions dans Sentry -->
<dependency>
    <groupId>io.sentry</groupId>
    <artifactId>sentry-logback</artifactId>
</dependency>

<!-- Nécessaire pour utiliser les conditions dans les appender logback -->
<dependency>
    <groupId>org.codehaus.janino</groupId>
    <artifactId>janino</artifactId>
</dependency>

Paramétrage

Deux paramètres doivent être définis pour utiliser sentry :

• sentry.dsn : dsn vers lequel les évènements sont envoyés
• sentry.environment : environement du projet

La présence du sentry.dsn est vérifiée pour activer l'appender.

Les paramètres sentry peuvent être définis

• via le fichier env.properties présent dans le dossier storage/conf :

sentry.dsn=https://mondsn
sentry.environment=dev-ksup-master
sentry.release=7.0

• via les JAVA_OPTS :

-Dsentry.dsn=https://mondsn -Dsentry.environment=dev-ksup-master -Dsentry.release=7.0

Liste des paramètres disponibles :

Appender Sentry

<!-- Appender pour envoyer les logs sur Sentry -->
<if condition='isDefined("sentry.dsn")'>
    <then>
        <appender name="Sentry" class="io.sentry.logback.SentryAppender">
            <minimumEventLevel>${sentry.minimumEventLevel:-ERROR}</minimumEventLevel>
            <minimumBreadcrumbLevel>${sentry.minimumBreadcrumbLevel:-ERROR}</minimumBreadcrumbLevel>
            <options>
                <dsn>${sentry.dsn}</dsn>
                <environment>${sentry.environment:-production}</environment>
                <shutdownTimeout>${sentry.shutdownTimeout:-2000}</shutdownTimeout>
                <flushTimeoutMillis>${sentry.flushTimeoutMillis:-15000}</flushTimeoutMillis>
                <debug>${sentry.debug:-false}</debug>
                <maxBreadcrumbs>${sentry.maxBreadcrumbs:-100}</maxBreadcrumbs>
                <sampleRate>${sentry.sampleRate:-1.0}</sampleRate>
                <attachThreads>${sentry.attachThreads:-false}</attachThreads>
                <attachStacktrace>${sentry.attachStacktrace:-false}</attachStacktrace>
                <serverName>${jvmRoute:-default}</serverName>
                <connectionTimeoutMillis>${sentry.connectionTimeoutMillis:-5000}</connectionTimeoutMillis>
                <readTimeoutMillis>${sentry.readTimeoutMillis:-5000}</readTimeoutMillis>
                <release>${sentry.release:-7.0}</release>
            </options>
        </appender>
    </then>
</if>


<root level="INFO">
    <appender-ref ref="WEBAPP-SIFING-APPENDER"/>
    <if condition='isDefined("sentry.dsn")'>
        <then>
            <appender-ref ref="Sentry" />
        </then>
    </if>
</root>

Modifier le fichier

Gestion des URLs de K-Sup

La fonctionnalité de gestion des URLs permet de disposer pour chaque contenus d'URL propre et spécifique. Cette fonctionnalité permet également d'administrer des URLs courtes.

Fonctionnement

Vue globale

Dans ce schéma on peut voir les différents éléments qui composent la gestion des URLs.

Points d'entrées

Différents acteurs intéragissent avec les URLS (utilisateurs ou acteurs techniques) :

• Enregistrement d'un contenu : quand un utilisateur sauvegarde une rubrique, une fiche ou un site, les URLs qui sont liées à ce contenu sont impactées
• Affichage d'un lien : quand on affiche une page qui fait un lien vers un contenu, il faut savoir quelle URL de ce contenu va être affichée
• Appel d'un lien : à chaque clic sur un lien, on cherche à retrouver le contenu qui lui est associé afin de l'afficher à l'utilisateur
• Flyway : de manière automatique, au premier démarrage de l'application les URLs sont calculées, mais il est également possible de créer des scripts qui vont demander un recalcul
• ScanSite : chaque nuit l'application réalise un traitement sur les URLs (Suppression des urls obsolètes).

Messages spring

À chaque enregistrement d'un contenu, un message spring est lancé sur le canal de communication global de l'application. Des écouteurs ont été mis en place afin d'identifier ceux qui intéressent le calcul d'URL.
Ils sont filtrés par des sélecteurs afin d'éviter les recalculs non nécessaires.

Traitements

Les différents éléments seront détaillés plus bas, voici comment on peut les résumer :
SlugTransfomer : S'occupe de transformer le slug saisie par l'utilisateur pour le faire "entrer dans le moule K-sup"
MakeUrlUnique : Se charge de vérifier l'unicité d'une URL et le cas échéant d'ajouter un incrément
UrlStatusProvider : Élément calculant le status d'une URL
ReservedUrlManager : Gestionnaire des URLs techniques ou non réservées par l'application

Modèle Objets

On distingue deux tables dans la base de données pour l'enregistrement des données liées aux URLs.

En complément de ces deux tables, il faut noter la présence d'un champs SLUG dans les différentes tables liées aux différents contenus de l'application (RUBRIQUE, METATAG, ARTICLE ...).

Table URL

Table principale de la gestion des URLs.

Table URL_REDIRECT

Table permettant de tracer les appels des URLs de redirection.

Services et accès à la base de données

Pour accéder aux données de la base, une couche classique de service et de DAO a été mise en place pour les deux tables citées ci-dessus.
Une particularité a cependant été mise en place concernant la création d'instance d'UrlBean. Il n'est pas possible de créer de telles instances. Pour créer un UrlBean, il faut passer par le UrlBeanBuilder qui réalise des vérifications au moment de la création de l'instance. Cette dernière classe renseigne également de manière automatique certaines données lorsqu'elles sont nécessaires (date de modification, date de création, hash, id, première visible)

ContentController

La classe ContentController est le point d'entrée principal de l'application. Chaque fois qu'une URL de contenu est appelée, c'est ce controller qui répond. Il se charge de récupérer depuis la base de données l'URL appelée et de renvoyer, en fonction du contenu qui lui est associée, la page correspondante.
C'est également ce controller qui se charge de réaliser la redirection dans le cas de l'appel d'une URL au statut redirect.
Enfin, si aucune URL n'est trouvée, ou si son statut ne permet pas un affichage, il se charge de renvoyer une erreur 404.

UrlProvider

L'URLProvider est l'élément qui se charge de fournir une URL quand on cherche à afficher un lien vers un contenu (par exemple dans une liste de fiches, ou un lien dans un menu etc).
Afin de répondre aux différentes règles métier de l'affichage d'une URL, une chaîne de responsabilité a été mise en place. Chaque maillon de la chaîne de responsabilité est un enfant de la classe abstraite UrlProviderProcessor. Chacun se charge de vérifier dans un premier temps s'il est en mesure d'appliquer sa règle métier, si ce n'est pas le cas, il passe la main au maillon suivant. S'il peut y répondre, il applique sa règle et renvoie l'URL.

C'est la classe UrlProviderChainController qui se charge du rôle de chef d'orchestre. Il crée la chaîne de responsabilité dans un ordre précis et identifie les points d'entrées possibles (avec ou sans rubrique forcée) afin de proposer les différents modes de calcul.

Enfin, UrlProvider est le point d'entrée à ce module. Il est d'ailleurs la seule classe visible du package contenant l'ensemble des classes présentes ci-dessus.

Module d'écoute des actions

Grâce au tissage d'aspect, un grand nombre d'actions effectuées sur l'application sont interceptées et transmettent des messages sur un canal de communication globale à l'application. Il est possible de voir l'ensemble des écouteurs présents dans le fichier publish-interceptor.xml.

Des écouteurs sont présents dans l'application, ceux-ci écoutent les messages qui passent sur ce canal principal, et quand un message les intéresse, il lance une action. C'est le cas pour les URLs à travers le fichier url-subscribe.xml.

Cependant, afin de s'assurer que les actions nécessitent un recalcul d'URL, des filtres sont appliqués, sur la base des informations présentes dans le message transmis, les messages qui intéressent le calcul d'URL.
Par exemple la modification du contenu d'une toolbox n'intéresse pas le calcul d'URL, en revanche la modification de son slug implique directement ses URLs.

Ces objets sont les message selector. Il en existe un pour chaque contenu pouvant impacter les URLs :

• MetatagUrlSelector
• SectionUrlSelector
• SiteUrlSelector

Ceux-ci se chargent donc de vérifier si la DSI ou le slug ou les niveaux montant et descendant des sites etc ont été modifiés.

Transformation de slug

De manière historique, tous les caractères ne sont pas autorisés dans les URLs. Certains vont être transformés, d'autres supprimés.
Ci-dessous la table d'association des caractères :

Pour réaliser ceci, des objets de transformation de caractère ont été créés.

L'interface CharacterTransformation défini comment un objet de transformation doit être écrit. On a donc deux objets de transformation possibles, ceux qui prennent en entrée une fourchette de caractères, et ceux qui prennent un ou plusieurs caractères.
La classe CharacterTransformer instancie les différent éléments de transformations. Enfin SlugTransformer, qui est le point d'entrée de cette fonctionnalité, transforme l'ensemble des caractères d'une chaîne qu'on lui transmet.

Gestion de l'unicité des URLs

Un composant en particulier s'occupe de l'unicité des URLs, il s'agit de MakeUrlUnique. Il prend en paramètre une URL, et se charge de regarder s'il existe déjà une même URL. Si c'est le cas, un incrément est ajouté à la fin de l'URL jusqu'à ce qu'on se retrouve avec une URL qui n'existe pas.
Un incrément max (9999) est déclaré dans la classe afin d'éviter d'itérer sur l'URL à l'infini.

Gestion des URLs réservées de l'application

Au sein de l'application il existe trois types d'URLs réservées :

• Les URLs réservées par paramétrage, il est possible d'en ajouter via un ListToAddBean sur la liste parametrizedReservedUrlList du bean reservedUrlManager
• Les URLs techniques réservées, il s'agit de toutes les URLs des différents controllers de l'application ainsi que les URLs de base des différentes extensions
• Les URLs de site réservées. Ces URLs sont déclarées directement sur la configuration des sites et permettent de bloquer certaines URLs à toute utilisation par une fiche.

Fournisseur de première rubrique visible

La classe FirstVisibleCalculator est appelée directement par l'UrlBeanBuilder dans le but de fournir une première rubrique visible. Elle se charge de remonter l'arbre de la rubrique de l'URL afin de déterminer quelle est la première rubrique parente visible.

Fournisseur de statut d'URL

Cette fonctionnalité permet de fournir un statut pour une URL.

Deux classes sont visibles dans ce package, UrlStatus qui est l'énumération proposant les différents statuts (voir Définition des statuts), et UrlStatusProvider qui est le point d'entrée du calcul de statut.
Dans le schéma ci-dessus on peut voir les interconnexions entre les différents éléments. Quand une des classe n'est pas en mesure de répondre elle va appeler la classe en-dessous elle pour lui demander de fournir un statut à l'URL.

Calcul des URLs

Le calcul des URLs est un traitement coûteux en terme de ressource. L'idée est que ce traitement soit fait au moment de l'enregistrement des contenus afin qu'au moment de sa consultation, aucun traitement de recalcul d'URL ne soit effectué.

Points d'entrées et relais

Le point d'entrée principal du calcul d'URL est la classe CalculateUrlTaskListener. C'est cette classe qui est appelée quand un message (voir module d'écoute des actions) est intercepté et accepté par le module. Elle se charge alors de relayer l'appel vers l'objet de traitement qui correspond.
FullCalculateUrlTask est également un point d'entrée, celui-ci peut être appelé par flyway, mais il est surtout appelé par le job de recalcul d'URL disponible dans le backoffice.

Ce schéma permet de tracer comment les appels sont relayés jusqu'aux principaux services opérants CalculateSectionUrl, CalculateContentUrl et ServiceUrl.

Généralités à propos du calcul

Que ce soit pour le calcul d'URL de rubrique ou de fiche, la même manière de procéder est utilisée. On calcul dans un premier temps la liste des URLs impactées par la modification à l'origine du calcul sans s'intéresser aux URLs déjà présentes en base, puis cette liste est synchronisée (c'est à dire mise en conformité avec les données existantes puis sauvegardée) avec les données de l'application.
Durant ce traitement les URLs à synchroniser sont groupées par fiche afin de conserver une cohérence forte au moment du calcul.

CalculateContentUrl

Cette classe comporte deux traitements, un de suppression (removeUrlForContent) appelé au moment de la suppression effective de la fiche, un de calcul (calculContentUrl) appelé à la modification d'une fiche. Il prend en paramètre le metatag avant et après la modification à l'origine de l'exécution de la méthode.

Ci-dessous le détail du traitement de calcul d'URL :

Dans la première partie de ce traitement on calcul les urls impactées par la modification en question. Pour ce faire les différentes rubriques de la fiche sont récupérées puis des URLs sont générées pour celles-ci. Des cas particuliers liés aux différentes rubriques sont gérés au passage de ce traitement.
Le traitement de synchronisation est ensuite appelé, voir la section détaillant son fonctionnement.

CalculateSectionUrl

Ce traitement fonctionne sensiblement de la même manière que celui vu précédemment. Sa particularité réside dans le fait que sa complexité ne se situe pas au niveau du calcul des URLs du contenu car une rubrique n'a qu'une seule URL visible. Sa complexité se situe dans l'impact qu'il a sur l'ensemble des autres URLs.
En effet, dans la mesure ou le slug de la rubrique modifiée peut apparaître dans un grand nombre d'URL de différents contenus, il faut avoir en tête de notifier tous les contenus impactés par les changements sur la rubrique.
C'est ce qu'on peut voir dans la seconde partie du traitement, la méthode doSectionNiveauSuivant va remonter l'arbre des rubrique pour effectuer le traitement de recalcul sur les rubriques parentes et les contenus qui leur sont liés, et ce de manière récursive.

ServiceUrl

Le ServiceUrl permet de réaliser un trop grand nombre d'actions :

• Échanges avec la base de données autour de la table URL
• Calcul d'impact (affichage de popin lors de modification de contenus en backoffice)
• Synchronisation des URLs
• etc

Par souci de simplicité (sic), nous détaillerons ici que la partie synchronisation. Le point d'entrée de cette fonctionnalité est la méthode synchronizeUrlList qui s'attend à recevoir les URLs à synchroniser groupées par metatag (il peut y avoir un groupe d'URL sans metatag pour les URLs de rubrique).
L'utilité d'avoir les URLs regroupées est que pour chaque groupe on va pouvoir déterminer en une seule fois quelle est l'URL canonique du groupe d'URL. La synchronisation peut provoquer une modification d'URL canonique pour la fiche liée, dans ce cas, un recalcul est demandé par notification.
Pour chaque URL, quelle soit dans un groupe de metatag ou non, la méthode synchronizeUrl est appelée.

synchronizeUrl

Dans un premier temps, la méthode tente de repérer s'il existe une URL dans la base de données qui pourrait être ré-utilisée pour la nouvelle URL. Cela permet d'éviter d'ajouter un incrément sur des URLs quand cela n'est pas nécessaire et de traiter au passage les URLs qui n'auront plus lieu d'être après le traitement. Si l'URL réutilisée était de type canonique, alors elle est destituée (c'est à dire passée au statut "en ligne") de son statut avant d'être ré-utilisée.
C'est également à ce moment que l'URL est rendue unique en appelant MakeUrlUnique.
Ensuite l'URL est sauvegardée. Si elle est possède un statut canonique, on informe toute ses soeurs (URL pointant sur la même fiche) qu'il y a une nouvelle canonique à référencer. S'il existe des URLs au statut "redirect" pointant sur la même rubrique et, dans le cas d'une URL de type fiche, la même fiche, alors on les informe toutes qu'elles doivent rediriger vers l'URL qui vient d'être créée.

Gestion des anciennes URLs

Afin de gérer les montées de version des applications présentent en prod avant la 6.7, un job de calcul des anciennes URLs a été mis en place, FullCalculateOldUrlTask. Celui-ci se charge de créer des URLs de type redirection vers les nouvelles URLs.
Dans le cas où certaines URLs seraient manquantes, le filtre OldUrlFilter écoute toutes les URLs correspondant au format d'avant la 6.7 et tente de rediriger vers la fiche censée lui correspondre.
Il est important de noter que pour fonctionner, ce job nécessite d'avoir l'ancien format de paramétrage des URLs dans sa configuration :

# Affichage des rubriques dans les urls
site.code_site.reecriture_rubrique_mode = 2
# Niveau à partir duquel la rubrique est précisée dans l'url
site.code_site.reecriture_rubrique_min = 100
# Niveau maximum pris en compte dans l'url Ex : /rub_min/rub_xxx/rub-yyy/rub_max/ma-page.htm
site.code_site.reecriture_rubrique_max = 100

Paramétrage

Propriétés

Configuration dans l'application

Modifier le fichier

Propriété dsi.activation

Présentation

La propriété dsi.activation permet d'activer ou désactiver globalement les fonctionnalités DSI dans K-Sup :

• affichage des écrans/onglets liés à la DSI
• prise en compte des règles de restriction de contenus et de rubriques
• synchronisation de groupes DSI, etc.

Configuration

Utilisation

Diffusion/restriction de contenu

Back Office – Saisie/Consultation de fiches

Initialise et affiche l’onglet/champs de diffusion (PUBLIC_VISE_DSI, PUBLIC_VISE_DSI_RESTRICTION, DIFFUSION_MODE_RESTRICTION), et applique les contrôles de ces champs lors de l’enregistrement.

Références :

• ControleurUniv.preparerPrincipal()
• ControleurUniv.traiterEnregistrementDiffusion(...)

Back Office – Saisie des rôles/permissions

Ajoute l’onglet Diffusion et les permissions techniques dsi dans l’édition de rôles quand la propriété est active.

Références :

• SaisieRole.preparerPRINCIPAL()

Back Office – Saisie des rubriques

Ajoute l’onglet Restriction(s) d'accès dans l’édition des rubriques quand la propriété est active.

Références :

• rubrique_saisie.jsp

Back Office – Saisie des groupes DSI

Active la saisie du champ Type dans l'écran d'édition de groupe DSI.

Références :

• groupedsi_saisie.jsp

Back Office - Saisie des services externes

Active la saisie des Restrictions dans l'écran d'édition de service externe.

Références :[

• preferences_service.jsp

Désactivation du contrôle d’accès aux contenus en front office

La désactivation de la propriété dsi.activation permet de court-circuiter la vérification DSI lors de la lecture d'un contenu.

Références :

• ServiceContent.controlerRestriction()
• FicheUnivMgr.controlerRestriction()

Désactivation des contraintes des DSI dans la recherche SQL

La propriété dsi.activation alimente la constante ACTIVATION_DSI dans la classe ConstanteSQL.

La désactivation de celle-ci désactive la vérification des contraintes DSI dans les requêtes SQL effectuées par :

• RequeteurFiches.select()
• RequeteSQLHelper.getRequeteGenerique()

Autres usages

Front office – FrontOfficeBeanUtil

La propriété dsi.activation alimente l'attribut activationDSI du bean FrontOfficeBean.

Cet attribut est utilisé pour :

• Affichage du menu intranet sur le template legacy
• Alimenter l'attribut dsi du bean FrontOfficeBean, l'attribut est à true si la DSI est active et que l'utilisateur est connecté.

L'attribut dsi est utilisé pour :

• Ajouter une classe connecte dans la liste des classeBody du template legacy
• Ajouter une classe edition_fiche sur le formulaire de saisie front

Synchronisation automatique des groupes DSI

La désactivationde la propriété dsi.activation désactive la création/synchro automatique des groupes DSI basés sur la structure, même si la synchro structure est activée par ailleurs.

Références :

• SynchroGroupedsiStructure.synchroniserGroupeDsi()

Modifier le fichier

Gestion des médias

Modèle objet

Les médias sont gérés avec deux objets :

• Media
  • Table MEDIA
  • Contient toutes les informations décrivant le média :
    • Titre, légende, description, ...
    • Type de ressource : audio, fichier, photo, svg, flash
    • Source : Nom du fichier source
    • Url : Nom du fichier stocké sur disque
• Ressource
  • Table RESSOURCE
  • Enregistre le lien entre le média et le contenu qui l'utilise
  • La ressource porte les informations suivantes
    • L'idMedia : id du media
    • codeParent : Code calculé permettant de retrouver le contenu utilisant le média
    • etat : Etat de la ressource permettant la gestion de son cycle de vie
    • ordre :

Ajout d'un média

Ajout et utilisation d'un média dans la médiathèque

Lorsqu'un média est ajouté dans la médiathèque, celui-ci devient automatiquement public. Le média sera consultable sans vérification de permission. Le média pourra être utilisé sur toute l'application par les contributeurs. Lorsqu'un média est inséré dans un contenu (toolbox par exemple), un enregistrement sera créé dans la table ressource.

Ajout et utilisation d'un média hors médiathèque

Le média peut être directement ajouté dans un contenu (via la toolbox par exemple). Suivant la configuration de l'environnement (via la propriété mediatheque.secure.xxx) l'accès au média sera contrôlé en fonction des permissions de l'utilisateur (pas d'accès public). Dans tous les cas, le média ne pourra pas être utilisé sur plusieurs contenus.

• Si la propriété mediatheque.secure.xxxx est égale à 1, alors il n'y a pas de vérification de permission (meilleure performance)
• Si la propriété mediatheque.secure.xxxx est égale à 2, alors une vérification des permissions est effectuée à chaque appel en fonction des droits de l'utilisateur. Le média porte les restrictions de son contenu l'utilisant (restriction d'une fiche ou restriction d'une rubrique). Lors de l'ajout d'un média, un enregistrement dans la table ressource est effectué afin d'identifier où est utilisé le média.

Remarque sur les Tags medias [id-image] et [id-fichier]

Au cours de la vie du code, le format des médias a évolué. Certains contenus contiennent des anciens format de tag. Aucun traitement de reprise des données n'ayant été effectué, les traitements manipulant des contenus de toolboxes doivent impérativement prendre en compte les formats suivants:

• [id-image]1234567890[id-image]
• [id-image]F1234567890[id-image]
• [id-fichier];1234567890[id-fichier]
• [id-fichier]1234567890;[id-fichier]
• [id-fichier]1234567890;INLINE[id-fichier]

La méthode publique ParserRequete.parseRessources tient compte de ces différents format. Elle peut être utilisée pour extraire la liste des médias d'un contenu de toolbox. En fonctionnement standard, cette méthode est appelée lors de la soumission d'une contribution. Cela permet d'jouter dans l'infoBean deux collections pré-initialisées avec les médias détectés dans les toolboxes : contentNewRessources et contentOldRessources.

/!\ Les autres (anciens) tags médias (legende_image, title-image, ..), ne sont pas gérés par cette méthode /!

Optimisation de l'espace de stockage

Le format image/webp

Le nouveau format image/webp permet de reduire considérablement la taille de certaines images sans perte notoire de qualité. Un mécanisme a été mis en place dans K-Sup pour enregistrer automatiquement les images au format webp.

Ce mécanisme est contrôlé grace à la propriété "mediatheque.photo.output.format" qui permet de spécifier un format unique d'enregistrement des medias (image/webp par défaut). Si cette valeur est surchargée à vide par un projet, cela désactive la fonctionnalité. cf mediatheque.photo.output.format, mediatheque.photo.excluded.format, mediatheque.photo.output.quality et mediatheque.photo.output.compression dans le fichier medias-properties.md)

Note sur l'orientation Exif

Certains fichiers peuvent contenir un Exif d'orientation indiquant le sens réel d'affichage d'une image.

Il existe 8 orientations possibles :

1. 0 degrees: the correct orientation, no adjustment is required.
2. 0 degrees, mirrored: image has been flipped back-to-front.
3. 180 degrees: image is upside down.
4. 180 degrees, mirrored: image has been flipped back-to-front and is upside down.
5. 90 degrees, mirrored: image has been flipped back-to-front and is on its side.
6. 90 degrees: image is on its side.
7. 270 degrees: image has been flipped back-to-front and is on its far side.
8. 270 degrees, mirrored: image is on its far side.

Lorsque l'image est enregistrée sans optimisation webp, les informations exif sont conservées.
Cependant, toute réécriture de l'image (rotation, redimensionnement ou crop) entraine la perte des informations exif.
A cet effet, un traitement de redressement est appliqué à l'image avant réécriture en webp ou transformation de l'image.

Modifier le fichier

Paramétrage de la gestion des médias

Le paramétrage de l'extension est réalisé dans le fichier core.properties.

Surcharge

La surcharge des propriétés peut se faire en créant un fichier :

• application_xxx.properties dans les sources d'un projet
• env.properties dans le répertoire de configuration d'un environnement (référencé par la propriété conf.dir)

Propriétés

Modifier le fichier

Les processus K-Sup

Point d'entrée

Le point d'entrée pour tous les processus de K-Sup est la servlet SGController. SGContoller effectue une appel à TraitementRequeteHTTP#traiterRequeteHTTP qui renvoie un objet de type ResponseEntity/ModelAndView.

TraitementRequeteHTTP#traiterRequeteHTTP permet de générer le flux retourné par le SGController en fonction du type de flux attendu URL/JSP/XML/HTML/Objet sérialisé.

Affichage d'un flux JSP

Dans le cas d'un flux de type JSP, le viewAdapterSelector pouvant prendre en charge la requête courante est récupéré et son adapter est appelé afin de généré le flux attendu.

L'affichage des écrans de processus back-office sont gérés par le DefaultViewAdapter qui génère le flux de retour à partir de la jsp correspondant au processus et l'écrit directement dans la réponse. Une ResponseEntity.ok() est retournée au controller.

Les Selector

Les Selector sont des beans ordonnés qui étendent AbstractViewAdapterSelector.
Chaque selector prend en charge un contexte, connu à partir de la requête courante.

public boolean accept(final HttpServletRequest request) {
    ...
}

Le selector est directement lié à un ViewAdapter qui est en charge de généré le flux attendu.

public abstract class AbstractViewAdapterSelector<R extends AbstractViewAdapter<?>> implements Selector<HttpServletRequest> {}

Les Adapter

Les Adapter étendent AbstractViewAdapter.
Ils définissent un méthode process en charge de généré le flux de retour pour l'affichage du processus.

public class MonViewAdapter extends AbstractViewAdapter<ModelAndView> {

    @Override
    public ModelAndView process(final DescriptifPageRetour desc, final HttpServletRequest req, final HttpServletResponse res, ProcedureBean bean) {
        ...
    }
}

Modifier le fichier

Paramétrage du HTTPS dans l'usine à sites

Par défaut le HTTPS est activé sur tous les sites créés dans l'usine à site.

Afin de pouvoir lancer des environnements locaux (*.localhost) sans certificat, une propriété permet de surcharger le comportement par défaut.

en ajoutant la valeur

site.secure=false 

dans votre env.properties, le HTTPS sera désactivé par défaut.

Modifier le fichier

Insertion de liens dans la toolbox

Style d'affichage des liens

Lors de l'insertion d'un lien dans la toolbox, il est possible de choisir l'apparence du lien. Une liste déroulante "Apparence du lien" présente en bas de la modal d'insertion, permet de choisir l'apparence à appliquer.

Un bean linkStyleManager est défini dans le fichier core-ckeditor.xml pour définir les styles de liens disponibles:

    <bean id="linkStyleManager" class="com.kosmos.content.link.view.LinkStyleManager">
        <property name="styles">
            <map>
                <entry key="style-default" value="Par défaut" />
                <entry key="style-bouton" value="Lien bouton" />
            </map>
        </property>
    </bean>

La clé de chaque entrée correspond à la classe CSS à appliquer au lien. La valeur correspond au libellé affiché dans la liste déroulante.

Ajouter un style de lien

Pour ajouter un style de lien, il suffit de déclarer une nouvelle entrée dans le bean linkStyleManager en définissant la classe CSS à appliquer et le libellé à afficher.

    <bean id="mapToAddlinkStyleManager" class="com.kportal.core.context.MapToAddBean">
        <property name="idExtensionToMerge" value="core"/>
        <property name="idBeanToMerge" value="linkStyleManager"/>
        <property name="mapToMerge" value="styles"/>
        <property name="add">
            <map>
                <entry key="style-bouton-2" value="Lien bouton coloré"/>
            </map>
        </property>
    </bean>

Il faut ensuite déclarer le css correspondant dans les fichiers du projet.

a[data-style="style-bouton-2"] {
    background-color: #f00;
    color: #fff;
    padding: 10px 20px;
    border-radius: 5px;
    text-decoration: none;
}

Modifier le fichier

jsTree avec Multiselect

Dans le cas d'un jsTree multiselect, le chargement initial est fait de manière asynchrone.

En effet, la valeur du champ SELECTED de l'URL peut-être extrêment longue si beaucoup d'éléments sont sélectionnés. Les URLs étant limitées en longueur, il a été nécessaire de changer le chargement dans ce cas précis en le rendant asynchrone pour :

• les groupes
• les rubriques
• les structures

Les autres données représentées en arbre n'étant pas en multiselect.

Mécanisme

Avant le chargement de l'iFrame, deux variables sont ajoutées aux sessionStorage en javascript :

sessionStorage.setItem('jsTreeSelection', $input.val()); // Valeur de la sélection
sessionStorage.setItem('jsTreeInitUrl', $component.data('urlinittree')); // URL de chargement des données

• jsTreeSelection : contient la liste des éléments sélectionnés dans l'arbre
• jsTreeInitUrl : contient l'URL du endpoint permettant de récupérer l'initialisation de l'arbre

Coté jsTree, au chargement, si une variable de session jsTreeSelection existe alors, l'URL jsTreeInitUrl est appelée en POST avec en body la valeur de jsTreeSelection. Les variables sont immédiatement supprimées pour éviter de se chevaucher entre deux utilisations de jsTree.

Le résultat permet d'initialiser l'arbre en ouvrant les nœuds nécessaires et en cochant les nœuds sélectionnés.

Un overlay avec un spinner est affiché le temps de ce chargement afin d'indiquer à l'utilisateur de patienter.

Initialisation de l'arbre

Il y a deux méthodes d'initialisation de l'arbre

setState

L'utilisation de set_state du jsTree. Les données injectées sont seulement les états des différents nœuds : sélectionné et/ou ouvert.

setData

L'utilisation de create_node du jsTree. Les données injectées sont complètes, c'est à dire qu'il y a l'état ET les données des nœuds (texte, ID, etc.)

Modifier le fichier

Construction des données JSON-LD

Introduction

Le format JSON-LD est un format de données structurées basé sur le format JSON. Il permet de décrire des données de manière structurée et de les rendre plus facilement interprétables par les machines. Il est notamment utilisé pour décrire des données sémantiques sur le web.

Syntaxe

La syntaxe JSON-LD est basée sur le format JSON. Elle permet de décrire des données sous forme de graphes.

Un document JSON-LD est un objet JSON qui contient un champ @context qui définit le contexte du document. Le contexte permet de définir des abréviations pour les termes utilisés dans le document.

Voici un exemple de document JSON-LD :

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type":"WebSite",
      "url":"http://www.ksup7.localhost:8080/",
      "name":"www",
      "description":"La baseline",
      "inLanguage":"fr"
    }
  ]
}

Construction des données

La classe AbstractViewModel possède un attribut jsonLdModels qui permet de stocker les modèles JSON-LD (JsonLdModel) associés à la vue.

La liste des modèles JSON-LD est alimentée par le view preparer AbstractViewPreparer qui implémente la méthode prepareJsonLdModels.

public List<JsonLdModel> prepareJsonLdModels(final FrontContext frontContext, final V viewModel) {
    
}

Chaque vue possédant des données JSON-LD doit implémenter la méthode prepareJsonLdModels et appelée celle-ci dans la méthode prepare.

Modélisation des données

Pour modéliser les données JSON-LD, une classe AbstractJsonLdModel est fournie. Cette classe abstraite implémente l'interface JsonLdModel et contient les attributs @type et @id communs à la plupart des modèles JSON-LD.

/**
 * Classe abstraite des modèles JsonLd.
 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public class AbstractJsonLdModel implements JsonLdModel {

    @JsonProperty("@type")
    protected String type;

    @JsonProperty("@id")
    protected String id;

    public String getType() {
        return type;
    }

    public void setType(final String type) {
        this.type = type;
    }

    public String getId() {
        return id;
    }

    public void setId(final String id) {
        this.id = id;
    }
}

Récupération des données

La classe AbstractViewModel possède une méthode getAllJsonLdModels qui permet de récupérer la liste de l'ensemble des modèles JSON-LD associés à la vue finale.
Elle possède également une méthode serializeJsonLdModels qui permet de sérialiser les modèles JSON-LD en une chaîne de caractères JSON, cette méthode va demander à chaque viewModel de sérializer ses données JSON-LD via la méthode serialize.

Le handler de contenu ajoute les données JSON-LD à la vue dans la méthode getModelAndView de la facon suivante :

modelAndView.addObject(JSONLD_MODEL, viewModel.serializeJsonLdModels());

Un view preparer JsonLdViewPreparer est également ajouté pour ajouter les données JSON-LD à la vue finale.
Ce view preparer ajoute une vue de type jsonld qui insère les données JSON-LD dans une balise <script>.

/WEB-INF/jsp/seo/jsonld/jsonLd.jsp :

<script type="application/ld+json">
{
    "@context": "https://schema.org",
    "@graph": ${jsonLdModel}
}
</script>

Modifier le fichier

Gestion des libellés

Modifier le fichier

Paramétrage des libellés

Plusieurs propriétés permettent de configurer / adapter les libellés.

Surcharge

La surcharge des propriétés peut se faire dans les fichiers de surcharge du core.

Propriétés

Modifier le fichier

Migration de colonnes texte avec AbstractTextColumnsProcessor

Vue d’ensemble fonctionnelle

AbstractTextColumnsProcessor est une base de migration Flyway (Java) dédiée aux colonnes texte des tables applicatives. Elle permet de:

• Parcourir automatiquement toutes les tables (sauf exclusions configurées) et détecter les colonnes “texte”.
• Pour chaque ligne, transformer le contenu des colonnes texte:
  • Si la valeur est un JSON “wrappeur” (string commençant par { et finissant par }), extraire les valeurs texte et leur appliquer une transformation HTML, puis ré-encoder le JSON.
  • Sinon, considérer la valeur comme du HTML et l’envoyer à une transformation HTML spécialisée.
• Vérifier l’intégrité “fonctionnelle” du contenu après transformation (pas de perte de texte visible) et, en cas d’échec, conserver la valeur d’origine.
• Mettre à jour en base uniquement les lignes modifiées, avec logs détaillés.

Les classes concrètes définissent:

• La logique de transformation HTML (processHtmlContent).
• Le prédicat SQL ciblant uniquement les lignes susceptibles d’être impactées (buildColumnPredicat).

Des exemples existants:

• V7_3_1_6__migration_grilles: migration des grilles CKEditor -> nouveau layout.
• V7_3_1_10__migration_accordeons: migration d’anciens accordéons <dl/dt/dd> vers <details>.
• V7_3_1_7__migration_styles, V7_3_1_8__migration_styles_v2, V7_3_1_9__migration_onglets: mêmes patterns pour d’autres structures.

Architecture et flux d’exécution (technique)

1. Initialisation Flyway

   • La classe étend BaseJavaMigration et implémente migrate(Context). Flyway l’exécute au moment des migrations (au démarrage).

2. Sélection des tables à traiter

   • listAllTables(Connection): récupère l’ensemble des tables via les métadonnées JDBC.
   • Exclusions: la propriété text_column_processor.excluded_tables (chargée via PropertyHelper) peut contenir une liste de tables à ignorer, séparées par des virgules.
     • Exemple de configuration (fichier env.properties de l’environnement):

       text_column_processor.excluded_tables=HISTORIQUE_LOGS,TMP_IMPORT
       

3. Détection des colonnes texte

   • listTextColumns(Connection, String table):
     • Tente un SELECT * FROM {table} LIMIT 1 et lit le ResultSetMetaData.
     • Est considérée comme “texte” une colonne dont le type JDBC est LONGVARCHAR, ou de type VARCHAR d’une taille supérieure à un seuil minimal, ou dont le type contient TEXT.
     • Seuil configurable au niveau de la classe via le champ protégé minimumColumnSize (valeur par défaut: 1024). Une classe fille peut l’ajuster si nécessaire.
     • Exclut systématiquement la colonne identifiant ID_{TABLE}.

4. Construction des requêtes SQL

   • buildQuerySelect(table, columns): construit le SELECT avec ID_{table} + colonnes texte, et y ajoute une clause WHERE construite par buildColumnPredicat(table, columns) (spécifique à la classe fille).
   • buildQueryUpdate(table, columns): construit un UPDATE avec paramètres, du style UPDATE {table} SET col1=?, col2=?, ... WHERE ID_{table}=?.
   • buildColumnPredicat(Set<String> columns, String needle): utilitaire générique pour produire une clause WHERE (col LIKE '%needle%' OR ...), avec échappement des ' dans needle.

5. Traitement ligne par ligne

   • Pour chaque ligne du SELECT:
     • On lit l’ID (getIdValue) et chaque colonne texte.
     • processColumn(col, oldVal) décide de la voie:
       • JSON wrappeur ? (isJsonWrapped(value): valeur non vide, trim, commence par { et finit par }): processJsonWrappedContent(col, value)
         • Parse via CodecJSon.decodeStringJSonToClass en Map<String, Object>.
         • Pour chaque valeur de type String, applique processHtmlContent(html).
         • Re-encode le JSON via CodecJSon.encodeObjectToJSonInString.
       • Sinon: processHtmlContent(value) directement.
     • Si la valeur a changé et que l’intégrité est validée, on UPDATE la ligne.

6. Vérification d’intégrité

   • verifyContentIntegrity(originalValue, processedValue):
     • Convertit HTML -> texte via Jsoup.parse(...).text() de part et d’autre.
     • Normalise (suppression \n, \t, espaces; tri des caractères) puis compare.
     • Si l’intégrité échoue et que applyIntegrityVerification est à true (par défaut), la migration pour cette ligne est annulée (on écrit la valeur d’origine), avec un WARN.
     • Une classe fille peut désactiver ce garde-fou en réglant applyIntegrityVerification=false si elle doit effectuer des transformations modifiant intentionnellement le texte visible.

Points d’attention et bonnes pratiques

• Prédicats SQL efficaces

  • Évitez un scan complet des tables: construisez un WHERE qui restreint aux contenus suspects (via buildColumnPredicat(columns, "motif")).
  • Double gestion « non échappé / échappé » si vos motifs peuvent se trouver dans du HTML direct ou du HTML sérialisé en JSON string (voir SEARCH_ESCAPED).

• Intégrité du texte visible

  • Conservez applyIntegrityVerification=true tant que possible. Ne désactivez que si vos transformations changent volontairement le texte (ex. suppression de décorations textuelles devenues obsolètes).

Créer un nouveau script de migration: guide pas-à-pas

1. Étendre AbstractTextColumnsProcessor

   • Implémenter:
     • protected String processHtmlContent(String htmlValue).
     • protected String buildColumnPredicat(String tableName, Set<String> columns).

2. Construire des constantes de recherche

   • Exemple:

     private static final String SEARCH = "<div class=\"old-widget\">";
     private static final String SEARCH_ESCAPED = "<div class=\\\\\"old-widget\\\\\">"; // pour JSON string
     

3. Implémenter buildColumnPredicat

4. Implémenter processHtmlContent

   • Pattern recommandé:

     @Override
     protected String processHtmlContent(final String value) {
         if (!value.contains("old-widget")) {
             return value; // court-circuit
         }
         final Document doc = Jsoup.parseBodyFragment(value);
         setXmlSettings(doc);
         boolean changed = false;
         // Sélectionner précisément ce que vous transformez
         final Elements widgets = doc.select("div.old-widget");
         for (final Element w : widgets) {
             final Element replacement = transformWidget(w);
             if (replacement != null) {
                 w.replaceWith(replacement);
                 changed = true;
             }
         }
         return changed ? doc.body().html() : value;
     }
     
     private Element transformWidget(final Element old) {
         // Construire le nouveau DOM (balises, classes, attributs) en réutilisant le inner HTML si besoin
         final Element container = new Element("div").addClass("new-widget");
         final Element inner = new Element("div");
         inner.html(old.html());
         container.appendChild(inner);
         return container;
     }
     

5. Ajuster les garde-fous si nécessaire

   • Si la transformation modifie le texte visible (suppression de libellés), envisagez this.applyIntegrityVerification = false; (dans un bloc d’initialisation ou un constructeur) avec prudence et justification.
   • Vous pouvez aussi abaisser/augmenter minimumColumnSize si votre migration doit couvrir des VARCHAR plus petits/grands.

Modèle minimal de classe de migration

package com.kosmos.core.migration;

import java.util.Set;
import org.apache.commons.lang3.StringUtils;
import org.jsoup.Jsoup;
import org.jsoup.nodes.Document;
import org.jsoup.nodes.Element;
import org.jsoup.select.Elements;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import com.kosmos.migration.core.executor.AbstractTextColumnsProcessor;

public class V7_3_1_X__migration_mon_widget extends AbstractTextColumnsProcessor {

    private static final Logger LOG = LoggerFactory.getLogger(V7_3_1_X__migration_mon_widget.class);

    // Motifs pour ciblage SQL (HTML direct vs HTML encodé dans JSON)
    private static final String SEARCH = "<div class=\"old-widget\">";
    private static final String SEARCH_ESCAPED = "<div class=\\\\\"old-widget\\\\\">";

    @Override
    public Integer getChecksum() {
        return 1234567890; // fige le checksum Flyway de cette migration Java
    }

    @Override
    protected String processHtmlContent(final String value) {
        if (!value.contains("old-widget")) {
            return value;
        }
        final Document doc = Jsoup.parseBodyFragment(value);
        setXmlSettings(doc);
        boolean changed = false;
        final Elements olds = doc.select("div.old-widget");
        for (final Element old : olds) {
            final Element neo = transformOldToNew(old);
            if (neo != null) {
                old.replaceWith(neo);
                changed = true;
            }
        }
        return changed ? doc.body().html() : value;
    }

    private Element transformOldToNew(final Element old) {
        final Element container = new Element("div").addClass("new-widget");
        final Element inner = new Element("div");
        inner.html(old.html());
        container.appendChild(inner);
        return container;
    }

    @Override
    protected String buildColumnPredicat(final String tableName, final Set<String> columns) {
        final String p1 = buildColumnPredicat(columns, SEARCH);
        final String p2 = buildColumnPredicat(columns, SEARCH_ESCAPED);
        if (StringUtils.isEmpty(p1) && StringUtils.isEmpty(p2)) return StringUtils.EMPTY;
        if (StringUtils.isEmpty(p1)) return p2;
        if (StringUtils.isEmpty(p2)) return p1;
        return p1 + p2.replace(" WHERE ", " OR ");
    }
}

FAQ / points spécifiques

• Et si mon contenu JSON n’est pas un objet au niveau racine ?

  • isJsonWrapped ne reconnaît que les strings démarrant/finissant par {/}. Si vous avez du JSON tableau ou un wrapper différent, ajustez isJsonWrapped dans une sous-classe (ou surchargez processColumn).

• Puis-je désactiver l’intégrité uniquement pour une colonne ?

  • Le garde-fou est global à l’instance. Pour un contrôle plus fin, surchargez processColumn pour décider au cas par cas si l’intégrité doit bloquer la migration et retournez la valeur d’origine si besoin.

• Et si ID_{TABLE} n’existe pas ?

  • getIdValue tente ID_{TABLE} puis, en fallback, la première colonne du ResultSet. Si aucune n’est accessible, la ligne est ignorée (pas d’UPDATE possible).

Modifier le fichier

Notes sur la prévisualisation dans K-Sup (aperçu)

Au clic sur le bouton "prévisualiser" (ou aperçu en front), le formulaire de saisie est soumis en ajax. L'action est préalablement positionnée à la valeur "ENREGISTRER" et un flag "APERCU" est ajouté au formulaire. Les données soumises sont validées par le processus idoine.

On analyse ensuite le retour Json Le retour est de la forme {"result": "OK", "preview": "https://www.ksup.org/apercu/12345"} ou {"result": KO", "messages": "La date est invalide"}```

• si le resultat est OK, on ouvre un nouvel onglet pour visualiser l'URL de preview
• si le resultat est KO, on clippe les message d'erreur dans la zone prévue dans l'écran courant.

Ce fonctionnemnt permet de n'ouvrir l'onglet d'aperçu qu'au dernier moment et la page en cours d'édition reste synchrone avec l'infobean.

Modifier le fichier

Gestion de la recherche anonyme de K-Sup

Description de la fonctionnalité

La fonctionnalité de recherche anonyme permet d'effectuer une recherche de fiches hors du périmètre de l'utilisateur. L'utilisateur ne doit pas pouvoir éditer la fiche mais doit pouvoir contribuer un lien vers la fiche par exemple à l'aide du tag de toolbox "lien".

Paramétrage

La recherche anonyme s'active pour chaque type de fiche avec la propriete fiche.NOM_OBJET.recherche_anonyme, les valeurs possibles sont les suivantes :

• recherche anonyme=0 pas de recherche anonyme autorisée
• recherche anonyme=1 recherche anonyme autorisée

Activation de la recherche anonyme

Le déclenchement de la recherche anonyme est piloté par le service OutscopedSearchService.

Ce service est initialisé avec une liste de beans qui permettent d'activer ou non la recherche anonyme en fonction d'un paramètre de contexte.

Chaque bean d'activation implémente l'interface OutscopedSearchActivator.

Dès qu'un des activators retourne "true", la recherche anonyme est activée pour le contexte.

Le service vérifie ensuite que la recherche anonyme est possible pour le type de fiche considéré. (par vérification d'une propriété fiche.OBJET.recherche_anonyme valorisée à 1)

Le contexte est porté par le composant lui même. Par exemple, un selecteur de fiche pour un lien vers une fiche sera associé à un UUID de contexte. Un selecteur multifiche sera associé à un autre UUID de contexte. Chaque composant de recherche de fiche (ou écran de recherche de fiche) possède son propre contexte.

La classe com.univ.utils.actiongenerator.ContextZoneAction resense les différents contextes connus.

La recherche anonyme intervient dans les différents datagrids des fiches :

graph
style E fill:#a02020,stroke:#333,stroke-width:1px
erA0(FicheUnivDatagrid) --> B(#traiterRechercheDepuisRequete)
A1(FicheToolboxDatagrid) --> B(#traiterRechercheDepuisRequete)
B --> C(#traiterRequeteAvecControlePerimetre)
C --> D(#initialiserControleBo)
D --> E(OutscopedSearchService#isOutscopedSearchActive)

graph
style F fill:#a02020,stroke:#333,stroke-width:1px
A0(MultiFicheDatagrid) --> B(#traiterRechercheDepuisRequete)
A1(MultiFicheToolboxDatagrid) --> B(#traiterRechercheDepuisRequete)
A2(SaisieFiche  #ECRAN_LOGIQUE#=RECHERCHE) --> C(RechercheMultificheHelper#rechercherParmisToutesLesFiches)
B --> C
C --> D0(RechercheMultificheHelper#rechercheMetaParUrlFiche)
D0 --> E(#verifierDroitVisibiliteFiche)
E --> F
C --> D1(RechercheMultificheHelper#rechercherParCriteresMultiples)
D1 --> F(OutscopedSearchService#isOutscopedSearchActive) 

Tests

Fonctionnalités à tester sur la recherche anonyme :

• Insertion d'une fiche en page d'accueil de rubrique
• Rattachement manuel d'une fiche à une rubrique (kmonoselect)
• Rattachement d'une fiche à une liste manuelle
• Lien interne vers une fiche dans une toolbox
• Rattachement manuel d'une fiche à une fiche (kmonoselect)
• Rattachement manuel de fiches à une fiche (kmultiselect)
• Selecteur de fiche (critère) dans un écran de recherche de fiche (taglink)

Modifier le fichier

Gestion du robots.txt

Le produit expose un controller permettant de générer dynamiquement le fichier robots.txt.

Ce fichier est initialisé à l'aide du fichier webapp-contrib/src/main/resources/default-robots.txt
Le contenu de ce fichier peut être surchargé en projet par environnement depuis le storage.

Il suffit de créer un fichier robots.txt avec le contenu souhaité dans le dossier conf du storage

Par ailleurs, chaque extension (y compris le projet) peut ajouter un contenu spécifique dans le robots.txt généré.
Il suffit pour cela que l'extension expose un fichier robots-xxx.txt à la racine des ressources (src/main/resources) où xxx est l'identifiant de votre extension (ou du projet).

L'ordre de construction du robots.txt généré est le suivant:

• Le fichier default-robots.txt du produit ou le fichier conf/robots.txt du storage en cas de surcharge
• Les fichiers robots-xxx.txt des extensions
• Les références aux fichiers sitemap.

Modifier le fichier

Paramétrage de la saisie

Plusieurs propriétés permettent de configurer / adapter la saisie des fiches ou de certains contenus.

Fiche

Il est possible de spécifier de manière globale ou objet par objet

• si un champ est saisissable
• si un champ est modifiable
• si un champ est facultatif ou obligatoire
• la taille maximmum des champs texte

(cf UnivFmt.java méthode getModeSaisieZone et getMaximumCharLength)

Seuls les champs communs RESUME, THEMATIQUE et PHOTO bénéficient de cette fonctionnalité.

Les propriétés INVISIBLE, MODIFIABLE et FACULTATIF ont une porté au niveau de la source d'import. Dans ce cas, la propriété est de la forme

saisie.{{NOM_DU_CHAMP}}.{{SOURCE_IMPORT}}.INVISIBLE=0

ou pour un type de fiche donné, de la forme

saisie.{{OBJET}}.{{NOM_DU_CHAMP}}.{{SOURCE_IMPORT}}.INVISIBLE=0

Si le paramètrage s'applique quelle que soit la source, la propriété est de la forme

saisie.{{NOM_DU_CHAMP}}.INVISIBLE=0

ou pour un type de fiche donné, de la forme

saisie.{{OBJET}}.{{NOM_DU_CHAMP}}.INVISIBLE=0

Remarque sur le comportement :

• Si un champ renseigné est rendu invisible, il n'est pas effacé au ré-enregistrement de la fiche (et pourrait continuer de s'afficher en front)
• Si un champ passe obligatoire, il faudra le renseigner si on modifie une fiche dans laquelle il est n'est pas renseigné.
• Si on passe obligatoire un champ non modifiable, il ne sera pas possible de le saisir pour les fiches dnas lesquelles il n'est pas renseigné.
• Si on ne saisit pas un champ facultatif non modifiable à la création, on ne pourra pas le renseigner en modification

Surcharge

La surcharge des propriétés par défaut peut se faire dans les fichiers de surcharge du core. La surcharge des propriétés par objet peut se faire dans les fichiers de surcharge des extensions.

Propriétés

Les propriétés peuvent être adaptées par objet pour surcharger les valeurs par défaut

Modifier le fichier

Création d'un script automatisé

Déclaration XML

L'ajout d'un script automatisé nécessite au minimum la définition de deux beans dans le context Spring.

Déclaration d'un bean de type JobModule qui prend plusieurs paramètres :

Exemple de définition d'un JobModule :

<bean id="monScriptJobModule" class="com.kportal.scheduling.module.JobModuleImpl">
    <property name="jobDetails">
        <list>
            <ref bean="monScriptJob"/>
        </list>
    </property>
    <property name="type" ref="TYPE_PARAMETRABLE"/>
    <property name="libelle" value="MON_SCRIPT.JOB_LIBELLE"/>
    <property name="permissions">
        <list>
            <bean class="com.kportal.core.autorisation.Permission">
                <property name="code" value="monScriprJob"/>
                <property name="type" value="SCRIPT"/>
                <property name="actions">
                    <list>
                        <bean class="com.kportal.core.autorisation.ActionPermission">
                            <property name="code">
                                <util:constant static-field="com.kportal.scheduling.util.ScriptsAutomatisesUtil.ACTION_LANCEMENT"/>
                            </property>
                        </bean>
                    </list>
                </property>
                <property name="libelle" value="MON_SCRIPT.JOB_LIBELLE"/>
            </bean>
        </list>
    </property>
</bean>

Déclaration du bean de job qui étend JobDetailFactoryBean qui prend plusieurs paramètres :

Exemple de définition d'un JobDetailFactoryBean :

<bean id="monScriptJob" class="org.springframework.scheduling.quartz.JobDetailFactoryBean">
    <property name="description" value="Description du job"/>
    <property name="jobClass" value="com.kosmos.toto.batch.job.MonScriptJob"/>
    <property name="durability" value="true"/>
</bean>

Création de la classe du job

La classe d'exécution du job doit étendre LogReportJob et implémenter Runnable. Le traitement du job est effectué dans la méthode run().

Exemple de classe d'exécution du job :

public class MonScriptJob extends LogReportJob implements Runnable {
 
    /**
     * Logger.
     */
    private static final Logger LOGGER = LoggerFactory.getLogger(MonScriptJob.class);
 
    /**
     * Constructeur vide.
     */
    public MonScriptJob() {
        super();
    }
 
    /**
     * {@inheritDoc}
     */
    @Override
    public void run() {
        // Implémentation de l'exécution du job
    }
 
    /**
     * {@inheritDoc}
     */
    @Override
    public void perform() {
        run();
    }
}

Utilisation de paramètres pour l'exécution du job

Il est possible de saisir des paramètres lors du lancement d'un script automatique.

Déclaration des paramètres

Les paramètres du job sont passés sous forme de Map au bean de type JobDetailFactoryBean via la propriété jobDataAsMap.

Exemple pour le job déclaré précédément :

<bean id="monScriptJob" class="org.springframework.scheduling.quartz.JobDetailFactoryBean">
    <property name="description" value="Description du job"/>
    <property name="jobClass" value="com.kosmos.toto.batch.job.MonScriptJob"/>
    <property name="durability" value="true"/>
     <property name="jobDataAsMap">
        <map>
            <entry key="parametres">
                <value>param1;param2</value>
            </entry>
        </map>
    </property>
</bean>

Le label du champ de saisie du paramètre est récupéré à partir d'une clé de message portant le nom du paramètre () Il est possible de définir 3 types de paramètre de job différents :

1. Champ de saisie Si le paramètre du job ne contient qu'une clé et une valeur vide, un champ de saisie de type text sera affiché à l'utilisateur afin de saisir la valeur du paramètre.
2. Valeur unique non modifiable Si le paramètre du job ne contient qu'une seule valeur non vide, un champ de saisie non modifiable sera présent avec la valeur renseignée.
3. Liste de valeurs Si le paramètre contient une liste de valeurs, une liste déroulante sera affichée avec la liste des valeurs.

Pour chaque paramètre saisissable une entrée est ajoutée dans la map avec pour clé le nom du paramètre et pour value la liste des valeurs possibles.

Définition de la liste des valeurs

La liste des valeurs pour un paramètre peut être définie de 2 manières : Avec une Map En passant une Map<String, String> en valeur de votre paramètre, la liste déroulante sera alimentée avec pour chaque entrée de la map, la clé en tant que valeur et la value en tant que libellé.

Avec une liste de String Il est possible d'alimenter la liste de valeurs d'un paramètre à partir d'une liste de String, chaque valeur étant séparée par un point virgule :

<map>
	<entry key="parametres">
		<value>param1;param2;param3</value>
	</entry>
</map>

Lors de l'utilisation d'une liste de String, la liste déroulante sera alimentée avec pour valeurs les différentes chaine de caractères séparées par un point virgule et pour libellés une clé de message définie dans les fichiers I18n de l'application.

Les traductions des paramètres sont saisies dans le fichier I18N de l'extension avec la règle de nommage suivante BO.NOM_EXTENSION.JOB_PARAM.NOM_PARAMETRE.

Exemple pour les paramètres déclarés ci-dessus :

# Clé de message pour le label du champ
BO.CORE.JOB_PARAM.PARAMETRES=Paramètre du job

# Clés de message pour les différentes valeurs sélectionnables
BO.CORE.JOB_PARAM.PARAM1=Paramètre 1
BO.CORE.JOB_PARAM.PARAM2=Paramètre 2
BO.CORE.JOB_PARAM.PARAM3=Paramètre 3

Récupération des paramètres saisis

Les paramètres saisis lors du lancement du script peuvent être récupérés via le JobContext, celui-ci est disponible dans les méthodes init() et execute() de LogReportJob.

Exemple de récupération des paramètres pour le job monScriptJob :

public class MonScriptJob extends LogReportJob implements Runnable {
 
    ...

    private String parametre;

    ...


    @Override
    public void init(final JobExecutionContext context) {
        // Récupération du paranètre saisi lors du lancement du script
        // Celui-ci peut ensuite être utilisé dans la méthode run()
        parametre = context.getMergedJobDataMap().getString("parametres");
    }

    ...
}

Modifier le fichier

Gestion du SSO interne de K-Sup

La fonctionnalité de gestion du SSO permet d'authentifier automatiquement un utilisateur sur différents sites K-Sup avec des domaines différents.

Description de la fonctionnalité

La fonctionnalité de SSO s'active dans le back-office, dans la gestion des sites.
Il suffit de cocher la case "Site SSO" dans l'onglet "informations générales".

Le processus est le suivant :

• L'utilisateur s'authentifie sur le site courant.
  • À la fin de l'autentification, un fichier XML avec les informations de la session est créé dans le dossier "session" du storage.
  • Un rebond est effectué sur une URL d'enregistrement de la connexion (connectionRegistry)
  • Une fois la connexion enregistrée, l'utilisateur est envoyé vers la page initialement demandée.
• L'utilisateur navigue sur un site d'un autre domaine (site K-Sup)
  • Si le site est SSO et que l'utilisateur n'est pas authentifié sur le site courant, un check est effectué sur le site principal
  • Comme la connexion de l'utilisateur a été enregistrée dans le registre, le check va retrouver la connexion précédente et générer un jeton signé à usage unique pour l'autoconnexion.
  • Une popin s'ouvre en bas de la page et propose à l'utilisateur d'être connecté automatiquement sur le site courant.
• Si l'utilisateur accepte, l'utilisateur est connecté via le jeton d'authentification.
  • Un rebond est ensuite effectué sur le site principal pour enregistrer la connexion sur le nouveau site.
  • L'utilisateur est ensuite redirigé vers la page qu'il consultait initialement.

Les fichiers session sont de la forme session_950c4fff-a3c6-4ffa-92db-6c5a4a4338da.xml avec le contenu suivant

<?xml version="1.0" encoding="utf-8"?>
<SESSION>
    <ID>950c4fff-a3c6-4ffa-92db-6c5a4a4338da</ID>
    <CODE>john.doe</CODE>
    <CODE_LDAP/>
    <CIVILITE>0000</CIVILITE>
    <NOM>Doe</NOM>
    <PRENOM>John</PRENOM>
    <EMAIL>john.doe@kosmos.fr</EMAIL>
    <STRUCTURE/>
    <PROFIL/>
    <GROUPES/>
</SESSION>

Les fichiers jeton JWT sont de la forme 0oT7FMGxuf sans contenu La session TOMCAT sera initialisée par les données présentes dans le fichier XML (alimentation réalisée dans le filter ContexteFilter). L'utilisateur sera alors reconnu comme authentifié et identifié.

@startuml
autonumber
skinparam style strictuml

Actor "Bob" as B
Participant Navigateur as N
Participant "K-Sup" as K

activate B
B -> N: Se connecte sur site A
activate N
N -> K: Appele l'URL de login
activate K
K -> N: Génère la page de login
deactivate K
N -> B: Affiche la page
deactivate N
B -> N: Saisit son identifiant et le mot de passe
activate N
N -> K: Soumet le formulaire d'identification
activate K
K -> K: Authentifie l'utilisateur
K -> K: Détermine la page d'atterissage
K -> N: Retourne un formulaire auto-submit sur le site principal
deactivate K
N -> K: Soumet le formulaire
activate K
K -> K: Enregistre La connexion \nde l'utilisateur sur le site A \ndans une connectionRegistry
K -> N: Retourne une redirection vers la page d'atterrisage
deactivate K
N -> K: Demande la page d'atterrissage
activate K
K -> N: Retourne la page demandée
deactivate K
N -> B: Affiche la page
deactivate N
...L'utilisateur navigue sur le site...
B -> N: Clique sur un lien vers le site B
activate N
N -> K: Appelle l'URL demandée
activate K
K -> N: Génère la page demandée <font color="red"><b>"Anonyme"</b></font>
deactivate K
N -> B: Affiche la page
N -> K: Interroge la connectionRegistry sur le site principal
activate K
K -> N: Retourne une jeton d'auto-connexion 
deactivate K
N -> B: Affiche la popin d'auto-connexion
B -> N: Clique sur le lien d'auto-connexion
N -> K: Soumet le formulaire d'auto-connexion
activate K
K -> K: Valide le jeton 
K -> K: Authentifie l'utilisateur sur le site B
K -> N: Retourne un formulaire auto-submit sur le site principal
deactivate K
N -> K: Soumet le formulaire
activate K
K -> K: Enregistre La connexion \nde l'utilisateur sur le site B\ndans une connectionRegistry
K -> N: Retourne une redirection vers la page initiale
deactivate K
N -> K: Demande la page initiale
activate K
K -> K: Génère la page\ncontextualisée <font color="green"><b>à bob</b></font>
K -> N: 200: retoune la page générée <font color="green"><b>pour bob</b></font>
deactivate K
N -> B: Affiche la page
deactivate N
@enduml

Service "RegistryCleaner"

Les connexions sont enregistrées par défaut pendant 8 heures à partir de la dernière connexion.
Une tache récurrente a pour fonction de purger les connexions expirées. Cette tâche démarre par défaut au bout de 60 seconde et s'exécute par défaut toutes les 60 secondes.
La session SSO est supprimée uniquement si elle ne contient plus de session HTTP.

Les propiétés suivantes permettent de personnaliser le fonctionnement de la purge:

• connection.registry-cleaner.delay : fixe le délais avant le lancement de la première purge.
• connection.registry-cleaner.period : fixe la période entre deux purges
• connection.registry.expiration : fixe la durée de vie (TTL) de la session SSO

Cette purge n'impacte que la fonctionnalité de SSO. : un utilisateur connecté au BO ne sera pas déconnecté tant que sa session est vivante.

Modifier le fichier

Gestion du SLO interne de K-Sup

La fonctionnalité de gestion du SLO permet de déconnecter un utilisateur sur les différents sites K-Sup SSO auxquels il s'est connecté.

Description de la fonctionnalité

La déconnection est toujours effectuée sur un endpoint du site principal

Le processus est le suivant :

• L'utilisateur clique sur le bouton "Déconnecter" du site courant
• Il est redirigé vers le endpoint de déconnexion du site principal qui contient le registre des connexions
• Les différentes sessions liées à la connexion SSO sont invalidées sur les différents membres du cluster.
  • En cas de connexion depuis une source externe , une fois les différents sites K-Sup déconnectés, l'utilisateur est renvoyé sur l'URL de déconnexion de la source externe
  • Une fois la déconnexion terminée, l'utilisateur est redirigé vers la page d'atterrissage

Calcul de la page d'atterrissage

• En déconnexion FO, l'utilisateur est redirigé par défaut sur la page d'accueil du site courant
• En déconnexion BO, l'utilisateur est redirigé par défaut sur la page /adminsite/ du site courant
• Si la propriété source.redirection_front est activée (ou sinon la propriété default.redirection_front), l'utilisateur sera redirigé vers l'accueil front en cas de déconnexion depuis le BO
• Si le propriété source.fo.logout.callback est valorisée (ou sinon la propriété default.logout.fo.callback), l'utilisateur sera redirigé vers la page indiquée par la propriété pour une déconnexion FO
• Si le propriété source.bo.logout.callback est valorisée (ou sinon la propriété default.logout.bo.callback), l'utilisateur sera redirigé vers la page indiquée par la propriété pour une déconnexion BO

@startuml
autonumber
skinparam style strictuml

Actor "Bob" as B
Participant Navigateur as N
Participant "K-Sup" as K
Participant "Source Auth." as S

activate B
B -> N: Se déconnecte depuis le site A
activate N
N -> K: Appele l'URL de logout
activate K
K -> K: Invalidation des sessions locales
K -> K: Invalidation des sessions cluster
K -> N: Génération de l'URL de déconnexion de la source
deactivate K
N -> S: deconnexion de la source
activate S
S -> N: redirection vers la page d'atterrissage
deactivate S
N -> K: génération de la page demandé
activate K
K -> N: page générée
deactivate K
N -> B: Affichage de la page d'atterrissage
deactivate N
@enduml

Modifier le fichier

Sonde de vie

Un endpoint permet d'obtenir l'état de santé (basique) de l'application. Par défaut, le endpoint écoute l'URL /health et retourne un code 200 (sans contenu pour l'instant) si l'application est démarrée.

Modifier le fichier

Tags K-Sup

Définition d'un tag

Un tag doit être de type DefaultPluginTag ou doit l'étendre.

Lors de la définition du tag, les propriétés suivantes peuvent être définies :

• identifiantTag : identifiant du tag
• extracteur : bean de type ExtracteurTag qui défini la facon dont le contenu du tag est extrait du texte parsé
• interpreteurs : liste de beans de type AbstractInterpreteurTag qui définissent comment sera interprété le tag selon un contexte donné
• baliseOuvrante : chaine de caractères définissant le début du tag
• baliseFermante : chaine de caractères définissant la fin du tag
• order : ordre d'interprétation du tag (1000 par défaut)

<bean id="tagMailto" class="com.kportal.extension.module.plugin.toolbox.DefaultPluginTag">
    <property name="identifiantTag" value="[mailto]"/>
    <property name="extracteur">
        <bean class="com.kportal.tag.extracteur.impl.ExtracteurHtmlEnDehorsDuTag">
            <property name="identifiantTag" value="[mailto]"/>
        </bean>
    </property>
    <property name="interpreteurs">
        <bean class="com.kportal.tag.interpreteur.impl.InterpreteurMailto">
            <property name="contextesTag">
                <list>
                    <util:constant static-field="com.kportal.tag.util.ContexteTagUtil.DEFAUT"/>
                </list>
            </property>
        </bean>
    </property>
    <property name="baliseOuvrante" value="&lt;a"/>
    <property name="baliseFermante" value="&lt;/a&gt;"/>
</bean>

Extracteur

L'extracteur permet de récupérer au sein d'un texte, le contenu du tag ainsi que les balises ouvrante/fermante.
La classe de l'extracteur doit implémenter ExtracteurTag et définir une méthode getContenuTagPresentDansTexte qui retourne le contenu du tag dont les balises sont passées en paramètre.

public class DefautExtracteurTag implements ExtracteurTag {

    @Override
    public String getContenuTagPresentDansTexte(String texte, String baliseOuvrante, String baliseFermante) {
        String contenuTag = StringUtils.substringBetween(texte, baliseOuvrante, baliseFermante);
        if (contenuTag != null) {
            contenuTag = baliseOuvrante + contenuTag + baliseFermante;
        }
        return contenuTag;
    }
}

Interpreteurs

Les interpréteurs du tag ont deux fonctions :

• parser le tag et retourner le résultat
• calculer les références vers les fiches/médias

Un tag peut avoir N interpréteurs, ceux-ci sont déclarés lors de la définition du tag ou peuvent être ajoutés via un ListToAddBean.

Chaque interpréteur défini la liste des contextes qu'il prend en charge.

  <property name="interpreteurs">
    <bean class="com.kportal.tag.interpreteur.impl.InterpreteurMailto">
        <property name="contextesTag">
            <list>
                <util:constant static-field="com.kportal.tag.util.ContexteTagUtil.DEFAUT"/>
            </list>
        </property>
    </bean>
</property>

Ordonancement des tags

Dans certains cas, il est nécessaire d'ordonnancer l'interprétation des tags : par construction, il est possible de générer des tags imbriqués

C'est le cas notamment du tag "centre d'intêret" qui peut-être utilsé comme paramètre du tag liste de fiche. Afin d'obtenir une interprétation correcte des tags, le tag "centre d'intêret" doit être interprété avant le tag "liste de fiches"

Cet ordonnancement est controlé par l'attribut "order" lors de la déclaration du tags dans le fichier de contexte, par exemple:

    ...
        <!--TAGS CENTRES D'INTERET -->
<bean id="tagCentresinteret" class="com.kportal.extension.module.plugin.toolbox.DefaultPluginTag">
    <property name="identifiantTag" value="[centresinteret]"/>
    <property name="extracteur" ref="defautExtracteurTag" />
    <property name="order" value="#{TAG_DEFAULT_ORDER-100}" />
    <property name="interpreteur">
        <bean class="com.kportal.tag.interpreteur.impl.InterpreteurCentresinteret"/>
        ...

Par défaut, tous les tags ont un ordre positionné à "1000". 4 tags ont été priorisés spécifiquement pour être interprétés prioritairement :

1. Le tag [centresinteret], ordre=900
2. Le tag [media;video;], ordre=950
3. Le tag [media;audio;], ordre=950
4. Le tag [media;pdfviewer;], ordre=950

Modifier le fichier

Limitation de la taille des fichiers (upload)

Le mécanisme de limitation de la taille des fichiers téléchargés a été amélioré afin de donner plus de possibilité de contrôle en fonction du contexte.

• La propriété fichiergw.maxsize est conservée.
• Un nouveau niveau de contrôle permet d'ajouter le code d'une extension K-Sup afin de spécifier une taille propre aux fichiers uplodés dans les processus de l'extension.
  Par exemple, la propriété fichiergw.uas.maxsize permet de limiter la taille des fichiers téléchargés dans les templates de site de l'usine à site.

De la même manière, on pourrait limiter la taille des fichiers ajouté aux formulaires en ajoutant la propriété fichiergw.formulaire.maxsize dans le env.properties.

Note: Les medias téléchargés dans la médiathèque (Processus SAISIE_MEDIA) sont gérés par un mécanisme propre à la médiathèque de contrôle basé sur le type de la ressource.

Modifier le fichier

Configuration des toolbox

Documentation fonctionnelle

La configuration d'une toolbox peut être définie à plusieurs niveaux :

• avec l'attribut configuration du composant toolbox
• en fonction du processus, sous forme de clé {nom_processus}, par exemple SAISIE_PAGELIBRE=/adminsite/ckeditor/configurations/styleParagraphe.json.
• en concaténant le nom du processus et le nom du champ, sous forme de clé {nom_processus}.{nom_champ}. Par exemple SAISIE_PAGELIBRE.COMPLEMENTS=/adminsite/ckeditor/configurations/styleParagraphe.json.
• en fonction du nom du champs, sous forme de clé {champ}, par exemple COMPLEMENTS=/adminsite/ckeditor/configurations/styleParagraphe.json. C'est utilisé notamment pour les champs communs à plusieurs fiches, comme les encadrés.

C'est la configuration la plus précise qui sera utilisée. Pour la page libre, on a la configuration suivante dans pagelibre_ckeditor.properties :

CKEDITOR_DEFAULT_PATH=/adminsite/ckeditor/configurations
SAISIE_PAGELIBRE=${CKEDITOR_DEFAULT_PATH}/styleParagraphe.json
SAISIE_PAGELIBRE.COMPLEMENTS=${CKEDITOR_DEFAULT_PATH}/defaultConfig.json

Cette configuration signifie que toutes les toolbox de la fiche page libre ont la configuration styleParagraphe.json, sauf la toolbox du champ COMPLEMENTS.

Si aucune configuration n'est définie, c'est la configuration par défaut définie dans ckeditor.properties qui sera utilisée :

DEFAULT=${CKEDITOR_DEFAULT_PATH}/defaultConfig.json

Pour ajouter une toolbox dans une jsp, on utilise le composant toolbox. Exemple du champ "Informations complémentaires" de la fiche page libre :

<components:toolbox extension="pagelibre" fieldName="COMPLEMENTS" label="BO_PAGELIBRE_COMPLEMENTS" min="0" max="16000" editOption='<%= FormateurJSP.SAISIE_FACULTATIF %>'/>

Surcharge d’une configuration dans un projet

Le chargement des fichiers *.properties servant à surcharger la configuration des toolbox suit un mécanisme particulier. Il nécessite l’utilisation d’un bean implémentant CkeditorConfigurer, permettant notamment de définir le format du nom des fichiers à rechercher. Pour effectuer une surcharge, il faut d’abord connaître la clé de la configuration à modifier. Exemple : pour surcharger CONTENU_ENCADRE dans l’extension article, il faut indiquer cette clé dans un fichier properties adapté.

• Si la configuration est spécifique à une fiche, on utilise le format suivant : nomextension_ckeditor-override.properties → visible uniquement par l’extension concernée.

• Si la configuration est commune à toutes les fiches on utilise le format suivant : application_nomextension_ckeditor.properties → visible par le core.

Dans tous les cas, la configuration définie dans le projet prend le pas sur celle du produit (extension ou koreparent).

Tutoriels

Surcharge d’une configuration spécifique à l’extension article : description

Dans le cadre d'un projet, on souhaite modifier la toolbox du champ Description (élément spécifique à Article, défini dans son saisie.jsp).

Objectif : retirer l’élément Accordéon.

1. Création du fichier : src/main/resources/article_ckeditor-override.properties → il sera pris en compte uniquement par l’extension Article.

2. Clé concernée (d’après CkeditorConfigurerUtils) : CORPS.

3. Contenu du fichier :

   SAISIE_ARTICLE.CORPS=/adminsite/ckeditor/configurations/styleParagrapheSpe.json
   SAISIE_ARTICLE_FRONT.CORPS=/adminsite/ckeditor/configurations/styleParagrapheSpe.json
   

4. Le style par défaut est styleParagraphe. On crée donc une variante styleParagrapheSpe.json, sans Accordéon, dans le dossier src/main/webapp/adminsite/ckeditor/configurations.

Cette configuration spécifique sera utilisée en priorité grâce à la surcharge réalisée.

Surcharge d’une configuration commune : contenu encadré

Toujours pour un projet, on souhaite cette fois retirer l’élément Onglet de la toolbox contenu encadré, qui n’est pas spécifique à Article (défini dans fiche_bas.jsp de Koreparent).

1. Création du fichier : src/main/resources/application_article_ckeditor.properties → visible par le core.

2. Clé concernée : CONTENU_ENCADRE.

3. Contenu du fichier :

   SAISIE_ARTICLE.CONTENU_ENCADRE=/adminsite/ckeditor/configurations/styleParagrapheSpe2.json
   SAISIE_ARTICLE_FRONT.CONTENU_ENCADRE=/adminsite/ckeditor/configurations/styleParagrapheSpe2.json
   

4. Le style par défaut étant styleParagraphe, on crée une version adaptée styleParagrapheSpe2.json (sans Onglet) dans le même répertoire de configuration que les styles existants de Koreparent.

Cette configuration spécifique sera utilisée en priorité grâce à la surcharge réalisée.

Modifier le fichier

Tiles

Présentation

Tiles est utilisé principalement en BO pour insérer des fragments de JSP. Il est également utilisé dans les front legacy (pour search par exemple)

La classe java com.kosmos.context.CommonTilesConfig porte la configuration de tiles.

Les fichiers de configuration sont scannés aux emplacements suivants

• /WEB-INF/**/tiles*.xml
• /**/extensions/**/WEB-INF/**/tiles*.xml
• /**/legacy/tiles*.xml
• /WEB-INF/**/*-tiles.xml

Propriétés

Modifier le fichier

Template « Site web »

Objectif

Le template « Site web » est un layout générique fourni par koreparent pour construire une page d’accueil en une colonne et 15 lignes, simple à personnaliser côté projet.

Définition

• Déclaration du layout et des slots: koreparent/layout/src/main/resources/core-layout.xml
• Bean du layout: siteWeb (com.kosmos.layout.grid.impl.DragNDropGrid)
• Liste des slots: bean slotsTemplateSiteWeb
• Par défaut, chaque slot accepte les types ToolboxCardBean et SearchCardBean

Structure et slots

• Le template expose 15 slots verticaux numérotés de 0 à 14 (soit 15 positions).
• Chaque slot est un bean DragNDropSlot nommé siteWeb-slotX.
• Pour chaque slot, la liste des types de cards autorisées est fournie par un bean CardClassList nommé allowedCardTypesTemplateSiteWeb-slotX.

Extrait simplifié de core-layout.xml:

<!-- Liste par défaut des cards autorisées pour le template -->
<bean id="defaultAllowedCardTypesTemplateSiteWeb" class="java.util.ArrayList" abstract="true">
    <constructor-arg type="java.util.Collection">
        <list>
            <value>com.kosmos.layout.card.bean.ToolboxCardBean</value>
            <value>com.kosmos.layout.card.bean.SearchCardBean</value>
        </list>
    </constructor-arg>
</bean>

        <!-- Slot 0 (même principe pour 0..14) -->
<bean id="allowedCardTypesTemplateSiteWeb-slot0" class="java.util.ArrayList" parent="defaultAllowedCardTypesTemplateSiteWeb"/>

<bean id="siteWeb-slot0" class="com.kosmos.layout.slot.impl.DragNDropSlot">
<property name="allowedCardTypes" ref="allowedCardTypesTemplateSiteWeb-slot0"/>
<property name="key" value="ba204506-dd15-4ee0-b79b-191260da31b1"/>
<property name="row" value="0"/>
<property name="column" value="0"/>
<property name="colSpan" value="1"/>
<property name="rowSpan" value="1"/>
</bean>

Règles de personnalisation des cards autorisées

• La liste par défaut des types de cards autorisées pour le template est defaultAllowedCardTypesTemplateSiteWeb, c'est une définition abstraite donc non instanciée, elle n'est ainsi pas extensible via le listToAddBean.
• Chaque instance de liste pour un slot (allowedCardTypesTemplateSiteWeb-slot0 … -slot14) est initialisée depuis cette liste abstraite.

Il est possible de :

• surcharger la liste abstraite pour impacter tous les slots du template
• ajouter/retirer des types uniquement pour un slot donné

Cas d’usage et exemples

1. Modifier globalement les types autorisés (tous les slots) en surchargeant defaultAllowedCardTypesTemplateSiteWeb

<!-- Dans le ApplicationContext.xml du projet -->
<bean id="defaultAllowedCardTypesTemplateSiteWeb" class="java.util.ArrayList" abstract="true">
    <constructor-arg type="java.util.Collection">
        <list>
            <!-- Conservez celles du socle et ajoutez les vôtres -->
            <value>com.kosmos.layout.card.bean.ToolboxCardBean</value>
            <value>com.kosmos.layout.card.bean.SearchCardBean</value>
            <value>com.kosmos.actualite.card.ActualiteCardBean</value>
        </list>
    </constructor-arg>
</bean>

Effet : tous les slots (0..14) accepteront ToolboxCardBean, SearchCardBean et ActualiteCardBean.

2. Ajouter une card uniquement sur un slot précis en faisant un listToAddBean

<!-- Ajoute une card seulement sur le slot 7 -->
<bean id="addDemarcheCardBeanToTemplateSiteWeb-slot1" class="com.kportal.core.context.ListToAddBean">
    <property name="idBeanToMerge" value="allowedCardTypesTemplateSiteWeb-slot1"/>
    <property name="add">
        <list value-type="java.lang.Class">
            <value>com.univ.objetspartages.card.DemarcheCardBean</value>
        </list>
    </property>
</bean>

Effet : seul siteWeb-slot1 acceptera DemarcheCardBean en supplément des autres types définis.

Modifier le fichier

Module de recherche avec Opensearch

Ce module gère l'ensemble du mécanisme permettant de mettre en place le moteur de recherche sur le produit K-Sup.

Le moteur de recherche est basé sur l'utilisation du serveur Opensearch dans la version 2.4.0

Dans ce module vous trouverez :

• La configuration de la communication avec le serveur de données (Opensearch).
• Le mécanisme d'indexation des données.
• Les méthodes pour constituer les requêtes et les exécuter.

Les notes suivantes décrivent le fonctionnement général intégré à K-Sup. Vous trouverez aussi des informations pour surcharger certaines parties du comportement.

Infrastucture et intégration d'Opensearch

Fonctionnement

Fonctionnement général

Le moteur Opensearch est un serveur RESTful nativement scalable. Ce moteur expose des API REST pour échanger avec lui. K-Sup va interagir avec ce moteur en utilisant les différentes API REST exposées.

Opensearch utilise une base de données NoSQL orientée document. Les objets manipulés sont donc des documents.

API Java

Opensearch propose de plus des librairies Java permettant de manipuler facilement les objets échangés :

• Pour la constitution des requêtes de recherche : query, agrégation, highlight
• Pour l'utilisation des outils exposés : percolateur, santé du serveur ...
• Pour la manipulation des objets retournés : réponse, highlight ...

Deux librairies sont publiées :

• Java Low Level REST Client : permettant la communication via HTTP avec le serveur
• Java High Level REST Client : surcouche de la librairie précédente, mais exposant les APIs métier.

Nativement, K-Sup utilise un moteur de recherche mono-serveur (configuré avec un seul shard), mais il est possible de modifier ce comportement pour communiquer avec un cluster Opensearch par exemple ( ou pour ajouter des shards ou des réplicas).

Afin de fonctionner, le serveur Opensearch nécessite l'installation de plugins :

• ingest-attachment : plugin utilisé pour l'indexation de pièce jointe (utilisation de Tika).

Environnement de production

L'installation d'un serveur Opensearch est décrite dans la documentation se trouvant sur le site de la documentation K-Sup : Serveur Opensearch.

Attention cette documentation n'est pas à jour car pointe sur un environnement 2.4.6 (alors que la présente version est en 7.9).

Environnement de développement

Afin de pouvoir utiliser la recherche sur un poste de développement, il faut avoir a disposition un serveur Opensearch déployé.

Si vous avez besoin de déployer un serveur sur votre poste, vous pouvez utiliser le conteneur docker suivant : ksup-docker-opensearch. Vous trouverez sur le repository la documentation d'utilisation de ce conteneur.

Déclaration du serveur sur un poste K-Sup

Dans les fichiers de properties de votre projet, il faut déclarer le serveur Opensearch cible. Pour se faire, il faut créer un fichier env_opensearch.properties dans le répertoire storage de votre application et déclarer à minima la propriété suivante search.nodes pour indiquer le hostname du serveur Opensearch ainsi que son port :

search.nodes=localhost:32787

Modification du comportement K-Sup

Propriétés exposées

Indexation

Fonctionnement

Les documents présents dans Opensearch sont sérialisés au format json par K-Sup et sont ensuite poussés via l'API du serveur Opensearch. Seules les fiches sont aujourd'hui sérialisées au travers de l'objet FicheIndexDocument. Cet objet permet lors de la sérialisation, de dénormaliser le modèle objet des fiches afin de stocker en plus des données propre de la fiche :

• Les différentes rubriques sur lesquelles la fiche est visible : rubrique de rattachement et multi-publication.
• Les plugins liés à la fiche
• Les ressources attachées : médias issus de la médiathèque ou non.
• Différentes informations techniques
  • Code de la fiche.
  • ID du metatag lié à la fiche.
  • Type de fiche.
  • Date de publication de la fiche.
  • Si la fiche est visible en front offic (en ligne, dans un site actif ...).
  • Les contrôles d'accès : Champ utilisé pour effectuer avec une regexp la vérification des droits sur la fiche.
• Liste des champs utilisés pour les agrégations transverses entre chaque fiche (thématique).

L'indexation des fiches est effectuée de différentes manières :

• au fil de l'eau lors de l'enregistrement d'un contenu.
  • si un contenu modifié est référencé dans d'autres contenus, ces contenus parents seront mis à jour afin d'avoir les données en phase. Ces traitements sont réalisés via des jobs SpringBatch. Les contenus écoutés de cette manière sont :
    • Les fiches enfant : fiche structure par exemple.
    • Les libellés.
    • Les utilisateurs.
    • Les rubriques.
  • Les traitements d'indexation au fil de l'eau sont réalisés via un bus de message déclenché lors d'évènements métiers (enregistrement). Ces messages sont gérés via le framework Spring Integration
• de manière globale lors de l'exécution du script automatisé indexerJobModule Indexation complète des contenus.

Afin de sérialiser les objets et leurs attributs avec le bon type (Texte, date, booléen ...), Opensearch utilise des templates. Il faut donc décrire comment chaque champ doit être indexé.

Opensearch met à disposition 2 types de templates :

• index_template : template utilisé pour décrire le mapping d'un template
• component_template : fragment de template mutualisé entre différents index_template.

Dans K-Sup il y a autant d'index que de langues (et donc autant de index_template). Les templates sont chargés à la création de chaque index.

Description des templates

Les templates décrivant l'indexation des données K-Sup sont placés dans le répertoire /resources/com/kosmos/search/mapping. Le répertoire index_template contient les fichiers décrivant les indexes et le répertoire component_template contient les fragments.

Description des fichier index_template

Les fichiers index_template décrivent les analyzers utilisés pour les différentes langues. Il y a un ainsi fichier par langue. Ces templates vont décrire les analyzer utilisés pour chaque langue :

• Tokenizer utilisés
• Filtres spécifiques à la langue : stemming, stop words ...

Les analyzer de chaque langue sont toujours écrits de la même manière :

• un analyzer nommé analyzer_core_xx décrivant l'analyze par défaut des données stockées.
• un analyzer nommé analyzer_core_raw_xx décrivant l'analyze des données avec peu de traitement.
  • Les tokens seront ensuite stockés avec un chemin préfixé par .raw*.
• un analyzer nommé analyzer_core_raw_stemmer_xx l'analyze des données sans stemming.
• un analyzer nommé analyzer_core_ngram_xx décrivant l'analyze des données avec l'utilisation du filtre edgengram.
  • Les tokens seront ensuite stockés avec un chemin préfixé par .ngram.

Plusieurs mapping sont ensuite décrits dans ce fichier

Champ fulltext

Afin de limiter le nombre de champs sur lesquels est effectuée la recherche un champ nommé fullText est créé en plus des champs de la fiche. Ce champ va contenir toutes valeurs de tous les champs candidats à la recherche fullText. Dans l'index, nous aurons donc l'ensemble des champs et ce champ. Il sera possible de requêter ainsi de manière indifférente sur ce champ ou sur un champ individuel (pour ajouter un boost particulier sur un champ par exemple).

Mapping dynamique

Un mapping dynamique est aussi présent pour détailler comment sérializer les champs de type String de l'application.

Ce mapping dynamique doit décrire :

• le champ par défaut utilisant l'analyzer analyzer_core_xx
  • Ce champ doit aussi contenir l'instruction pour copier les données dans le champ full_text.
• un champ raw utilisant l'analyzer analyzer_core_xx
• un champ ngram utilisant l'analyzer analyzer_core_ngram_xx Afin d'effectuer les highlights avec l'algorithme (plus performant), il est nécessaire de mettre l'attribut "term_vector": "with_positions_offsets" pour chaque analyzer.

Description des fichiers component_template

Ces fichiers contiennent les fragments mutualisés entre les différentes langues. Ils décrivent notamment le mapping de certains champs comme ceux que l'on souhaite exclure du mapping par défaut :

• code de fiche
• date ...

Indexation par batch

Lors de certaines modifications des batchs sont déclenchés afin de mettre à jour les données présentes dans les indexes Opensearch. Ces batches réalisés avec Spring-Batch sont déclarés dans le fichier search-batch-job.xml. Pour chaque élément modifié une requête est effectuée pour récupérer l'ensemble des éléments liés à modifier. Ces requêtes sont déclarées en utilisant un template mustache. Les items lus sont ensuite modifiés et de nouveau sérialisés dans le serveur Opensearch. Exemple de requête :

<bean id="searchFicheMetatagItemReader" parent="searchAbstractItemReader" scope="step">
		<property name="template">
			<bean class="org.opensearch.script.mustache.SearchTemplateRequest">
				<property name="script">
					<value>
						{
							"query":{
								"query_string" : {
									"fields": [
										"*.fiche_id_metatag"
									],
									"query": "{{idFicheMetatag}}"
								}
							}
						}
					</value>
				</property>
				<property name="scriptType" value="INLINE"/>
				<property name="scriptParams">
					<map>
						<entry key="idFicheMetatag" value="#{jobParameters['job.id_fiche_metatag']}" />
					</map>
				</property>
			</bean>
		</property>
	</bean>

Indexation des dépendances

Lors de l'indexation d'un contenu, les dépendances du contenu seront aussi sérialisées (libellé, fiche, rubrique, utilisateur). Ces serialisations sont déclenchées par l'ajout d'annotation sur les attributs des beans décrivant les objets (héritant de AbstractFicheBean)

Sérialisation des utilisateurs

La sérialisation est activée en ajoutant l'annotation @User sur l'attribut.

@User
protected String codeValidation = StringUtils.EMPTY;

Une fois sérialisé, un utilisateur est de la forme suivante :

"codeValidation": {
    "user_birthday": null,
    "user_ldap_code": "",
    "user_mail": "admin@xxx.fr",
    "user_first_name": "Administrateur",
    "user_code": "admin",
    "user_id": 1,
    "user_name": "K-Sup",
"user_gender": null
},

Sérialisation des rubriques

La sérialisation est activée en ajoutant l'annotation @Rubrique sur l'attribut.

@Rubrique
protected String codeRubrique = StringUtils.EMPTY;

Une fois sérialisé, un utilisateur est de la forme suivante :

"codeRubrique": [
    {
      "rubrique_category": "0000",
      "rubrique_value": "Fonctionnalités éditoriales",
      "rubrique_code": "1404583540039",
      "rubrique_id": 16
    }
],

Sérialisation des libellés

La sérialisation est activée en ajoutant l'annotation @Label sur l'attribut.

@Label(type = "04")
protected String thematique = null;

Cette anotation prend 3 paramètres :

• type : Définit le type de Libelle (issu de la table LIBELLE).
• strategy : Stratégie de mapping permettant d'associer le code de libellé avec une valeur. Il y a deux valeurs possibles :
  • ServiceLabelStrategy (stratégie par défaut) : stratégie utilisée pour les libellés stockés en base de données.
  • DatLabelStrategy : stratégie utilisée pour les libellés stockés dans les fichiers .dat. Cette propriété est obligatoire si on utilise la stratégie DatLabelStrategy.
• contexte : Contexte d'extension (extension dans laquelle se trouve le libellé)

Une fois sérialisé, un libellé est de la forme suivante :

"thematique": [
    {
        "label_value": "Thématique 1",
        "label_id": 1000035,
    	"label_code": "THEM"
    },
    {
        "label_value": "Administratif",
        "label_id": 1000010,
    	"label_code": "01"
    },
    {
    	"label_value": "Sports-Loisirs",
      	"label_id": 1000014,
    	"label_code": "05"
	}
],

Sérialisation des fiches

La sérialisation est activée en ajoutant l'annotation @Fiche sur l'attribut.

@Fiche(contexte = "ofin", nomObjet = "annuaireksup")
private String codeResponsable = null;

Cette annotation prend 2 paramètres :

• nomObjet : nom de l'objet cible du rattachement.
• contexte : contexte de l'extension dans laquelle se trouve l'objet cible. Afin de ne pas sérialiser l'ensemble de la base de données, la profondeur de sérialisation est paramétrable et est limitée par défaut à 2 niveaux de profondeur. Pour les données écartées, leurs identifiants sont sérialisés (code, langue, état).

La fiche structure d'une fiche est sérialisée. Mais la fiche structure parente de la fiche structure ne l'est pas. Seules ses identifiants sont sérialisée.

Indexation des toolboxes

Afin de sérialiser les toolboxes, il faut que l'annotation @GetterAnnotation soit placé sur le getter de l'attribut souhaité.

@GetterAnnotation(isToolBox = true)
protected String getResume() {
    return this.resume;
}

Cette annotation indique que le contenu indexé provient d'une toolbox, il va donc interpréter les tags de toolbox et le code HTML au lieu de les mettre en brut. Lors de la serialisation, les balises HTML sont filtrées et ne sont donc pas présentes dans le document Opensearch. La sérialisation est effectuée par la classe ToolboxSerializer.

Indexation des plugins

Les plugins sont indexés dans le champ plugins de la fiche. Les données sont sérialisées sont à intégrer dans un bean héritant de PluginIndexableBean généré par la méthode generatePluginIndex du Plugin (héritant de IPluginFiche). L'implémentation par défaut de DefaultPluginFiche return null. Il faut donc implémenter un traitement spécifique pour chaque plugin en surchargeant la méthode generatePluginBean. Le bean PluginBean indexé peut utiliser les annotations de sérialisation (@Label, @User, ...) afin de sérialiser des objets liés comme pour les fiches.

Indexation des medias

L'indexation des médias est réalisé lors de la sérialisation des fiches. Tous les médias sont sérialisés dans le champ resources de la fiche.

Ajouter un champ additionnel à l'indexation d'une fiche

Il est possible d'indexer des données additionnelles lors de l'indexation d'une fiche en déclarant un bean de type AdditionalSearchField. Lors de l'indexation d'une fiche, l'ensemble des beans de type AdditionalSearchField sont récupérés et ajoutés dans un objet additionalProperties.[TYPE_FICHE] dans l'index de la fiche.

"additionalProperties": {
    "formation": {
      "libelleAffichable": "Master Sciences du Médicament"
    }
}

Pour créer une donnée additionnelle, il faut créer une classe qui étende AdditionalSearchField. La classe doit surcharger la méthode serialize pour définir le contenu du champ. Exemple AdditionalFieldLibelleAffichable :

public class AdditionalFieldLibelleAffichable extends AdditionalSearchField {

    private static final long serialVersionUID = -7342698426096788996L;

    @Override
    public void serialize(final AbstractFicheBean abstractFicheBean, final JsonGenerator gen, final SerializerProvider serializers) throws IOException {
        final ServiceFiche serviceFiche = ServiceManager.getServiceForBean((abstractFicheBean.getClass()));
        if (serviceFiche != null) {
            gen.writeStringField(getFieldName(), serviceFiche.getLibelleAffichable(abstractFicheBean));
        }
    }
}

Puis ajouter la déclaration du bean dans le contexte du projet en déclarant le nom que portera le champ dans l'index :

<bean id="additionalFieldLibelleAffichable" class="com.kosmos.search.index.mapper.AdditionalFieldLibelleAffichable">
    <property name="fieldName" value="libelleAffichable"/>
</bean>

Modification du comportement K-Sup

Propriétés exposées

Ajout de template

Ajout d'une langue

Si votre projet nécessite le besoin d'ajouter une langue, il suffit d'ajouter un fichier nommé template_xx.json dans le répertoire /resources/com/kosmos/search/mapping/index_template de votre application.

Il faudra ensuite décrire l'ensemble des éléments nécessaires à la description des mappings.

Pour cela il faut s'inspirer des templates existant : template_fr.json.

Ajout d'un template spécifique

Si votre projet a besoin de décrire un template spécifique pour un objet que vous avez à sérialiser, il faut ajouter un fichier dans le répertoire : /resources/com/kosmos/search/mapping/component_template de votre application.

Ajout de serializer spécifique

Lors de la sérialisation des objets, il est possible de déclarer un serializer spécifique afin d'effectuer un traitement particulier. Il faut alors l'enregistrer dans le fichier de contexte de l'extension : Création du serializer :

public class CustomIndexSerializer extends StdSerializer<CustomIndexableBean> {
 
    public CustomIndexSerializer() {
        super(CustomIndexableBean.class);
    }
 
    /**
     * Sérialisation  des données.
     */
    @Override
    public void serialize(final CustomIndexableBean customBean, final JsonGenerator jgen, final SerializerProvider serializers) throws IOException, JsonProcessingException {
        jgen.writeStartObject();
        //TODO serialize specific data
        jgen.writeEndObject();
    }
 
}

Déclaration du serializer dans le fichier de contexte de l'extension (ExtensionContext.xml) :

<bean id="customModule" class="com.fasterxml.jackson.databind.module.SimpleModule">
    <constructor-arg type="java.lang.String" value="customModule"/>
    <property name="serializers">
        <bean id="agendaSimpleSerializer" class="com.fasterxml.jackson.databind.module.SimpleSerializers">
            <constructor-arg>
                <list>
                    <bean id="customStdSerialize" class="com.kosmos.agenda.index.CustomIndexSerializer"/>
                </list>
            </constructor-arg>
        </bean>
    </property>
</bean>
 
<!-- Ajout du module de serialisation aux serializers du core -->
<bean id="coreSearchMapper" class="com.kportal.core.context.MergedModulesJacksonBean">
    <property name="idBeanToMerge" value="coreSearchMapper"/>
    <property name="idExtensionToMerge" value="core"/>
    <property name="modules">
        <list>
            <ref bean="customModule"/>
        </list>
    </property>
</bean>

Indexation d'une fiche spécifique

Pour qu'une fiche soit indexable, il faut :

• que l'objet FicheUniv représentant la fiche soit indexable. Il faut vérifier que l'attribut isIndexable ne soit pas à false @FicheAnnotation(isIndexable = false) (il est à true par défaut).
• ajouter les différentes annotations (@Label, @User ...) sur les attributs du bean héritant de AbstractFicheBean afin d'ajouter la sérialisation des objets liés.

Indexation des plugins

Pour indexer les plugins, il faut :

• créer un objet héritant IndexablePluginBean détaillant les champs à sérialiser.
• implémenter la méthode generatePluginIndex dans la classe héritant de IPluginFiche du plugin. Cette méthode alimente le bean IndexablePluginBean.

Recherche

Documentation du controllerSearchServlet

Introduction

La SearchServlet dans le package com.kosmos.search.query.servlet est un contrôleur Spring qui gère les requêtes de recherche. Elle exécute la recherche et interroge les différents AbstractSearchHandler pour déterminer lequel peut prendre en charge la construction de la vue.

Fonctionnement

Méthode doGet

Cette méthode est appelée pour traiter les requêtes GET.

1. Génération des options de recherche :

• Les options de recherche sont générées à partir des paramètres de la requête en utilisant searchOptionFeeder.

2. Appel du service de recherche :

• Le service de recherche (FulltextSearchFactory) est appelé pour obtenir un ServiceSearcher approprié.
• Si un ServiceSearcher est trouvé, il exécute la recherche et obtient un SearchResultBean.

3. Initialisation du contexte de recherche :

• La méthode initContext initialise un SearchContext avec les informations de la requête, les résultats de la recherche, et d'autres métadonnées.

4. Gestion des résultats de recherche :

• Si des résultats de recherche sont obtenus, le servlet parcourt les AbstractSearchHandler disponibles pour trouver celui qui peut gérer la requête et la réponse.
• Le AbstractSearchHandler approprié est utilisé pour construire et retourner un ModelAndView.

5. Gestion des erreurs :

• Si aucun ServiceSearcher ou résultat de recherche n'est trouvé, une exception est levée.

Modifier le fichier

Documentation du Système de Chargement des Templates OpenSearch

Introduction

Cette documentation explique en détail le fonctionnement du chargement des templates OpenSearch, où ils sont stockés et dans quel ordre ils sont chargés.

Architecture du Système de Chargement

Types de Templates

Le système gère deux types principaux de templates OpenSearch :

1. Component Templates (templates de composants)

   • Emplacement : com/kosmos/search/mapping/component_template/**/*.json
   • Fragments réutilisables de configuration de mapping
   • Chargés automatiquement depuis le classpath

2. Index Templates (templates d'index)

   • Définis via des beans Spring IndexTemplateReference
   • Templates complets pour la création d'index
   • Peuvent référencer des component templates

Processus de Chargement

Le chargement des templates est orchestré par la classe TemplateLoader, qui est un composant Spring activé au démarrage de l'application. Le processus se déroule en deux phases distinctes :

1. Chargement des Component Templates

   • Exécuté en premier
   • Scanne le classpath pour trouver tous les fichiers JSON dans le répertoire des component templates
   • Charge chaque template trouvé dans OpenSearch

2. Chargement des Index Templates

   • Exécuté après les component templates
   • Récupère tous les beans Spring de type IndexTemplateReference
   • Charge chaque template référencé dans OpenSearch

Mécanisme de Découverte des Templates

Découverte des Component Templates

Les component templates sont découverts par un scan du classpath, en utilisant le pattern suivant :

classpath*:com/kosmos/search/mapping/component_template/**/*.json

Ce pattern permet de trouver tous les fichiers JSON dans le répertoire des component templates, y compris ceux qui se trouvent dans des JAR dépendants.

Le processus de découverte utilise une chaîne de responsabilité avec deux lecteurs :

1. ClasspathFileListReader : Pour lire les fichiers depuis les JARs
   • Bootstrap ClassLoader
     • Classes de la JVM (rt.jar, java.base, etc.)
   • System ClassLoader / Common ClassLoader (Tomcat level)
     • Fichiers JAR dans ${CATALINA_HOME}/lib
2. FileSystemFileListReader : Pour lire les fichiers depuis le système de fichiers local
   • Webapp ClassLoader (ParallelWebappClassLoader)
     • Fichiers WEB-INF/classes/
     • Fichiers WEB-INF/lib/*.jar

Découverte des Index Templates

Les index templates sont découverts par l'inspection du contexte Spring, en recherchant tous les beans de type IndexTemplateReference. Chaque bean définit :

• Un nom de template
• Un chemin vers le fichier JSON du template
• Une priorité
• Des patterns d'index
• Optionnellement, un chemin vers des component templates à utiliser

Ordre de Chargement et Mécanisme de Surcharge

Ordre de Chargement des Fichiers

L'ordre de chargement des fichiers dans le classpath est déterminé par plusieurs facteurs :

1. Ordre de Découverte

   • Les fichiers sont découverts dans l'ordre du classpath Java
   • Les JARs sont scannés dans l'ordre défini par le classloader
   • Les fichiers du système de fichiers local sont généralement traités en dernier

2. Déduplication

   • Les templates avec le même nom sont dédupliqués
   • Le premier template trouvé est conservé

Mécanisme de Surcharge

Lorsqu'un projet inclut koreparent en tant que dépendance JAR, il peut surcharger les templates existants de deux façons :

1. Surcharge par Nom

   • En plaçant un fichier avec le même nom au même chemin relatif
   • Exemple : pour surcharger com/kosmos/search/mapping/component_template/content/template_fiche.json du JAR koreparent, placer un fichier avec le même nom au même chemin dans le projet

2. Surcharge par Priorité (pour les Index Templates)

   • En définissant un bean IndexTemplateReference avec une priorité plus élevée
   • Les templates avec une priorité plus élevée sont appliqués en priorité par OpenSearch

Diagramme du Processus de Chargement

Ordre de Priorité des Templates

Component Templates

Pour les component templates, l'ordre de priorité est déterminé par l'ordre de chargement :

1. Les templates définis dans le projet ont priorité sur ceux définis dans les JARs dépendants
2. En cas de conflit de noms, le dernier template chargé (selon l'ordre du classpath) écrase les précédents

Index Templates

Pour les index templates, l'ordre de priorité est explicitement défini par le paramètre priority :

1. Plus la valeur de priorité est élevée, plus le template est prioritaire
2. En cas d'égalité de priorité, le dernier template chargé a la priorité

Exemple de Surcharge de Templates

Surcharge d'un Component Template

Pour surcharger un component template existant dans koreparent :

1. Identifiez le template à surcharger, par exemple :

   com/kosmos/search/mapping/component_template/content/template_fiche.json
   

2. Créez un fichier avec le même nom au même chemin dans votre projet :

   src/main/resources/com/kosmos/search/mapping/component_template/content/template_fiche.json
   

3. Le template de votre projet sera chargé avant celui de koreparent et sera conservé.

Ajout d'un Nouveau Component Template

Pour ajouter un nouveau component template :

1. Créez un fichier JSON dans le répertoire approprié :

   src/main/resources/com/kosmos/search/mapping/component_template/custom/mon_template.json
   

2. Le template sera automatiquement découvert et chargé.

Surcharge d'un Index Template

Pour surcharger un index template existant :

1. Créez un bean IndexTemplateReference avec une priorité plus élevée :

   @Bean
   public IndexTemplateReference monTemplateIndex() {
       return new IndexTemplateReference(
           "nom_template",
           "chemin/vers/mon_template.json",
           300, // Priorité plus élevée que le template original
           null,
           "pattern_index"
       );
   }
   

2. Le template avec la priorité la plus élevée sera appliqué par OpenSearch.

Génération des templates dynamiques OpenSearch

Fonctionnement

Au démarrage de l'application, le système scanne tous les beans qui implémentent l'interface TemplateField et génère un template JSON contenant tous les champs déclarés. Ce template est injecté dans OpenSearch sous le nom "template_fiche_dynamique".

Comment déclarer un nouveau champ de template

Vous pouvez déclarer un bean XML dans votre fichier de configuration Spring qui utilise la classe MultiPathKeywordTemplateField ou MultiPathDateTemplateField et spécifier une liste de chemins à mapper. Exemple :

<bean id="monKeywordTemplate" class="com.kosmos.search.mapping.fields.MultiPathKeywordTemplateField">
    <property name="paths">
        <list>
            <value>*.diffusionPublicVise</value>
            <value>*.diffusionPublicViseRestriction</value>
            <value>*.etatObjet</value>
            <value>*.id</value>
        </list>
    </property>
</bean>

<bean id="coreDateTemplate" class="com.kosmos.search.mapping.fields.MultiPathDateTemplateField">
    <property name="match" value="date*" />
</bean>

Chaque extension peut déclarer son propre bean avec sa liste de champs à mapper. Les différents beans sont lus au démarrage pour générer le template. Un nom unique est généré automatiquement pour chaque chemin dans la liste, en supprimant les "." et en convertissant les segments en CamelCase (par exemple, "DiffusionPublicViseTemplate" pour le chemin ".diffusionPublicVise" ou "ActualiteTypeEvenementLabelCodeTemplate" pour le chemin ".actualite.typeEvenement..label_code").

Le mapping peut être effectué sur une liste de chemins paths, ou sur une regex correspondant au nom du champ match.

Surcharger un template dynamique

Pour surcharger un template dynamique il faut effectuer un AttributeToOverrideBean pour redéfinir les paths ou le match du bean de template.

Exemple :

<bean id="coreKeywordTemplateOverride" class="com.kportal.core.context.AttributeToOverrideBean">
   <property name="idExtensionToMerge" value="core"/>
   <property name="idBeanToMerge" value="coreKeywordTemplate"/>
   <property name="attributes">
      <map>
         <entry key="paths">
            <list>
               <value>*toto</value>
            </list>
         </entry>
      </map>
   </property>
</bean>

Classes de base disponibles

• KeywordTemplateField : Classe de base abstraite pour créer des champs de type keyword
• DateTemplateField : Classe de base abstraite pour créer des champs de type date
• MultiPathKeywordTemplateField : Implémentation concrète de KeywordTemplateField pour définir plusieurs chemins via XML
• MultiPathDateTemplateField : Implémentation concrète de DateTemplateField pour définir plusieurs chemins via XML

Créer une nouvelle classe de base pour un nouveau type de champ

Si vous avez besoin d'un nouveau type de champ, créez d'abord une classe abstraite qui étend AbstractTemplateField et définit les propriétés communes à ce type de champ. Ensuite, créez des implémentations concrètes qui étendent cette nouvelle classe de base.

// Classe de base pour un nouveau type de champ
public abstract class NewFieldTypeTemplateField extends AbstractTemplateField {
    @Override
    public String getFieldType() {
        return "new_field_type";
    }
}

Exemple de template généré

Le template généré aura une structure similaire à celle-ci :

{
  "template": {
    "mappings": {
      "dynamic_templates": [
        {
          "dateTemplate": {
            "match_mapping_type": "long",
            "match": "date*",
            "mapping": {
              "type": "date",
              "format": "strict_date_optional_time||epoch_millis"
            }
          }
        },
        {
          "idTemplate": {
            "match_mapping_type": "string",
            "path_match": "*.id",
            "mapping": {
              "type": "keyword"
            }
          }
        },
        {
          "DiffusionPublicViseTemplate": {
            "match_mapping_type": "string",
            "path_match": "*.diffusionPublicVise",
            "mapping": {
              "type": "keyword"
            }
          }
        },
        {
          "DiffusionPublicViseRestrictionTemplate": {
            "match_mapping_type": "string",
            "path_match": "*.diffusionPublicViseRestriction",
            "mapping": {
              "type": "keyword"
            }
          }
        }
      ]
    }
  }
}

Création du template

Le template est créé au démarrage de l'application via le ComponentTemplateLoader. Voici le processus :

1. Le DynamicTemplateGenerator génère le template JSON en scannant tous les beans TemplateField
2. Le ComponentTemplateLoader vérifie si le template existe déjà sur OpenSearch
3. S'il existe, le loader compare la version existante avec la nouvelle version générée
4. Si les versions sont différentes ou si le template n'existe pas, le nouveau template est créé/mis à jour sur OpenSearch

Le template est stocké comme un component template nommé "template_fiche_dynamique".

Bonnes Pratiques

1. Nommage Unique

   • Utilisez des préfixes spécifiques à votre projet pour éviter les collisions de noms
   • Exemple : projet_template_fiche.json au lieu de template_fiche.json

2. Priorités Cohérentes

   • Utilisez des plages de priorités cohérentes :
     • 0-100 : Templates de base (koreparent)
     • 101-200 : Templates de modules
     • 201+ : Templates spécifiques aux projets

3. Documentation

   • Documentez les templates que vous ajoutez ou surchargez
   • Indiquez clairement les modifications apportées aux templates existants

4. Tests

   • Testez vos templates avant déploiement
   • Vérifiez que les surcharges fonctionnent comme prévu

Conclusion

Le système de chargement des templates OpenSearch dans koreparent offre une grande flexibilité pour personnaliser et étendre les fonctionnalités d'indexation. En comprenant l'ordre de chargement et les mécanismes de surcharge, les projets peuvent adapter les templates à leurs besoins spécifiques tout en bénéficiant des fonctionnalités de base fournies par koreparent.

La clé pour une utilisation efficace de ce système est de comprendre que :

1. Les component templates sont chargés avant les index templates
2. Les fichiers sont chargés selon l'ordre du classpath Java
3. Les templates avec le même nom sont dédupliqués
4. Les index templates peuvent définir des priorités explicites pour contrôler l'ordre d'application

Modifier le fichier

Script de migration flyway du module de recherche

Certaines modifications dans la structure des fiches ou dans la définition des templates nécessitent des actions au niveau du moteur de recherche. A cet effet, le module Search met à disposition deux outils dédiés.

L'AbstractSearchEngineIndexing

Cet outil permet de planifier un job de reindexation totale ou partielle (par type de fiche). Pour utiliser cet outil, il suffit de créer une classe qui étend la classe abstraite et d'implémenter la méthode migrate.

Implémentation pour une indexation complète :

public class V1_2_3_45__reindexation_complete extends AbstractSearchEngineIndexing {

    private static final Integer CHECKSUM = 1234567890;

    @Override
    public Integer getChecksum() {
        return CHECKSUM;
    }

    @Override
    public void migrate(final Context context) throws Exception {
        // On indique qu'il s'agit d'une indexation complète
        scheduleFullIndexation();
        super.migrate(context);
    }
}

Implémentation pour une indexation partielle :

public class V1_2_3_45__reindexation_partielle extends AbstractSearchEngineIndexing {

    private static final Integer CHECKSUM = 1234567890;

    @Override
    public Integer getChecksum() {
        return CHECKSUM;
    }

    @Override
    public void migrate(final Context context) throws Exception {
        // On indique via une collection les codes objet à indexer.
        schedulePartialIndexation("0016", "0002");
        super.migrate(context);
    }
}

• Si plusieurs ré-indexations complètes sont demandées, une seule sera réellement exécutée.
• Si plusieurs ré-indexations partielles sont demandées, les types de fiches concernés seront fusionnés et le traitement lancé sur les types de fiches concernés.
• Si une ré-indexation totale est demandée, les ré-indexations partielles sont ignorées (car inutiles du fait de la ré-indexation totale).

L'AbstractSearchEngineManagement

Cet outil permet d'exposer le client REST du moteur de recherche. Il peut être utilisé par exemple pour supprimer un index devenu inutile.

public class V1_2_3_45__suppression_index extends AbstractSearchEngineManagement {

    private static final Integer CHECKSUM = 1234567890;

    @Override
    public Integer getChecksum() {
        return CHECKSUM;
    }
    
    @Override
    public void migrate(final RestHighLevelClient restClient) {
        final DeleteIndexRequest deleteIndexRequest = new DeleteIndexRequest("nom_index_à_supprimer");
        restClient.indices().delete(deleteIndexRequest, RequestOptions.DEFAULT);
    }
}

Modifier le fichier

Module de statistiques

Présentation

Le module statistiques se base des technologies existantes du core. Lorsque un indicateur est collecté, un message spring-integration est diffusé sur la file channel.core.out.
Une nouvelle file nommée "channel.in.statistics" duplique les messages channel.core.out via un bridge.
Les messages sont routés vers un service activator (le logger) afin d'être matérialisés sur disque ou dans une table de la base de données.

Format de sortie des indicateurs

Le format de sortie est décrit dans cette page

Le module met à disposition le service StatisticsService qui permet de générer des entêtes standardisés. La méthode initMessageHeaders permet d'initiliser de manière standardisée les entêtes. La méthode retourne une map d'entêtes nécessaires aux indicateurs

    ...
final Map<String, Object> headers=statisticsService.initMessageHeaders("NOM_DU_MARQUEUR");
        ...

L'envoi de l'indicateur est réalisé via le service ServiceCorePublisher

    ...
private ServiceCorePublisher publisher;
        ...
        publisher.publish(payload,TARGET_MARKER_XXXXX,null,null,headers);
        ...

La valeur TARGET_MARKER_XXXXX est une chaine de caractère permettant d'aiguiller le message vers un service activator adapté.

Selection d'un endpoint

Les différents message spring integration sont envoyés vers un nouveau channel channel.in.statistics via un bridge.
Un routeur permet de répartir les message vers deux endpoints fournis par le produit.

1. Le StatisticsLogger qui permet d'écrire dans un fichier de log (type logback). Pour inscrire un indicateur dans le fichier de log, il suffit de valoriser l'entête "target" du message avec la constante StatisticsService.TARGET_MARKER_LOGGER

  ...
      publisher.publish(payload,StatisticsService.TARGET_MARKER_LOGGER,null,null,headers);
      ...

2. Le StatisticEventsService qui permet d'écrire des indicateurs dans une table de donnée (table STATISTIC_EVENTS).
   Cette table a vocation à cumuler les indicateurs d'action avant de procéder à une aggrégation (comptage) et à leur extraction.
   Pour inscrire un indicateur dans la table STATISTIC_EVENTS, il suffit de valoriser l'entête "target" du message avec la constante StatisticsService.TARGET_MARKER_EVENT

  ...
      publisher.publish(payload,StatisticsService.TARGET_MARKER_EVENT,null,null,headers);
      ...

Modifier le fichier

Format de sortie des indicateurs

Les indicateurs écrit dans le fichier respectent le format suivant

LOGGER.info("{};{};{};{};{};{}", marker, timestamp, client, server, profile, payload);

• marker est le nom de l'indicateur.
  Le fichier concentre les différents indicateurs collectés.
• timestamp est la date de la collecte à un des formats ISO-8601
• client est le code du client.
  Le code est extrait de l'identifiant du bean extension depuis le fichier de contexte du projet.
  À défaut, le système utilise la propriété statistics.client.id (cf core-statistics.properties)
• server est la jvmRoute configurée.
• profile est une valeur calculée à partir des droits de l'utilisateur connecté.
  Un ensemble ordonné de bean étendant "AbstractProfileDecider" permette de catégoriser fonctionnellement les utilisateurs en fonction de la présence de certaines permissions.
• payload est la carge utile de l'indicateur.
  La charge utile dépend de chaque indicateur.
  Elle est composée d'une chaine de type "clé=valeur" séparée par le caractère "&".
  Par exemple, METHOD=GET&URL=http%3A%2F%2Fkdev70.localhost%2F&TIME=3223&SQLCOUNT=258&SQLTIME=181&SQLMAX=8

Modifier le fichier

Calcul d'un profil fonctionnel

Le calcul du profil fonctionnel est réalisé par une liste ordonnée de convertisseur (? extends AbstractProfileDecider).
Le module met à disposition un ensemble de ProfileDecider.

• anonymousProfileDecider : ce bean détecte les utilisateurs non connectés (AutorisationBean null dans le contexte).
• webmasterProfileDecider : ce bean détecte les utilisateurs avec la permission "Webmaster".
• siteManagerProfileDecider : ce bean détecte les utilisateurs avec la permission "Edition de rubrique (C ou M ou S)".
• contentManagerProfileDecider : ce bean détecte les utilisateurs la permission de création ou traduction et la modification et la suppression sur au moins une fiche hors fiches des extensions formation.
• contributorProfileDecider : ce bean détecte les utilisateurs avec des permissions.
• defaultProfileDecider : ce bean détecte les utilisateurs connectés, mais sans permission.

Tous ces beans sont ordonnés via l'utilisation de la propriété "order".
Les extensions peuvent insérer dans la liste leur(s) propre(s) bean(s) de décision.
C'est par exemple le cas des extensions ofin ou offreformation qui ajoutent le bean suivant:

• programManagerProfileDecider : ce bean détecte les utilisateurs avec la permissions de modification sur la fiche Formation. Le bean est inséré entre les beans contentManagerProfileDecider et contributorProfileDecider.

Pour ajouter un nouveau bean, il suffit

• soit d'instancier le bean PermissionProfileDecider dans votre fichier de contexte en valorisant les propriétés requiredPermissions et/ou excludedPermissions et order selon vos besoins
  
• soit de créer un nouvean bean étendant AbstractProfileDecider en implémentant la méthode String apply(AutorisationBean).
  La méthode apply prend en paramètre l'AutorisationBean de l'utilisateur courant et retourne une chaine de caractère correspondant au profil fonctionnel souhaité.

Modifier le fichier

Intégration projet du module Statistiques

Activation du module

Par défaut, le module "Statistiques" est désactivé.

Avant d'activer le module, il est nécessaire d'obtenir l'accord du client.

Activation programmatique

Afin d'activer les statistiques de manière programmatique, il est nécessaire de le faire au premier démarrage de l'application.

L'activation s'effectue en ajoutant les 3 beans suivant dans le fichier ExtensionContext.xml de votre projet :

Exemple : monProjetExtensionContext.xml

    <bean id="activationTemplateSiteComposant" class="com.kportal.core.context.AttributeToOverrideBean">
        <property name="idExtensionToMerge" value="core"/>
        <property name="idBeanToMerge" value="composantStatistics"/>
        <property name="attributes">
            <map>
                <entry key="etat">
                    <util:constant static-field="com.kportal.extension.module.IModule.ETAT_ACTIF"/>
                </entry>
            </map>
        </property>
    </bean>
    <bean id="activationStatisticsJobModule" class="com.kportal.core.context.AttributeToOverrideBean">
        <property name="idExtensionToMerge" value="core"/>
        <property name="idBeanToMerge" value="statisticJobModule"/>
        <property name="attributes">
            <map>
                <entry key="etat">
                    <util:constant static-field="com.kportal.extension.module.IModule.ETAT_ACTIF"/>
                </entry>
            </map>
        </property>
    </bean>
    <bean id="activationStatisticsTrigger" class="com.kportal.core.context.AttributeToOverrideBean">
        <property name="idExtensionToMerge" value="core"/>
        <property name="idBeanToMerge" value="statisticsTrigger"/>
        <property name="attributes">
            <map>
                <entry key="etat">
                    <util:constant static-field="com.kportal.extension.module.IModule.ETAT_ACTIF"/>
                </entry>
            </map>
        </property>
    </bean>

Activation manuelle

Il est possible d'activer manuellement le module dans l'interface de K-Sup. Mais il est conseillé de réaliser l'activation de manière programmatique.

Dans le backoffice, l'activation du module nécessite les actions suivantes :

• Depuis le gestionnaire d'extensions, déplier la section "Socle CMS"
• Activer les modules "Statistique" et "Script automatisé de génération des statistiques"
• Depuis l'écran de gestion des traitement planifiés, activer le traitement planifié "Batch d'extraction des statistiques"

A partir de la version 7.0, l'applicatif va déterminer lui-même le client en scannant l'ExtensionContext du projet. A défaut de bean Extension dans le projet, c'est la valeur de la propriété statistics.client.id qui est utilisée.

En 6.7,vous devez valoriser la propriété statistics.client.id dans le fichier application_projet.properties de votre projet

Ajout d'un endpoint

L'ajout d'un nouveau endpoint, nécessite la déclaration d'un nouveau channel et d'un bridge depuis channel.in.core
Dans le cadre des statistiques, il est peu probable d'avoir besoin d'un nouveau endpoint. Le cas échéant, voir avec l'équipe produit.

Ajout d'un profil fonctionnel

Le fonctionnement du calcul du profil est décrit dans cette page

Pour ajouter un nouveau profil fonctionnel , il suffit

• Soit d'instancier le bean PermissionProfileDecider dans votre fichier de contexte en valorisant les propriétés * requiredPermissions* et/ou excludedPermissions et order selon vos besoins
  Par exemple, pour ajouter un profil fonctionnel regroupant les utilisateurs ayant les droits sur la médiathèque,

    ...
    <bean id="mediaManagerProfileDecider" class="com.kosmos.statistics.util.decider.profile.PermissionProfileDecider">
        <property name="profile" value="MEDIAMANAGER"/>
        <property name="order" value="xxxxxx"/>
        <property name="requiredPermissions" value="#{'TECH/pho/C'.split(',')}"/>
    </bean>
    ...
  

  A l'aide de l'attribut order, vous pouvez insérer votre bean dans la liste des deciders à l'endroit adapté à vos besoins.
  
• Soit de créer un nouvean bean étendant AbstractProfileDecider en implémentant la méthode String apply(AutorisationBean).
  La méthode apply prend en paramètre l'AutorisationBean de l'utilisateur courant et retourne une chaine de caractère correspondant au profil fonctionnel souhaité.

  ...
  public class XxxxxxManagerProfileDecider extends AbstractProfileDecider {
  
      private static final String XXXXX_MANAGER = "XXXXXMANAGER";
  
      @Override
      public String apply(final AutorisationBean arg) {
          if (arg != null && arg.isXxxxxxManager()) {
              LOGGER.debug("L'utilisateur actuel est .....");
              return XXXXX_MANAGER;
          }
          LOGGER.trace("L'utilisateur actuel n'est pas ....");
          return null;
      }
  }
  ...
  

  Il suffit ensuite de déclarer le bean dans votre fichier de contexte

    ...
    <bean id="siteManagerProfileDecider" class="com.acme.statistics.util.decider.XxxxxxManagerProfileDecider">
        <property name="order" value="42000"/>
    </bean>
    ...
  

  A l'aide de l'attribut order, vous pouvez insérer votre bean dans la liste des deciders à l'endroit adapté à vos besoins.
  

Ajout d'un indicateur d'action

L'ajout d'un indicateur d'action se fera de manière préférentielle par de l'AOP sur une ou plusieurs méthodes d'un service (ou assimilé) voire d'un DAO dans le cas de certains objets historiques K-Sup.
Selon les cas, on utilisera un aspect de type Before ou Around.

Ajout d'un indicateur HTTP d'accès à une URL

L'ajout d'un indicateur d'action nécessite la simple déclaration d'un filter. Par exemple, pour filtrer tous les appels HTTP au processus MON_PROCESSUS de l'extension MON_EXTENSION, déclarer le bean suivant et l'injecter dans les filtres d'inclusion du marqueur HTTP

    ...
    <bean id="monprocessusHttpMarker" class="com.kosmos.statistics.marker.http.requestfilter.UrlMatchesFilter">
        <property name="uri" value="${SGcontroller.mapping:/servlet/com.jsbsoft.jtf.core.SG}"/>
        <property name="parameters">
            <map>
                <entry key-ref="EXT" value="MON_EXTENSION"/>
                <entry key-ref="PROC" value="MON_PROCESSUS"/>
            </map>
        </property>
    </bean>

    <bean class="com.kportal.core.context.ListToAddBean">
        <property name="idExtensionToMerge" ref="EXTENSION_CORE"/>
        <property name="idBeanToMerge" value="httpMarkerProcessor"/>
        <property name="listToMerge" value="includes"/>
        <property name="add">
            <list>
                  <ref bean="monprocessusHttpMarker"/>
            </list>
        </property>
    </bean>
    ...

Ajout d'un indicateur d'action sur une création / mise à jour d'un bean de type PersitanceBean

Pour les PersitanceBean, le produit met à disposition un aspect générique, ContentUpdateAspect, permettant d'exécuter un code applicatif suite à une interception de méthode. Cet aspect applique une liste de processeurs (cf interface MarkerProcessor) Le bean applique une liste de MarkerProcessor (La liste des processeurs est initialisée par découverte). Chaque MarkerProcessor à la responsabilité de vérifier qu'il s'applique ou non via la méthode accept

    ...
@Override
    public boolean accept(final PersitanceBean before, final PersitanceBean after) {
        return isConditionRemplie && isClassAccepted(before.getClass());
        }
        ...

La seconde méthode permet d'éxécuter un code applicatif

    ...
@Override
    public void process(final PersitanceBean before, PersitanceBean after){
        ...
        Code applicatif permettant de générer l'indicateur
        ...
        }
        ...

Ajout d'un indicateur d'action sur un objet autre qu'un PersitanceBean

• Déclarer un intercepteur sur la ou les méthodes.
  • La méthode doit être publique et non statique
  • La méthode doit être appelée depuis l'extérieur de la classe — l'AOP ne fonctionne pas sur les appels internes
  • La classe doit être dans le même contexte — l'AOP ne fonctionne pas sur une classe d'un jar externe
  • La classe doit être un bean du contexte Spring
  • La méthode interceptée doit être dans la classe écoutée, sinon, écouter la classe parente
  • Ne pas réaliser d'interception de type * sur une classe ou un package, mais cibler précisément les méthodes

  ...
  <aop:config proxy-target-class="true">
      <aop:aspect id="serviceXxxxxAspect" ref="xxxxxAspect">
          <aop:pointcut id="xxxxxStatisticsInterceptor" expression="execution(* com.acme.service.ServiceXxxxx.save(..))" />
          <aop:around pointcut-ref="xxxxxStatisticsInterceptor" method="maMethode"/>
      </aop:aspect>
  </aop:config>
  ...
  <bean id="xxxxxAspect" class="com.acme.aspect.XxxxxAspect" parent="abstractStatisticsAspect"/>
  ...
  

• Créer un nouvel aspect dédié à votre indicateur.
  La classe doit étendre AbstractStatisticsAspect afin de bénéficier du service ServiceCorePublisher de publication de message (publisher) et du service ServiceStatistique.

  ...
  public class XxxxxAspect extends AbstractStatisticsAspect {
  
      public void maMethode(ProceedingJoinPoint call) throws Throwable {
          call.proceed();
          try {
              final Object arg0 = call.getArgs()[0];
              ...
              construction de la payload et des headers
              ...
              publisher.publish(payload, ..., null, null, headers);
          } catch (final Exception e) {
              LOG.error("Impossible de générer le marqueur statistiques", e);
          }
      }
     ...
  }
  

Ajout d'un indicateur de volume (batch)

Packages

Voici la syntaxe des packages a utiliser pour la mise en place des indicateurs sur votre projet :

package com.kosmos.[EXTENSION].statistics.marker.processor;
package com.kosmos.[EXTENSION].statistics.marker.module;
package com.kosmos.[EXTENSION].statistics.marker.volume.counter;

Ajout d'un indicateur de volume sur un type de fiche en ligne

Vous n'avez rien à faire : le produit va détecter les objets partagés et générer les compteurs de fiches en ligne.

Ajout d'un compteur spécifique

Pour ajouter un compteur de volume, il faut créer une classe implémentant com.kosmos.statistics.marker.volume.counter.Counter et déclarer le bean dans le contexte.

Exemple avec le compteur de "document en mode téléchargement" :

package com.kosmos.ged.statistics.marker.volume.counter;

import com.kosmos.ged.context.GedConfig;
import com.kosmos.statistics.marker.volume.counter.Counter;
import com.kosmos.statistics.util.Indicator;
import com.kosmos.statistics.marker.volume.counter.CounterOnlineContent;
import com.univ.objetspartages.bean.DocumentBean;
import com.univ.objetspartages.dao.impl.DocumentDAO;
import com.univ.objetspartages.om.EtatFiche;

import java.util.List;

/**
 * Coumpteur du nombre de fiches Document uniquement en téléchargement.
 */
public class CounterDocumentTelechargement implements Counter {

    private static final String CONTENT = "DocumentTelechargement";

    private DocumentDAO documentDAO;

    @Override
    public Indicator count() {
        Indicator result = new Indicator();
        result.setComponent(GedConfig.ID_EXTENSION);
        result.setMarker(CounterOnlineContent.MARKER);
        final List<DocumentBean> documents = documentDAO.select(" JOIN METATAG m on m.META_ID_FICHE = T1.ID_DOCUMENT and m.META_CODE_OBJET = '0017' and ETAT_OBJET = '" + EtatFiche.EN_LIGNE + "' and META_DOCUMENT_FICHIERGW = '1'");
        result.addToPayload(Indicator.PAYLOAD_CONTENT_TYPE, CONTENT);
        result.addToPayload(Indicator.PAYLOAD_COUNT, documents.size());
        return result;
    }

    public void setDocumentDAO(final DocumentDAO documentDAO) {
        this.documentDAO = documentDAO;
    }
}

<bean id="statisticsDocumentTelechargementCounter" class="com.kosmos.ged.statistics.marker.volume.counter.CounterDocumentTelechargement">
    <property name="documentDAO" ref="documentDAO"/>
</bean>

Modifier le fichier

Insertion du tableau de bord et gestion des jetons d'accès

Intégration du tableau de bord dans K-Sup

Le tableau de bord est basé sur Apache Superset. Superset est hébergé par Kosmos. Pour pouvoir visualiser le tableau de bord, nous avons utilisé le package NPM @superset-ui/embedded-sdk. Il se charge de gérer lui-même l'intégration du tableau de bord dans la page, via une iframe. Il permet également de renouveler automatiquement le jeton d'accès qui permet de visualiser le tableau de bord.

Lorsqu'un utilisateur accède à la page de visualisation des statistiques, du JavaScript se lance pour faire appel à une JSP renvoyant seulement le token d'accès en JSON. Ce token d'accès est soit généré en appelant l'API de Superset, soit donné directement dans les propriétés de l'application. Le tableau de bord est ensuite affichée dans l'iframe grâce au package qui se charge de lui fournir les données dont elle a besoin.

Configuration nécessaire pour le tableau de bord

Afin de pouvoir voir le tableau de bord, il faut renseigner la propriété dashboard.guestToken (jeton généré par Kosmos, voir ci-dessous). Par défaut, le profil Webmaster a la permission de voir le tableau de bord. Pour les autres profils, il faut leur accorder l'accès (permission à donner dans la gestion des rôles).

Gestion de l'accès au tableau de bord

Afin de visualiser le tableau de bord, il faut soit :

• Générer un jeton d'accès (guest_token) grâce à un utilisateur Superset qui a les droits nécessaires
• Donner un jeton valide au package embedded-sdk

Remarque : Nous utilisons un seul tableau de bord et un seul serveur Apache Superset pour tous les clients. Ils accèdent au même tableau de bord, mais avec des restrictions d'accès différentes (ils ne voient que les données de leur établissement). Or, seul un utilisateur peut être désigné pour générer les jetons d'accès dans Superset. On ne peut donc pas créer un utilisateur par client et restreindre l'accès aux données directement depuis Superset. K-Sup étant open source, on ne peut pas non plus définir les restrictions d'accès dans le projet, car elles seraient modifiables et les établissements pourraient changer le code pour accéder à d'autres données (toutes les données ou celles d'autres établissements). Le choix fait pour l'instant est que Kosmos génère un jeton d'accès avec des droits qui limitent aux données d'un seul établissement. Il y a ainsi un token à générer par client.

Les properties mentionnées sont dans le fichier src/main/resources/core-statistics.properties.

Avec un jeton d'accès entré manuellement

Si on choisit de saisir manuellement un jeton, il aura été généré au préalable par Kosmos et aura une durée de vie longue (plusieurs mois, voire plusieurs années). Il est renseigné par la propriété dashboard.guestToken.

Les jetons prennent en compte des restrictions d'accès aux données (pour que chaque établissement ne voie que ses données).

Le diagramme suivant détaille ensuite le déroulement de l'affichage du tableau de bord si un jeton est entré manuellement. Le participant "Embed Superset (client)" désigne le package NPM embedded-sdk utilisé automatiquement par le client.

Les tokens sont générés via un script interne à Kosmos dont voici le diagramme de séquence.

Voici la liste des variables les propriétés qui leur correspondent ainsi qu'une valeur d'exemple :

Avec un jeton d'accès généré puis renouvelé

Pour pouvoir générer un jeton d'accès, il faut disposer du nom d'utilisateur et mot de passe du compte qui a les droits pour générer ce jeton. On peut les renseigner via les propriétés dashboard.provider.username et dashboard.provider.password.

Le package intégrant le tableau de bord se chargera ensuite de faire les appels nécessaires à Superset pour obtenir le jeton. Il sera renouvelé toutes les 5 minutes et peut intégrer des restrictions d'accès aux données (pour que chaque établissement n'ait accès qu'à ses données).

On doit tout d'abord se connecter à l'API de Superset en précisant l'utilisateur, le provider (db ou ldap) ainsi qu'un booléen indiquant si on souhaite obtenir un token de rafraîchissement ou non. Une fois connecté à l'API, on peut demander le guest_token, en précisant le token d'accès (utilisé pour se connecter à l'API), le nom d'utilisateur, le type de ressource à laquelle on souhaite accéder, l'identifiant du tableau de bord auquel on souhaite accéder puis des restrictions d'accès aux données (en choisissant un établissement par exemple).

Le diagramme suivant explique les appels faits par le processus /src/main/java/com/kosmos/statistics/processus/VisualiserStatistiques.java si un utilisateur générant un token est renseigné.

Les variables utilisées sont les mêmes que celles désignées dans le tableau ci-dessus à l'exception de tokenUrl. Cette variable désigne l'URL de la JSP qui contient le guestToken. En effet, les appels montrés sont déclenchés par un fetch d'une page contenant seulement un guest token JSON, effectué par le JavaScript de ka JSP de visualisation des statistiques.

Modifier le fichier

Paramétrage du module statistique

Surcharge

La surcharge des propriétés peut se faire dans les fichiers de surcharge du socle. En créant un fichier :

• application_core.properties dans les sources d'un projet
• env.properties dans le répertoire de configuration d'un environnement (référencé par la propriété conf.dir)

Propriétés

Modifier le fichier

Affichage du front office de K-Sup

Cette section décrit la construction des vues du front office de K-Sup.
Cet affichage se base sur la bibliothèque de composants K-Sup.

Modifier le fichier

Construction des vues en front office

Théorie

La construction des vues repose sur le modèle MVC.
Une vue est définie par trois éléments :

• un fichier jsp
• un preparer
• un modèle

Le preparer doit récupérer les données nécessaires à la construction du modèle, il met en forme ces données telles qu'elles doivent apparaitre à l'écran et les injecte dans le modèle.
Le modèle est ensuite poussé dans la jsp via le controller.

Une vue peut correspondre à un organisme, une molécule ou un atome. La page finale affichée à l'écran correspond à un ensemble de vue qui sont combinées et imbriquées.

Dans la pratique

Une vue est définie par un ViewPreparer qui étend AbstractViewPreparer, celui-ci déclare les propriétés suivantes :

• view : chemin de la jsp
• type : type de la vue
• order : ordre de priorité d'utilisation de la vue
• includedSiteTemplate : liste des codes de template de site pouvant utiliser la vue
• excludedSiteTemplate : liste des codes de template de site ne pouvant pas utiliser la vue
• expectedViewTypes : liste des types de vue qui compose la vue

Le preparer définit le modèle qu'il utilise :

public class MyViewPreparer<V extends MyViewModel> extends AbstractViewPreparer<V> {
    ...
}

Le preparer doit posséder les méthodes suivantes :

accept : défini le contexte pour lequel la vue répond. La méthode prend en paramètre un FrontContext et retourne un boolean.

public boolean accept(FrontContext context) {
    return true;
}

prepare : construit le modèle associé à la vue. La méthode prend en paramètre un FrontContext et la liste des viewPreparers qui composent la vue.

public V prepare(final FrontContext context, final Map<String, List<IViewPreparer>> preparers) {
    final V viewModel = super.prepare(frontContext, preparers);
    ...
}

Le modèle

Le modèle porte l'ensemble des données affichées dans la vue, le viewPreparer est en charge d'effectuer la transformation des données afin de les injecter dans le modèle. Le modèle défini une méthode getId() qui retourne l'id utilisé pour l'insertion du modèle dans la jsp.

ArticleViewModel :

public class ArticleViewModel extends AbstractContentViewModel {

    @Override
    public String getId() {
        return "articleViewModel";
    }
}

article.jsp :

<jsp:include page="${articleViewModel.view}"/>

Le modèle possède également une liste de viewModels qui correspondent aux types de vue qui composent la vue.

protected Map<String, IViewModel> viewModels = new HashMap<>();

Il est possible de récupérer la grappe complète de viewModels à plat via la méthode getAllViewModels().

Un point d'extension permet d'effectuer un traitement à postériori de la préparation.
Une fois les différents preparers appelés, on récupère la totalité des bean actifs ordonnés de type ViewModelPostProcessor. On applique alors chaque processor accepé sur les viewModels.

Gestion des inclusions/exclusions des vues dans les templates de site

Par défaut, une vue est incluse dans tous les templates de site existants.

Il est possible de définir une liste de templates ne pouvant pas utiliser la vue via la propriété excludedSiteTemplate. Si un ou plusieurs codes de template sont présents dans les excludedSiteTemplate, la vue va être utilisée par tous les templates SAUF ceux présent dans les excludedSiteTemplate.

Le paramètre includedSiteTemplate est restrictif et absolu. Cela veut dire que si une vue définit un ou plusieurs codes dans la liste des includedSiteTemplate, seules ces templates pourront utiliser la vue. Cela veut également dire que si un code de template est présent dans la liste des includedSiteTemplate et également présent dans la liste des excludedSiteTemplate, l'exclusion n'est pas prise en compte.

Exemple :

<bean id="myViewPreparer1" >
    <property name="includedSiteTemplate">
        <list>
        </list>
    </property>
    <property name="excludedSiteTemplate">
        <list>
        </list>
    </property>
</bean>

<bean id="myViewPreparer2" >
    <property name="includedSiteTemplate">
        <list>
            <value>template2</value>
        </list>
    </property>
    <!-- exclus dans aucun templates de site -->
    <property name="excludedSiteTemplate">
        <list>
        </list>
    </property>
</bean>

<bean id="myViewPreparer3" >
    <property name="includedSiteTemplate">
        <list>
            <value>template1</value>
        </list>
    </property>
    <property name="excludedSiteTemplate">
        <list>
            <value>template1</value>
            <value>template3</value>
        </list>
    </property>
</bean>

<bean id="myViewPreparer4" >
    <!-- inclus par défaut dans tous les templates de site -->
    <property name="includedSiteTemplate">
        <list></list>
    </property>
    <!-- exclus dans aucun templates de site -->
    <property name="excludedSiteTemplate">
        <list>
            <value>template1</value>
            <value>template2</value>
        </list>
    </property>
</bean>

Récupération des vues pour un template de site

Au démarrage de l'application, le SiteTemplateBeanManager créer une Map contenant la liste des vues regroupées par type pour chaque template de site :

public class SiteTemplateBeanManager extends AbstractBeanManager {

    // Map<codeTemplate, Map<typeVue, List<viewPreparer>>>
    private Map<String, Map<String, List<IViewPreparer>>> viewPreparersByTemplatesSiteAndTypes;
    ...
}

Il est possible de récupérer la liste des viewPreparers pour un template de site comme suit :

final Map<String, List<IViewPreparer>> viewPreparers = SiteTemplateBeanManager.getInstance().getViewPreparersByTemplateSiteCode(context.getInfosSite().getCodeTemplate());

Affichage de la vue

Le controller

L'affichage d'une vue est géré par un controller. Les controllers en charge d'afficher une vue possèdent une liste de handlers typés selon la vue à afficher (fiche, rubrique, search...). La liste de handlers est interrogée afin de récupérer le handler pouvant prendre en charge le contexte courant, puis demande au handler de retourner le ModelAndView correspondant à la vue.

Exemple :

public ModelAndView handleContent(final HttpServletRequest request, final HttpServletResponse response) throws Exception {
    final ContentContext context = initContext(request);
    final Map<String, AbstractContentHandler> handlerList = ApplicationContextManager.getAllActivatedBeansOfType(AbstractContentHandler.class);
    final AbstractContentHandler handler = handlerList.values().stream()
        .filter(h -> h.supports(request, response, context))
        .findFirst()
        .orElse(null);
    return handler.getModelAndView(request, response, context);
}

Les handlers

Les handlers sont en charge de retourner le ModelAndView final au controller.

Un handler doit implémenter com.kosmos.controllers.handlers.ModelAndViewHandler.

public class MyHandler implements ModelAndViewHandler {
    ...
}

Le handler doit posséder une méthode supports qui défini pour quel contexte il répond. Les handlers sont ordonnés afin de pouvoir prioriser plusieurs handlers supportant le même contexte.
Exemple :

@Override
public boolean supports(final HttpServletRequest request, final HttpServletResponse response, final FrontContext frontContext) {
    final ContentContext contentContext = ContentContext.of(frontContext);
    return contentContext.getUrlBean() != null && contentContext.getUrlBean().getIdMetatag() != null;
}

Le handler doit également posséder une méthode getModelAndView en charge de construire le ModelAndView à retourner au controller.
Cette méthode va faire appel ViewModelHelper.prepareViewModel afin de préparer la grappe de viewPreparers qui composent le template que l'on souhaite afficher.

@Override
public ModelAndView getModelAndView(HttpServletRequest request, HttpServletResponse response, final FrontContext frontContext) throws ErreurApplicative {
    final ContentContext contentContext = populateContext(frontContext);
    final AbstractViewModel viewModel = ViewModelHelper.prepareViewModel(DefaultTemplateViewModel.TEMPLATE, contentContext, request, response);
    final ModelAndView modelAndView = new ModelAndView();
    ViewModelHelper.setView(viewModel, modelAndView);
    modelAndView.addAllObjects(viewModel.getAllViewModels());
    return modelAndView;
}

Les templates

Les templates sont des vues globales qui composent la page finale affichée à l'écran, elles sont de type template.
Les templates sont des vues particulières qui représentent le squelette de la page, elles sont utilisées pour regrouper et imbriquer les vues.

<bean id="defaultTemplateViewPreparer" class="com.kosmos.template.DefaultTemplateViewPreparer">
    <property name="type" value="template" />
    <property name="view" value="/WEB-INF/jsp/main.jsp" />
    <property name="expectedViewTypes">
        <list>
            <value>head</value>
            <value>banner</value>
            <value>skiplinks</value>
            <value>header</value>
            <value>breadcrumbs</value>
            <value>body</value>
            <value>footer</value>
            <value>autologin</value>
        </list>
    </property>
</bean>

Modifier le fichier

Fonctionnement de la grille KSup

KSup implémente une structure de page générique, comprenant différentes zones qui peuvent être agencées entre elles de différentes façon selon les pages visitées et les supports sur lesquels elles sont consultées. Ces zones sont repérées par les classes suivantes :

• .pre-content : contient les éléments sous l'en-tête qui précèdent le contenu principal de la page
• .page-main-content : le cœur de la page avec son contenu
• .page-sidebar : une barre de navigation généralement placée sur le côté
• .page-boxes : des contenus annexes, présentés sous forme d' « encadrés »

À ces classes s'ajoutent des classes qui vient se positionner sur le body :

• .is-homepage : indique que la page visitée est une page d'accueil, le point d'entrée du site Web (à différencier de la fiche Accueil, qui présente un contenu riche dont l'agencement est personnalisé en contribution)
• .is-insidepage : qualifie toutes les autres pages du site Web

Variables CSS et personnalisation

L'ensemble de la page est agencé à l'aide d'une grille CSS. Un certain nombre de calculs (détaillés ci-après) "dégrossissent" le travail d'agencement des différentes zones décrites ci-avant. L'idée ici est de répondre à 2 besoins :

• N'avoir, idéalement, à modifier que des variables pour personnaliser l'agencement des contenus sur un site Web
• Éviter, autant que faire se peut, de "surcharger" des JSP critiques de KSup

Voici les variables en question, déclarées sur body :

* Le nombre de colonnes de base devrait se baser sur le nombre de colonnes configuré dans le projet (variable SCSS).

Le tableau ci-dessus décrit les valeurs par défaut définies pour ces variables. L'implémentation des sites KSup suivant le principe du mobile-first, on peut donc considérer que ces valeurs par défaut vont s'appliquer notamment sur des petits écrans. L'implémentation de la grille réalisée par défaut vient ensuite changer les règles au-delà du point de rupture $screen-md (48rem, 768px par défaut).

Les calculs réalisés sur les écrans plus larges sont les suivants :

1. Une "nouvelle" variable est introduite : --_page-layout-aside-columns-count (le _ au début désigne une variable "privée" dans le sens où elle permet simplement de simplifier les calculs suivants). Cette variable calcule le nombre de colonnes occupées par la sidebar et les encadrés, s'ils sont sur la même ligne que le contenu principal. Le calcul est le suivant :

   aside-columns-count = use-same-row-content * (sidebar-columns-count + boxes-columns-count)
   

   Ici, la variable --page-layout-use-same-row-content prend tout son sens : si on ne veut pas afficher les contenus sur la même ligne (ils seront donc les uns sous les autres), la valeur de 0 viendra donc annuler la multiplication. Si c'est 1, on additionne donc le nombre de colonnes occupées par la sidebar et par la zone d'encadrés.

2. Le nombre de colonne du contenu principal central (--page-layout-main-content-columns-count) est recalculé :

   main-content-columns-count = columns-count - aside-columns-count
   

   Il s'agit du nombre total de colonnes de la grille moins le nombre de colonnes occupées par la sidebar et les encadrés.

3. L'indice de la première colonne où doit se placer le contenu principal (--page-layout-main-content-offset) est recalculé :

   main-content-offset = offset - sidebar-columns-count
   

   On prend l'indice de la première colonne de l'intégralité du contenu* et on y ajoute le nombre de colonnes occupées par la sidebar.

4. Le nombre de colonnes du "pré-contenu" est recalculé. Il correspond en réalité au nombre de colonnes occupées par le contenu principal, de la sidebar et la zone d'encadrés (qui n'est pas forcément égal au nombre total de colonnes de la grille).

   pre-content-columns-count = main-content-columns-count + aside-columns-count
   

5. Enfin, on recalcule l'indice de la première colonne du "pré-contenu" sur le même principe que le point №2.

   pre-content-offset = columns-count - pre-content-columns-count + offset
   

** L'intégralité du contenu ne commence par nécessairement à la 1e colonne. Dans le cas de KSup, la 1e colonne de la grille CSS (ainsi que la dernière) contient la marge variable sur le côté, permettant de centrer le contenu du site dans la fenêtre. L'intégralité du contenu démarre donc réellement à la 2e colonne.

Une fois tous ces calculs réalisés, il ne reste plus qu'à modifier la position des éléments en fonction des différents contextes. Prenons le cas d'une page intérieure ("inside page") sur un écran large (> 768px) avec des encadrés.

Les règles CSS qui vont s'appliquer sont les suivantes (d'après ce qui est définit dans les feuilles de styles de KSup) dans sa version simplifiée :

@media screen and (min-width: 48rem) {
    body {
        --_page-layout-aside-columns-count: calc(
            var(--page-layout-use-same-row-content)
            * (var(--page-layout-sidebar-columns-count)
            + var(--page-layout-boxes-columns-count))
        );

        --page-layout-main-content-columns-count: calc(
            var(--page-layout-columns-count)
            - var(--_page-layout-aside-columns-count)
        );

        --page-layout-main-content-offset: calc(
            var(--page-layout-offset)
            + var(--page-layout-sidebar-columns-count)
        );

        --page-layout-pre-content-columns-count: calc(
            var(--page-layout-main-content-columns-count)
            + var(--_page-layout-aside-columns-count)
        );

        --page-layout-pre-content-offset: calc(
            var(--page-layout-columns-count)
            - var(--page-layout-pre-content-columns-count)
            + var(--page-layout-offset)
        );
    }

    .is-insidepage {
        --page-layout-sidebar-columns-count: 0;
    }


    .is-insidepage:has(.page-sidebar, .page-boxes) {
        --page-layout-columns-count: 12;
        --page-layout-offset: 2;
        --page-layout-use-same-row-content: 1;
    }

    .is-insidepage:has(.page-boxes) {
        --page-layout-boxes-columns-count: 3;
    }
}

Notez ici que les calculs de positionnement dans la grille sont effectifs dès lors que les éléments sont présents dans la page. Cela, même si lesdits éléments sont vides !

Si on détaille les différentes règles :

• On a d'abord le body qui définit les règles de calcul avec les variables qui seront déclarées après.
• On peut voir que le nombre de colonnes occupées par la sidebar vaut 0 par défaut. Il n'y a pas de sidebar, donc cette valeur restera à 0.
• On indique que le nombre de colonnes de l'intégralité du contenu est à 12. Cette variable est redéfinie ici, car dans KSup, le nombre de colonnes du contenu principal d'une page intérieure, sans sidebar et sans zone d'encadrés, est de 10.
• Avec 12 colonnes de contenu, on replace la première colonne du contenu à 2 (au lieu de 3) par défaut.
• On précise que l'on veut mettre tous les contenus sur la même ligne.
• Enfin, on indique que la zone d'encadrés occupe 3 colonnes à elle seule.

Dans la feuille de styles de KSup, les différentes zones sont placées, par défaut, de cette façon, en réutilisant les variables décrites précédemment :

.pre-content {
    grid-column: var(--page-layout-pre-content-offset) / span var(--page-layout-pre-content-columns-count);
}

.page-main-content {
    grid-column: var(--page-layout-main-content-offset) / span var(--page-layout-main-content-columns-count);
}

.page-sidebar {
    grid-column: content / span var(--page-layout-sidebar-columns-count);
}

.page-boxes {
    grid-column: span var(--page-layout-boxes-columns-count) / content;
}

Le mot-clé span indique que la valeur utilisée désigne un nombre de colonnes et non un indice de référence. Le mot-clé content désigne la colonne occupée par l'intégralité du contenu par défaut (dans les faits, ça indique donc l'indice 2 pour l'indice de début, et l'indice 11 pour l'indice de fin de la colonne) ; cela découle directement du fonctionnement des zones nommées dans les grilles CSS.

Dispositions définies par défaut dans KSup en fonction des contextes et des contenus

En vue mobile (< 768px), on applique les règles suivantes :

• La sidebar n'est pas affichée
• Les contenus se placent les uns sous les autres et occupent toute la largeur (12 colonnes)
• Dans l'ordre, on affiche le "pré-contenu", le contenu principal puis les encadrés

À l'heure actuelle, il n'y pas de règles qui régissent les écrans moyens (tablettes). Les règles d'affichage en vue "desktop" (≥ 768px) sont plus élaborées et sont décrites ci-dessous.

Les numéros indiquées dans le tableau suivent ce modèle :

L (@S‑E)

• L désigne le nombre de colonnes occupées par la zone (L pour Length)
• S désigne l'indice de la colonne du début de la zone (S pour Start)
• E désigne l'indice de la colonne de fin de la zone (E pour End)

Les symboles présents dans le tableau désignent :

• ✅ : La zone est présente dans la page
• ❌ : La zone est absente de la page

*** La taille du "contenu principal" de la fiche accueil (ne pas confondre avec "page d'accueil") peut, en réalité, dépasser sur les zones latérales (marges). Le nombre indiqué dans la colonne "contenu principal" indique simplement où se place la majorité du contenu de la fiche accueil.

**** La colonne "Même ligne ?" désigne si les zones "sidebar", "contenu principal" et "encadrés" doivent se trouver sur la même ligne ou non. Le "pré-contenu" se trouve toujours avant tout le reste.

Sources

Le tableau ci-dessus se base sur l'intégration qui est faite dans le fichier dédié.

Documents de spécification :

• K-Sup 7.3 - Layout de la page
• K-Sup 7.3 - Design System

Deux commentaires viennent également appuyer ce fonctionnement (mais viennent potentiellement en contradiction avec ce qui est implémenté actuellement) :

• Commentaire de Camille Lebugle
• Commentaire de Django Janny

Modifier le fichier

Affichage d'une fiche

Le controller

L'affichage d'une fiche à pour point d'entrée ContentController, celui-ci initialise un contexte de type ContentContexte et filtre sa liste d'AbstractContentHandler afin de récupérer le handler prenant en charge le contexte courant.

Le handler

Les handlers utilisés pour l'affichage des fiches doivent hérités de AbstractContentHandler, le handler par défaut est ContentHandler.

public class ContentHandler extends AbstractContentHandler {
  ...
}

La méthode supports du handler vérifie la présence d'un id métatag dans l'UrlBean du contexte.

    @Override
public boolean supports(final HttpServletRequest request, final HttpServletResponse response, final FrontContext frontContext) {
    final ContentContext contentContext = ContentContext.of(frontContext);
    return contentContext.getUrlBean() != null && contentContext.getUrlBean().getIdMetatag() != null;
}

Le contexte

Le contexte de type ContentContext est initialisé par le ContentController à partir du contexte de type FrontContext.

private ContentContext initContext(final HttpServletRequest request) {
    final ContexteUniv ctx = ContexteUtil.getContexteUniv();
    final String uri = getURI(request.getRequestURI());
    final InfosSite infosSite = serviceInfosSite.getActiveSiteByHost(request.getServerName());
    final UrlBean urlBean = serviceUrl.getByUrlAndSite(uri, infosSite);
    final ContentContext context = ContentContext.of(new DefaultContext());
    context.setCtx(ctx);
    context.setInfosSite(infosSite);
    context.setUrlBean(urlBean);
    return context;
}

Il est ensuite alimenté par le ContentHandler pour récupérer la fiche courante, le titre et le metatag de la fiche.

private ContentContext populateContext(final FrontContext context) throws ErreurApplicative {
    final ContentContext contentContext = ContentContext.of(context);
    final AbstractFicheBean ficheBean = new ContentKsupFetcher(contentContext.getUrlBean()).getAbstractFicheBean();
    contentContext.getCtx().setFicheCourante(ReferentielObjets.initFiche(ficheBean));
    contentContext.getCtx().setLocale(LangueUtil.getLocale(ficheBean.getLangue()));
    contentContext.setContent(ficheBean);
    final MetatagBean metatag = serviceMetatag.getById(contentContext.getUrlBean().getIdMetatag());
    contentContext.setTitle(metatag.getMetaLibelleFiche());
    contentContext.setMetatag(metatag);
    return contentContext;
}

La vue

Des templates par défaut sont définis dans le produit, ils sont utilisés pour l'affichage des fiches.
Ils incluent les vues de type head, header, body, footer etc...

Il est possible de définir un template de fiche spécifique pour un type de contenu.
Pour cela, il faut créer un viewPreparer qui hérite de DefaultTemplateViewPreparer et surcharger la méthode supports pour que celui-ci prenne en charge le type de contenu souhaité.

Dans la plupart des cas, l'affichage spécifique d'une fiche ne concerne que le corps de la page (type body).
Un viewPreparer de type body est apporté par défaut dans le produit, il inclut le contenu de la fiche (type content) ainsi que les encadrés (type boxes).

Chaque fiche déclare un viewPreparer de type content qui inclut les données de la fiche dans le modèle.

<bean id="articleContentViewPreparer" class="com.kosmos.article.ArticleContentViewPreparer" parent="contentViewPreparer">
    <property name="imagePreparer" ref="imageViewPreparer"/>
    <property name="type" value="content"/>
    <property name="view" value="/extensions/article/WEB-INF/jsp/article-content.jsp"/>
</bean>

Le viewPreparer étend AbstractContentViewPreparer, il surcharge la méthode accept pour définir quel type de fiche il prend en charge.

@Override
public boolean accept(final FrontContext context) {
    return ContentContext.of(context).getContent() instanceof ArticleBean;
}

Puis alimente le modèle à partir des données de la fiche via la méthode prepare.

Modifier le fichier

Tutoriel : Mise en place d'une personnalisation projet d'un affichage d'une fiche

K-Sup est conçu pour servir de socle commun à différents projets clients, chacun ayant ses propres besoins fonctionnels. Pour éviter toute duplication ou modification du produit, des mécanismes de surcharge permettent aux projets de personnaliser ou d’enrichir le socle sans le modifier.

Plusieurs approches sont possibles pour adapter l’affichage ou le comportement.

Pendant ce tutoriel, nous allons prendre l'exemple de l'extension Pagelibre, dont un projet va souhaiter personnaliser différents aspects.

1. Mécanismes de surcharge dans K-Sup

Le socle K-Sup repose sur une architecture modulaire avec des extensions et des contextes Spring isolés. Il offre plusieurs mécanismes de surcharge permettant aux projets de personnaliser leur comportement ou leur interface :

• Surcharge de la configuration Spring
• Surcharge de beans, notamment les ViewPreparer (ou le modèle) et les CardViewBuilder
• Surcharge des vues JSP Ces mécanismes permettent aux projets d’intervenir uniquement sur les points nécessaires sans impacter les autres extensions ou le cœur du produit.

2. Surcharge de la configuration Spring

2.1 Description de la fonctionnalité

Chaque extension dispose de son propre contexte Spring, isolé. Les projets peuvent surcharger les beans en déclarant leur propre configuration XML, sans impacter le produit ou les autres extensions.

Ce mécanisme permet de modifier la valeur d’un ou plusieurs attributs d’un bean, ou de le redéfinir totalement.

2.2 Architecture générale

Prenons l’exemple du bean pagelibreContentViewPreparer :

<bean id="pagelibreContentViewPreparer" class="com.kosmos.pagelibre.PagelibreContentViewPreparer" parent="contentViewPreparer">
    <property name="type" value="content"/>
    <property name="view" value="/extensions/pagelibre/WEB-INF/jsp/pagelibre-content.jsp"/>
    <property name="expectedViewTypes">
        <value>contentBox</value>
    </property>
</bean>

• type : permet à un autre viewPreparer, comme un preparer de template, de demander à ce que soit préparé un certain type de bean.

• view : correspond au chemin vers la JSP du modèle à afficher.

• expectedViewTypes : liste les types de vues qui seront préparés via AbstractViewPreparer.prepareExpectedViews(). Ce mécanisme permet notamment à un template d’utiliser des sous-vues (header, body, content…) sans connaître leur implémentation exacte. Il existe également d'autres paramètres communs:

• includedSiteTemplate : indique la liste des template ou ce preparer doit être utilisé

• excludedSiteTemplate : indique la liste des template ou ce preparer NE doit Pêtre utilisé

• order : priorise le bean lors de la recherche de beans.

2.3 Procédure

Pour surcharger ce bean, il suffit de créer un fichier XML dans le dossier resources/spring du projet.

Ce fichier doit être explicitement importé par le fichier de contexte de l’extension concernée. Par exemple, dans l’extension Pagelibre :

<!-- Ouverture à la surcharge projet -->
<import resource="classpath*:spring/pagelibre-override.xml"/>

On place alors dans resources/spring/pagelibre-override.xml une redéfinition partielle ou totale du bean concerné, selon les besoins du projet.

3. Cas d’usage : surcharge d’un ViewPreparer

La surcharge de configuration Spring est souvent utilisée pour injecter des beans spécifiques dans le projet. Un cas fréquent est celui des ViewPreparer, introduits dans le cadre de la refonte des vues dynamiques.

3.1 Fonctionnement général des ViewPreparer

Chaque ViewPreparer fournit un modèle (ViewModel) associé à une vue, utilisable dans une JSP.

Lorsqu’un contrôleur est appelé, il demande une vue adaptée à son contexte. Le système parcourt les ViewPreparer déclarés en tant que beans Spring et sélectionne le premier qui accepte de préparer la vue (via la méthode accept()).

3.2 Surcharge via Spring : injection du nouveau bean

Un projet peut vouloir injecter son propre ViewPreparer, plus prioritaire que celui du socle. Il suffit pour cela :

1. De créer un bean dans un fichier -override.xml
2. De le rendre prioritaire via la propriété order
3. D’utiliser un parent pour hériter de la configuration existante

Exemple : Ajout de la date en haut des pages libres

<!-- Pagelibre avec affichage de la date de mise à jour -->
<bean id="datedPagelibreContentViewPreparer" class="com.kosmos.pagelibre.DatedPagelibreContentViewPreparer" parent="pagelibreContentViewPreparer">
    <property name="order" ref="ORDRE_CRITIQUE"/>
    <property name="view" value="/WEB-INF/jsp/pagelibre/pagelibre-content.jsp"/>
</bean>

Définir un order plus prioritaire que celui du bean par défaut est indispensable pour que ce nouveau bean soit sélectionné.

Bonne pratique : utiliser la constante Spring suivante pour avoir la priorité la plus haute possible :

<util:constant id="ORDRE_CRITIQUE" static-field="org.springframework.core.Ordered.HIGHEST_PRECEDENCE"/>

3.3 Surcharge via Java : redéfinition du comportement prepare()

Dans la classe Java associée au nouveau bean, on peut redéfinir le comportement métier, tout en conservant celui du bean parent.

Exemple Java

public class DatedPagelibreContentViewPreparer extends PagelibreContentViewPreparer<PagelibreContentViewModel> {

    @Override
    public PagelibreContentViewModel prepare(final FrontContext frontContext, final Map<String, List<IViewPreparer>> preparers) {
        final PagelibreContentViewModel pagelibreContentViewModel = super.prepare(frontContext, preparers);
        final ContentContext contentContext = ContentContext.of(frontContext);
        final PagelibreBean bean = contentContext.getContent();
        pagelibreContentViewModel.setPublicationDate(PublicationDateProcessor.process(
            contentContext.getMetatag().getMetaDateMiseEnLigne(),
            bean.getDateModification()
        ));
        return pagelibreContentViewModel;
    }
}

Ce mécanisme permet de personnaliser complètement la donnée injectée dans la JSP sans perturber les autres composants.

3.4 Surcharge du ViewModel (optionnel)

Il est également possible d’utiliser un ViewModel différent pour y injecter des attributs supplémentaires spécifiques au projet. Il faut alors :

• Définir un nouveau modèle Java
• Adapter la JSP en conséquence (voir section suivante)

4. Surcharge de JSP

4.1 Description de la fonctionnalité

L’interface peut être adaptée en redéfinissant les fragments JSP utilisés. Deux approches principales sont possibles :

• Surcharge par redéfinition à l'identique
• Surcharge par modification du chemin dans le bean

4.2 Surcharge par redéfinition du fichier à l'identique

Il s’agit de redéfinir un fichier JSP à l’identique dans le projet.

Le fichier du projet, s’il est trouvé à un chemin identique, sera utilisé à la place de celui du socle.

Exemple : surcharge de la JSP Pagelibre

Le bean pagelibreContentViewPreparer utilise la JSP suivante :

/WEB-INF/jsp/pagelibre/pagelibre-content.jsp

Pour la surcharger, il faut créer dans le projet le fichier suivant :

src/main/webapp/WEB-INF/jsp/pagelibre/pagelibre-content.jsp

Le moteur de rendu utilisera automatiquement la version projet s’il la trouve à cet emplacement.

4.3 Surcharge par changement de chemin de vue

Une autre solution consiste à ne pas surcharger par overlay, mais à déclarer un nouveau chemin de JSP dans un bean surchargé. Cela permet d’avoir un fichier au nom différent, plus clair, et de coexister avec la version produit sans la masquer.

Exemple dans le bean projet :

<property name="view" value="/WEB-INF/jsp/pagelibre/pagelibre-content-projet.jsp"/>

Cette méthode est particulièrement utile pour éviter toute ambiguïté ou écrasement involontaire.

Attention, il n'est parfois pas nécessaire de surcharger une vue entièrement pour modifier l'affichage. Si l'élément à modifier est défini par une propriété (comme il est courant pour les messages), il suffit de surcharger cette propriété via un fichier properties.

Modifier le fichier

Principes d'intégration des vues

Déclaration d'une nouvelle vue

1. Créer la jsp de la vue
2. Créer un viewModel hériant de AbstractViewModel qui contient les données de la vue

public class MyViewModel extends AbstractViewModel {
    ...
}

3. Créer un viewPreparer qui hérite de AbstractViewPreparer
   • Implémenter la méthode accept, pour définir le contexte d'utilisation de la vue
   • Implémenter la methode prepare, pour injecter les données dans le modèle

import com.kosmos.context.front.FrontContext;

public class MyViewPreparer<V extends MyViewModel> extends AbstractViewPreparer<V> {

   @Override
   public boolean accept(FrontContext context) {
        ...
   }

   @Override
   public V prepare(FrontContext context, final Map<String, List<IViewPreparer>> preparers) {
      final V viewModel = super.prepare(context, preparers);
        ...
      return viewModel;
   }
}
}

4. Déclarer le bean du viewPreparer en spécifiant
   • Le type de vue
   • Le chemin vers la jsp de la vue
   • Son ordre
   • Les types des sous-vues composant la vue
   • Les templates de site à inclure/exclure

<bean id="myViewPreparer" class="com.kosmos.preparer.MyViewPreparer">
    <property name="type" value="myViewType" />
    <property name="view" value="/WEB-INF/jsp/myView.jsp" />
    <property name="order" value="1000" />
    <property name="expectedViewTypes">
        <list>
            ...
        </list>
    </property>
    <property name="includedSiteTemplate">
        <list>
            ...
        </list>
    </property>
    <property name="excludedSiteTemplate">
        <list>
            ...
        </list>
    </property>
</bean>

Retrait d'un code de template site dans les listes includedSiteTemplate/excludedSiteTemplate d'une vue produit

1. Effectuer un AttributeToOverrideBean pour modifier les listes includedSiteTemplate/excludedSiteTemplate

<bean id="myArticleViewPreparer" class="com.kportal.core.context.AttributeToOverrideBean">
    <property name="idExtensionToMerge" value="article"/>
    <property name="idBeanToMerge" value="articleViewPreparer"/>
    <property name="attributes">
        <map>
            <entry key="includedSiteTemplate">
                <list>
                    ...
                </list>
            </entry>
            <entry key="excludedSiteTemplate">
                <list>
                    ...
                </list>
            </entry>
        </map>
    </property>
</bean>

Ajout d'un code de template site dans les listes includedSiteTemplate/excludedSiteTemplate d'une vue

1. Effectuer un ListToAddBean pour ajouter les codes désirés dans les listes includedSiteTemplate/excludedSiteTemplate

 <bean id="myArticleViewPreparer" class="com.kportal.core.context.ListToAddBean">
   <property name="idBeanToMerge" value="articleViewPreparer"/>
   <property name="idBeanToMerge" value="articleViewPreparer"/>
   <property name="listToMerge" value="includedSiteTemplate"/>
   <property name="add">
      <list>
         <value>template1</value>
      </list>
   </property>
</bean>

Modification de l'ordre de priorité d'une vue

1. Effectuer un AttributeToOverrideBean pour modifier l'attribut order sur le viewPreparer

<bean id="myArticleViewPreparer" class="com.kportal.core.context.AttributeToOverrideBean">
    <property name="idExtensionToMerge" value="article"/>
    <property name="idBeanToMerge" value="articleViewPreparer"/>
    <property name="attributes">
        <map>
            <entry key="order">
                <value>2000</value>
            </entry>
        </map>
    </property>
</bean>

Surcharge d'une vue pour modifier son affichage

Création d'une jsp sur le projet avec le même chemin et nom que la jsp à surcharger.

OU

Création d'une nouvelle jsp et modification du chemin de la vue dans le viewPreparer via AttributeToOverrideBean.

Surcharge d'une vue pour modifier le contenu du modèle

1. Création d'un nouveau viewPreparer qui étend le viewPreparer de la vue à surcharger
2. Override de la méthode prepare pour changer la construction du modèle
3. Déclaration du viewPreparer avec un order prioritaire au viewPreparer surchargé

Surcharge d'une vue pour modifier la structure du modèle

La modification de la structure du modèle implique la modification de tous les éléments de la vue (jsp, preparer, model). Cela implique donc de créer une nouvelle vue possédant la même méthode accept que la vue à surcharger et de lui assigner un order plus prioritaire.

Modifier le fichier

Intégration d'un nouveau controller affichant une vue

Récupération du handler

L'ajout d'un nouveau controller nécessite de récupérer le handler du type de page à afficher.

protected ModelAndView doGet(final HttpServletRequest request, final HttpServletResponse response) throws Exception {
    final Frontcontext context = initContext(request, result);
    final Map<String, MyHandler> handlerMap = ApplicationContextManager.getAllActivatedBeansOfType(MyHandler.class);
    final MyHandler handler = handlerMap.values().stream()
        .filter(h -> h.supports(request, response, context))
        .findFirst()
        .orElseThrow(() -> new IllegalStateException("Aucun handler trouvé"));
    return handler.getModelAndView(request, response, frontContext);
}

Création du handler

Le handler est une classe qui implémente l'interface ModelAndViewHandler.
Les handlers sont ordonnés afin de pouvoir déterminer lequel doit être utilisé en priorité.
Ils définissent une méthode supports qui permet de déterminer si le handler peut gérer la requête courante.
La méthode getModelAndView permet de récupérer le modèle et la vue à afficher.

public class MyHandler implements ModelAndViewHandler {

    private int order;

    @Override
    public boolean supports(final HttpServletRequest request, final HttpServletResponse response, final FrontContext frontContext) {
        final MyContext context = MyContext.of(frontContext);
        return myContext.canHandle();
    }

    @Override
    public ModelAndView getModelAndView(HttpServletRequest request, HttpServletResponse response, final FrontContext frontContext) {
        final MyContext context = MyContext.of(frontContext);
        final AbstractViewModel viewModel = ViewModelHelper.prepareViewModel("myTemplateType", contentContext, request, response);
        final ModelAndView modelAndView = new ModelAndView();
        modelAndView.setViewName(viewModel.getView());
        modelAndView.addAllObjects(viewModel.getAllViewModels());
        return modelAndView;
    }

    @Override
    public int getOrder() {
        return order;
    }

    public void setOrder(final int order) {
        this.order = order;
    }

}

Création de la vue

La création de la vue repose sur le même principe que pour les autres vues.
Un viewModel est créé et un viewPreparer est associé à ce viewModel (cf Principe d'intégration des vues).

Modifier le fichier

Intégration des encadrés

4 types d'encadrés sont disponibles dans K-Sup :

Chaque type d'encadré possède son modèle et son préparateur de vue.

Le modèle par défaut contient une liste de com.kosmos.box.Box, chaque Box contient un titre, et un contenu.

L'affichage par défaut de la zone d'encadré est déterminé par la présence de contenu préparé. Pour calculer la présence d'un contenu, le BoxesViewPreparer va itérer sur les preparedViews (les vues préparées via par le expectedViewTypes) et vérifier si la vue à un contenu. Pour cela, il faut que chaque vue du expectedViewTypes implémente l'interface BoxViewModel et la méthode hasContent().

Modifier le fichier

Les plugins

Intégration d'un plugin

L'intégration d'un plugin suit les mêmes principes d'intégration que pour les autres éléments :

• Création de la jsp de vue
• Déclaration d'un ViewModel
• Déclaration d'un ViewPreparer

Le ViewPreparer doit étendre AbstractPluginViewPreparer et déclarer quatre propriétés :

• dataKey : clé poussé dans le contexte pour stocker les informations du plugin
• idBean : permet de vérifier la présence du plugin sur la fiche courante
• idExtensionPoint : permet d'identifier de manière unique la vue du plugin
• pointNames : défini la liste des zones dans lequel le plugin va s'afficher.

Exemple :

<bean id="ficheLinkViewPreparer" class="com.kosmos.preparer.FicheLinkViewPreparer">
    <property name="type" value="fichelinkPlugin"/>
    <property name="view" value="/WEB-INF/jsp/ficheLinkPlugin.jsp"/>
    <property name="idBean" value="fichelinkPluginFiche"/>
    <property name="dataKey" value="fichelinkPluginFiche#fichelink"/>
    <property name="idExtensionPoint" value="fichelinkPluginFicheAddOn"/>
    <property name="pointNames">
        <list>
            <value>default-plugins</value>
        </list>
    </property>
</bean>

Cela permet de bénéficier de la méthode accept du AbstractPluginViewPreparer qui vérifie si le plugin est présent dans le contexte courant et s'il est disponible pour la fiche courante et permet également au plugin d'être récupéré par le PluginsViewPreparer (voir section suivante),

Inclusion de tous les plugins

Il est possible de faire une inclusion de tous les plugins disponibles pour la fiche courante au sein de la page. Le ViewPreparer dans lequel les plugins seront injectés doi ajoutés dans sa liste de expectedViewTypes le type plugins.

<property name="expectedViewTypes">
    <value>plugins</value>
</property>

L'ajout du type plugins dans les expectedViewTypes va effectuer la préparation du PluginsViewPreparer.
Le PluginsViewPreparer est en charge de récupérer la liste des tous les ViewPreparer qui étendent AbstractPluginViewPreparer et appeler la méthode prepare de chaque ViewPreparer; les ViewModel résultants sont poussés dans la map reliant chaque zones d'affichages aux plugins qui y sont abonnés, dans PluginsViewModel.
L'affichage des plugins est géré par le pluginAddOn.

Modifier le fichier

Intégration d'une carte de layout

L'intégration d'une carte de layout utilise le fonctionnement standard des viewPreparers.

Définition d'un viewPreparer de carte

Le mécanisme s'appuie sur un viewModel qui étend AbstractCardViewModel

public class AcmeCardViewModel extends AbstractCardViewModel {
    private String uuid;
    private String subtitle;
    
    ...
}

et d'un preparer qui étend AbstractCardViewPreparer.

public class AcmeCardViewPreparer<V extends AcmeCardViewModel> extends AbstractCardViewPreparer<V> {

    protected ServiceAcme serviceAcme;

    ...

    @Override
    public boolean accept(final FrontContext context) {
        return super.accept(context) && CardContext.of(context).getCard() instanceof AcmeCardBean && ...;
    }

    @Override
    public V prepare(final FrontContext context, final Map<String, List<IViewPreparer>> preparers) {
        final V viewModel = super.prepare(context, preparers);
        final AcmeCardBean card = CardContext.of(context).getCard();
        ...
}

Déclaration d'un viewPreparer de carte

Création d'un viewPreparer qui à pour parent abstractCardViewPreparer et déclare comme propriétés :

• type : card
• view : La jsp correspondant à la carte

<bean id="acmeCardViewPreparer" parent="abstractCardViewPreparer">
    <property name="type" value="card"/>
    <property name="view" value="/WEB-INF/jsp/layout/acme.jsp"/>
    <property name="serviceAcme" value="serviceAcme"/>
    ...
</bean>

Modifier le fichier

Intégration d'une fiche

Les fiches de K-Sup sont servies par défaut par le ContentHandler, celui-ci va récupérer les viewPreparer de type template afin de retrouver la liste des templates de fiche disponibles pour le template de site courant.

Le template va représenter la structure globale de la page, celui-ci défini les types de vue présents à la racine de la vue principale (exemple : head, header, ..., body, ..., footer).

Création d'un template de fiche

Par défaut, le template de fiche est défini globalement pour l'ensemble des fiches (via le template du site), il est possible de définir un template de fiche spécifique pour un type de contenu.

1. Création d'un viewPreparer qui hérite de AbstractContentViewPreparer

public class ArticleTemplateViewPreparer extends AbstractContentViewPreparer<ArticleTemplateViewModel> {
    
    @Override
    public boolean accept(ContentContext context) {
        return context.getContent() instanceof ArticleBean;
    }

    @Override
    public ArticleTemplateViewModel prepare(FrontContext context, final Map<String, List<IViewPreparer>> preparers) {
        return super.prepare(context, preparers);
    }
}

2. Création du viewModel, l'id du viewModel des fiches est par défaut mainViewModel (défini dans MainViewModel).

public class ArticleTemplateViewModel extends AbstractContentViewModel {

}

3. Définition du bean viewPreparer avec le type template

<bean id="articleTemplateViewPreparer" class="com.kosmos.preparer.ArticleTemaplateViewPreparer">
    <property name="order" value="-100" />
    <property name="type" value="template" />
    <property name="view" value="/WEB-INF/jsp/article.jsp" />
    <property name="expectedViewTypes">
        <list>
            <value>head</value>
            <value>header</value>
            <value>body</value>
            <value>footer</value>
            <value>autologin</value>
        </list>
    </property>
</bean>

4. Création de la jsp principale qui effectue l'insertion des sous-vues

<%@ page trimDirectiveWhitespaces="true" errorPage="/WEB-INF/jsp/error/exception.jsp" %>

<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>

<%--@elvariable id="headViewModel" type="com.kosmos.core.model.fragments.HeadViewModel"--%>
<%--@elvariable id="headerViewModel" type="com.kosmos.core.header.HeaderViewModel"--%>
<%--@elvariable id="bodyViewModel" type="com.kosmos.body.BodyViewModel"--%>
<%--@elvariable id="footerViewModel" type="com.kosmos.footer.FooterViewModel"--%>

<!DOCTYPE html>
<html>
<c:if test="${not empty headViewModel.view}">
    <jsp:include page="${headViewModel.view}"/>
</c:if>
<body class="k-body">
<c:if test="${not empty headerViewModel.view}">
    <jsp:include page="${headerViewModel.view}"/>
</c:if>
<jsp:include page="${bodyViewModel.view}"/>
<c:if test="${not empty footerViewModel.view}">
    <jsp:include page="${footerViewModel.view}"/>
</c:if>
</body>
</html>

Création d'un contenu de fiche

1. Création d'un viewPreparer qui hérite de AbstractContentViewPreparer

public class ArticleContentViewPreparer<V extends ArticleContentViewModel> extends AbstractContentViewPreparer<V> {

    @Override
    public boolean accept(final FrontContext context) {
        return ContentContext.of(context).getContent() instanceof ArticleBean;
    }

    @Override
    public V prepare(final FrontContext frontContext, final Map<String, List<IViewPreparer>> preparers) {
        final V viewModel = super.prepare(frontContext, preparers);
        final ContentContext contentContext = ContentContext.of(frontContext);
        final ArticleBean bean = contentContext.getContent();
        viewModel.setPublicationDate(PublicationDateProcessor.process(contentContext.getMetatag().getMetaDateMiseEnLigne(), bean.getDateModification()));
        viewModel.setDate(prepareDate(bean));
        ...
        return viewModel;
    }
}

2. Création du viewModel (l'id du viewModel des fiches est par défaut mainViewModel (défini dans MainViewModel))

public class ArticleContentViewModel extends AbstractContentViewModel {

    private String corps;

    private String resume;

    private String dateCreation;

    private String dateUpdate;

    private String sousTitre = StringUtils.EMPTY;

    private Set<String> thematiques = new HashSet<>();
    
    ...
}

3. Définition du bean viewPreparer avec le type content

<bean id="articleContentViewPreparer" class="com.kosmos.preparer.ArticleContentViewPreparer">
    <property name="type" value="content"/>
    <property name="view" value="/WEB-INF/jsp/article-content.jsp"/>
</bean>

4. Création de la jsp d'affichage du contenu

<%@ page trimDirectiveWhitespaces="true" %>
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
<%@ taglib prefix="kuik" uri="kuik" %>
<%@ taglib prefix="kore" uri="kore" %>

<%--@elvariable id="mainViewModel" type="com.kosmos.article.ArticleContentViewModel"--%>
<%--@elvariable id="contentBoxViewModel" type="com.kosmos.content.box.ContentBoxViewModel"--%>

<div class="l-col-9°md l-col-12">
    <article class="grid">
        <c:if test="${not empty mainViewModel.topics}">
            <ul class="list list--inlined l-col-12">
                <c:forEach items="${mainViewModel.topics}" var="thematique">
                    <li class="list__item"><kuik:cartouche size="xl"><c:out value="${thematique}"/></kuik:cartouche></li>
                </c:forEach>
            </ul>
...

5. Répéter les étapes 1 à 4 pour créer les sous-vues qui composeront la page

Modifier le fichier

Intégration d'un nouveau style de liste

Description

Les styles de liste permettent de mettre en forme le résultat d'une requête de liste de fiches au niveau des toolbox notamment.

<span class="klist">[traitement;requete;objet=actualite#TRI_DATE=DATE_ASC#STYLE=0002#CODE_RUBRIQUE=1733170925027#NOMBRE=3#DATE_PATTERN_FORMAT=dd/MM/yyyy]</span>

Création de style de liste

La création d'un nouveau style nécessite les opérations suivantes :

Déclaration du style de liste

Les différents styles de liste doivent être déclarés dans un fichier dat adapté au contenu.
Pour cela, créer un fichier /resources/tables/<<EXTENSION>>/<<OBJET>>_style_affichage.dat avec les différents styles à intégrer.
Par exemple, /resources/tables/annuairesup/ANNUAIREKSUP_style_affichage.dat pour créer des style d'affichage pour l'objet Annuaire de l'extension Annuairesup.

Titre + Dates + Résumé                                              0001
Titre + Dates + Lieux                                               0002
Titre + Dates                                                       0003

Création d'un bean d'affichage

Le produit met à disposition le bean KsupMedia qui est directement utilisable par le tag media de la librairie ksup-components.

<%@ page trimDirectiveWhitespaces="true" %>
<%@ taglib prefix="kuik" uri="kuik" %>

<%--@elvariable id="contentListItemViewModel" type="com.kosmos.content.list.AbstractContentListItemViewModel"--%>

<kuik:media media="${contentListItemViewModel.content}" orientation="vertical"/>

Il est possible de typer plus fortement le contenant en étendant cette classe.

public class ActualiteMediaCard extends KsupMedia {}

Les données préparées seront stockées dans ce bean.

Création du viewModel d'élément de liste

Afin de mutualiser le code, un viewModel container encapsule le bean de données.

public class ActualiteContentListItemViewModel<T extends ActualiteMediaCard> extends AbstractContentListItemViewModel<T> {}

Création d'un builder commun aux différents style de liste

Ce builder ksupMediaBuilder mutualise les éléments communs:

public class KsupMediaBuilder<T extends KsupMediaBuilder<T, C, B>, C extends KsupMedia, B extends AbstractFicheBean> {
    ...
}

Ce builder construit les éléments communs a toute les fiches

• Titre (Inconditionnel)
• Lien vers le contenu (Inconditionnel)
• Thématiques (Conditionnel)
• Résumé (Conditionnel)
• Image (Conditionnel)

exemple

    ...
    final MediaCard data = new KsupMediaBuilder<>(context, thumbnailViewPreparer, serviceActualite)
        .withTopics()
        .withSummary()
        .build
    ...

Etendre le builder a tous les styles de fiches

public class ActualiteMediaCardBuilder<C extends ActualiteMediaCard> extends KsupMediaBuilder<ActualiteMediaCardBuilder<C>, C, ActualiteBean> {
    ...
}

Ce builder étend KsupMediaBuilder et ajoute

• Sous-titre (Conditionnel)
• Date (Conditionnel)

exemple

    ...
    final ActualiteMediaCard Actualitedata = new ActualiteMediaCardBuilder<>(context, thumbnailViewPreparer, serviceActualite)
        .withTopics()
        .withDate()
        .withSubtitle()
        .build
    ...

Création du preparer abstrait d'élément de liste

Ce preparer a pour fonction de mutualiser le code commun à tous vos styles de liste:

public abstract class AbstractActualiteContentListItemViewPreparer<V extends ActualiteContentListItemViewModel<ActualiteMediaCard>> extends AbstractContentListItemViewPreparer<V> {
    
    protected ServiceActualite serviceActualite;

    ...
    @Override
    public boolean accept(final FrontContext context) {
        return ContentContext.of(context).getContent() instanceof ActulaliteBean
               && this.supportedStyle().equals(context.get(ContentListTagProcessor.STYLE, String.class));
    }

    public void setServiceActualite(final ServiceActualite serviceActualite) {
        this.serviceActualite = serviceActualite;
    }
}

Création des preparers de liste et d'éléments de liste

Ensuite,

• dériver la classe abstraite avec chaque style de liste,

public class Style1ActualiteContentListItemViewPreparer<V extends ActualiteContentListItemViewModel<ActualiteMediaCard>> extends AbstractActualiteContentListItemViewPreparer<V> {
    ...
}

• définir une condition pour prise en charge du preparer

    @Override
    protected String supportedStyle() {
        return "0001";
        }

• surcharger la méthode prepare

    @Override
    public V prepare(final FrontContext context, final Map<String, List<IViewPreparer>> preparer) {
        ...
        }

La méthode prepare est structurée de la manière suivante:

• la génération du viewModel via le super.prepare(..) et construction de la MediaCard via builder

    @Override
    public V prepare(final FrontContext context, final Map<String, List<IViewPreparer>> preparer) {
        final V viewModel = super.prepare(context, preparer);
        final ActualiteMediaCard actualiteMediaCard = new ActualiteMediaCardBuilder<>(context, thumbnailViewPreparer, serviceActualite)
            .withTopics()
            .withSummary()
            .build();
            viewModel.setContent(actualiteMediaCard);
            return viewModel;
    }

Déclaration des beans de style dans le contexte de l'extension

La dernière étape consiste à déclarer les beans dans le fichier de contexte de l'extension /resources/spring/<<EXTENSION>>-override.xml

    <bean id="abstractActualiteContentListItemViewPreparer" class="com.kosmos.actualite.AbstractActualiteContentListItemViewPreparer" abstract="true" parent="abstractContentListItemViewPreparer">
        <property name="serviceActualite" ref="actualiteService"/>
        <property name="order" value="-10000"/>
    </bean>

    <bean id="style1ActualiteContentListItemViewPreparer" class="com.kosmos.actualite.Style1ActualiteContentListItemViewPreparer" parent="abstractActualiteContentListItemViewPreparer"/>
    
    <bean id="style2ActualiteContentListItemViewPreparer" class="com.kosmos.actualite.Style2ActualiteContentListItemViewPreparer" parent="abstractActualiteContentListItemViewPreparer"/>

Activation des styles de liste

Les styles de liste ne sont pas disponibles par défaut sur tous les types de contenus.
Pour permettre à l'utilisateur de sélectionner un style de liste lors de la contribution d'un tag liste, la propriété fiche.<<OBJET>>.style_affichage doit être valorisée à :

• 1 (style obligatoire)
• 2 (style optionnel)

Ajouter la clé dans le fichier application_<<EXTENSION>>.properties de votre projet ou env_<<EXTENSION>>.properties de votre storage selon le besoin.

fiche.DOCUMENT.style_affichage=2

How to

Je veux un affichage spécifique de mon élément de liste

Par défaut les éléments de liste utilisent la configuration produit

<bean id="abstractContentListItemViewPreparer" class="com.kosmos.content.list.AbstractContentListItemViewPreparer" abstract="true">
    <property name="type" ref="TYPE_CONTENT_LIST_ITEM"/>
    <property name="view" value="/WEB-INF/jsp/toolbox/content-list-item.jsp"/>
</bean>

Tout bean dont le parent direct ou indirect est abstractContentListItemViewPreparer et qui ne surcharge pas la vue utilisera la jsp content-list-item.jsp du produit.

<%@ page trimDirectiveWhitespaces="true" %>
...

<%--@elvariable id="contentListItemViewModel" type="com.kosmos.content.list.AbstractContentListItemViewModel"--%>

<li class="l-col-12 l-col-6°sm l-col-4°md">
    <kuik:media media="${contentListItemViewModel.content}" orientation="vertical">
        ...
    </kuik:media>
</li>

Pour avoir un visuel spécifique, ajoutez la propriété view dans la définition de votre bean (abstract ou styleX selon vos besoins)

    <bean id="abstractActualiteContentListItemViewPreparer" class="com.kosmos.actualite.AbstractActualiteContentListItemViewPreparer" abstract="true" parent="abstractContentListItemViewPreparer">
        <property name="serviceActualite" ref="actualiteService"/>
        <property name="order" value="-10000"/>
    </bean>

    <bean id="style1ActualiteContentListItemViewPreparer" class="com.kosmos.actualite.Style1ActualiteContentListItemViewPreparer" parent="abstractActualiteContentListItemViewPreparer">
        <property name="view" value="/jsp/actualite/style1.jsp"/>
    </bean>
    
    <bean id="style2ActualiteContentListItemViewPreparer" class="com.kosmos.actualite.Style2ActualiteContentListItemViewPreparer" parent="abstractActualiteContentListItemViewPreparer"/>
    
    ...

et créez la jsp avec votre affichage spécifique. L'élément de liste est disponible dans le scope "request" sous le nom contentListItemViewModel

    ...
    <span>${contentListItemViewModel.content.title}</span>
    ...

Je veux un affichage spécifique de ma liste

C'est le même principe qu'au dessus, mais avec le bean abstractContentListViewPreparer

Je veux un style de liste même si le style n'est pas défini

Par défaut, s'il n'y a pas de style défini, le produit affiche simplement le libellé de la fiche dans une liste à puce (<ul> + <li> natif html).

Il est cependant possible de forcer un affichage différent.
Pour cela, il faut définir un preparer qui étend AbstractContentListViewPreparer et un qui étend AbstractContentListItemViewPreparer. Ces beans vont prendre l'ascendant par rapport aux preparers par défaut.

    <bean id="acmeContentListViewPreparer" class="com.kosmos.acme.AcmeContentListViewPreparer"  parent="abstractContentListViewPreparer">
    <property name="view" value="/jsp/acme/content-list.jsp"/>
        <property name="order" value="-10000"/>
    </bean>

    <bean id="acmeContentListItemViewPreparer" class="com.kosmos.acme.AcmeContentListItemViewPreparer" parent="abstractContentListItemViewPreparer">
        <property name="view" value="/jsp/acme/content-list-item.jsp"/>
        <property name="order" value="-10000"/>
    </bean>

Mon élément de liste n'est pas une fiche ou le contenu n'étend pas KsupMedia

L'effacement de type est ouvert (pas d'extends) : vous pouvez faire une liste de n'importe quel bean.
Par exemple, regarder le modèle de vue com.kosmos.toolbox.DefaultContentListItemViewModel et son preparer com.kosmos.content.list.DefaultContentListItemViewPreparer dans le module webapp-front de koreparent.

Modifier le fichier

Tutoriel : Mise en place d'une personnalisation projet de la structure de la page

Construction de la structure d'une page

Les pages refronte sont construites à partir de différents ViewModel. La structure de la page est définie par le modèle de vue "template". Le template possède en sous-vue les principaux bloc de la page, qui ont eux-mêmes des sous-vues.

Structure par défaut des pages K-Sup V7

Ce système d'emboitement de vue permet de personnaliser une partie de la structure de la page sans impacter le reste, par exemple personnaliser le header. On peut toutefois vouloir modifier la structure globale de la page.

Pour rappel, on parle ici de template au sens de template de page, pas de template de site. Cf documentation sur les templates de site. On peut créer un nouveau template de site sans nouveau template de page, en déclarant de nouveaux viewPreparer pour les zones à personnaliser.

Architecture générale

Le template des pages suit le pattern MVC de Spring et s'intègre dans l'architecture K-Sup avec les composants suivants :

• ViewPreparer de template : hérite de DefaultTemplateViewPreparer
• Bean de déclaration du template : implémente le viewPreparer, liste les sous-vues
• Jsp du template : la jsp d'affichage

Il n'y a généralement pas besoin de personnaliser le modèle de vue, le template n'affiche pas de données. Les données sont portées par les sous-vues.

Procédure

Le tutoriel présenté ci-dessous reprend les principes de personnalisation de la structure. Il n'est pas toujours obligatoire de modifier tous les éléments listés.

Déclarer le bean du prépareur de vue

En fonction de la personnalisation voulue, il ne sera pas utile de personnaliser tous les éléments :

• Si la condition d'utilisation du template est sur un template de site, il n'est pas utile de créer un nouveau préparer de vue. Il faut déclarer un bean de classe DefaultTemplateViewPreparer et indiquer le code du template dans la propriété includedSiteTemplate du bean.
• Si la personnalisation du template consiste à ne pas utiliser certain type de sous-vue, il n'y a pas besoin de personnaliser la jsp

Exemple de bean à déclarer :

    <util:constant id="codeTemplateVotreTemplate" static-field="fr.votreprojet.utils.VotreprojetUtils.CODE_TEMPLATE_VOTRETEMPLATE"/>

    <bean id="votreTemplateViewPreparer" class="fr.votreprojet.template.view.VotreTemplateViewPreparer">
        <property name="type" value="template" />
        <property name="view" value="/WEB-INF/jsp/votreProjet/main.jsp" />
        <property name="expectedViewTypes">
            <list>
                <value>head</value>
                <value>header</value>
                <value>body</value>
                <value>footer</value>
            </list>
        </property>
        <property name="includedSiteTemplate">
            <list>
                <ref bean="codeTemplateVotreTemplate"/>
            </list>
        </property>
    </bean>

Créer le préparateur de vue du template

La classe fr.votreprojet.template.view.VotreTemplateViewPreparer permet de spécifier les conditions d'utilisation du template et de préparer les données qui vont être affichées

/**
 * Préparateur de la vue de [Description].
 */
public class VotreTemplateViewPreparer extends DefaultTemplateViewPreparer {

    /**
     * Indique si le préparateur de contenu est habilité à traiter une requête en fonction du contexte.
     * @param frontContext Le contexte.
     * @return true si le préparateur est habilité, false sinon.
     */
    @Override
    public boolean accept(final FrontContext frontContext) {
        return // vos conditions;
    }
}

Créer la jsp d'affichage

Créer la jsp à l'emplacement indiqué dans le bean :

<%@ page trimDirectiveWhitespaces="true" errorPage="/WEB-INF/jsp/error/exception.jsp" %>

<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>

<%--@elvariable id="headViewModel" type="com.kosmos.core.model.fragments.HeadViewModel"--%>
<%--@elvariable id="headerViewModel" type="com.kosmos.core.header.HeaderViewModel"--%>
<%--@elvariable id="bodyViewModel" type="com.kosmos.body.BodyViewModel"--%>
<%--@elvariable id="footerViewModel" type="com.kosmos.footer.FooterViewModel"--%>

<!DOCTYPE html>
<html lang="${headViewModel.lang}">
    <c:if test="${not empty headViewModel.view}">
        <jsp:include page="${headViewModel.view}"/>
    </c:if>
    <body class="k-body body l-expanded-body">
        <c:if test="${not empty headerViewModel.view}">
            <jsp:include page="${headerViewModel.view}"/>
        </c:if>
        <jsp:include page="/WEB-INF/jsp/technical/pre-content.jsp" />
        <jsp:include page="${bodyViewModel.view}"/>
        <c:if test="${not empty footerViewModel.view}">
            <jsp:include page="${footerViewModel.view}"/>
        </c:if>
        <jsp:include page="/WEB-INF/jsp/technical/footer.jsp" />
    </body>
</html>

Modifier le fichier

Personnalisation d'une partie de la page

Description de la fonctionnalité

Quelle que soit la partie à personnaliser, il faut se rapprocher au maximum du fonctionnement produit et ne personnaliser qu'en cas d'absolu nécessité. Chaque partie de la page a un type. Il est possible de définir plusieurs affichages par type et de conditionner l'affichage au template de site, ou sur d'autres critères. Ici, on prend pour exemple la personnalisation du header par l'ajout d'une sous-vue.

Architecture générale

Le header suit le pattern MVC de Spring et s'intègre dans l'architecture K-Sup avec les composants suivants :

• ViewPreparer : hérite de AbstractViewPreparer
• ViewModel : hérite de AbstractViewModel
• Bean du ViewPreparer : déclaration du bean du ViewPreparer personnalisé
• Bean du Header : ajoute le ViewPreparer personnalisé
• Jsp du header : ajoute le ViewModel personnalisé
• Jsp personnalisée : l'affichage qu'on souhaite ajouter au header

Procédure

Créer le modèle de vue

Créer le modèle de vue contenant les données à afficher :

package fr.votreprojet.votrepackage;

/**
 * Modèle de vue [description]
 */
public class ExempleViewModel extends AbstractViewModel {
 
    private AttributExemple attributExemple;
 
    @Override
    public String getId() {
        return "exempleViewModelId";
    }
 
    public AttributExemple getAttributExemple() {
        return attributExemple;
    }
 
    public void setAttributExemple(final AttributExemple attributExemple) {
        this.attributExemple = attributExemple;
    }
}

Créer le préparer de vue

Créer le préparer de vue, indiquer les conditions d'utilisation dans la méthode ExempleViewPreparer#accept et préparer les données à afficher dans la méthode ExempleViewPreparer#prepare.

package fr.votreprojet.votrepackage;

/**
 * Préparateur de la vue [description]
 */
public class ExempleViewPreparer extends AbstractViewPreparer<ExempleViewModel> {

    /**
     * Indique si le préparateur de contenu est habilité à traiter une requête en fonction du contexte.
     * @param frontContext Le contexte.
     * @return true si le préparateur est habilité, false sinon.
     */
    @Override
    public boolean accept(final FrontContext context) {
        return ...; // Les conditions d'affichage, si besoin.
    }

    /**
     * Prépare le modèle de la vue en fonction du contexte.
     * @param frontContext Le contexte d'affichage
     * @param preparers les preparers de la page courante
     * @return Le modele T qui étend {@link AbstractViewModel}.
     */
    @Override
    public ExempleViewModel prepare(final FrontContext frontContext, final Map<String, List<IViewPreparer>> preparers) {
        final ExempleViewModel viewModel = super.prepare(frontContext, preparers);
        viewModel.setAttributExemple(attributExemple);
        return viewModel;
    }
}

Déclarer les beans

Déclaration du bean du ViewPreparer du nouvel élément et déclaration du header projet pour y ajouter le nouveau type dans la liste expectedViewTypes :

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:util="http://www.springframework.org/schema/util"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util.xsd">

    <!-- ViewPreparer d'exemple -->
    <bean id="exempleViewPreparer" class="fr.votreprojet.votrepackage.ExempleHeaderViewPreparer">
        <property name="type" value="exemple"/>
        <property name="view" value="/WEB-INF/jsp/votreChemin/exemple.jsp"/>
    </bean>

    <bean id="votreHeader" class="com.kosmos.core.header.HeaderViewPreparer">
        <property name="type" value="header"/>
        <property name="view" value="/WEB-INF/jsp/votreChemin/headerVotreProjet.jsp"/>
        <property name="order">
            <util:constant static-field="org.springframework.core.Ordered.HIGHEST_PRECEDENCE"/>
        </property>
        <property name="attributes">
            <map>
                <entry key="expectedViewTypes">
                    <list>
                        <value>mainMenu</value>
                        <value>quickaccess</value>
                        <value>langMenu</value>
                        <value>panel-search-bar</value>
                        <value>exemple</value>
                    </list>
                </entry>
            </map>
        </property>
    </bean>
</beans>

Le paramétrage est commun à tous les ViewPreparer, cf documentation Construction des vues en front office. Pour rappel, on peut spécifier les templates sur lesquels les préparers de vue sont utilisées avec les paramètres suivants :

• includedSiteTemplate : liste des template sur lesquels le préparer de vue est accepté
• excludedSiteTemplate : liste des templates sur lesquels le préparer de vue est exclu

Attention, on ajoute un type de ViewModel dans la liste des view du header, pas directement un viewPreparer précis. Ce mécanisme permet de déclarer plusieurs ViewPreparer du même type, utilisés dans des cas différents. Par exemple, on pourrait avoir un seul header pour plusieurs template, mais vouloir spécifier notre ViewPreparer de type "exemple". C'est la méthode #accept des ViewPreparer qui permettra de déterminer quel ViewPreparer afficher. Si deux ViewPreparer sont acceptés, il est possible d'indiquer une priorité vie l'attribut order dans le bean.

Création de la jsp affichant les nouvelles données dans /WEB-INF/jsp/votreChemin/exemple.jsp :

...
<%@ page trimDirectiveWhitespaces="true" %>

<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>

<c:if test="${not empty exempleViewModelId.attributExemple}">
    <c:out value="${exempleViewModelId.attributExemple}"/>
</c:if>

...

Ajouter l'appel de la nouvelle vue dans /WEB-INF/jsp/votreChemin/headerVotreProjet.jsp :

...
<%--@elvariable id="exempleViewModelId" type="fr.votreprojet.votrepackage.ExempleViewModel"--%>
<c:if test="${not empty exempleViewModelId}">
    <jsp:include page="${exempleViewModelId.view}"/>
</c:if>
...

Modifier le fichier

Tutoriel : Créer un accueil de rubrique en refronte

Vue d'ensemble

Un accueil de rubrique permet définir un écran à afficher lorsque l'utilisateur se rend sur la rubrique. Il peut être de différents types (moteur de recherche, fiche, liste automatique...). La documentation utilisateur est disponible ici : https://docs.ksup.org/fr/version-6-7/utiliser/rubriques # TODO : URL à éditer

Architecture générale

L'accueil de rubrique suit le pattern MVC de Spring et s'intègre dans l'architecture K-Sup avec les composants suivants :

1. Classe d'accueil de rubrique : Hérite de DefaultPageAccueilRubrique
2. Bean de page d'accueil : Implémente BeanPageAccueil
3. View Model : Modèle de vue pour le front
4. View Preparer : Prépare les données pour la vue
5. Configuration : Configuration Spring

Étapes de création

Le tutoriel ci-dessous nous permettra de créer un accueil de rubrique qui affiche un titre et une description.

Créer le Bean de page d'accueil

Cette classe représente les données relatives à la page d'accueil, dans fr.votreprojet.votremodule.rubrique. La classe doit implémenter BeanPageAccueil.

package fr.votreprojet.votremodule.rubrique;

import java.io.Serial;

import org.apache.commons.lang3.StringUtils;

import com.kportal.extension.module.plugin.rubrique.BeanPageAccueil;

/**
 * Bean de la page d'accueil pour [Description de votre module].
 */
public class VotreModuleBeanPageAccueil implements BeanPageAccueil {

    /**
     * serialVersionUID.
     */
    @Serial
    private static final long serialVersionUID = -5646188278620975957L;
    
    /**
     * Le titre à afficher.
     */
    private String titre;

    /**
     * La description à afficher.
     */
    private String description;
    
    @Override
    public String getUrlRubrique(final String codeRubrique, final String langue, final boolean ampersands) {
        return StringUtils.EMPTY; // Indispensable actuellement pour le front legacy
    }

    @Override
    public String getUrlModification(final String codeRubrique, final String langue, final boolean ampersands) {
        return StringUtils.EMPTY; // Indispensable actuellement pour le front legacy
    }

    @Override
    public String getLibelleAffichable() {
        return StringUtils.EMPTY; // Indispensable actuellement pour le front legacy
    }

    public String getTitre() {
        return titre;
    }

    public void setTitre(final String titre) {
        this.titre = titre;
    }

    public String getDescription() {
        return description;
    }

    public void setDescription(final String description) {
        this.description = description;
    }
}

• Notes :
  • Les méthodes getUrlRubrique, getUrlModification et getLibelleAffichble étaient utilisées pour le front legacy. Il est encore nécessaire de les implémenter jusqu'à ce que le ticket CORE-7775 soit résolu.

Créer la classe d'accueil de rubrique

Il faut ensuite créer la classe fr.votreprojet.votremodule.rubrique.VotreModuleAccueilRubrique représentant l'accueil de rubrique (enregistrement et affichage en BO). Elle doit hériter de DefaultPageAccueilRubrique. Elle contient les méthodes preparerPRINCIPAL et traiterPRINCIPAL relatives à l'enregistrement et l'affichage de l'accueil de rubrique en BO :

package fr.votreprojet.votremodule.rubrique;

import java.io.Serial;
import java.util.Map;

import com.kportal.extension.module.plugin.rubrique.DefaultPageAccueilRubrique;

/**
 * Accueil de rubrique permettant d'afficher [Description de votre fonctionnalité].
 */
public class VotreModuleAccueilRubrique extends DefaultPageAccueilRubrique<VotreModuleBeanPageAccueil> {

    /**
     * Le type d'accueil de rubrique.
     */
    public static final String TYPE_ACCUEIL_RUBRIQUE = "8010";

    /**
     * serialVersionUID.
     */
    @Serial
    private static final long serialVersionUID = 2744706230254106056L;

    @Override
    public void preparerPRINCIPAL(final Map<String, Object> infoBean, final VotreModuleBeanPageAccueil beanPageAccueil) {
        // Logique de préparation des données si nécessaire
        infoBean.put("TITRE", beanPageAccueil.getTitre());
        infoBean.put("DESCRIPTION", beanPageAccueil.getDescription());
    }

    @Override
    public void traiterPRINCIPAL(final Map<String, Object> infoBean, final VotreModuleBeanPageAccueil beanPageAccueil) {
        // Logique de traitement des données si nécessaire
        beanPageAccueil.setTitre((String) infoBean.get("TITRE"));
        beanPageAccueil.setDescription((String) infoBean.get("DESCRIPTION"));
    }
}

• La constante TYPE_ACCUEIL_RUBRIQUE représente le code de l'accueil de rubrique. Il doit être unique
• Dans la méthode preparerPRINCIPAL, on affecte à l'infobean les données qui seront affichées en back-office.
• Dans la méthode traiterPRINCIPAL, on récupère les données de l'infobean pour pouvoir ensuite les enregistrer en base.

Créer le modèle de vue

Il faut ensuite créer un modèle de vue, permettant d'afficher les données. Dans notre cas, nous allons afficher un titre et une description contribués en back-office au sein d'une page. Dans fr.votreprojet.votremodule.view.model, on vient créer une classe VotreModuleViewModel.

package fr.votreprojet.votremodule.view.model;

import com.kosmos.body.BodyViewModel;

/**
 * Modèle de vue pour l'affichage de [Description].
 */
public class VotreModuleViewModel extends BodyViewModel {

    /**
     * Le titre.
     */
    private String titre;

    /**
     * La description.
     */
    private String description;

    /**
     * Constructeur.
     */
    public VotreModuleViewModel() {
        super();
    }

    // Getters et setters
    public String getTitre() {
        return titre;
    }

    public void setTitre(final String titre) {
        this.titre = titre;
    }

    public String getDescription() {
        return description;
    }

    public void setDescription(final String description) {
        this.description = description;
    }
}

• Notes :
  • Dans cet exemple, nous souhaitons afficher des données au sein d'une page sur un site K-Sup. Nous reprenons donc l'entête et le pied de page définis par défaut pour le site. Afin de ne surcharger que le contenu relatif au corps de la page, nous étendons BodyViewModel. (cf. Principe d'intégration)).

Créer le préparateur de vue

La classe fr.votreprojet.votremodule.view.preparer.VotreModuleViewPreparer permet de préparer les données qui vont être affichées.

package fr.votreprojet.votremodule.view.preparer;

import java.util.List;
import java.util.Map;

import com.kosmos.context.front.FrontContext;
import com.kosmos.context.front.SectionContext;
import com.kosmos.preparer.IViewPreparer;
import com.kosmos.section.home.AbstractSectionHomeViewPreparer;

/**
 * Préparateur de la vue de [Description].
 */
public class VotreModuleViewPreparer extends AbstractSectionHomeViewPreparer<VotreModuleViewModel> {

    @Override
    public boolean accept(final FrontContext context) {
        return super.accept(context) && SectionContext.of(context).getBeanPageAccueil() instanceof VotreModuleBeanPageAccueil;
    }

    @Override
    public VotreModuleViewModel prepare(final FrontContext context, final Map<String, List<IViewPreparer>> preparers) {
        final VotreModuleViewModel viewModel = super.prepare(context, preparers);
        final SectionContext sectionContext = SectionContext.of(context);
        // Préparer les données du viewModel
        final VotreModuleBeanPageAccueil beanPageAccueil = (VotreModuleBeanPageAccueil) sectionContext.getBeanPageAccueil();
        viewModel.setTitre(beanPageAccueil.getTitre());
        viewModel.setDescription(beanPageAccueil.getDescription());
        return viewModel;
    }
}

• *Notes :
  • La classe étend de AbstractSectionHomeViewPreparer puisqu'on veut afficher des données au sein d'une page K-Sup. Pour d'autres affichages, d'autres préparateurs de vue abstraits sont disponibles.
  • Méthode accept : cette méthode permet de savoir si le préparateur de vue peut préparer les données pour le bean de page d'accueil courant ;
  • Méthode prepare : cette méthode va préparer les données à afficher. Puisqu'on est au sein d'une page K-Sup, on récupère le contexte de la section (SectionContext).

Fichiers de propriétés pour l'internationalisation

On crée les fichiers relatifs aux traductions dans src/main/resources. Par exemple, pour les messages en français, on crée le fichier Application_votremodule_fr_FR.properties avec :

# Votre Module
## Accueil de rubrique
RUBRIQUE.PAGE_ACCUEIL_VOTRE_MODULE=Votre premier accueil de rubrique

VOTRE_PROJET.VOTRE_MODULE.RUBRIQUE.PAGE_ACCUEIL.BO.TITRE=Titre
VOTRE_PROJET.VOTRE_MODULE.RUBRIQUE.PAGE_ACCUEIL.BO.DESCRIPTION=Description

Configuration XML Spring

Il faut ensuite configurer les beans pour votre accueil de rubrique dans le fichier src/main/resources/spring/votreprojet-votremodule.xml Pour les paramètres du préparateur de vue, vous pouvez vous référer à la documentation Principes d'intégration des vues

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:util="http://www.springframework.org/schema/util"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd http://www.springframework.org/schema/util https://www.springframework.org/schema/util/spring-util.xsd">

    <util:constant id="ORDRE_CRITIQUE" static-field="org.springframework.core.Ordered.HIGHEST_PRECEDENCE"/>

    <!-- Préparateur de vue pour votre module -->
    <bean id="votreModuleViewPreparer" class="fr.votreprojet.votremodule.view.preparer.VotreModuleViewPreparer" parent="abstractSectionHomeViewPreparer">
        <property name="order" ref="ORDRE_CRITIQUE"/>
        <property name="view" value="/templates/votretemplate/template/votremodule/index.jsp"/>
        <property name="includedSiteTemplate">
            <list>
                <value>...</value>
            </list>
        </property>
    </bean>

    <!-- Accueil de rubrique pour votre module -->
    <bean id="votreModuleAccueilRubrique" class="fr.votreprojet.votremodule.rubrique.VotreModuleAccueilRubrique">
        <property name="typeRubrique">
            <util:constant static-field="fr.votreprojet.votremodule.rubrique.VotreModuleAccueilRubrique.TYPE_ACCUEIL_RUBRIQUE"/>
        </property>
        <property name="libelle" value="RUBRIQUE.PAGE_ACCUEIL_VOTRE_MODULE"/>
        <property name="interne" value="true"/>
        <property name="pathSaisieBo" value="/WEB-INF/jsp/votremodule/bo/saisie.jsp"/>
    </bean>
</beans>

• Notes :
  • Déclaration du préparateur de vue votreModuleViewPreparer :
    • order : L'ordre de priorité du préparateur de vue. Pour des préparateurs de vue liés au projet, on utilisera la priorité Spring HIGHEST_PRECEDENCE ;
    • view : Le chemin vers la jsp de la vue ;
    • includedSiteTemplate / excludedSiteTemplate : Les templates de site à inclure/exclure ;
    • type : Le type de vue (ici, il est déclaré dans le bean abstractSectionHomeViewPreparer) ;
  • Déclaration de l'accueil de rubrique votreModuleAccueilRubrique :
    • typeRubrique : Le code de votre nouvel accueil de rubrique. Il doit être unique ;
    • libelle : Le libellé qui apparaîtra dans la liste déroulante "Type d'écran" (Gestion des sites > Rubriques > Ma Rubrique > Informations générales > Page d'accueil > Type d'écran) ;
    • interne : Indique si la redirection vers la page d'accueil sera faite de manière invisible pour l'utilisateur (via un forward de la requête) ou non (via un redirect de la requête). Dans le cas d'une redirection "interne", l'URL du navigateur reste celle de la rubrique. Cela permet de masquer l'URL "technique".
    • pathSaisieBo (optionnel) : Une JSP qui sera affichée pour la saisie en BO.

Affichage des données

Back-office

Afin de permettre au contributeur de renseigner un titre et une description, nous avons déclaré dans notre bean votreModuleAccueilRubrique une JSP permettant la saisie back-office. Elle est placée dans src/main/webapp/WEB-INF/jsp/votremodule/bo/saisie.jsp :

<jsp:useBean id="infoBean" class="com.jsbsoft.jtf.core.InfoBean" scope="request"/>
<jsp:useBean id="univFmt" class="com.univ.utils.UnivFmt" scope="page"/>
<jsp:useBean id="fmt" class="com.jsbsoft.jtf.core.FormateurJSP" scope="page"/>
<% 
    univFmt.insererChampSaisie(fmt, out, infoBean, "TITRE", FormateurJSP.SAISIE_OBLIGATOIRE, FormateurJSP.FORMAT_TEXTE,0, 255, module.getMessage("VOTRE_PROJET.VOTRE_MODULE.RUBRIQUE.PAGE_ACCUEIL.BO.TITRE")); 
    univFmt.insererChampSaisie(fmt, out, infoBean, "DESCRIPTION", FormateurJSP.SAISIE_FACULTATIVE, FormateurJSP.FORMAT_TEXTE,0, 255, module.getMessage("VOTRE_PROJET.VOTRE_MODULE.RUBRIQUE.PAGE_ACCUEIL.BO.DESCRIPTION"));
%>

• Dans la JSP de saisie back-office, il faut ajouter deux champs de saisie, l'un pour le titre (qui sera obligatoire) et l'autre pour la description, qui est facultative.

Front-office

Pour afficher nos données, il est nécessaire de créer la JSP déclarée dans le bean votreModuleViewPreparer, à l'emplacement suivant : src/main/webapp/templates/votretemplate/template/votremodule/index.jsp.

<%@ page trimDirectiveWhitespaces="true" %>
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
<%@ taglib prefix="kuik" uri="kuik" %>

<%--@elvariable id="bodyViewModel" type="fr.votreprojet.votremodule.view.model.VotreModuleViewModel"--%>
<%--@elvariable id="mainViewModel" type="com.kosmos.template.MainViewModel"--%>

<c:if test="${not empty mainViewModel.bodyType}">
    <c:set var="bodyTypeClass" value="main--${mainViewModel.bodyType}"/>
</c:if>

<main class="main ${bodyTypeClass} l-grid l-expanded-body__expander" data-layout="page">
    <div class="l-content">
        <kuik:heading title="${bodyViewModel.titre}" level="1" size="md" class="visually-hidden" />

        <div class="box box--light box--expand">
            <c:if test="${not empty bodyViewModel.description}">
                <p><c:out value="${bodyViewModel.description}"/></p>
            </c:if>
        </div>
    </div>
</main>

• L'instruction trimDirectiveWhitespaces permet d'éviter les sauts de lignes indésirables. Si sa présence n'est pas obligatoire, elle reste fortement conseillée.
• Pour afficher le titre de l'accueil de rubrique, nous utilisons la librairie kuik. Cette librairie est présente par défaut avec le produit. Sa documentation est disponible ici.
• Pour connaître le type de body sur lequel nous nous trouvons, nous pouvons récupérer la propriété bodyType. La classe contenue dans cette propriété est utilisée pour l'intégration.

Configuration Spring

Si votre accueil de rubrique fait appel à un contrôleur (par exemple, chargement de données via l'appel à une URL dans un datagrid), il faut penser à ajouter l'annotation @ComponentScan(basePackages = {"fr.votreprojet"}) dans la classe de configuration.

package fr.votreprojet.context;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;

@Configuration
@ComponentScan(basePackages = {"fr.votreprojet"})
@EnableWebMvc
public class VotreProjetConfig {
    // Configuration beans si nécessaire
}

Modifier le fichier

Utilisation des points d'extensions des vues en front office (frontAddOn)

Un frontAddOn est un point d'extension présent dans une jsp. Il permet d'injecter un affichage sans avoir à impacter la jsp mère.

Par exemple: l'extension panier injecte un bouton d'ajout dans le panier sur une fiche de K-Sup qui ne connaît pas panier.

Une JSP peut contenir plusieurs frontAddOn pour proposer des points d'extensions à différents endroits de la vue. Un frontAddOn est décrit par un identifiant permettant de le cibler (pointName).

Utilisation des frontAddOn

Un FrontAddon est toujours contextuel à un contexte. Le contexte est le viewModel courant. Cela permet de gérer des FrontAddon au niveau des item de liste.

Injecter une vue spécifique dans un frontAddOn

En utilisant un frontAddOn, il est possible d'injecter une vue dans une autre JSP, sans impacter cette dernière.

Identifier un frontAddOn

Un frontAddOn possède un paramètre obligatoire et peut avoir des paramètres optionnels.

Un frontAddOn peut mettre à dispositions un ou plusieurs paramètres, qui seront alors utilisables par les vues injectées.

Exemple: La JSP ficheApplication propose un point d'extension, tout en mettant à disposition son modèle :

<kore:frontAddOn pointName="applicationcontent-tools" context="${applicationViewModel}"/>

Injecter une vue

La vue injectée est un viewModel standard de refronte. C'est donc le résultat d'un viewPreparer.

<bean id="acmeAddon1" class="com.kosmos.ViewPreparer">
    <property name="type" value="addon1"/>
    <property name="view" value="/extensions/acme/WEB-INF/jsp/addon1.jsp"/>
    <property name="pointNames">
        <list>
            <value>emplacement13</value>
            <value>emplacement42</value>
        </list>
    </property>
</bean>

Pour injecter une vue dans un frontAddon, il suffit abonner son preparer aux addons de la vue soit directement dans la déclaration, soit à l'aide d'un ListeToAddBean.

<bean id="acmeViewPreparer" class="com.kosmos.AcmeViewPreparer">
    <property name="type" value="acmeType"/>
    <property name="view" value="/extensions/acme/WEB-INF/jsp/acme.jsp"/>
    <property name="expectedViewTypes">
        <list>
            <value>expected1</value>
            <value>...</value> 
         </list>
    </property>
    <property name="addons">
        <list>
            <value>addon1</value>
            <value>...</value> 
        </list>
    </property>
</bean>

Ajouter un addOn dans une jsp

Le paramètre pointName est l'identifiant du point d'extension.

Pour proposer un point d'extension dans une JSP, il faut utiliser le tag frontAddOn:

    ...
    <div class="app-header__links">
        <kore:frontAddOn pointName="emplacement13" context="${mainViewModel}"/>
        ...
    </div>
    ...

Modifier le fichier

Liens d'évitement

Description

Les liens d’évitement permettent aux utilisateurs naviguant au clavier, ou équipés de lecteurs d'écran, d’accéder plus rapidement à des zones précises de la page.

Mise en oeuvre

Le produit fournit 3 preparers pour générer les liens d'évitements vers le header de recherche, vers le contenu principal et vers le footer.

Le lien d'évitement consiste simplement en un lien de type "a href" vers une ancre de la la page.
Le fonctionnement impose donc que les composants ciblés possèdent un identifiant unique.
Par exemple, 'header-search-trigger' pour le header de recherche,

...
<kuik:button status="neutral" icon="true" popovertarget="panel-search" id="header-search-trigger">
    <kuik:icon source="icon://ui/search" size="md"/>
...

'content' pour le contenu principal,

...
<main id="content" class="main ${bodyTypeClass} l-grid l-expanded-body__expander u-rg-sm">
    <div>
...