Contrôle de l’édition des champs avec l’API FieldStatus

JCMS permet de définir des types de publications composés d’un ensemble de champs. Lors de la définition des champs, il est possible d’indiquer si le champ est obligatoire à la saisie et aussi si le champ est visible. Néanmoins, il est parfois nécessaire de pouvoir contrôler dynamiquement le caractère visible, éditable et obligatoire d’un champ. Par exemple :

• Le champ Introduction ne devient obligatoire que si l'on passe la publication à l'état Publié ;
• Le champ Titre n'est plus éditable dans l'état Validation ;
• Le champ TopSecret n'est visible et éditable que si l’utilisateur est administrateur.

A partir de JCMS 6.0 SP1, l’API FieldStatus permet ce type de contrôle sur tous les champs des types de publications. (Un champ doit etre visible et optionnel par défaut pour pouvoir être modifié dynamiquement)

1. La méthode DataController.processFieldStatusMap

Les DataController disposent d'une nouvelle méthode, processFieldStatusMap, permettant d'indiquer pour la donnée reçue en paramètre un statut particulier pour chacun de ses champs.

public void processFieldStatusMap(Data data, Member mbr, Map<String, FieldStatus> map)

Les clés de la Map fournit en paramètre sont le nom de champ et les valeurs sont des FieldStatus. Si un champ n'est pas présent dans cette Map, il aura le statut par défaut.

2. La classe FieldStatus

La classe FieldStatus propose 5 constantes représentant le statut du champ :

• FieldStatus.DEFAULT : statut tel que décrit dans le type.xml ;
• FieldStatus.HIDDEN : le champ est invisible ;
• FieldStatus.DISABLED : le champ est visible mais non éditable ;
• FieldStatus.EDITABLE : le champ est éditable mais non requis ;
• FieldStatus.REQUIRED : le champ est éditable et requis.

La classe propose la méthode addStatus() qui permet d'additionner des statuts. Plusieurs DataController peuvent donner leur avis sur le même champ du même type. Dans ce cas, c'est la contrainte de saisie la plus forte qui l'emporte. La relation d’ordre entre les contraintes est la suivante :

Required > Editable > Disabled > Hidden > Default.

Le FieldStatus.REQUIRED indique au widget que le champ est requis. Cependant, le widget ne fait que placer un astérisque mais ne fait aucun contrôle. C'est le rôle de la méthode checkIntegrity() des DataController. Dans ce cas, c'est au développeur d'assurer dans son DataController la cohérence entre les méthodes processFieldStatusMap() et checkIntegrity().

ATTENTION : Ne pas oublier que pour pouvoir utiliser ce mécanisme la définition du champ au niveau du type ne doit pas spécifier un caractère obligatoire ou masqué.

3. Contrôle à l’affichage

Pour les JSP, il est aussi possible de vérifier l'état d'un champ (par exemple, pour ne pas afficher les champs cachés).

Exemple :

<% if (!pub.getFieldStatus("intro").isHidden()) { %>
<%= pub.getIntro() %>
<% } %>

4. Exemple

Dans cet exemple, on souhaite contrôler le mode d'édition du champ Intro du type SmallNews :

• Edition non obligatoire de l’état initial à l’état planifié ;
• Edition obligatoire à l'état planifié ;
• Non éditable à partir de l'état publié.

package com.jalios.jcmsplugin.demo;
import generated.SmallNews;
import java.util.Map;
import com.jalios.jcms.BasicDataController;
import com.jalios.jcms.ControllerStatus;
import com.jalios.jcms.Data;
import com.jalios.jcms.FieldStatus;
import com.jalios.jcms.Publication;
import com.jalios.jcms.WorkflowConstants;

public class DemoDataController extends BasicDataController {

  @Override
  public void processFieldStatusMap(Data data, Member mbr, Map map) {
    SmallNews pub = (SmallNews)data;
    updateFieldStatusMap(map, "intro", getIntroStatus(pub));
  }
  
  private FieldStatus getIntroStatus(Publication pub) {
    if (pub.getPstatus() >= WorkflowConstants.PUBLISHED_PSTATUS) {
      return FieldStatus.DISABLED;
    }    
    if (isIntroRequired(pub.getPstatus())) { 
      return FieldStatus.REQUIRED;
    }
   return FieldStatus.DEFAULT;    
  }
  
  @Override
  public ControllerStatus checkIntegrity(Data data) {
    
    if (!(data instanceof SmallNews)) {
      return ControllerStatus.OK;
    }
    
    SmallNews pub = (SmallNews)data;
    
    ControllerStatus status = null;
    
    // Intro required
    if (isIntroRequired(pub.getPstatus())) {
      status = checkFieldMLRequired(pub, "intro", pub.getIntro(), pub.getIntroML());
      if (status != ControllerStatus.OK) {
        return status;
      }
    }

    return ControllerStatus.OK;
  }
  
  private boolean isIntroRequired(int pstatus) {
    return pstatus >= WorkflowConstants.SCHEDULED_PSTATUS;
  }
}