# Buzz Fields

Buzz Fields è la nostra libreria Javascript per inserire blocchi Vue tramite API.

# Installazione

1. Installare il pacchetto NPM

npm install --save @nodopiano/buzz-fields

# Oppure, utilizzando yarn

yarn add @nodopiano/buzz-fields

2. Importare il plugin e lo stile nel progetto

import Vue from 'vue'
import BuzzFields from '@nodopiano/buzz-fields'

/* Stile */
import '@nodopiano/buzz-fields/dist/buzz-fields.css'

Vue.use(BuzzFields, {
  locale: 'it',
  getItems: function(resource) {},
  getErrors: function(resource) {},
  updateItems: function(newValue, resource) {},
  updateErrors: function(traverse, resource) {}
});

# Opzioni

• locale: La lingua con cui caricare moment.js e element-ui. È possibile scegliere tra it, en, fr, de, es
• getItems: Callback per richiedere gli items. resource corrisponde alla risorsa a cui si fa riferimento.
• getErrors: Callback per richiedere gli errori. resource corrisponde alla risorsa a cui si fa riferimento.
• getItems: Callback per aggiornare gli items. newValue corrisponde al nuovo valore per l'item, mentre resource indica la risorsa a cui fa riferimento.
• getItems: Callback per aggiornare gli items. traverse corrisponde al percorso dell'errore all'intero dell'oggetto di errori, mentre resource indica la risorsa a cui fa riferimento.

# Utilizzo

Inserire all'interno del template Vue il componente blocks-view

<template>
  <blocks-view :page="oggettoBlocchi" resource="nome-della-risorsa" />
</template>

<script>
export default {
  data() {
    return {
      oggettoBlocchi: {}
    }
  }
}
</script>

# Props

blocks-view accetta due props obbligatorie:

• pageoggetto: descrive quali blocchi vanno inseriti nella pagina.
• resourcestringa: definisce a quale gruppo o risorsa appartiene il contenuto da mostrare all'interno dei blocchi.

# Slots

Per rendere più flessibile l'aggiunta di contenuti tra i vari blocchi o all'interno di essi, blocks-view permette l'uso di slot dinamici, organizzati in quattro categorie:

• prepend: Lo spazio prima di un blocco
• append: Lo spazio dopo un blocco
• prefix: Lo spazio prima del contenuto all'interno del blocco (Slot prefix specifico di ogni blocco - fare riferimento alla guida dei vari blocchi)
• suffix: Lo spazio dopo il contenuto all'interno del blocco (Slot suffix specifico di ogni blocco - fare riferimento alla guida dei vari blocchi)

Gli slot vengono distinti in base al traverse e all'indice del blocco e in base al suo nome.

Ad esempio: se il blocco è all'indice 3 (è il terzo che viene inserito) e è di tipo table, gli slot verranno chiamati prepend-3_table, append-3_table, prefix-3_table, suffix-3_table.

Se il blocco ha anche una proprietà traverse, questa verrà utilizzata al posto dell'indice.

Ad esempio: se il blocco ha il traverse owners e è di tipo form, gli slot verranno chiamati prepend-owners_form, append-owners_form, prefix-owners_form, suffix-owners_form.

# JSON per la pagina

BuzzFields è completamente basato su dei file JSON per costruire l'interfaccia della pagina.

Ogni file JSON dovrebbe essere strutturato nel seguente modo:

{
  "label": "Un nome per questa pagina",
  "blocks" [
    {
      "component": "blocco-da-mostrare",
      "header": "un titolo per questo blocco",
      "footer": "un footer per questo blocco",
      "traverse": "eventuale.percorso.interno.all.oggetto"
      ...
    },
    ...
  ]
}

header e footer supportano la scrittura template.

#Scrittura dei template

Per qualche proprietà è possibile costruire un template. Questa scrittura permette di sostituire in automatico all'interno di una stringa uno dei valori dell'oggetto in considerazione.

"header": {
  "template": "Nome: [0], ID: [1]",
  "traverse": [
    "name",
    "id"
  ]
}

Se il template contiene solo un placeholder ([0]), traverse può essere la sola stringa contenente la chiave all'interno dell'oggetto a cui fare riferimento.

# Inserimento condizionale

È possibile decidere di nascondere o mostrare dei blocchi in base a delle condizioni riferite a dei valori specifici dell'oggetto di riferimento.

"show": {
  "condition": "is_set",
  "traverse": "billing.from_owner"
}

Le condizioni al momento presenti sono le seguenti:

# Blocchi

BuzzFields contiene al suo interno tre principali blocchi: TableView, FormView e RepeaterView.

# TableView

Mostra una tabella responsive.

# JSON

{
  "component": "table",
  "columns": [
    ...
  ],
  "hide_button": true
}

Campi speciali:

• hide_buttonbool: Mostra o nasconde il pulsante Visualizza come ultima cella di ogni riga. Default: false

# Campi disponibili

Le colonne vengono tutte scritte tramite il componente CustomColumn. Ogni colonna può avere le seguenti proprietà:

• traversestringa: chiave dell'oggetto che si vuole mostrate (nel formato path.to.value)

• labelstringa: Nome della colonna,

• sortablebool: Determina o meno se mostrare i pulsante di sorting per quella colonna. Default: false

• linkoggetto: Se presente, la cella si trasforma in un link costruita tramite le seguenti sottoproprietà:

  • basestringa: Url di base (es. /owners/)
  • fieldstringa: Chiave all'interno dell'oggetto a cui deve fare il riferimento il link (es. owner.id)

  Per creare un link a /owners/{id proprietario}, bisogna strutturare link in questo modo:

  "link": {
    "base": "/owners/",
    "field": "owner.id"
  }
  

• subtextstringa | oggetto: Mostra per ogni cella una scritta posizionata appena sotto il contenuto principale. Se è una stringa, il testo sarà uguale per tutte le celle della colonna e corrisponderà alla stringa stessa. Se è un oggetto, dovrebbe avere le seguenti proprietà:

  • traversestringa: Chiave all'interno dell'oggetto a cui deve fare riferimento

# Slots

Questo blocco non utilizza alcuno slot. Pertanto, prefix e suffix verranno ignorati.

# FormView

Mostra un form interattivo. Gestisce in automatico gli errori. Può essere anche readonly.

# JSON

{
  "component": "form",
  "fields": [
    ...
  ]
}

Campi speciali:

• hide_buttonbool: Mostra o nasconde il pulsante Visualizza come ultima cella di ogni riga. Default: false

# Campi disponibili

A differenza di TableView, FormView si basa su molti componenti di input.

Tutti i componenti hanno però delle proprietà in comune:

# Slots

• prefix: Viene posto a inizio riga, prima di un componente di input
• suffix: Viene posto a fine riga, dopo un componente di input