Personalizzate il modo in cui vengono visualizzati i vostri contenuti utilizzando i modelli

Sebbene alcuni moduli di Yapla possano visualizzare i dati provenienti dalle funzionalità Dati ed Eventi (per i tipi di congressi), è possibile creare da zero un modello di visualizzazione per questi dati nel proprio sito web Yapla. Ci sono diversi esempi possibili: il programma del congresso, i relatori del congresso, un elenco di offerte di lavoro, un elenco di persone o risorse, ecc.

In questo articolo per gli sviluppatori di siti web, imparerete i passi da compiere per creare i vostri primi modelli.

Prerequisiti

Per poter creare modelli Yapla, è necessario disporre del pacchetto Premium e di un sito web Yapla. È inoltre necessario aver creato un oggetto nella funzionalità Dati. Gli oggetti che si desidera recuperare devono avere visibilità pubblica.

Creare un modello

I modelli possono essere creati dal riquadro Viste e modelli del sito web nella funzione Sito web, quindi nella scheda Schemi.

Tipi di modelli

• Modello di modulo Yapla: per personalizzare l'aspetto e la funzionalità di un modulo Yapla esistente. Alcuni moduli possono avere più modelli per le loro diverse interfacce.
• Modello indipendente: per creare un modello da zero, non collegato a un modulo Yapla.

Tutti i template offrono le stesse possibilità: un template che utilizza il motore di rendering Vue JS, CSS e una query GraphQL per recuperare informazioni dai dati. La query e il CSS sono opzionali e verranno caricati solo quando il template viene utilizzato in una pagina.

I modelli di modulo sono precompilati per impostazione predefinita con il codice di base del modulo, per facilitarne la personalizzazione.

Visualizzazione del modello

Per visualizzare un modello, è necessario utilizzare il modulo corrispondente al tipo di modello utilizzato. Nel caso di un modello personalizzato per il modulo del sito web "Programmazione eventi", ad esempio, è necessario selezionare il modello nella configurazione del modulo.

Per un modello indipendente, utilizzare il modulo "Visualizzazione personalizzata degli oggetti".

Recupero di informazioni da Dati

I modelli possono accedere alle voci degli oggetti in Data utilizzando un'API GraphQL generata dagli oggetti pubblici dell'associazione. Viene generato uno schema statico che può essere consultato con software di terze parti (come Postman, ad esempio) all'indirizzo https://votresite.com/fr/graphql.

È con questa API che il modello può interagire per recuperare i dati. Nella scheda "Query" del modello è presente l'editor GraphQL, che fornisce un'analisi della sintassi della query e offre un completamento automatico intelligente basato sullo schema dell'associazione.

Esempio di schema di un oggetto Yapla

type Query {
  allCharacterEntries(
    after: String
    first: Int
    before: String
    last: Int
  ): characterEntryConnection
  allEpisodeEntries(
    after: String
    first: Int
    before: String
    last: Int
  ): episodeEntryConnection
}

"A connection to a list of items."
type characterEntryConnection {
  "Information to aid in pagination."
  pageInfo: PageInfo!

  "Information to aid in pagination"
  edges: [characterEntryEdge]
}

"Information about pagination in a connection."
type PageInfo {
  "When paginating forwards, are there more items?"
  hasNextPage: Boolean!

  "When paginating backwards, are there more items?"
  hasPreviousPage: Boolean!

  "When paginating backwards, the cursor to continue."
  startCursor: String

  "When paginating forwards, the cursor to continue."
  endCursor: String
}

"An edge in a connection"
type characterEntryEdge {
  "The item at the end of the edge"
  node: characterEntry

  "A cursor for use in pagination"
  cursor: String!
}

type characterEntry {
  identifiant: Float
  status: String
  name: String
  appears_in(
    after: String
    first: Int
    before: String
    last: Int
  ): episodeEntryConnection
}

"A connection to a list of items."
type episodeEntryConnection {
  "Information to aid in pagination."
  pageInfo: PageInfo!

  "Information to aid in pagination"
  edges: [episodeEntryEdge]
}

"An edge in a connection"
type episodeEntryEdge {
  "The item at the end of the edge"
  node: episodeEntry

  "A cursor for use in pagination"
  cursor: String!
}

type episodeEntry {
  identifiant: Float
  status: String
  name: String
  characters(
    after: String
    first: Int
    before: String
    last: Int
  ): characterEntryConnection
}

Esempio di query

query {
  episodes: allEpisodeEntries {
    edges {
      node {
        name
        characters {
          edges {
            node {
              name
            }
          }
        }
      }
      cursor
    }
  }
}

Il componente <Query>

Il componente <Query> è usato per eseguire la query e recuperare il risultato restituito dal server. Il risultato viene restituito nello slot props del componente. Riprendendo l'esempio precedente, per visualizzare l'elenco degli episodi si utilizzerà il seguente codice:

<Query v-slot="{ queryData }">
  <h3>Épisodes</h3>
  <div class="episodes">
    <div
      v-for="(episodes, i) in queryData?.episodes.edges"
      :key="i"
      class="episode"
    >
      <p>{{ episode.node.name }}</p>
      <div class="characters">
        <p>Personnages de l'épisode</p>
        <div
          v-for="(character, y) in episode.node.characters.edges"
          :key="y"
          class="character"
        >
          <p>{{ character.node.name }}</p>
          <p></p>
        </div>
      </div>
    </div>
  </div>
</Query>

Paginazione

L'API generata da Yapla offre la paginazione con un cursore. Combinando i ritorni del server con il componente <Query> possiamo implementare due tipi di paginazione:

• Un elenco infinito
• Una paginazione bidirezionale non numerica

Elenco infinito

Per impostare una paginazione di tipo elenco infinito, possiamo usare le seguenti variabili:

• pageInfo.hasNextPage per scoprire se abbiamo raggiunto la fine dei risultati
• pageInfo.endCursor per definire il punto di partenza del prossimo segmento di risultati.

Dovremo anche utilizzare la funzione fetchNext nel componente <Query> e aggiungere i parametri di paginazione alla query GraphQL. Tutto questo in un semplice esempio:

query ($first: Int, $after: String) {
  episodes: allEpisodeEntries(first: $first, after: $after) {
    edges {
      node {
        name
      }
      pageInfo {
        hasNextPage
        endCursor
      }
      cursor
    }
  }
}

Query a pagine

<Query :first="5" v-slot="{ queryData, aggregatedData, isLoading, fetchNext }">
  <h3>Épisodes</h3>
  <div class="episodes">
    <div
      v-for="(episodes, i) in aggregatedData?.episodes.edges"
      :key="i"
      class="episode"
    >
      <p>{{ episode.node.name }}</p>
    </div>
    <button
      v-if="queryData?.episodes?.pageInfo?.hasNextPage"
      :loading="isLoading"
      @click="fetchNext(5, queryData.episodes.pageInfo.endCursor)"
    >
      Charger plus d'épisodes
    </button>
  </div>
</Query>

In questo esempio impaginiamo gli episodi 5 per 5 e utilizziamo la variabile aggregatedData per combinare i nuovi risultati con quelli vecchi e ottenere l'effetto di un elenco infinito.

Bidirezionale

Per la paginazione bidirezionale, il metodo è molto simile, ma aggiungiamo l'altra direzione, cioè le seguenti variabili:

• pageInfo.hasPreviousPage
• pageInfo.startCursor
• fetchPrevious nel componente <Query>

Ecco un semplice esempio di visualizzazione episodio per episodio:

query ($first: Int, $after: String, $last: Int, $before: String) {
  episodes: allEpisodeEntries(
    first: $first
    last: $last
    after: $after
    before: $before
  ) {
    edges {
      node {
        name
      }
      pageInfo {
        hasPreviousPage
        hasNextPage
        endCursor
        startCursor
      }
      cursor
    }
  }
}

Nota: I nomi delle variabili della query sono molto importanti e non devono differire dagli esempi, in modo che il componente <Query> possa popolarle con le informazioni corrette.

<Query :first="1" v-slot="{ queryData, isLoading, fetchNext, fetchPrevious }">
  <h3>Épisode</h3>
  <div class="episode">
    <p v-if="queryData?.episodes.edges.length > 0">
      {{ queryData?.episodes.edges[0].node.name }}
    </p>
    <button
      v-if="queryData?.episodes?.pageInfo?.hasNextPage"
      :loading="isLoading"
      @click="fetchNext(1, queryData.episodes.pageInfo.endCursor)"
    >
      Episode suivant
    </button>
    <button
      v-if="queryData?.episodes?.pageInfo?.hasPreviousPage"
      :loading="isLoading"
      @click="fetchPrevious(1, queryData.episodes.pageInfo.startCursor)"
    >
      Episode précédent
    </button>
  </div>
</Query>

Combinare il contenuto dei dati con un modello di modulo

È anche possibile utilizzare il componente <Query> e l'API GraphQL del sito nei modelli di modulo Yapla. È anche possibile condizionare la chiamata al componente in base a uno dei parametri del modulo. Ad esempio, per visualizzare risorse aggiuntive nei dettagli di un workshop a seconda della categoria del workshop.

<div class="workshop-detail">
  <Query
    v-slot="{queryData}"
    v-if="workshop?.tags.find(t => t.name === 'Ressources')"
  >
    <div class="resources-link">
      <p v-for="(resource, i) in queryData?.resources.edges" :key="i">
        {{ resource.node.name }}
      </p>
    </div>
  </Query>
</div>

Per andare oltre: alcuni riferimenti

<Query>

Il componente usato per eseguire la query del modello e restituire il risultato.

Parametri

• first: numero: il numero di risultati da restituire partendo dall'inizio. Utilizzato nella query per impaginare i risultati.
• last: numero: il numero di risultati da restituire, a partire dalla fine. Utilizzato nella query per impaginare i risultati.

Variabili

Accessibili dall'ambito dello slot.

• queryData: Oggetto: Contiene i risultati dell'ultima query GraphQL, formattati secondo lo schema specificato nella scheda Query.
• aggregatedData: Oggetto Contiene i risultati combinati di tutte le query GraphQL (le variabili dei bordi sono combinate insieme). Utilizzato per impostare la paginazione di un elenco infinito.
• isLoading: boolean : riflette lo stato di caricamento della query corrente.

Metodi

• fetchNext(size: numero, cursore: stringa): Recupera il numero di risultati specificato dopo il cursore.
• fetchPrevious(size: numero, cursore: stringa) : Recupera il numero di risultati specificati prima del cursore.
  

<Pulsante>

Componente di utilità di Yapla per i pulsanti che utilizzano il design del sito.

Parametri

• type?: string<'primary'|'secondary'> : Imposta lo stile del pulsante come primario o secondario. Predefinito: "primario".
• disabled?: boolean : serve a disabilitare il pulsante Predefinito: false
• loading?: boolean : visualizza lo stato di caricamento del pulsante e lo disattiva Predefinito: false

Eventi

• @click: Richiamato quando il pulsante viene cliccato

Documentazione correlata

• Vue.js
• GraphQL