MB_PseudoForm

Mb_PseudoForm allows you to organize input, select and textarea elements in a container (typically a DIV element) and to send data entered by the user to a server using an "Ajax Request".

Mb_PseudForm can be useful:

in all situations when you want to send the user's input to the server without unloading the page.
in particular if you want to create entry modules in a WebForm ASP.NET application without using the Asp form (see the example in the demo folder)

Mb_PseudForm sends data in the form as a list of objects. This allows you to build generic handlers server side, independent of the structure of the input module to elaborate.

The attached demo is a WebForm ASP.NET application where an API Controller transforms any group of data entered by the user into a formatted email that is sent to the site staff.

Getting started

MB_PseudoForm can be loaded directly from CDN,

<script src="https://cdn.jsdelivr.net/npm/@magicbruno/mb_pseudoform@1.0.0/dist/MB_PseudoForm.min.js"></script>

installed via NPM,

npm install @magicbruno/mb_pseudoform@1.0.0

or you can clone the GitHub repository:

git clone https://github.com/magicbruno/MB_PseudoForm.git

How does it work

A pseudo form is an HTML element (for example a div element) that contains input, select and textarea elements and at least one clickable element (<Button> or <a>) which will submit the data.

Minimum conditions because an HTML element becomes a pseudo form are:

that the handler intended to receive data server-side is defined using the data-mb-action attribute to be applied to the element itself
that the element contains a * Submit Button * defined by assigning to an element <Button> or to an element <a> the attribute data-mb-toggle="submit .

<div id="sample1-en" data-mb-action="api/PseudoForm">
  <!-- Input fields -->
  <button type="button" data-mb-toggle="submit">Invia dati</button>
</div>

Initialization

You can activate the pseudo form via javascript (pform can be a CSS selector or an HTML element)

const myPseudoForm = new MB_PseudoForm(pForm) ;

or simply by assigning the attribute data-mb-ride="pseudo-form" to the element.

<div id="sample1-en" data-mb-action="api/PseudoForm" data-mb-ride="pseudo-form">
  <!-- Input fields -->
  <button type="button" data-mb-toggle="submit">Invia dati</button>
</div>

Properties and methods

It could be useful to illustrate how the pseudo form works. For more details, we recommend examining the code directly. It's clear and fully commented.

MB_PseudoForm is based on three Javascript classes:

MB_PseudoForm, the main class
MB_PseudoFormValue which defines the object in which the user's entered fields are transformed for sending the server
ValuesList which provides some methods to manage a list of MB_PseudoFormValue

MB_PseudoFormValue

MB_PseudoFormValue provides 5 properties that reflect the characteristics and value of the fields compiled by the user.

Property	Type	Description
`Name`	`string`	Reflects the content of the attribute `name` of the element. If the `name` attribute is not present, the `id` attribute will be used.
`Type`	`string`	Reflects the content of the property `type` of the element.
`Value`	`any`	If the element is a `checkbox`, it's' `true` if selected, otherwise `false`. If the element is an input of type `file`, `Value` is the content of the file coded as DataUrlBase64. In other cases it reflects the content of the property `value` of the element.
`Label`	`string`	Reflects the content of the attribute `aria-label` of the element. If the attribute is not present it returns the same value that `Name`
`Detail`	`string`	If the element is an input of type `file`, it returns the original file name. In other cases it can be used to transfer to the server additional information on that field (see demo)

The the pseudo form fields are transformed into MB_PseudoFormValue objects using the asynchronous static method MB_Pseudoformvalue.CreateAsync which returns a Promise that resolves with the created object.

ValuesList

The value returned by the MB_PseudoForm.collectData method (see below), which collects the fields compiled by the user as a list of MB_PseudoFormValue objects is an instance of the ValueList class.

The ValueList class exposes only one property, length (which returns the length of the list) and offers some methods that help to manage it.

Method	Type returned	Description
`item(i)`	`MB_PseudoFormValue`	Parameter: i `number`. Returns the `MB_PseudoFormValue` object with index i
`push(obj)`	`number`	Parameter: obj `MB_PseudoFormValue`. Add a `MB_PseudoFormValue` object to the list. If there is already an object with the same `Name`, the present object is replaced by the one inserted. Returns the new length of the list.
`remove(name)`	`boolean`	Parameter: name `string`. Removes the object with `Name` = name from the list. It returns `true` if the object has been removed `false` if it has not been found on the list.
`indexOf(name)`	`number`	Parameter: name `string`. Search the list with the object with `Name` = name. If object is found, it returns its index otherwise `-1`.
`getValue(name)`	`any`	Parameter: name `string`. Search the list with the object with `Name` = name. If found, returns it's `Value`, otherwise `null`.
`clear()`	`none`	Clear the list

MB_PseudoForm

In general, it should not be necessary to directly access the properties and methods of MB_PseudoForm. The interface with the pseudo form is guaranteed by the events (change.mb.pseudoform, validate.mb.pseudoform e submitted.mb.pseudoform) which are dispatched in the key moments of the process.

Properties

Property	Type	Description
`pseudoForm`	`HTML element`	Readonly property. Returns the HTML element on which the pseudo form was built.
`submit`	`HTML element`	Readonly property. Returns the HTML element that is used as Submit Button
`inputs`	`static NodeList`	Readonly property. Returns the list of elements (`input`, `select` e `textarea`) which are part of the pseudo form as a static NodeList.
`pendingChanges`	`boolean`	It returns `true` if at least one input element has been changed. It is automatically reset when the data is sent to the server. It can be reset (set to `false`) also programmatically.

Methods

Method	Type returned	Description
`collectData`	`Promise`	Asynchronous method. The Promise returned resolves the list of values entered by the user as a `ValueList`.
`submitData`	none	It allows you to programmatically send the pseudo form to the server. It dispatches a `validate.mb.pseudoform` event (cancelable) immediately before sending data and a `submitted.mb.pseudoform` event immediately after receiving the response from the server.

Events

All events are sent to the HTML element on which the pseudo form is built. To manage them, therefore, just add an event listener to the element itself:

<div id="sample1-en" data-mb-action="api/PseudoForm" data-mb-ride="pseudo-form">
  <!-- Input fields -->
  <button type="button" data-mb-toggle="submit">Invia dati</button>
</div>
....
<script>
  const myForm = document.getElementById("sample1-en");
  myForm.addEventListener('validate.mb.pseudoform', event => {
    const values = event.detail;
    // .......
  })
</script>

Event	Description
`change.mb.pseudoform`	It is dispatched every time a pseudo form field is modified. The `detail` property of the event contains the HTML element whose `value` has been modified.
`validate.mb.pseudoform`	It is dispatched immediately before the data is sent to the server.The detail property of the event contains the `ValueList` which is about to be sent. It allows you to validate the data before sending. To extract information on specific fields, the `ValueList` class methods can be applied to the list. To cancel sending process, apply the `preventDefault` method to the event
`submitted.mb.pseudoform`	It is issued after the data is sent and either you have received the response from the server, or an error occurs. In the case of response from the server, the `detail` event property contains the response, in case of error contains an object with four properties: `Success` (`Boolean`, set to `false`), `Message` (`string`, contains the error message), `Exitcode` and `Data` currently not used (see demo for live example).

Demo

In the demo folder of the project you will find a simple ASP.NET Web Application that shows how to use MB_PseudoForm together with an API controller to generate, starting from a MB_PseudoForm, a formatted email with the information inserted by the user to send to the site staff and a thanksgiving email sent to the user himself.

Using the demo

Clone the GIT repository on your computer

git clone https://github.com/magicbruno/MB_PseudoForm.git

or download it.

Open /demo/demo.sln in Visual Studio.

Before running the application you must configure the SMTP server that the controller will use to send the generated email messages.

Open Web.config in Visual Studio editor and in the appSettings section enter the data:

    <appSettings>
    <!-- Enter URL of the smtp server -->
        <add key="SmtpServer" value="..."/>
    <!-- Insert smtp credentials -->
        <add key="SmtpUsername" value="..."/>
        <add key="SmtpPassword" value="..."/>
    <!-- Change the SSL settings if necessary -->
        <add key="SmtpPort" value="25"/>
        <add key="SmtpUseSSL" value="false"/>
    <!-- Sender of the messages sent by the server -->
        <add key="DefaultSmtpFromMail" value="..."/>
    <!-- Staff mailbox -->
        <add key="MailTo" value="..."/>
    </appSettings>

Then launch the application in Iis Express by pressing f5 o ctrl + f5.

Note

To use the API controller /ApiControllers/PseudoFormController.cs in your project you could have to install the package Microsoft.AspNet.WebApi. You must also add the classes /ApiControllers/ApiControllerResponse.cs and /ApiControllers/PseudoFormModel.cs to the project. More information about ASP.NET Web Api here.