Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

update types to parent Form class; add builder options type #5585

Closed
wants to merge 3 commits into from
Closed

update types to parent Form class; add builder options type #5585

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2a36250
update types to parent Form class; add builder options type
brendanbond May 6, 2024
1b5b070
minor update
brendanbond May 7, 2024
66139bc
Merge branch 'master' into update-form-types
brendanbond May 30, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
151 changes: 124 additions & 27 deletions src/Form.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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<JSON>} 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);
Expand All @@ -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 = '';
}

Expand Down Expand Up @@ -413,3 +507,6 @@ Formio.createForm = (...args) => {
};

Formio.Form = Form;

// eslint-disable-next-line no-undef
export { FormOptions };
30 changes: 30 additions & 0 deletions src/FormBuilder.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 || {};
Expand Down
101 changes: 7 additions & 94 deletions src/Webform.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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';
Expand Down Expand Up @@ -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<JSON>} 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<import('./Form').FormOptions, 'display' | 'buttonSettings' | 'breadcrumbSettings' | 'allowPrevious' | 'wizardButtonOrder' | 'showCheckboxBackground' | 'zoom'>} 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;
Expand Down
Loading