smartforms.js

This is the official front-end JavaScript library for Fifth Ocean's SmartForms.

Usually direct use of this library is not required, because there should be a plugin available for your content management system or JavaScript framework, which does all the hard work for you. Nonetheless, it is available for use in custom integrations.

It includes the following bundles:

| Component | File Name | Description | |-----------|-----------|-------------| | HTML5/JavaScript | smartforms.min.js | Provides a function for browsers to load SmartForms: smartformsInit. Can be embedded directly on static web pages. | | Vue.js | vue.js | A SmartForm component for Vue.js v2. Can be installed from npm and imported as smartforms/vue. | React.js | react.js | A SmartForm component for React. Can be installed from npm and imported as smartforms/react. | API | api.js | An API intended for use from Node.js applications (primarily for generating signed requests for frontends)

Usage

General Instructions

To use SmartForms on a web page, you will need 3 items:

• Your realm (this refers to which region your SmartForms account is kept in.) You can get this from your SmartForms Account Management or SmartForms Admin Console (it will be au.smartfor.ms or north.smartfor.ms or something like that).
• Your INITIATOR_ID (this refers to the specific form mode and campaign you want to display on the web page). You can get this from the SmartForms Admin Console.
• A signedRequest (this authenticates the visitor to your form). You can get this from the SmartForms Admin Console.

None of these values are sensitive.

To install this package into a HTML/Node project:

npm install smartforms --save

Using HTML5/JavaScript

The script (located in ./node_modules/smartforms/smartforms.min.js) exports a function to the window object: window.smartformsInit and is intended to be embedded directly on your web page (not an external script).

The script expects markup to be present on the page in the following way:

<!-- Substitute INITIATOR_ID with your real initiator ID -->
<iframe name="INITIATOR_ID" id="INITIATOR_ID" frameborder="0" height="400px" style="opacity: 0; border: none; overflow-x: hidden; width: 100%; max-height: 400px; transition: max-height 0.5s, opacity 0.5s;"></iframe>

The iframe is where the form facility will be displayed. Don't worry about the CSS - the script will handle resizing it for you.

In any place in the document below this form, include the following:

<script type="text/javascript">
/* Insert the contents of smartforms.min.js */
// ...

/* And then initialize the form */
// Make sure to replace:
// - INITIATOR_ID     (usually a UUID)
// - realm            (e.g. au.smartfor.ms)
// - signedRequest    (a long string)
window.smartformsInit({ initiator: 'INITIATOR_ID', realm: 'https://' + 'realm', request: 'signedRequest'  });
</script>

and you're all done! An example HTML file that implements this method can be found in the examples/smartforms-html5 directory.

Using Vue

The basic usage of the Vue component is as follows:

<template>
  <div>
    <SmartForm initiator="INITIATOR_ID" realm="realm" request="signedRequest" />
  </div>
</template>

<script>
import SmartForm from 'smartforms/vue'

export default {
  components: {
    SmartForm
  }
}
</script>

and you're all done! An example Vue project that implements this method can be found in the examples/smartforms-vue directory.

Using React

The basic usage of the React component (using JSX) is as follows:

import SmartForm from 'smartforms/react'

const form = (initiator, realm, signedRequest) => (
    <SmartForm initiator={initiator} realm={realm} request={signedRequest} />
);

An example React project that implements this method can be found in the examples/smartforms-react directory.

Using API

The API package provides the ability to create signatures (the signedRequest) from Node.js web applications, which can then be consumed by frontends (such as HTML5, Vue or React).

An example usage is as follows:

const api = require('smartforms/api')

const signedRequest = api.createRequest({
  clientId: 'your-smartforms-client-id',
  secret: 'your-smartforms-client-secret',
  viewMode: api.ViewMode.Form,
  initiatorId: '1234-1234',
  origin: 'https://site.where.you.embed.the.form',
  user_id: 'identifier-of-the-user-browsing-your-site'
})

Keep the secret secret! The signedRequest, INITIATOR_ID and realm is all you need to expose to the browser.

You may also pass additional options:

| Option | Description | Example | |--------|-------------|---------| | admin | Whether the visitor should have access to administrative facilities | false (default) | | roles | A list of roles that the user has | ['Admin','User']| | portal_data | CMS specific parameters that can be accessed from within forms | { "portal.user.email": "[email protected]" } | | session_data | Session parameters that can be accessed from within forms | { "attribute-name": "attribute-value" } | | request_data | Intended for HTTP request parameters that can be accessed from within forms | { "a": "b" } | | expiresSeconds | How many seconds should this request be valid for | 300 (default) |

Development

npm run build

License

The MIT License

Copyright 2018 Fifth Ocean Technologies Pty Ltd

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.