Sheets et ApplicationV2

Introduction

Les Sheets sont les interfaces visuelles permettant aux joueurs d'interagir avec leurs personnages, objets et autres documents. Avec FoundryVTT v13, une nouvelle API appelee ApplicationV2 remplace l'ancienne API Application v1.

Application v1 vs ApplicationV2

Voici les differences principales entre les deux API :

Exemple comparatif

Ancienne API (v1) - A eviter :

// Application v1 (ancienne API - DEPRECIE)
class OldSheet extends Application {
  static get defaultOptions() {
    return foundry.utils.mergeObject(super.defaultOptions, {
      template: "path/to/template.hbs",
      width: 500,
      height: 400
    });
  }
  
  getData() {
    return { data: this.object };
  }
  
  activateListeners(html) {
    super.activateListeners(html);
    html.find(".my-button").click(this._onButtonClick.bind(this));
  }
}

Nouvelle API (v2) - Recommandee :

// ApplicationV2 (nouvelle API v13)
class ModernSheet extends foundry.applications.api.ApplicationV2 {
  static DEFAULT_OPTIONS = {
    position: { width: 500, height: 400 },
    actions: {
      myAction: ModernSheet.#onMyAction
    }
  };
  
  static PARTS = {
    main: { template: "path/to/template.hbs" }
  };
  
  async _prepareContext(options) {
    return { data: this.document };
  }
  
  static #onMyAction(event, target) {
    // Gestionnaire d'action (this = instance de la sheet)
    console.log("Action declenchee !");
  }
}

Structure d'une Sheet moderne

Une Sheet moderne herite typiquement de DocumentSheetV2 ou de ses specialisations comme ActorSheetV2 et ItemSheetV2.

Hierarchie des classes

// Hierarchie d'heritage pour les Sheets
foundry.applications.api.ApplicationV2
    |
    +-- HandlebarsApplicationMixin
    |   +-- ApplicationV2Mixin (systeme)
    |       +-- Application5e
    |
    +-- foundry.applications.api.DocumentSheetV2
        +-- foundry.applications.sheets.ActorSheetV2
        |   +-- BaseActorSheet (systeme)
        |       +-- CharacterActorSheet
        |       +-- NPCActorSheet
        |
        +-- foundry.applications.sheets.ItemSheetV2
            +-- ItemSheet5e (systeme)

Structure de base

// module/applications/actor/character-sheet.mjs
const { ActorSheetV2 } = foundry.applications.sheets;
const { HandlebarsApplicationMixin } = foundry.applications.api;

export default class CharacterSheet extends HandlebarsApplicationMixin(ActorSheetV2) {
  
  /** Configuration statique */
  static DEFAULT_OPTIONS = {
    classes: ["mon-systeme", "actor", "character"],
    position: { width: 600, height: 700 },
    window: {
      resizable: true,
      title: "MON_SYSTEME.Sheet.Character"
    },
    actions: {
      rollAttribute: CharacterSheet.#onRollAttribute
    },
    form: {
      submitOnChange: true,
      closeOnSubmit: false
    }
  };

  /** Templates modulaires */
  static PARTS = {
    header: {
      template: "systems/mon-systeme/templates/actor/header.hbs"
    },
    tabs: {
      template: "systems/mon-systeme/templates/actor/tabs.hbs"
    },
    attributes: {
      template: "systems/mon-systeme/templates/actor/attributes.hbs",
      scrollable: [""]
    },
    biography: {
      template: "systems/mon-systeme/templates/actor/biography.hbs",
      scrollable: [""]
    }
  };

  /** Preparation des donnees pour les templates */
  async _prepareContext(options) {
    const context = await super._prepareContext(options);
    context.isEditable = this.isEditable;
    context.system = this.actor.system;
    return context;
  }

  /** Gestionnaire d'action statique */
  static async #onRollAttribute(event, target) {
    const attr = target.dataset.attribute;
    await this.actor.rollAttribute(attr);
  }
}

DEFAULT_OPTIONS

DEFAULT_OPTIONS est un objet statique qui definit la configuration par defaut de l'application.

static DEFAULT_OPTIONS = {
  // Identifiant unique (avec placeholder {id})
  id: "my-app-{id}",
  
  // Classes CSS appliquees a l'application
  classes: ["mon-systeme", "my-app"],
  
  // Tag HTML de l'application (defaut: "div")
  tag: "div",
  
  // Configuration de la fenetre
  window: {
    title: "Titre de la fenetre",
    icon: "fas fa-user",        // Icone FontAwesome
    resizable: true,            // Redimensionnable ?
    minimizable: true,          // Minimisable ?
    controls: [                 // Boutons dans l'en-tete
      {
        action: "configureToken",
        icon: "fa-solid fa-user-circle",
        label: "Token",
        ownership: "OWNER"
      }
    ]
  },
  
  // Position et dimensions
  position: {
    width: 600,
    height: 400,
    top: null,    // null = centre automatique
    left: null
  },
  
  // Actions declaratives
  actions: {
    save: MySheet.#onSave,
    delete: {
      handler: MySheet.#onDelete,
      buttons: [0, 2]  // Boutons souris acceptes (0=gauche, 2=droit)
    }
  },
  
  // Configuration du formulaire
  form: {
    handler: MySheet.#onSubmit,
    submitOnChange: true,     // Soumet a chaque modification
    closeOnSubmit: false      // Ferme apres soumission ?
  }
};

Systeme de PARTS

Le systeme de PARTS permet de diviser une application en sections independantes, chacune avec son propre template. Cela permet un rendu partiel : seules les parties modifiees sont re-rendues.

static PARTS = {
  // PART simple avec un template
  header: {
    template: "systems/mon-systeme/templates/actor/header.hbs"
  },
  
  // PART avec templates additionnels (partials)
  inventory: {
    template: "systems/mon-systeme/templates/actor/inventory.hbs",
    templates: [
      "systems/mon-systeme/templates/inventory/item-row.hbs",
      "systems/mon-systeme/templates/inventory/encumbrance.hbs"
    ],
    scrollable: [""]  // La PART entiere est scrollable
  },
  
  // PART avec conteneur specifique
  sidebar: {
    container: { 
      id: "main",
      classes: ["main-content"] 
    },
    template: "systems/mon-systeme/templates/actor/sidebar.hbs"
  },
  
  // PART conditionnelle
  spells: {
    container: { classes: ["tab-body"], id: "tabs" },
    template: "systems/mon-systeme/templates/actor/spells.hbs",
    scrollable: [""]
  }
};

Rendu partiel

Pour re-rendre uniquement certaines parties :

// Re-rendre uniquement l'inventaire
await this.render({ parts: ["inventory"] });

// Re-rendre plusieurs parties
await this.render({ parts: ["header", "attributes"] });

Configuration conditionnelle des PARTS

/** @inheritDoc */
_configureRenderParts(options) {
  const parts = super._configureRenderParts(options);
  
  // Retirer une PART conditionnellement
  if (!this.actor.system.hasSpellcasting) {
    delete parts.spells;
  }
  
  return parts;
}

_prepareContext()

La methode _prepareContext() remplace l'ancien getData(). Elle prepare les donnees qui seront passees aux templates.

/**
 * Prepare le contexte global partage par tous les templates.
 * @param {object} options - Options de rendu
 * @returns {Promise