YbObjects

YbList

Présentation

La YbList permet de dessiner une liste dans le thème de Yellowbox :

Exemple YbList

Pour pouvoir construire cet objet, 2 méthodes JavaScript sont rendues disponibles :

/**
 * @param {String} tableId - <table> element ID
 * @param {Object} listParams - JSON containing list parameters
 * @return {Object} DataTable object 
 */
function drawList(tableId, listParams)

Où :

  • tableId est l’ID de l’élément <table> qui va accueillir le tableau.
  • listParams est un JSON contenant les paramètres de construction de la liste. Il sera décrit plus bas.

Cette méthode renvoie un objet DataTable après avoir constuit la liste dans l’élément HTML <table> spécifié par son ID.

/**
 * @param {String} tableId - <table> element ID
 * @param {String} buildingServletName - List-parameter-building servlet
 * @param params {Object} - Servlet params, if any
 * @param onSuccess {Function} - Method to execute on building success, if any. No argument expected.
 * @param onError {Function} - Method to execute on building error, if any. 3 arguments expected : jqXHR, textStatus, errorThrown.
 * @return {Object} DataTable object 
 */
function drawListFromServlet(tableId, buildingServletName, params, onSuccess, onError)

Où :

  • tableId est l’ID de l’élément <table> qui va accueillir le tableau.
  • buildingServletName est l’ID de la servlet qui retournera le JSON, sous forme de String, les paramètres de la liste, comme le paramètre listParams de la méthode drawList.
  • params est un JSON contenant les paramètres de la servlet. Ce paramètre peut être vide (= null / undefined / {}).
  • onSuccess est une methode contenant du code à exécuter après succès de la construction de la liste. Ce paramètre peut être vide (= null / undefined / () => {} / function() {}).
  • onError est une methode contenant du code à exécuter en cas d’erreeur de la construction de la liste. Ce paramètre peut être vide (= null / undefined / () => {} / function() {}).

Cette méthode renvoie un objet DataTable après avoir constuit la liste dans l’élément HTML <table> spécifié par son ID.

Les paramètres listParams

Voici comment se présente les paramètres de la liste :

const listParams = {
    columns: [
        {
            id: String,
            name: String,
            orderable: Boolean,
            searchable: Boolean,
            title: String,
            type: 'RAW'|'LINK'|'BUTTON',
        },
        ...
    ],
    data: [
        {
            '[FIRST_COLUMN_ID]': {
                id: String,
                label: String,
                onClick: String,
                imgUrl: String,
            },
            '[SECOND_COLUMN_ID]': {
                ...
            },
            ...
        },
        ...
    ],
    pageLength: Number,
    responsive: Boolean,
    searchValueJsCallbackName: String,
    serverSide: Boolean,
    serverSideServletName: String,
};

Les colonnes

Il s’agit d’un tableau d’objets où chaque objet décrit une colonne. L’ordre d’affichage dépendra de l’ordre dans lequel les colonnes sont située le tableau.

const column1 = {
    id: String,
    name: String,
    orderable: Boolean,
    searchable: Boolean,
    title: String,
    type: 'RAW'|'LINK'|'BUTTON',
};

const columns = [
    column1,
    column2,
    ...,
];

Où :

  • id : ID de la colonne qui sera repris dans le tableau des données data. Il ne peut pas être vide.
  • name : Attribut name en HTML.
  • orderable : Indique si la colonne sera triable ou non. La valeur false est forcée pour un type BUTTON.
  • searchable : Indique si la colonne sera cherchable ou non. La valeur false est forcée pour un type BUTTON.
  • title : Le nom de la colonne. Il ne peut pas être vide.
  • type : Le type de données qui sera présent dans cette colonne: RAW, LINK ou BUTTON.

Les données

Il s’agit d’un tableau d’objets où chaque objet représente une ligne. L’ordre dans lequel sont insérées les lignes représente l’ordre dans lequel elle apparaîtront dans la liste.

Chaque ligne est composée d’objets qui représentent les cellules de la ligne. Le nombre de cellules est strictement égal au nombre de colonnes définies dans columns. Chaque cellule est associée à la bonne colonne en indiquant l’ID de la colonne comme clé de valeur, définie dans column.id (voir ci-dessous).

const cell1 = {
    id: String,
    label: String,
    onClick: String,
    imgUrl: String,
};

const line1 = {
    column1.id: cell1,
    column2.id: cell2,
    ...,
};

const data = [
    line1,
    line2,
    ...
];

Où :

  • id : ID de la cellule dans le DOM. Il n’a aucun lien avec l’ID de la colonne. Il peut servir pour pouvoir interagir avec le contenu de la cellule.
  • label :
    • RAW : Le texte affiché. Non null.
    • LINK : Du texte cliquable affiché. Non null.
    • BUTTON : Le texte affiché au survol du bouton. Peut être null.
  • onClick (LINK et BUTTON uniquement) : Le code à exécuter sous forme de fonction (Ex : "() => console.log('Hello World!')"). Non null. Si la valeur est vide (i.e. ''), alors une cellule de type BUTTON n’affichera pas de contenu et aura la propriété CSS opacity: 0.
  • imgUrl (BUTTON uniquement) : L’URL de l’image à afficher pour le bouton. Si la valeur est vide, alors le bouton aura pour image l’icône glyphicon-flash.

Les autres paramètres 

const listParams = {   
    columns: columns,
    data: data,

    // Other parameters
    pageLength: Number,
    responsive: Boolean,

    // Server-side processing    
    searchValueJsCallbackName: String,
    serverSide: Boolean,
    serverSideServletName: String,
}
  • pageLength : Nombre de lignes par page. Doit être supérieur à 0. 10 par défaut.
  • responsive : Activer ou non le mode responsive. true par défaut.

Pour le traitement des données côté serveur :

  • serverSide : indique que la liste sera gérée par une servlet en back-end. false par défaut.
  • serverSideServletName : La servlet à appeler pour la gestion de la liste.
  • searchValueJsCallbackName : Nom de la méthode Javascript qui renverra une valeur à chercher. La méthode doit retourner un string.

API Java

Une API Java est disponible dans le plugin.jar afin de pouvoir construire facilement une YbList dans une servlet. Vous pouvez disposer des objets suivants :

  • YbList.java : La classe principale qui représente l’objet listParams en JavaScript. Cette classe contient une méthode YbList.toJson() qui permet d’obtenir le JSON complet sous forme de String.
  • YbColumn.java : La classe qui permet de définir une colonne avec les attributs nécessaires.
  • YbCell.java : La classe abstraite qui permet de définir une cellule. Elle est héritée par ses 3 classes filles :
    • YbRawCell.java : Pour les cellules de type RAW.
    • YbLinkCell.java : Pour les cellules de type LINK.
    • YbButtonCell.java : Pour les cellules de type BUTTON.
  • YbListBuilderServlet.java : Une servlet qui se focalise sur la construction d’une YbList. Elle est à utiliser comme une servlet YellowBox classique.
  • YbListUpdateServlet.java : Une servlet qui se focalise sur la gestion des données d’une liste en server-side.
  • YbListServerData.java : Les données à renvoyer à l’issue du traitement d’une YbListUpdateServlet.

Voici un exemple simplifié d’utilisation d’une YbList classique :

List<YbColumns> columns = new ArrayList<>();
columns.add(new YbColumn("0", "Colonne 1", YbColumn.Type.BUTTON));
// ...

YbCell cell1 = new YbButtonCell("() => { alert('Hey!') }");
Map<String, YbCell> row1 = new HashMap<>();
row1.put("0", cell1);
// ...

List<Map<String, YbCell>> data = new ArrayList<>();
data.add(row1)
// ...

YbList list = new YbList(columns, data);
list.setPageLength(5);
list.setResponsive(false);

return list.toJson();

Voici un exemple simplifié d’utilisation d’une YbList server-side :

/**
 * Construction de la liste
 */
List<YbColumns> columns = new ArrayList<>();
columns.add(new YbColumn("0", "Colonne 1", YbColumn.Type.BUTTON));
// ...

YbList list = new YbList(columns, UpdateListServlet.class.getSimpleName());
list.setPageLength(5);
list.setResponsive(false);
list.setServerSide(true);
list.setSearchValueJsCallbackName("searchValueCallback");

return list.toJson();

/**
 * Servlet de gestion de la YbList
 */
public class UpdateListServlet extends YbListUpdateServlet {

	@Override
	public YbListServerData update(YbListUpdateServletParams params) {
        YbListServerData serverData;
        String search = params.getDraw();
        
        try {
            String search = params.getSearch().getValue();

            int start = params.getStart();
            int length = params.getLength();
            int pageNumber = (params.getStart() / params.getLength()) + 1;

            // Here is where you fetch you data and transform them into the according fomart
            MyApiCaller api = new MyApiCaller();
            MyResponse response = api.getData(pageNumber, search);
            List<Map<String, YbCell>> data = MyParser.parse(response);

            serverData = new YbListServerData(data, draw, nbResults, nbResults);
        } catch(Exception e) {
            serverData = new YbListServerData(null, draw, 0, 0);
            serverData.setError("Error: " + e.getMessage());
        }

        return serverData;
    }

	@Override
	public String getName() {
		return getClass().getSimpleName();
	}

}

Vous pourrez trouver un exemple détaillé dans la section Exemples

← Tests unitaires
Exemples →