Share Form

GitHub Source Link @nycopportunity/standard/src/components/share-form

Demonstration
Come back to it later

We can send you a link to this page to help you get back to it when you're ready.

Code

The Share Form enables a user to text or email themselves a link to a web page. It uses JavaScript to post the form data to an endpoint that can pass the data to a email to text messaging service. The Share Form also uses the Disclaimer Toggle to show or hide disclaimer based on the visibility of either form input. The disclaimer provides informed consent as to how the data submitted in the form may or may not be used.

The Share Form exposes text messaging and email sharing directly in the interface. It is useful for sharing timely and important information as well as collecting contact information for outreach.

The Web Share form can be used in place of the Share Form to enabling users to open a native dialog for sharing URLs on the platform of their choice. The Web Share doesn’t require a backend service for emailing or text messaging. However, information from the Web Share can’t be collected for outreach.

Usage Anchor Link Usage

Global Script

The Share Form requires JavaScript for showing and hiding the form input and disclaimer, for form validation, input masking, and submitting the form to an endpoint backend processing. To initialize the Share Form and Disclaimer instances from the global script use the following code:

<!-- Global Script -->
<script src="https://cdn.jsdelivr.net/gh/nycopportunity/standard@v0.0.20/dist/js/default.js"></script>

<script>
  var Standard = new Default();

  Standard.disclaimer();
  Standard.shareForm();
  Standard.masks();
</script>

This will attach event listeners for toggling the form and disclaimer open and form validation and submission.

Module Import

For module imports, import the mask utility, Disclaimer and Share Form modules from the source. You must pass a DOM selection of each Share Form to a new instance of the class. A selector reference is stored in the class.

import MaskPhone from '@nycopportunity/standard/src/utilities/mask/mask-phone.js';
import Disclaimer from '@nycopportunity/standard/src/components/disclaimer/disclaimer';
import ShareForm from '@nycopportunity/standard/src/components/share-form/share-form';

new MaskPhone();
new Disclaimer();

let elements = document.querySelectorAll(ShareForm.selector);

elements.forEach(element => {
  new ShareForm(element);
});
Submit method

When submitted, the script will post the form data to the URL endpoint in the form action attribute. Below is an example of the data submitted by the text message form;

{
  'action': 'sms_send'
  'url': '{{ MY_URL }}'
  'hash': '{{ MY_HASH }}'
  'GUID': '{{ MY_GUID }}'
  'to': '{{ PHONE_NUMBER or EMAIL_ADDRESS }}'
  'lang': 'en'
}

The body can be modified to meet the needs of the application. The endpoint will need to be set up on the server side to direct the request to the email or SMS service of choice.

ACCESS NYC uses the Amazon SES service to send emails and the Twilio service to send text messages.

Response

The proxy service should respond with a JSON object to indicate success or failure of the response.

{
  'success': true
}
Localization

Strings (and other properties) can be passed in an object {} to the Share Form for localization. View the source link at the top of this page for defaults.

let element = document.querySelector(ShareForm.selector);

let shareForm = new ShareForm(element);

shareForm.strings = {
  {{ MY_CUSTOM_STRINGS }}
};