# Forms Generator

Forms Generator package is a helper package to reduce boilerplate code for the postcall/precall creation using the package

# Dependencies

@pitcher/forms-generator package depends on 3 other packages. Make sure you have these packages installed in your project:

  "@vue/composition-api": ">= 1.0.0-rc.1",
  "vue": ">= 2.6.0",
  "@pitcher/core": "LATEST",
  "@pitcher/forms": "LATEST"

# Installation

To install @pitcher/forms-generator package, simply run:

yarn add @pitcher/forms-generator

npm install @pitcher/forms-generator

# Getting Started

Forms generator package contains helper methods to remove all boilerplate code from the codebase. It handles postcall rendering and initialization by itself. You only need to provide the necessary structure for the form. To initialize it change the src/main.js file of the vue project to contain this:

import { createPostcall } from '@pitcher/forms-generator'
import { initPostcall } from '@/postcallFormConfig/initPostcall' // a function that would get called initially to extract form information.

createPostcall(initPostcall)

initPostcall would look something like this:

// src/postcallFormConfig/initPostcall.js

import { useFormGenerator } from '@pitcher/forms-generator'

import { getPostcallItems } from './postcallItems'

export function initPostcall() {
  const { onLoad, pluginItem, upsertItem } = useFormGenerator()
  const postcallItems = [
    {
      id: 'postcallTextArea',
      weight: 200,
      component: 'PFormTextarea',
      props: {
        submissionParam: 'notes',
        title: $t('Description'),
      },
    },
    {
      weight: 700,
      id: 'discussionItems',
      component: 'PFormSelect',
      itemsFetcher: {
        query: 'SELECT * FROM tbl_crm_ditems_PIT_v1',
      },
      defaultValue: '',
      props: {
        submissionParam: 'discussionItem',
        precallField: 'discussionItem',
        itemValue: 'Id',
        itemText: 'Name',
        disableLookup: true,
        title: $t('Discussion Items'),
        searchable: false,
        returnObject: false,
      },
    }
  ]

  postcallItems.forEach((item) => upsertItem(pluginItem(item)))

  // must be called as last
  setTimeout(() => {
    onLoad()
  }, 1000)
}

# Forms Generator APIs

useFormGenerator

Main function that exposes generator APIs.

import { useFormGenerator } from '@pitcher/forms-generator'

const {
  upsertItem, // used to add fields to postcall. Expects an option object, see below for more details
  formState, // reactive state of the current form. Selected calues of the items that are upserted with `upsertItem` can be accessed with their respective `id`s. Can be quite useful when conditionally rendering / filtering between fields are handled.
  useFormRef, // returns a ref that is bound to `formState`. Expects the field name as first parameter, and default value as the second. If there is a field already defined on `formState` with the given field name than returns that fields ref, else creates that field and returns the ref. See below for details
  addValidator, // Adds a validator to the form to be called with `window.canSubmit`
  useWithForm, // same as `useWithForm` from `@pitcher/forms`
  onLoad, // have to be called at the end of forms initializator function 
} = useFormGenerator()

upsertItem({
  id: 'callKeyMessages', // id of the item in the item registry
  weight: 700, // weight of the item - to control the order of fields
  component: 'PFormSelect', // component to be rendered, can be given string names of any component from @pitcher/forms, or can be a custom component
  itemsFetcher: {
    query: 'SELECT * FROM tbl_crm_ccm_PIT_v1 WHERE PITCHER__Parent_Discussion_Item__c = {{ discussionItems }}', // if the items for the  given selection is fetched from database this query will be used. can be given filters depending on other fields inside double curly braces. In this example this query will be filtered by the selected `discussionItems`
  },
  defaultValue: '', // default value for the given field
  visible: 'discussionItems' // can be a boolean or a string value for another fields id. 
  props: { // any expecred prop for the given component, very useful when used with @pitcher/forms components
    submissionParam: 'discussionItem',
    precallField: 'discussionItem',
    itemValue: 'Id',
    itemText: 'Name',
    disableLookup: true,
    title: $t('Discussion Items'),
    searchable: false,
    returnObject: false,
  },
})

// To add a signature pad to the postcall
upsertItem({
  id: 'signature',
  component: 'PSignaturePad',
  weight: 900,
  props: {
    submissionParam: 'signature',
    title: $t('Signature'),
  },
})

const myFormField = useFormRef('myFormField', null) 

watch(() => formState.value.myFormField, () => {
  console.log(myFormField.value)
  console.log(formState.value.myFormField)
})

myFormField.value = 'Test' // watch would log 'Test' twice
formState.value.myFormField = 'Second Test' // watch would log 'Second Test' twice

← Forms Forms Generator Cookbook →