Improve server-side dashboard js script documentation

[maxencelaurent]

Amélioration du typage

J'ai un peu améliorer la documentation pour que l'éditeur de serveur script comprenne mieux WegasDashboard.registerVariable

Quelques exemples d'utilisations un peu tordus :

Afficher le mail d'un joueur dans le dashboard. On se base sur aucune variable, donc on peut passer undefined. La valeur envoyée au client est calculée par la mapFn a partir du teamId.

    WegasDashboard.registerVariable(undefined, {
        id: 'email',
        label: 'mail',
        active: false,
        mapFn: function (teamId) {
            var t = Team.find(teamId);
            if (t) {
                var player = t.getAnyLivePlayer();
                if (player) {
                    var user = player.getUser();
                    if (user) {
                        var account = user.getMainAccount();
                        if (account) {
                            var email = account.getEmail();
                            if (email) {
                                return email;
                            }
                        }
                    }
                }
            }
            // par exemple les tests players ou les équipes vides
            return "pas trouvé..."
        }
    })

le même, mais avec un engine js un peu moins vieux :

    WegasDashboard.registerVariable(undefined, {
        id: 'email',
        label: 'mail',
        active: false,
        mapFn:  (teamId) =>  
                  Team.find(teamId)
                            ?.getAnyLivePlayer()
                            ?.player.getUser()
                            ?.user.getMainAccount()
                            ?.account.getEmail() 
                         || 'pas trouvé ...'
    })

Dans le pmg, il y des phases de jeu (de 1 à 4) et dans chaque phase, il y a des périodes (de 1 à n) La phase courante est stockée dans currentPhase, les périodes de chaque phases sont stockées dans periodPhase1, periodPhase2, periodPhase3 et periodPhase4. Dans le dashboard, on veut afficher le numéro de la période courante en fonction de la phase courante.

On register d'abord currentPhase, puis on ajoute des `periodPhaseX' en extraArgs. On est obligé de fournir un id car currentPhase est déjà enregistré dans le dashboard. La mapFN va se baser sur les instances de toutes ces variables pour retourner la bonne valeur.

    WegasDashboard.registerVariable("currentPhase", {
        id: "currentPeriod",
        label: "Period",
        mapFn: function(teamId, currentPhase, p1, p2, p3, p4) {
            return arguments[currentPhase.getValue() + 1].getValue();
        },
        mapFnExtraArgs: ["periodPhase1", "periodPhase2", "periodPhase3", "periodPhase4"]
    });

Dans la même veine, on veut afficher le nombre de questions auxquelles les joueurs ont déjà répondu pour la période courante:

    function questionAnswered(teamId, currentPhaseInstance,
        currentPeriod1Instance, currentPeriod2Instance, currentPeriod3Instance, currentPeriod4Instance) {

        var currentPhase = currentPhaseInstance.getValue();
        var currentPeriod = arguments[currentPhase + 1].getValue();

        var questions = PMGHelper.getQuestions(currentPhase, currentPeriod);
        var count = 0;
        var total = 0;

        for (i = 0; i < questions.length; i += 1) {
            inst = Variable.getInstancesByKeyId(questions[i])[teamId];
            if (inst instanceof com.wegas.mcq.persistence.QuestionInstance) {
                if (inst.getActive()) {
                    count += inst.getReplies().size() > 0 ? 1 : 0;
                    total++;
                }
            } else if (inst instanceof com.wegas.mcq.persistence.wh.WhQuestionInstance) {
                if (inst.getActive()) {
                    count += inst.isValidated() ? 1 : 0;
                    total++;
                }
            }
        }
        return count + "/" + total;
    }

    WegasDashboard.registerVariable("currentPhase", {
        id: "questions",
        label: "Questions",
        mapFn: questionAnswered,
        mapFnExtraArgs: ["periodPhase1", "periodPhase2", "periodPhase3", "periodPhase4"]
    });