oneblink-apps-vue

A faithful re-write of @oneblink/apps-react v0.5.5 form components for Vue 2 applications

Installation

npm install oneblink-apps-vue

Usage

import Vue from "vue"
import OneBlinkFormComponents from "oneblink-apps-vue";
Vue.use(OneBlinkFormComponents)

For component definitions and examples see Components

Styling

In App.vue you will need to add the following

import "oneblink-apps-vue/dist/oneblink-apps-vue.css"

You can customise the primary colour easily with scss

SCSS

If you don't have one create a scss file eg src/styles/custom.scss

@use "oneblink-apps-vue/dist/oneblink-apps-vue.scss" with (
  $primary: #ff0000 /* your desired colour here */
);

then in main.js

import ../styles/custom.scss

Note: you will still need to do the above (create a scss file) to import the styles even if you don't change the primary colour eg

@import "oneblink-apps-vue/dist/oneblink-apps-vue.scss"

`<OneBlinkForm />`

Component for rendering a OneBlink Form. This component will render the submit, cancel and save draft buttons but it is up to the developer to implement what happens when those buttons are clicked.

It is also recommended to import the css from this library as well.

import { OneBlinkForm } from '@oneblink/apps-react'
import '@oneblink/apps-react/dist/styles.css'

Props

Property	Type	Required	Description
`definition`	`Form`	Yes	The OneBlink Form to render
`initialSubmission`	`Object`	No	The initial submission data
`googleMapsApiKey`	`string`	Conditional	A Google Maps API Key. Required if the form contains a `location` form element.
`abnLookupAuthenticationGuid`	`string`	Conditional	An ABN Lookup Authentication Guid. Required if the form contains a `abn` form element.
`captchaSiteKey`	`string`	Conditional	A reCAPTCHA Site Key. Required if the form contains a `captcha` form element.
`disabled`	`boolean`	No	Whether the form is currently able to be submitted. False by default.
`buttons`	`ButtonsConfiguration`	No	Change properties for certain buttons on the form.
`primaryColour`	`string`	No	Hex colour value for certain inputs (defaults to `#4c8da7`) .

Events

Event	Type	Description
`submit`	`(FormSubmissionResult) => void`	Emitted when the user submits the form with valid submission data. See NewFormSubmission for the structure of the argument.
`cancel`	`() => void`	Emitted when the user cancels the form
`saveDraft`	`(FormSubmission) => void`	Emitted when the user wishes to save their submission data as a draft submission. If not specified, drafts cannot be saved. See NewDraftSubmission for the structure of the argument.

ButtonsConfiguration

Property	Type	Required	Description
`submit`	`ButtonConfiguration`	No	Change properties for the Submit button
`cancel`	`ButtonConfiguration`	No	Change properties for the Cancel button
`saveDraft`	`ButtonConfiguration`	No	Change properties for the Save Draft button
`cancelPromptYes`	`ButtonConfiguration`	No	Change properties for the Unsaved Changes - Discard button
`cancelPromptNo`	`ButtonConfiguration`	No	Change properties for the Unsaved Changes - Back button

ButtonConfiguration

Property	Type	Required	Description
`label`	`string`	No	Change the text that appears in the button
`icon`	`string`	No	Add a Material Icon to the button, the string must be the part that goes `<i class="material-icons">HERE</i>`)

FormSubmission

Property	Type	Description
`submission`	`Object`	The submission data
`definition`	`OneBlinkForm`	The OneBlink Form, this will be different from the `form` prop passed to the Component as it is cloned when the component mounts.

FormSubmissionResult

Inherits properties from FormSubmission

Property	Type	Description
`captchaTokens`	`string[]`	Captcha tokens gathered by a `captcha` Form Element

Example

<script>
//Form.vue
import Vue from "vue"
import { FormTypes } from '@oneblink/types'
import {
  OneBlinkAppsError,
  draftService,
  submissionService,
} from '@oneblink/apps'

export default Vue.extend({
  data(){
    return {
      captchaSiteKey:'ENTER_YOUR_SITE_KEY_HERE',
      googleMapsApiKey: 'ENTER_YOUR_MAPS_API_KEY_HERE',
      formsAppId: 1,
      definition: {
        id: 1,
        name: 'Name of Form',
        description: '',
        organisationId: 'abc123',
        formsAppEnvironmentId: 1,
        formsAppIds: [],
        elements: [],
        isAuthenticated: false,
        isMultiPage: false,
        isInfoPage: false,
        publishStartDate: null,
        publishEndDate: null,
        postSubmissionAction: 'FORMS_LIBRARY',
        submissionEvents: [],
        tags: [],
      },
      isSavingDraft: false,
      saveDraftError: null,
      formSubmissionResult: null,
      isSubmitting: false,
      submitError: null,
    }
  },
  methods: {
    async handleSubmit(newFormSubmission){
      const formSubmission = Object.assign(
        {},
        newFormSubmission,
        {
          formsAppId,
          jobId: null,
          externalId: null,
          draftId: null,
          preFillFormDataId: null,
        },
      )

      this.formSubmissionResult = null
      this.submitError = null
      this.isSubmitting: true
      
      try {
        const newFormSubmissionResult = await submissionService.submit({
          formSubmission,
        })
        if (
          newFormSubmissionResult.isOffline &&
          !newFormSubmissionResult.isInPendingQueue
        ) {
          throw new OneBlinkAppsError(
            'You cannot submit this form while offline, please try again when connectivity is restored.',
            {
              isOffline: true,
            },
          )
        }

        this.formSubmissionResult = newFormSubmissionResult
        this.isSubmitting = false
        this.submitError = null
        
      } catch (error) {
        this.formSubmissionResult = null
        this.isSubmitting = false
        this.submitError = error
      }
    },
    async handleSaveDraft(newDraftSubmission){
      const draftSubmission = {
        ...newDraftSubmission,
        formsAppId,
      }
      
      this.saveDraftError: null
      this.isSavingDraft: true

      try {
        await draftService.addDraft(
          {
            title: this.form.name,
            formId: this.form.id,
            externalId: null,
            jobId: null,
          },
          draftSubmission,
        )

        this.saveDraftError = null
        this.isSavingDraft = false
        
      } catch (error) {
        this.saveDraftError = error
        this.isSavingDraft = false   
      }
    }
  },
  handleCancel(){
    // handle cancel here...
  }
})

</script>

<template>
  <div>
    <template v-if="isSubmitting">
      <!-- Render submitting animation/loading -->
    </template>
    <template v-else-if="submitError">
      <!-- Render error while submitting -->
    </template>
    <template v-else-if="isSavingDraft">
      <!-- Render saving draft animation/loading -->
    </template>
    <template v-else-if="saveDraftError">
      <!-- Render error while saving draft -->
    </template>
    <template v-else-if="formSubmissionResult">
      <!-- Render submission success -->
    </template>
    <OneBlinkForm v-else
      :captchaSiteKey="captchaSiteKey"
      :googleMapsApiKey="googleMapsApiKey"
      :formsAppId="formsAppId"
      :definition="definition"
      @cancel="handleCancel"
      @submit="handleSubmit"
      @saveDraft="handleSaveDraft"
    />
  </div>
</template>

`<OneBlinkAutoSaveForm />`

This component is a drop in replacement for <OneBlinkForm /> with the addition of auto save happening periodically to prevent users from losing submission data.

Props

Inherits properties from <OneBlinkForm />

Property	Type	Required	Description
`autoSaveKey`	`string`	No	Optionally pass a unique key for this submission e.g. the `externalId` the parameter

`<OneBlinkFormControlled />`

Similar to <OneBlinkForm />, however requires props to control the submission value.

Props

Property	Type	Required	Description
`submission`	`Object`	Yes	The submission data

Also requires the same props as <OneBlinkForm /> with the exception initialSubmission

Events

Has the same events as <OneBlinkForm /> as well as:

Event	Type	Description
`updateSubmission`	(FormSubmission) => void	Emitted whenever the submission model changes. Can be used to override the submission data or form definition

Example

<script>
//Form.vue
import Vue from "vue"
import { FormTypes } from '@oneblink/types'
import {
  OneBlinkAppsError,
  draftService,
  submissionService,
} from '@oneblink/apps'

export default Vue.extend({
  data(){
    return {
      captchaSiteKey:'ENTER_YOUR_SITE_KEY_HERE',
      googleMapsApiKey: 'ENTER_YOUR_MAPS_API_KEY_HERE',
      formsAppId: 1,
      definition: {
        id: 1,
        name: 'Name of Form',
        description: '',
        organisationId: 'abc123',
        formsAppEnvironmentId: 1,
        formsAppIds: [],
        elements: [],
        isAuthenticated: false,
        isMultiPage: false,
        isInfoPage: false,
        publishStartDate: null,
        publishEndDate: null,
        postSubmissionAction: 'FORMS_LIBRARY',
        submissionEvents: [],
        tags: [],
      },
      submission: {},
      isSavingDraft: false,
      saveDraftError: null,
      formSubmissionResult: null,
      isSubmitting: false,
      submitError: null,
    }
  },
  methods: {
    async handleSubmit(newFormSubmission){
      const formSubmission = Object.assign(
        {},
        newFormSubmission,
        {
          formsAppId,
          jobId: null,
          externalId: null,
          draftId: null,
          preFillFormDataId: null,
        },
      )

      this.formSubmissionResult = null
      this.submitError = null
      this.isSubmitting: true
      
      try {
        const newFormSubmissionResult = await submissionService.submit({
          formSubmission,
        })
        if (
          newFormSubmissionResult.isOffline &&
          !newFormSubmissionResult.isInPendingQueue
        ) {
          throw new OneBlinkAppsError(
            'You cannot submit this form while offline, please try again when connectivity is restored.',
            {
              isOffline: true,
            },
          )
        }

        this.formSubmissionResult = newFormSubmissionResult
        this.isSubmitting = false
        this.submitError = null
        
      } catch (error) {
        this.formSubmissionResult = null
        this.isSubmitting = false
        this.submitError = error
      }
    },
    async handleSaveDraft(newDraftSubmission){
      const draftSubmission = {
        ...newDraftSubmission,
        formsAppId,
      }
      
      this.saveDraftError: null
      this.isSavingDraft: true

      try {
        await draftService.addDraft(
          {
            title: this.form.name,
            formId: this.form.id,
            externalId: null,
            jobId: null,
          },
          draftSubmission,
        )

        this.saveDraftError = null
        this.isSavingDraft = false
        
      } catch (error) {
        this.saveDraftError = error
        this.isSavingDraft = false   
      }
    }
  },
  handleCancel(){
    // handle cancel here...
  },
  updateSubmission({
      submission: newSubmission,
      definition,
    }: {
      submission: FormSubmissionModel
      definition: FormTypes.Form
    }) {
      // modify the definition or submission here
      Vue.set(this, "submission", newSubmission)
      Vue.set(this, "definition", definition)
    },
})

</script>

<template>
  <div>
    <template v-if="isSubmitting">
      <!-- Render submitting animation/loading -->
    </template>
    <template v-else-if="submitError">
      <!-- Render error while submitting -->
    </template>
    <template v-else-if="isSavingDraft">
      <!-- Render saving draft animation/loading -->
    </template>
    <template v-else-if="saveDraftError">
      <!-- Render error while saving draft -->
    </template>
    <template v-else-if="formSubmissionResult">
      <!-- Render submission success -->
    </template>
    <OneBlinkFormControlled v-else
      :captchaSiteKey="captchaSiteKey"
      :googleMapsApiKey="googleMapsApiKey"
      :formsAppId="formsAppId"
      :definition="definition"
      :submission="submission"
      @cancel="handleCancel"
      @submit="handleSubmit"
      @saveDraft="handleSaveDraft"
      @updateSubmission="updateSubmission"
    />
  </div>
</template>

Component for rendering a OneBlink Form in read-only mode. This component will render the form with all inputs disabled but will not render the submit, cancel and save draft buttons.

Props

Property	Type	Required	Description
`form`	`OneBlinkForm`	Yes	The OneBlink Form to render
`initialSubmission`	`Object`	No	The initial submission data. Without this the form will be blank
`googleMapsApiKey`	`string`	Conditional	A Google Maps API Key. Required if the form contains a `location` form element.

Example

<script>
//Form.vue
import Vue from "vue"
import { FormTypes } from '@oneblink/types'
import {
  OneBlinkAppsError,
  draftService,
  submissionService,
} from '@oneblink/apps'

export default Vue.extend({
  data(){
    return {
      captchaSiteKey:'ENTER_YOUR_SITE_KEY_HERE',
      googleMapsApiKey: 'ENTER_YOUR_MAPS_API_KEY_HERE',
      formsAppId: 1,
      definition: {
        id: 1,
        name: 'Name of Form',
        description: '',
        organisationId: 'abc123',
        formsAppEnvironmentId: 1,
        formsAppIds: [],
        elements: [],
        isAuthenticated: false,
        isMultiPage: false,
        isInfoPage: false,
        publishStartDate: null,
        publishEndDate: null,
        postSubmissionAction: 'FORMS_LIBRARY',
        submissionEvents: [],
        tags: [],
      },
    }
  }
})

</script>

<template>
  <div>
    <OneBlinkReadOnlyForm
      :googleMapsApiKey="googleMapsApiKey"
      :definition="definition"
    />
  </div>
</template>

Known Issues

TODO

[x] <OneBlinkReadOnlyForm />
[ ] Auto save with controlled form docs
[x] BSB Element
[x] ABN Element

oneblink-apps-vue

oneblink-apps-vue

Installation

Usage

Styling

SCSS

Components

`<OneBlinkForm />`

Props

Events

ButtonsConfiguration

ButtonConfiguration

FormSubmission

FormSubmissionResult

Example

`<OneBlinkAutoSaveForm />`

Props

`<OneBlinkFormControlled />`

Props

Events

Example

Props

Example

Known Issues

TODO

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

Weekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

oneblink-apps-vue

oneblink-apps-vue

Installation

Usage

Styling

SCSS

Components

<OneBlinkForm />

Props

Events

ButtonsConfiguration

ButtonConfiguration

FormSubmission

FormSubmissionResult

Example

<OneBlinkAutoSaveForm />

Props

<OneBlinkFormControlled />

Props

Events

Example

Props

Example

Known Issues

TODO

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

`<OneBlinkForm />`

`<OneBlinkAutoSaveForm />`

`<OneBlinkFormControlled />`

Weekly Downloads