Forms - Revision history

2A02:C7C:C43F:C600:D576:FD80:AC3E:FC1: /* Forms without an action */

2024-03-27T14:41:53Z

Forms without an action

← Older revision		Revision as of 14:41, 27 March 2024
Line 49:		Line 49:
	<Form submitLabel="Do the thing Javascript" onSubmitted={(submittedValues) => {		<Form submitLabel="Do the thing Javascript" onSubmitted={(submittedValues) => {
	console.log("The name: ", submittedValues.name);		console.log("The name: ", submittedValues.name);
	return ..optionally something that results in a promise, such as webRequest or Promise.all etc..		// return ..optionally something that results in a promise, such as webRequest or Promise.all etc..
	}}>		}}>
	<Input label='Name' name='name' />		<Input label='Name' name='name' />

2A02:C7C:C43F:C600:D576:FD80:AC3E:FC1: /* Forms without an action */

2024-03-27T14:41:40Z

Forms without an action

← Older revision		Revision as of 14:41, 27 March 2024
Line 43:		Line 43:
	=Forms without an action=		=Forms without an action=

	If you'd like to have a form where javascript exclusively handles the submitted response, simply create the form without an action and you can use onSuccess or onFailed ~~to track~~ the ~~validation state~~.		If you'd like to have a form where javascript exclusively handles the submitted response, simply create the form without an action and you can use onSubmitted to perform any processing you need. If you return a promise, the form will remain in the loading state. As with all other forms, onSuccess or onFailed will still occur depending on how that promise resolves. If onSubmitted does not return a promise, onSuccess always triggers provided the form contents were valid.

	<syntaxhighlight lang="dart" line="1">		<syntaxhighlight lang="dart" line="1">

	<Form submitLabel="Do the thing Javascript" ~~onSuccess~~={(submittedValues) => {		<Form submitLabel="Do the thing Javascript" onSubmitted={(submittedValues) => {
	console.log("The name: ", submittedValues.name);		console.log("The name: ", submittedValues.name);
			return ..optionally something that results in a promise, such as webRequest or Promise.all etc..
	}}>		}}>
	<Input label='Name' name='name' />		<Input label='Name' name='name' />

Luke at 16:45, 8 March 2023

2023-03-08T16:45:33Z

← Older revision		Revision as of 16:45, 8 March 2023
Line 40:		Line 40:

	Sometimes a custom endpoint will be created such as for logging in. As the action is just an endpoint name then the url of custom endpoints can be used as a form action too, provided it is expecting values to be POSTed to it of course.		Sometimes a custom endpoint will be created such as for logging in. As the action is just an endpoint name then the url of custom endpoints can be used as a form action too, provided it is expecting values to be POSTed to it of course.

			=Forms without an action=

			If you'd like to have a form where javascript exclusively handles the submitted response, simply create the form without an action and you can use onSuccess or onFailed to track the validation state.

			<syntaxhighlight lang="dart" line="1">

			<Form submitLabel="Do the thing Javascript" onSuccess={(submittedValues) => {
			console.log("The name: ", submittedValues.name);
			}}>
			<Input label='Name' name='name' />
			</Form>

			</syntaxhighlight>

	=Input=		=Input=

Luke at 16:23, 8 March 2023

2023-03-08T16:23:10Z

← Older revision		Revision as of 16:23, 8 March 2023
Line 14:		Line 14:
	<Form action="user" submitLabel="Create a user" successMessage="User created!" failureMessage="Unable to create a user now">		<Form action="user" submitLabel="Create a user" successMessage="User created!" failureMessage="Unable to create a user now">
	<Input type="text" name="email" label="Email Address" validate={["Required"]} />		<Input type="text" name="email" label="Email Address" validate={["Required"]} />
	<Input type="password" name="password" label="~~Email Address~~" />		<Input type="password" name="password" label="Password" />
	</Form>		</Form>

	</syntaxhighlight>		</syntaxhighlight>

			The action of a form is the [[Public API\|API endpoint]] that you would like to use. It is prefixed with /v1/ for you automatically. This means if you want to create an [[Entities\|entity]], the action is simply the name of the entity (user, page, locale etc). If you want to edit an entity, the endpoint is the name of the entity followed by a forward slash and its ID:


			<syntaxhighlight lang="dart" line="1">

			import Form from 'UI/Form';
			import Input from 'UI/Input';

			...

			// Edit user #14
			<Form action="user/14" submitLabel="Create a user" successMessage="User created!" failureMessage="Unable to create a user now">
			<Input type="text" name="email" label="Email Address" defaultValue={user.email} validate={["Required"]} />
			<Input type="password" name="password" label="Set a new password" />
			</Form>

			</syntaxhighlight>

			Note that create and edit are often almost identical. It is usually a good idea to make one component which can either create or edit depending on if it is given the object to edit or not.

			Sometimes a custom endpoint will be created such as for logging in. As the action is just an endpoint name then the url of custom endpoints can be used as a form action too, provided it is expecting values to be POSTed to it of course.

	=Input=		=Input=

Luke at 16:16, 8 March 2023

2023-03-08T16:16:25Z

← Older revision		Revision as of 16:16, 8 March 2023
Line 19:		Line 19:
	</syntaxhighlight>		</syntaxhighlight>

			=Input=

			The Input component from UI/Input is just a very thin wrapper over html input with common conveniences built in like a label and validation. It also exists as an extension point as custom Input types can be specified and Input will then route it through to the specified extension.

			<syntaxhighlight lang="dart" line="1">
			<Input type="text" name="email" label="Email Address" validate={["Required"]} />
			</syntaxhighlight>

			==Validation==

			The validate prop provides an array of validation functions. Each function can be an actual js function or a name of a module.

			<syntaxhighlight lang="dart" line="1">
			validate={["Required"]}
			validate={["UI/SomeCustomValidator"]}
			validate={[(value) => {
			// do nothing if the value is valid. Otherwise, return an error object (more on those below).
			if(!value){
			return {
			error: 'EMPTY',
			ui: 'This field is required'
			};
			}
			}]}
			</syntaxhighlight>

			If a string is provided, it will be treated as a module name. If that module name does not contain a forward slash, it will be prefixed with UI/Functions/Validation/. For example, these two are entirely the same:

			<syntaxhighlight lang="dart" line="1">
			validate={["Required"]}
			validate={["UI/Functions/Validation/Required"]}
			</syntaxhighlight>

			As with all module names, the word ThirdParty is ignored. This means you can make use of this shortened form for both thirdparty and firstparty custom validation modules by creating UI/Source/Functions/Validation and putting your custom validation functions in there.

			Validation functions themselves - either inline or from a module - are relatively simple: they should return nothing if the value is valid, and an error object if it is invalid. The error object must specify at least 2 fields - a non-localised error code and a localised message for the UI. Once you publish an error code you must not change it, as it exists for other functions to check for a particular error without needing to awkwardly read potentially localised user facing error messages. Here is the contents of the "Required" validator function:

			<syntaxhighlight lang="js" line="1">
			value => {

			if(!value \|\| (value.trim && value.trim() == '')){
			return {
			error: 'EMPTY', // machine readable, do not translate
			ui: `This field is required` // User readable, translate this. Also supports JSX
			};
			}

			}
			</syntaxhighlight>

	=Props=		=Props=

Luke at 12:41, 1 December 2022

2022-12-01T12:41:45Z

← Older revision		Revision as of 12:41, 1 December 2022
Line 1:		Line 1:
	Forms on websites are critical and often the main piece of user interactivity, so forms in SocialStack are intended to be as flexible as possible, without reinventing too much.		Forms on websites are critical and often the main piece of user interactivity, so forms in SocialStack are intended to be as flexible as possible, without reinventing too much. The Input react component is very commonly used through forms and [[Custom Input Types\|it can also be extended]].

	The <Form> React component is a very thin wrapper over <form> in order to add some common conveniences, such as using the submitForm function instead of the default browser page load form submit.		The <Form> React component is a very thin wrapper over <form> in order to add some common conveniences, such as using the submitForm function instead of the default browser page load form submit.

Luke: /* How form submit works */

2022-09-05T20:43:08Z

How form submit works

← Older revision		Revision as of 20:43, 5 September 2022
Line 79:		Line 79:
	* All the <input> fields inside the form are collected.		* All the <input> fields inside the form are collected.
	* If the input DOM element has an onValidationCheck function on it, it will be called. Note that this is where <Input> checks itself. This function should return true if the validation failed.		* If the input DOM element has an onValidationCheck function on it, it will be called. Note that this is where <Input> checks itself. This function should return true if the validation failed.
	* If the input DOM element has an onGetValue function on it, that function will be called and whatever it returns will be used as the value to submit. onGetValue is very useful if you have a custom input type which needs to map its internal state into some value ready to submit in the form.		* If the input DOM element has an onGetValue function on it, that function will be called and whatever it returns will be used as the value to submit. onGetValue is very useful if you have a custom input type which needs to map its internal state into some value ready to submit in the form. If any onGetValue returns a promise, it will be awaited before continuing.
	* If there were any validation errors, the submit halts and onFailed runs.		* If there were any validation errors, the submit halts and onFailed runs.
	* Otherwise, onValues is given the complete set of all values collected. If onValues returned a promise, it is awaited before the values are then submitted via a webRequest.		* Otherwise, onValues is given the complete set of all values collected. If onValues returned a promise, it is awaited before the values are then submitted via a webRequest.

Luke: /* Props */

2022-08-16T01:16:15Z

Props

← Older revision		Revision as of 01:16, 16 August 2022
Line 41:		Line 41:
	\| none		\| none
	\|-		\|-
	\| ~~failureMessage~~		\| failedMessage
	\| A JSX supporting message which will appear in an error alert when a non 2xx response is received. A common convenience piece.		\| A JSX supporting message which will appear in an error alert when a non 2xx response is received. A common convenience piece.
	\| No		\| No

Luke: /* How form submit works */

2022-08-15T15:24:54Z

How form submit works

← Older revision		Revision as of 15:24, 15 August 2022
Line 76:		Line 76:
	=How form submit works=		=How form submit works=

	* Whenever a form is submitted via any method, submitForm is called.		* Whenever a form is submitted via any method, submitForm is called. This function is from UI/Functions/SubmitForm and can, like all modules, be replaced with a site/ project specific implementation.
	* All the <input> fields inside the form are collected.		* All the <input> fields inside the form are collected.
	* If the input DOM element has an onValidationCheck function on it, it will be called. Note that this is where <Input> checks itself. This function should return true if the validation failed.		* If the input DOM element has an onValidationCheck function on it, it will be called. Note that this is where <Input> checks itself. This function should return true if the validation failed.

Luke: Added promise reject info

2022-07-27T12:43:04Z

Added promise reject info

← Older revision		Revision as of 12:43, 27 July 2022
Line 32:		Line 32:
	\|-		\|-
	\| onValues		\| onValues
	\| This callback function can be used to manipulate what is actually sent to the server. It is given the complete set of field values, and you must return the values that you would like to submit, or a promise which resolves to that. Typically this is just by returning the object you were given, after adding/ changing fields on it.		\| This callback function can be used to manipulate what is actually sent to the server. It is given the complete set of field values, and you must return the values that you would like to submit, or a promise which resolves to that. If you return a promise rejection, the form will display the error - this can be useful for validation particularly where validation depends on multiple field values. Typically this is just by returning the object you were given, after adding/ changing fields on it.
	\| No		\| No
	\| none		\| none