❤
npm
Sign UpSign In

@joyfill/components

3.8.0 • Public • Published

Install

npm install @joyfill/components or yarn add @joyfill/components

Getting Started

Head over to Joyfill developer docs to learn more, find guided tutorials and much more.

React Usage


import { JoyDoc, getDefaultDocument } from '@joyfill/components';

const App = () => {
  return (
    <JoyDoc
      doc={getDefaultDocument()}
      mode="edit"
      onChange={(changelogs, doc) => console.log(changelogs, doc)}
    />
  );
}

Javascript Usage (CDN)

<!DOCTYPE html>
<html>
  <head>
    <title>Joyfill for Javascript Example</title>
    <base href=".">
    <meta charset="UTF-8" />
    <script src=" https://cdn.jsdelivr.net/npm/@joyfill/components@latest/dist/joyfill.min.js"></script>
  </head>
  <body>
    <div id="joyfill"></div>
    <script>

      Joyfill.JoyDoc(
        document.getElementById('joyfill'),
        {
          mode: 'edit',
          onChange: (changelogs, doc) => console.log('onChange: ', changelogs, doc),
        }
      );

    </script>
  </body>
</html>

Javascript Usage (Module)

//index.html

<!DOCTYPE html>
<html>
  <head>
    <title>Joyfill for Javascript Example</title>
    <base href=".">
    <meta charset="UTF-8" />
  </head>
  <body>
    <div id="joyfill"></div>
    <script type="module" src="./index.js"></script>
  </body>
</html>

//index.js

import Joyfill from "@joyfill/components/dist/joyfill.min.js";

Joyfill.JoyDoc(
  document.getElementById('joyfill'),
  {
    mode: 'edit',
    onChange: (changelogs, doc) => console.log('onChange: ', changelogs, doc),
  }
);

JoyDoc Properties

  • mode: 'edit' | 'fill' | 'readonly'
    • Required*
    • Enables and disables certain JoyDoc functionality and features.
    • Options
      • edit is the mode where the form/pdf is desinged, styled, and configured.
      • fill is the mode where you simply input the field data into the built form/pdf.
      • readonly is the mode where everything is locked down and you're simply viewing the form/pdf and the inputed data.
  • width: number
    • Specifies the width of the form view
    • Default: 816px
  • height: number
    • Specifies the height of the form view
    • Required for field lazy loading
    • Default: 1056px
  • view: 'mobile' | undefined
    • Specifies that the mobile view should be displayed
    • The width: <screen_width>, view: 'mobile', and mode: 'fill properties enables filling out of forms in responsive web view.
  • lazyload: boolean
    • Specifies form fields should be lazy loaded
    • Default: false
  • doc: object
    • The default JoyDoc JSON starting object to load into the component view. Must be in the JoyDoc JSON data structure.
  • initialPageId: string
    • Specify the initial page to display in the form.
    • Utilize the _id property of a Page object. For instance, page._id.
    • If page is not found within the doc it will fallback to displaying the first page in the pages array.
  • theme: object
    • Specifies the theme. See theming section below for list of supported properties.
  • fieldOptions: [object, ...]
    • Overwrite the list of field options that can be dragged and dropped on the form/pdf.
    • Field option objects can have any JoyDoc JSON property. Any property set will be used as the new field defaults when dragged and dropped to the form/pdf.
  • fieldSettings: object
    • Customize file, page, and field settings.
    • Head over to the developer docs to learn more about customizing settings.
  • onChange: (changelogs: object_array, doc: object) => {}
    • Used to listen to any changes to the style, layout, values, etc. across all modes.
    • changelogs: object_array
      • Can contain one ore more of the changelog object types supported.
    • doc: object
      • Fully updated JoyDoc JSON structure with changes applied.
  • onUploadAsync: (params: object, fileUploads) => Promise
    • Required, if you want to support PDF uploads, page backgrounds, and image fields.
    • Must return a promise that will resolve to { url: string }.
      • url must be a valid image url or image base64 uri.
    • Utilize this handler to upload images for fields, page backgrounds, etc. to your own asset hosting service.
    • params: object
      • target: ('file.update' | 'page.update' | 'field.update') Determines the object within the doc (JoyDoc JSON structure) that was targeted with the change event.
      • _id The _id of the document|template.
      • identifier The identifier of the document|template.
      • fileId The id of the file that the change happened.
      • pageId The id of the page that the change happened.
      • fieldId The id of the field that the change happened.
      • fieldIdentifier The custom id of the field that the change happened.

Theming

  • All options below are optional. You can use one or all of the options listed to customize the SDK theme.
  • You are responsible for ensuring the fontFamily you specify is loaded and available within your application.
  • All properties that set color must use HEX code. HEX code example: #fffff.
  • All number options must be specified as numbers, not strings. Numbers will be used with pixel (px) sizing.
  • Field Styles
    • Theme and styles will be applied to the field based on the order below.
      1. First - Style set by the user on the field using the UI style settings.
      2. Second -Field theme property. ie. theme.field.fontColor
      3. Third - Top level theme property. ie theme.fontColorPrimary
      4. Fourth - Internal SDK default style
    • Example of how fontColor is applied to a field: const fontColor = field.fontColor || theme.field.fontColor || theme.fontColor || internal.fontColor
  • Theme Properties
    • fontFamily: string
    • fontColorPrimary: string(HEX Code)
    • fontColorSecondary: string(HEX Code)
    • primaryColor: string(HEX Code)
    • dangerColor: string(HEX Code)
    • warningColor: string(HEX Code)
    • backgroundColor: string(Hex Code)
    • borderColor: string(Hex Code)
    • borderRadius: number
    • field: object
      • titleFontSize: number,
      • titleFontColor: string(HEX Code),
      • titleFontStyle: string('italic' | 'normal'),
      • titleFontWeight: string('bold' | 'normal'),
      • titleTextAlign: string('left' | 'center' | 'right'),
      • titleTextTransform: string('uppercase' | 'none'),
      • titleTextDecoration: string('underline' | 'none'),
      • fontSize: number,
      • fontColor: string(HEX Code),
      • fontStyle: string('italic' | 'normal'),
      • fontWeight: string('bold' | 'normal'),
      • textAlign: string('left' | 'center' | 'right'),
      • textTransform: string('uppercase' | 'none'),
      • textDecoration: string('underline' | 'none'),
      • textOverflow: string('ellipsis'),
      • padding: number,
      • borderRadius: number,
      • borderWidth: number,
      • borderColor: string(HEX Code),
      • backgroundColor: string(HEX Code)

Field Events

  • Image

    • onFocus(params: object, e: object) * Empty - Triggers onFocus when file upload is initiated (click or file drop) * Populated - Triggers onFocus when when upload is clicked or image is deleted.
    • onUploadAsync * When user selects file(s) from the file system. * When files are dragged and dropped onto the field.
    • onChange is fired when an option is selected. * Triggers when onUploadAsync has successfully responded with image urls.

  • Text, Textarea, Number, Date

    • onFocus(params: object, e: object) is fired when the field is focused.
      • e.blur
        • Triggers onChange for any pending changes.
        • Triggers onBlur
    • onChange is fired when the field value is modified.
    • onBlur is fired when the field is blurred.

  • Dropdown

    • onFocus(params: object, e: object) is fired when the field is focused.
      • e.blur
        • Triggers onBlur
    • onChange is fired when an option is selected or unselected in the field.
    • onBlur is fired when the field is blurred.

  • MultiSelect

    • onFocus is fired when an option is selected or unselected for the first time on the field.
    • onChange is fired when an option is selected or unselected in the field.

  • Selector (Checkbox/Circle etc)

    • onFocus(params: object, e: object) is fired when an option is selected or unselected.
    • onChange is fired when an option is selected or unselected.

  • Signature

    • onFocus(params: object, e: object) is fired when sign button is clicked.
      • e.blur
        • Closes the signature modal
    • onChange is fired when the submit button is clicked.
    • onBlur is fired when the modal is closed.

  • Chart

    • onFocus(params: object, e: object) is fired when edit button is clicked.
      • e.blur
        • Closes the chart modal
    • onChange is fired when the submit button is clicked.
    • onBlur is fired when the modal is closed.

  • Table / Input Group

    • Text Cell

      • onFocus(params: object, e: object) is fired when cell is focused.
        • e.blur
          • Triggers onBlur
      • onChange is fired when the text cell is blurred.
      • onBlur is fired when the cell is blurred.

    • Dropdown Cell

      • onFocus(params: object, e: object) is fired when cell is focused.
        • e.blur
          • Triggers onBlur
      • onChange is fired when an option is selected.
      • onBlur is fired when the cell is blurred.

    • Image Cell

      • onFocus(params: object, e: object) * Empty - Triggers onFocus when file upload is initiated (click or file drop) * Populated - Triggers onFocus when when upload is clicked or image is deleted.
      • onUploadAsync * When user selects file(s) from the file system. * When files are dragged and dropped onto the field.
      • onChange is fired when an option is selected.
        • Triggers when onUploadAsync has successfully responded with image urls.

  • Individual Table / Input Group Cell Field

    • Text Cell

      • onFocus(params: object, e: object) is fired when the field is focused.
        • e.blur
          • Triggers onChange for any pending changes.
          • Triggers onBlur
      • onChange is fired when the field value is modified.
      • onBlur is fired when the field is blurred.

    • Dropdown Cell

      • onFocus(params: object, e: object) is fired when the field is focused.
        • e.blur
          • Triggers onBlur
      • onChange is fired when the field value is modified.
      • onBlur is fired when the field is blurred.

    • Dropdown Selector Cell

      • onFocus(params: object, e: object) is fired when an option is chosen.
      • onChange is fired when an option is chosen.

    • Image Cell

      • onFocus(params: object, e: object) * Empty - Triggers onFocus when file upload is initiated (click or file drop) * Populated - Triggers onFocus when when upload is clicked or image is deleted.
      • onUploadAsync * When user selects file(s) from the file system. * When files are dragged and dropped onto the field.
      • onChange is fired when an option is selected.
        • Triggers when onUploadAsync has successfully responded with image urls.

Components Helper Methods

  • getDefaultDocument
    • Get a default Joyfill Document object
  • getDefaultTemplate
    • Get a default Joyfill Template object
  • getDocumentFromTemplate: ( template: object )
    • Generate a Joyfill Document object from a Joyfill Template object
  • duplicate: ( original: object, defaults: object )
    • Duplicate a Joyfill Document or Template object.
  • duplicatePage: ( original: object, fileId: string, pageId: string )
    • Duplicate a Joyfill Document or Template Page object.
    • Returns: { doc: object, changelogs: array }
      • doc fully updated Document or Template with the page added
      • changelogs array of changelogs for new duplicate page.
  • applyLogic: ( items: object_array, fields: object_array, fieldLookupKey: string )
    • Apply show/hide logic to pages and fields for external filtering.
    • Wrapper around @joyfill/conditional-logic library. View library

Contributing

Environment Versions

  • Module manage yarn
  • Node version 18+

Commands

  • Run Tests yarn run test
  • Coverage Report yarn run coverage
  • Auto Fix Linting Errors yarn run lint-fix
  • See Linting Linting yarn run lint
  • Generate Visual Coverage Report yarn coverage-report -- filename

Readme

Keywords

none

Package Sidebar

Install

npm i @joyfill/components

Repository

github.com/joyfill/components

Homepage

github.com/joyfill/components#readme

Weekly Downloads

1,176

Version

3.8.0

License

SEE LICENSE IN LICENSE.txt

Unpacked Size

27.6 MB

Total Files

10

Last publish

Collaborators

  • jeremypagley
  • sayo96
  • jdpagley
Try on RunKit
Report malware