@joyfill/components

v3.14.1

Published

a month ago

Joyfill UI Components

Downloads

18,271

0High
0Medium
0Low

jeremypagley

sayo96

jdpagley

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
getDefaultPage: ( defaults: object )
- Generate a default Joyfill Page for a Document or Template
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
validator: (doc: object)
- Performs validation on all visible required fields. Validation only validates the visible fields for the target view (desktop or mobile) and accounts for conditional logic.
- Returns object with validation state of the object as a whole and the individual fields.

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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme