Client

Firebolt Client

Uma biblioteca react que faz parte da stack Firebolt e tem como objetivos:

• Integrar-se automaticamente com o serviço do Firebolt onde os dados dos passos dos formulários são processados;
• Fornecer uma série de componentes que permitem a criação desses formulários em aplicações front-end de forma modular.

Instalação

# npm
npm install @iq-firebolt/client --save

# yarn
yarn add @iq-firebolt/client

Configuração

Para começarmos a usar o Firebolt client, precisamos configurar o Provider, ele é responsável por gerenciar o estado atual do formulário:

import { createFireboltProvider } from "@iq-firebolt/client";

const withFirebolt = createFireboltProvider({
  formAccess: {
    root: "https://firebolt-api-endpoint",
    formName: "sample",
  },
  withHistory: true,
  stepQueryParam: "step",
  debug: true,
});

Props Provider

Para usarmos o Provider, devemos encapsular a aplicação ou o componente da página que queremos renderizar o formulário:

const App = () => {
  return <div> my app </div>;
};

export default withFirebolt(App);

Componentes

Wizard

O Wizard é semelhante ao Switch do react-router, ele define qual componente renderizar a cada passo do formulário e também é possível definir um componente padrão para ser utilizado. Além disso, possui características importantes como:

• Rodar callbacks em situações especificas do formulário, por exemplo, na mudança de passo, caso haja um erro de conexão ou quando o formulário for finalizado;
• Definir um componente de fallback, ou seja, renderizar um componente durante a transição de passos, por exemplo um loader.

import { Wizard, createFireboltProvider } from "@iq-firebolt/client";

const withFirebolt = createFireboltProvider();

const App = () => {
  return (
    <div>
      <h1>My form</h1>
      <Wizard
        fallback={<MyLoader />}
        onFinishForm={(payload) => {}}
        onConnectionError={(err) => {}}
        onBeforeChangeStep={(proceed, { leavingStep, enteringStep }) => {}}
        onChangeStep={({ sentStep, currentStep }) => {}}
      ></Wizard>
    </div>
  );
};

export default withFirebolt(App);

Props Wizard

O Wizard renderiza/monta apenas um componente por vez, ou seja, se o formulário avançar para o próximo passo, o componente do template do passo atual será desmontado e o fallback ocupará o seu lugar.

Wizard.Step

O Wizard.Step funciona de forma similar ao Route do React router, ele fica responsável por atribuir a renderização de um componente especifico (template de passo/ step template) para um passo especifico do formulário. Com ele podemos definir utilizar um template padrão para os passos utilizando o pattern *:

import { Wizard, createFireboltProvider } from "@iq-firebolt/client";

// template components
import DefaultTemplate from "components/StepTemplates/Default";
import SummaryTemplate from "components/StepTemplates/Summary";

const withFirebolt = createFireboltProvider();

const App = () => {
  return (
    <div>
      <h1>My form</h1>
      <Wizard fallback={<MyLoader />}>
        {/* Default step template: */}
        <Wizard.Step match="*" component={DefaultTemplate} />
        {/* Custom template */}
        <Wizard.Step
          match={{ slug: "summary_step" }}
          component={SummaryTemplate}
        />
      </Wizard>
    </div>
  );
};

export default withFirebolt(App);

Props Wizard.Step

Toda prop passada para o Wizard.Step é repassada para o componente que ele deve renderizar.

Template de passo

Todo componente que for utilizado como template de passo recebe uma prop chamada fireboltStep, ela contem algumas informações sobre o passo atual e alguns métodos para a navegação no formulário. Esses valores também podem ser obtidos utilizando o hook useFirebolt.

const DefaultStepTemplate = ({ fireboltStep }) => {
  function goToNextStep() {
    fireboltStep.goNextStep({ cpf: "030.136.450-83" });
  }

  return (
    <div>
      <h1 className="default-step">Step title</h1>
      <button onClick={goToNextStep}>Próximo</button>
    </div>
  );
};

export default DefaultStepTemplate;

Conteúdo da prop fireboltStep

FireboltForm

A função do FireboltForm é transformar a parte do JSON Schema que descreve os campos necessários, em um formulário real. Ele mapeia e renderiza os campos, combinando eles com as inserções de conteúdo (Se necessário). exemplo:

import { FireboltForm } from "@iq-firebolt/client";

const DefaultStepTemplate = ({ fireboltStep }) => {
  return (
    <div>
      <h1 className="default-step">Step title</h1>
      <FireboltForm
        onSubmit={fireboltStep.goNextStep}
        schema={fireboltStep.fields}
        onGoBack={fireboltStep.goPreviousStep}
      />
    </div>
  );
};

export default DefaultStepTemplate;

Prop FireboltForm

FireboltForm.Insert

O FireboltForm.Insert nos permite inserir componentes entre campos que são gerados pelo FireboltForm, ele precisa apenas de uma referencia de onde deve ser inserido e o que ele deve renderizar:

import { FireboltForm } from "@iq-firebolt/client";

const DefaultStepTemplate = ({ fireboltStep }) => {
  return (
    <div>
      <h1 className="default-step">Step title</h1>
      <FireboltForm
        onSubmit={fireboltStep.goNextStep}
        schema={fireboltStep.fields}
        onGoBack={fireboltStep.goPreviousStep}
      >
        {/* Irá renderizar "something" depois do ultimo campo */}
        <FireboltForm.Insert after="last" render={<p>something</p>} />
        {/* Irá renderizar "something" antes do primeiro campo */}
        <FireboltForm.Insert before="first" render={<p>something</p>} />
        {/* Irá renderizar "something" antes do campo de cpf */}
        <FireboltForm.Insert
          before={{ fieldSlug: "cpf_field" }}
          render={<p>something</p>}
        />
      </FireboltForm>
    </div>
  );
};
export default DefaultStepTemplate;

A referencia pode ser last , first ou um objeto {fieldSlug: "field_slug"}

StepForm

A função do StepForm é simplificar a escrita dos templates de passo. Ao encapsular o FireboltForm, todas as suas propriedades passam a ser igualmente suportadas no StepForm e o resultado será o mesmo, tanto utilizando o StepForm quanto o FireboltForm. A diferença está na forma com que ele é utilizado, pois muitas dessas propriedades não precisam ser informadas no StepForm , deixando o código menor.

Exemplo de template de passo com FireboltForm

import { FireboltForm } from "@iq-firebolt/client";
import fireboltBlueberry from "firebolt-blueberry"; // tema
import { ActionButtons } from "components/ActionButtons";

const DefaultStepTemplate = ({ fireboltStep }) => {
  const autofill = { cpf: "123.232.523.23" };
  return (
    <div>
      <h1>my step template</h1>
      <FireboltForm
        schema={fireboltStep?.fields}
        onSubmit={fireboltStep?.goNextStep}
        remoteErrors={fireboltStep?.remoteErrors}
        theme={fireboltBlueberry}
        autoFill={autofill}
        customActionsChild={({ formData }) => (
          <ActionButtons
            formData={formData}
            onGoBack={handleGoBackform}
            beforeSubmitStep={runBeforeChangeStep}
          />
        )}
      />
    </div>
  );
};

export default DefaultStepTemplate;

Exemplo de template de passo com StepForm

import { StepForm } from "@iq-firebolt/client";
import { ActionButtons } from "components/ActionButtons";

const DefaultStepTemplate = ({ fireboltStep }) => {
  const autofill = { cpf: "123.232.523.23" };
  return (
    <div>
      <h1>my step template</h1>
      <StepForm
        autoFill={autofill}
        customActionsChild={({ formData }) => (
          <ActionButtons
            formData={formData}
            onGoBack={handleGoBackform}
            beforeSubmitStep={runBeforeChangeStep}
          />
        )}
      />
    </div>
  );
};

export default DefaultStepTemplate;

StepForm.Insert

Como o StepForm encapsula o FireboltForm, precisamos de um Insert também para o StepForm. O StepForm.Insert funciona exatamente igual o FireboltForm.Insert, nos permitindo inserir componentes nos espaços entre campos que são gerados pelo FireboltForm, que aqui, está dentro StepForm .

import { StepForm } from "@iq-firebolt/client";

const DefaultStepTemplate = ({ fireboltStep }) => {
  return (
    <div>
      <h1 className="default-step">Step title</h1>
      <StepForm>
        {/* Irá renderizar "something" depois do ultimo campo */}
        <StepForm.Insert after="last" render={<p>something</p>} />
        {/* Irá renderizar "something" antes do primeiro campo */}
        <StepForm.Insert before="first" render={<p>something</p>} />
        {/* Irá renderizar "something" antes do campo de cpf */}
        <StepForm.Insert
          before={{ fieldSlug: "cpf_field" }}
          render={<p>something</p>}
        />
      </StepForm>
    </div>
  );
};

export default DefaultStepTemplate;

A referencia pode ser last , first ou um objeto {fieldSlug: "field_slug"}