@joyfill/components
v3.15.1
Published
Joyfill UI Components
Downloads
27,610
Readme
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'
, andmode: '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 thepages
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.
- First - Style set by the user on the field using the UI style settings.
- Second -Field theme property. ie.
theme.field.fontColor
- Third - Top level theme property. ie
theme.fontColorPrimary
- 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 and styles will be applied to the field based on the order below.
- 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
- Triggers
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
- Triggers
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
- Triggers
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
- Triggers
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
- Triggers
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
- Triggers
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 addedchangelogs
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