@stackhouseos/box-core v4.8.0

Box

Libreria per la creazione di form e layout avanzati, è integrabile su qualsiasi progetto react/redux.

Table of Contents

• Installation
• Getting Started
• Configs
• Field schema
• Field component
• Id
• Methods
• Rules and validation
• Prefix
• Container
• Reducer

Peer Dependencies

Installation

npm install @stackhouseos/box-core

Getting Started

• Basic

import Box from '@stackhouseos/box-core';

const model = [{
  type: 'input',
  placeholder: 'Name',
  id: 'name'
}]

<Box prefix="nomereducer" fields={model} />

import Box from '@stackhouseos/box-core';

const CustomInput = ({onChange, value, placeholder}) => {
  return (
    <input 
      value={value}
      onChange={(evt) => onChange(evt.target.value)} placeholder={placeholder}
    />
  )
}

Box.extendControls({CustomInput});

const model = [
  {
    type: 'CustomInput',
    placeholder: 'Name',
    id: 'name'
  }
]

<Box prefix="nomereducer" fields={model} />

Attenzione per poter usare Box ricordati di estendere il tuo reducer con quello di Box

Esempio Reducer

Configs

Box

Field schema

Field Component

I tuoi componenti custom riceveranno in automatico le seguenti props, oltre al tutte le proprietà che userai nel tuo schema

Id

Il campo id viene utilizzato per recuperare i dati da redux o context, allo stesso modo viene utilizzato per salvare i dati su redux

const model = [
  {
    type: 'CustomInput',
    placeholder: 'Name',
    id: 'name',
  },
  {
    type: 'CustomInput',
    placeholder: 'tipologia',
    id: 'dettagli.tipologia',
  }
]

<Box prefix="nomereducer" fields={model} />

i dati potranno essere recuperati usando come id direttamente name, Box salverà i dati su redux nel reducer nomereducer.name e nomereducer.dettagli.tipologia

Può essere utile anche recuperare i dati da altri reducer che non sono al livello di nomereducer, tramite l'utilizzo del carattere ^ come prefisso dell'id, es:

• Redux state

const initialState = {
  attivita: {items: [1,2,3]},
  ticket: {name: 'Andrea', dettagli: {tipologia: 'dev'}}
}

import Box, { BoxContextProvider } from '@stackhouseos/box-core';

const model = [
  {
    type: 'Lista',
    id: '^attivita.items', // print [1,2,3]
  },
  {
    type: 'Testo',
    id: 'ticket.dettagli.tipologia', // print 'dev'
  },
  {
    type: 'Testo',
    id: '^role', // print 'user'
  }
]

<BoxContextProvider value={{ role: 'user' }}>
  <Box prefix="ticket" fields={model} />
</BoxContextProvider>

Questa convenzione sarà utilizzata anche per la gestione delle rules e validazioni

const model = [
  {
    type: 'Testo',
    placeholder: 'Name',
    id: 'name',
    rules: {
      '^role': {eq: 'user'} // appare solo se il ruolo utente è uguale a 'user'
    },
    validation: {
      'name': { min: 10 } // verrà validato solo se rules è valido
    }
  }
]

Methods

• Add components

Box.extendControls({ ...components });

• Set components

Box.setControls({ ...onlyThiscomponents });

• Extends data with Context, per aggiungere dati che non sono su redux

import Box, { BoxContextProvider } from '@stackhouseos/box-core';

const model = [
  {
    type: 'Testo',
    id: '^role', // print 'user'
  }
]

<BoxContextProvider value={{ role: 'user' }}>
  <Box prefix="ticket" fields={model} />
</BoxContextProvider>

Rules and validation

Utile quando si vuole disabilitare il tasto salva se nel form sono presenti errori

• example

{
  type: 'button',
  title: 'SALVA',
  ruleModeDisable: true,
  rules: { '^hasError': { eq: false } }
}

• Field con regole

Tutti i field passati nel modello possono esser gestiti tramite rules, basterà appendere al nome _rules

{
  type: 'button',
  title_default: 'Salva', // titolo se non si trova nessuna corrispondenza con le regole
  title_rules: {
    'Aggiungi': {
      'id' : {ex: false}, // il titolo sarà "Aggiungi" se id non esiste
    },
    'Salva': {
      'id' : {ex: true},  // il titolo sarà "Salva" se id esiste, questa regola può essere omessa usando il title_default
    }
  },
}

• Root reducer

^ utilizare l'accento circonflesso, per recuperare i dati dalla root di reducer, questo ignora un qualasi prefix indicato

Prefissi

E' possibile aggiungere un prefisso a livello di componente

<Box prefix="nomereducer" />

oppure dentro un qualsiasi fields. Aggiungendo un prefisso al padre sarà aggiunto in automatico a tutti i fields figli.

const modello = [
  {
    id: 'name', // selector nomereducer.name
    type: 'input'
  },
  {
    type: 'grid',
    prefix: 'dati',
    fields:[
      {
        id: 'name' // selector nomereducer.dati.name
      },
      {
        id: 'lastname' // selector nomereducer.dati.lastname
      }
    ]
  }
]

<Box prefix="nomereducer" fields={modello} />

Container

Capiterà molto spesso di dover mettere attorno ai tuoi fields un componente di layout, questa operazione si potrà fare in 2 modi:

• Modalità normale

  const model = [{
    type: 'Paper',
    fields:[{type: 'text', text: 'ciao'}]
  }]
  // esempio da compilato
  <Paper>
    <Text>Ciao</Text>
  </Paper>

• Modalità container base

  const model = [{
    container: 'Paper',
    type: 'text', 
    text: 'ciao'
  }]
  // esempio da compilato
  <Paper>
    <Text>Ciao</Text>
  </Paper>

• Modalità container con props

  const model = [{
    container: {type: 'Paper', color: 'red'},
    type: 'text', 
    text: 'ciao'
  }]
  // esempio da compilato
  <Paper color="red">
    <Text>Ciao</Text>
  </Paper>

Visualizzare tutti gli errori

Passare al context il campo showErrors: true, per visualizzare tutti gli errori

<BoxContextProvider value={{ showErrors: true }}>
  <Box prefix="ticket" fields={model} />
</BoxContextProvider>

Redux reducer

Se vuoi usare Box su un progetto esistente, ti basterà estendere il tuo reducer con l'azione di default

• Reducer example

  import { boxReducer } from '@stackhouseos/box-core';
  const ticketReducer = (state = initialState, action) =>
  produce(state, () => {
    switch (action.type) {
      case DEFAULT_ACTION:
        break;
      case TUE_AZIONI:
        break;
      default:
        // necessario per fare comunicare il tuo redux con Box
        return boxReducer('folder', state, action); 
    }
  });

• Reducer example Redux Toolkit

const slice = createSlice({
  name: 'categories',
  initialState,
  reducers: {
    // ... actions
  },
  extraReducers: {
    // necessario per fare comunicare il tuo redux con Box
    '@box/categories/update': (state, action) => _set(state, action.payload.id, action.payload.value),
  },
});