{"id":19178994,"url":"https://github.com/magicbruno/mb_pseudo_form","last_synced_at":"2025-02-23T01:26:21.735Z","repository":{"id":58973194,"uuid":"530164153","full_name":"magicbruno/MB_pseudo_form","owner":"magicbruno","description":null,"archived":false,"fork":false,"pushed_at":"2023-04-06T07:53:52.000Z","size":573,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-02-14T17:42:00.200Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/magicbruno.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-08-29T10:10:38.000Z","updated_at":"2024-02-14T17:42:00.201Z","dependencies_parsed_at":"2024-11-09T10:41:49.935Z","dependency_job_id":"59558847-cd4b-41b7-b824-27cc0325e3a8","html_url":"https://github.com/magicbruno/MB_pseudo_form","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":"magicbruno/Interceptor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magicbruno%2FMB_pseudo_form","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magicbruno%2FMB_pseudo_form/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magicbruno%2FMB_pseudo_form/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magicbruno%2FMB_pseudo_form/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/magicbruno","download_url":"https://codeload.github.com/magicbruno/MB_pseudo_form/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240256053,"owners_count":19772724,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-09T10:41:42.543Z","updated_at":"2025-02-23T01:26:21.716Z","avatar_url":"https://github.com/magicbruno.png","language":"JavaScript","readme":"# MB_PseudoForm\nMb_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\".\n\nMb_PseudForm can be useful:\n\n- in all situations when you want to send the user's input to the server without unloading the page.\n- 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)\n\n`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. \n\nThe 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.\n\n## Getting started\n`MB_PseudoForm` can be loaded directly from CDN,\n```\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/@magicbruno/mb_pseudoform@1.0.0/dist/MB_PseudoForm.min.js\"\u003e\u003c/script\u003e\n\n```\ninstalled via NPM,\n```\nnpm install @magicbruno/mb_pseudoform@1.0.0\n```\nor you can clone the GitHub repository: \n```\ngit clone https://github.com/magicbruno/MB_PseudoForm.git\n```\n\n## How does it work\nA pseudo form is an HTML element (for example a `div` element) that contains `input`, `select` and `textarea` elements and at least one clickable element (`\u003cButton\u003e` or `\u003ca\u003e`) which will submit the data.\n\nMinimum conditions because an HTML element becomes a pseudo form are:\n- that the handler intended to receive data server-side is defined using the `data-mb-action` attribute to be applied to the element itself\n- that the element contains a * Submit Button * defined by assigning to an element `\u003cButton\u003e` or to an element `\u003ca\u003e` the attribute `data-mb-toggle=\"submit `.\n\n\n```\n\u003cdiv id=\"sample1-en\" data-mb-action=\"api/PseudoForm\"\u003e\n  \u003c!-- Input fields --\u003e\n  \u003cbutton type=\"button\" data-mb-toggle=\"submit\"\u003eInvia dati\u003c/button\u003e\n\u003c/div\u003e\n```\n### Initialization\n\nYou can activate the pseudo form via javascript (`pform` can be a CSS selector or an HTML element)\n```\nconst myPseudoForm = new MB_PseudoForm(pForm) ;\n```\nor simply by assigning the attribute `data-mb-ride=\"pseudo-form\"` to the element.\n\n```\n\u003cdiv id=\"sample1-en\" data-mb-action=\"api/PseudoForm\" data-mb-ride=\"pseudo-form\"\u003e\n  \u003c!-- Input fields --\u003e\n  \u003cbutton type=\"button\" data-mb-toggle=\"submit\"\u003eInvia dati\u003c/button\u003e\n\u003c/div\u003e\n```\n## Properties and methods\n\nIt 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.\n\nMB_PseudoForm is based on three Javascript classes:\n- `MB_PseudoForm`, the main class\n- `MB_PseudoFormValue` which defines the object in which the user's entered fields are transformed for sending the server\n- `ValuesList` which provides some methods to manage a list of `MB_PseudoFormValue` \n\n### MB_PseudoFormValue\nMB_PseudoFormValue provides 5 properties that reflect the characteristics and value of the fields compiled by the user.\n\n|Property | Type | Description |\n|---|---|---|\n|`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.|\n|`Type`|`string`|Reflects the content of the property `type`  of the element.|\n|`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.|\n|`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`|\n|`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)|\n\nThe 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. \n\n### ValuesList\nThe 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.\n\nThe `ValueList` class exposes only one property, `length` (which returns the length of the list) and offers some methods that help to manage it.\n\n| Method | Type returned | Description |\n|---|---|---|\n|`item(i)`|`MB_PseudoFormValue`|**Parameter**: *i* `number`. Returns the  `MB_PseudoFormValue` object with index *i*|\n|`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.|\n|`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.|\n|`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`.|\n|`getValue(name)`|`any`|**Parameter**: *name* `string`. Search the list with the object with `Name` = *name*. If found, returns it's `Value`, otherwise `null`.|\n|`clear()`|`none`|Clear the list|\n\n### MB_PseudoForm\n\u003eIn 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.  \n\n#### **Properties**\n| Property | Type | Description |\n|---|---|---|\n|`pseudoForm`|`HTML element`|Readonly property. Returns the HTML element on which the pseudo form was built.|\n|`submit`|`HTML element`|Readonly property. Returns the HTML element that is used as *Submit Button*|\n|`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](https://developer.mozilla.org/en-US/docs/Web/API/NodeList).|\n|`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.|\n\n#### **Methods**\n| Method | Type returned | Description |\n|---|---|---|\n|`collectData`|`Promise`|Asynchronous method. The Promise returned resolves the list of values entered by the user as a `ValueList`. |\n|`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.|\n\n#### **Events**\nAll 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:\n\n```\n\u003cdiv id=\"sample1-en\" data-mb-action=\"api/PseudoForm\" data-mb-ride=\"pseudo-form\"\u003e\n  \u003c!-- Input fields --\u003e\n  \u003cbutton type=\"button\" data-mb-toggle=\"submit\"\u003eInvia dati\u003c/button\u003e\n\u003c/div\u003e\n....\n\u003cscript\u003e\n  const myForm = document.getElementById(\"sample1-en\");\n  myForm.addEventListener('validate.mb.pseudoform', event =\u003e {\n    const values = event.detail;\n    // .......\n  })\n\u003c/script\u003e\n```\n| Event | Description |\n|---|---|\n|`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. |\n|`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|\n|`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).|\n\n## Demo\nIn 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.\n\n### Using the demo\nClone the GIT repository on your computer\n```\ngit clone https://github.com/magicbruno/MB_PseudoForm.git\n```\nor [download it](https://github.com/magicbruno/MB_pseudo_form/archive/refs/heads/main.zip).\n\nOpen `/demo/demo.sln` in Visual Studio.\n\nBefore running the application you must configure the SMTP server that the controller will use to send the generated email messages.\n\nOpen `Web.config` in **Visual Studio** editor and in the `appSettings` section enter the data:\n```\n\t\u003cappSettings\u003e\n    \u003c!-- Enter URL of the smtp server --\u003e\n\t\t\u003cadd key=\"SmtpServer\" value=\"...\"/\u003e\n    \u003c!-- Insert smtp credentials --\u003e\n\t\t\u003cadd key=\"SmtpUsername\" value=\"...\"/\u003e\n\t\t\u003cadd key=\"SmtpPassword\" value=\"...\"/\u003e\n    \u003c!-- Change the SSL settings if necessary --\u003e\n\t\t\u003cadd key=\"SmtpPort\" value=\"25\"/\u003e\n\t\t\u003cadd key=\"SmtpUseSSL\" value=\"false\"/\u003e\n    \u003c!-- Sender of the messages sent by the server --\u003e\n\t\t\u003cadd key=\"DefaultSmtpFromMail\" value=\"...\"/\u003e\n    \u003c!-- Staff mailbox --\u003e\n\t\t\u003cadd key=\"MailTo\" value=\"...\"/\u003e\n\t\u003c/appSettings\u003e\n```\nThen launch the application in Iis Express by pressing \u003ckbd\u003ef5\u003c/kbd\u003e o \u003ckbd\u003ectrl\u003c/kbd\u003e + \u003ckbd\u003ef5\u003c/kbd\u003e.\n\n\u003e ## Note\n\u003e To use the API controller `/ApiControllers/PseudoFormController.cs` in your project you could have to install the package [Microsoft.AspNet.WebApi](https://www.nuget.org/packages/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](https://docs.microsoft.com/en-us/aspnet/web-api/).\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmagicbruno%2Fmb_pseudo_form","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmagicbruno%2Fmb_pseudo_form","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmagicbruno%2Fmb_pseudo_form/lists"}