diff --git a/src/Form.js b/src/Form.js index adce853a8c..cc614b7fea 100644 --- a/src/Form.js +++ b/src/Form.js @@ -5,29 +5,131 @@ import templates from './templates'; import * as FormioUtils from './utils/utils'; export default class Form extends Element { + /** + * Represents a JSON value. + * @typedef {(string | number | boolean | null | JSONArray | JSONObject)} JSON + */ + +/** + * Represents a JSON array. + * @typedef {Array} JSONArray + */ + +/** + * Represents a JSON object. + * @typedef {{[key: string]: JSON}} JSONObject + */ + +/** + * @typedef {Object} FormioHooks + * @property {function} [beforeSubmit] + * @property {function} [beforeCancel] + * @property {function} [beforeNext] + * @property {function} [beforePrev] + * @property {function} [attachComponent] + * @property {function} [setDataValue] + * @property {function} [addComponents] + * @property {function} [addComponent] + * @property {function} [customValidation] + * @property {function} [attachWebform] + */ + +/** + * @typedef {Object} SanitizeConfig + * @property {string[]} [addAttr] + * @property {string[]} [addTags] + * @property {string[]} [allowedAttrs] + * @property {string[]} [allowedTags] + * @property {string[]} [allowedUriRegex] + * @property {string[]} [addUriSafeAttr] + */ + +/** + * @typedef {Object} ButtonSettings + * @property {boolean} [showPrevious] + * @property {boolean} [showNext] + * @property {boolean} [showCancel] + * @property {boolean} [showSubmit] + */ + +/** + * @typedef {Object} FormOptions + * @property {boolean} [saveDraft] - Enable the save draft feature. + * @property {number} [saveDraftThrottle] - The throttle for the save draft feature. + * @property {boolean} [readOnly] - Set this form to readOnly. + * @property {boolean} [noAlerts] - Disable the alerts dialog. + * @property {{[key: string]: string}} [i18n] - The translation file for this rendering. + * @property {string} [template] - Custom logic for creation of elements. + * @property {boolean} [noDefaults] - Exclude default values from the settings. + * @property {any} [fileService] - The file service for this form. + * @property {EventEmitter} [events] - The EventEmitter for this form. + * @property {string} [language] - The language to render this form in. + * @property {{[key: string]: string}} [i18next] - The i18next configuration for this form. + * @property {boolean} [viewAsHtml] - View the form as raw HTML. + * @property {'form' | 'html' | 'flat' | 'builder' | 'pdf'} [renderMode] - The render mode for this form. + * @property {boolean} [highlightErrors] - Highlight any errors on the form. + * @property {string} [componentErrorClass] - The error class for components. + * @property {any} [templates] - The templates for this form. + * @property {string} [iconset] - The iconset for this form. + * @property {import('@formio/core').Component[]} [components] - The components for this form. + * @property {{[key: string]: boolean}} [disabled] - Disabled components for this form. + * @property {boolean} [showHiddenFields] - Show hidden fields. + * @property {{[key: string]: boolean}} [hide] - Hidden components for this form. + * @property {{[key: string]: boolean}} [show] - Components to show for this form. + * @property {Formio} [formio] - The Formio instance for this form. + * @property {string} [decimalSeparator] - The decimal separator for this form. + * @property {string} [thousandsSeparator] - The thousands separator for this form. + * @property {FormioHooks} [hooks] - The hooks for this form. + * @property {boolean} [alwaysDirty] - Always be dirty. + * @property {boolean} [skipDraftRestore] - Skip restoring a draft. + * @property {'form' | 'wizard' | 'pdf'} [display] - The display for this form. + * @property {string} [cdnUrl] - The CDN url for this form. + * @property {boolean} [flatten] - Flatten the form. + * @property {boolean} [sanitize] - Sanitize the form. + * @property {SanitizeConfig} [sanitizeConfig] - The sanitize configuration for this form. + * @property {ButtonSettings} [buttonSettings] - The button settings for this form. + * @property {Object} [breadcrumbSettings] - The breadcrumb settings for this form. + * @property {boolean} [allowPrevious] - Allow the previous button (for Wizard forms). + * @property {string[]} [wizardButtonOrder] - The order of the buttons (for Wizard forms). + * @property {boolean} [showCheckboxBackground] - Show the checkbox background. + * @property {number} [zoom] - The zoom for PDF forms. + */ + /** * Creates an easy to use interface for embedding webforms, pdfs, and wizards into your application. * - * @param {Object} element - The DOM element you wish to render this form within. - * @param {Object | string} form - Either a Form JSON schema or the URL of a hosted form via. form.io. - * @param {Object} options - The options to create a new form instance. - * @param {boolean} options.readOnly - Set this form to readOnly - * @param {boolean} options.noAlerts - Set to true to disable the alerts dialog. - * @param {boolean} options.i18n - The translation file for this rendering. @see https://github.com/formio/formio.js/blob/master/i18n.js - * @param {boolean} options.template - Provides a way to inject custom logic into the creation of every element rendered within the form. + * @param {Object} elementOrForm - The DOM element you wish to render this form within, or the form definition. + * @param {Object | string | FormOptions} formOrOptions - A Form JSON schema, the URL of a hosted form, or the form options. + * @param {FormOptions} [options] - The options to create a new form instance. * * @example * import Form from '@formio/js/Form'; * const form = new Form(document.getElementById('formio'), 'https://examples.form.io/example'); * form.build(); */ - constructor(...args) { - let options = args[0] instanceof HTMLElement ? args[2] : args[1]; + + /** + * @type {FormOptions} - the options for this Form. + */ + options; + + constructor(elementOrForm, formOrOptions, options = {}) { + let element, form, formOptions; + if (elementOrForm instanceof HTMLElement) { + element = elementOrForm; + form = formOrOptions; + formOptions = options; + } + else { + element = null; + form = elementOrForm; + formOptions = formOrOptions || {}; + } if (Formio.options && Formio.options.form) { - options = Object.assign(options, Formio.options.form); + formOptions = Object.assign(formOptions, Formio.options.form); } - super(options); + super(formOptions); if (this.options.useSessionToken) { Formio.useSessionToken(this.options); @@ -39,30 +141,22 @@ export default class Form extends Element { }); this.instance = null; - if (args[0] instanceof HTMLElement) { + if (element) { if (this.element) { delete this.element.component; } - this.element = args[0]; - this.options = args[2] || {}; - this.options.events = this.events; - this.setForm(args[1]) - .then(() => this.readyResolve(this.instance)) - .catch(this.readyReject); + this.element = element; } - else if (args[0]) { + else { this.element = null; - this.options = args[1] || {}; - this.options.events = this.events; - this.setForm(args[0]) + } + if (form) { + this.setForm(form) .then(() => this.readyResolve(this.instance)) .catch(this.readyReject); } - else { - this.element = null; - this.options = {}; - this.options.events = this.events; - } + this.options = formOptions; + this.options.events = this.events; this.display = ''; } @@ -413,3 +507,6 @@ Formio.createForm = (...args) => { }; Formio.Form = Form; + +// eslint-disable-next-line no-undef +export { FormOptions }; diff --git a/src/FormBuilder.js b/src/FormBuilder.js index 56e7a2e404..35db5f899f 100644 --- a/src/FormBuilder.js +++ b/src/FormBuilder.js @@ -3,7 +3,37 @@ import Builders from './builders'; import Form from './Form'; export default class FormBuilder extends Form { + /** + * @typedef FormBuilderOptions + * @property {string[]} [disabled] - An array of "keys" of components that should be disabled within the form builder. Example: ['firstName', 'lastName'] + * @property {boolean} [noNewEdit] - When set to TRUE no modal is shown when a component is dragged onto the form. + * @property {boolean} [noDefaultSubmitButton] - Set to TRUE to not include the default submit button in Webforms. + * @property {boolean} [alwaysConfirmComponentRemoval] - Set to TRUE to always require confirmation before removing a component. + * @property {Object} [formConfig] - Form configurations to apply to forms being created. These configurations are added to the "config" property of the form object. + * @property {string} [resourceTag] - The tag to use to query for the "Existing Resource Fields" section of the builder. + * @property {import('./Form').FormOptions} [editForm] - The options to apply to the Edit Form (the form that shows inside the modal when you edit a component). + * @property {string} [language] - The language to load into the form builder. + * @property {Object} [builder] - The builder options to pass to the builder. + * @property {'form'|'wizard'|'pdf'} [display] - The display mode of the builder. + * @property {string} [resourceFilter] - Filter applied to the resources that appear in the builder's Existing Resource Fields. + * @property {boolean} [noSource] - When set to TRUE, the resource ID in the builder's Existing Resource Fields will not be linked. + * @property {boolean} [showFullJsonSchema] - When set to TRUE, the full JSON schema will be displayed in the JSON edit menu. + */ + + /** @type {FormBuilderOptions} */ static options = {}; + + /** @type {FormBuilderOptions} */ + options; + + /** + * Creates a new form builder. + * @param {HTMLElement} element - The HTML element to place the form builder. + * @param {string|Object} form - The form to pass to the builder + * @param {FormBuilderOptions} options - The options to create this builder. + * @return {FormBuilder} - The form builder instance. + * + */ constructor(element, form, options) { form = form || {}; options = options || {}; diff --git a/src/Webform.js b/src/Webform.js index 2f306ce240..b7d2f42caf 100644 --- a/src/Webform.js +++ b/src/Webform.js @@ -1,7 +1,6 @@ import _ from 'lodash'; import moment from 'moment'; import { compareVersions } from 'compare-versions'; -import { Component } from '@formio/core'; import EventEmitter from './EventEmitter'; import i18nDefaults from './i18n'; import { Formio } from './Formio'; @@ -48,110 +47,24 @@ function getOptions(options) { return options; } -/** - * Represents a JSON value. - * @typedef {(string | number | boolean | null | JSONArray | JSONObject)} JSON - */ - -/** - * Represents a JSON array. - * @typedef {Array} JSONArray - */ - -/** - * Represents a JSON object. - * @typedef {{[key: string]: JSON}} JSONObject - */ - -/** - * @typedef {Object} FormioHooks - * @property {function} [beforeSubmit] - * @property {function} [beforeCancel] - * @property {function} [beforeNext] - * @property {function} [beforePrev] - * @property {function} [attachComponent] - * @property {function} [setDataValue] - * @property {function} [addComponents] - * @property {function} [addComponent] - * @property {function} [customValidation] - * @property {function} [attachWebform] - */ - -/** - * @typedef {Object} SanitizeConfig - * @property {string[]} [addAttr] - * @property {string[]} [addTags] - * @property {string[]} [allowedAttrs] - * @property {string[]} [allowedTags] - * @property {string[]} [allowedUriRegex] - * @property {string[]} [addUriSafeAttr] - */ - -/** - * @typedef {Object} ButtonSettings - * @property {boolean} [showPrevious] - * @property {boolean} [showNext] - * @property {boolean} [showCancel] - * @property {boolean} [showSubmit] - */ - -/** - * @typedef {Object} FormOptions - * @property {boolean} [saveDraft] - Enable the save draft feature. - * @property {number} [saveDraftThrottle] - The throttle for the save draft feature. - * @property {boolean} [readOnly] - Set this form to readOnly. - * @property {boolean} [noAlerts] - Disable the alerts dialog. - * @property {{[key: string]: string}} [i18n] - The translation file for this rendering. - * @property {string} [template] - Custom logic for creation of elements. - * @property {boolean} [noDefaults] - Exclude default values from the settings. - * @property {any} [fileService] - The file service for this form. - * @property {EventEmitter} [events] - The EventEmitter for this form. - * @property {string} [language] - The language to render this form in. - * @property {{[key: string]: string}} [i18next] - The i18next configuration for this form. - * @property {boolean} [viewAsHtml] - View the form as raw HTML. - * @property {'form' | 'html' | 'flat' | 'builder' | 'pdf'} [renderMode] - The render mode for this form. - * @property {boolean} [highlightErrors] - Highlight any errors on the form. - * @property {string} [componentErrorClass] - The error class for components. - * @property {any} [templates] - The templates for this form. - * @property {string} [iconset] - The iconset for this form. - * @property {Component[]} [components] - The components for this form. - * @property {{[key: string]: boolean}} [disabled] - Disabled components for this form. - * @property {boolean} [showHiddenFields] - Show hidden fields. - * @property {{[key: string]: boolean}} [hide] - Hidden components for this form. - * @property {{[key: string]: boolean}} [show] - Components to show for this form. - * @property {Formio} [formio] - The Formio instance for this form. - * @property {string} [decimalSeparator] - The decimal separator for this form. - * @property {string} [thousandsSeparator] - The thousands separator for this form. - * @property {FormioHooks} [hooks] - The hooks for this form. - * @property {boolean} [alwaysDirty] - Always be dirty. - * @property {boolean} [skipDraftRestore] - Skip restoring a draft. - * @property {'form' | 'wizard' | 'pdf'} [display] - The display for this form. - * @property {string} [cdnUrl] - The CDN url for this form. - * @property {boolean} [flatten] - Flatten the form. - * @property {boolean} [sanitize] - Sanitize the form. - * @property {SanitizeConfig} [sanitizeConfig] - The sanitize configuration for this form. - * @property {ButtonSettings} [buttonSettings] - The button settings for this form. - * @property {Object} [breadCrumbSettings] - The breadcrumb settings for this form. - * @property {boolean} [allowPrevious] - Allow the previous button (for Wizard forms). - * @property {string[]} [wizardButtonOrder] - The order of the buttons (for Wizard forms). - * @property {boolean} [showCheckboxBackground] - Show the checkbox background. - * @property {number} [zoom] - The zoom for PDF forms. - */ - /** * Renders a Form.io form within the webpage. */ export default class Webform extends NestedDataComponent { /** - * @type {FormOptions} - the options for this Webform. + * @typedef {Omit} WebformOptions + */ + + /** + * @type {WebformOptions} - the options for this Webform. */ options; /** * Creates a new Form instance. * - * @param {HTMLElement | Object | FormOptions} [elementOrOptions] - The DOM element to render this form within or the options to create this form instance. - * @param {FormOptions} [options] - The options to create a new form instance. + * @param {Object | WebformOptions} [elementOrOptions] - The DOM element to render this form within or the options to create this form instance. + * @param {WebformOptions} [options] - The options to create a new form instance. */ constructor(elementOrOptions, options) { let element, formOptions;