https://github.com/firstclasspostcodes/firstclasspostcodes-js-plugin
🔌This simple to use plugin helps you to get started quickly, allowing you to add postcode lookup to any address form in minutes.
https://github.com/firstclasspostcodes/firstclasspostcodes-js-plugin
javascript svelte umd
Last synced: about 1 year ago
JSON representation
🔌This simple to use plugin helps you to get started quickly, allowing you to add postcode lookup to any address form in minutes.
- Host: GitHub
- URL: https://github.com/firstclasspostcodes/firstclasspostcodes-js-plugin
- Owner: firstclasspostcodes
- Created: 2019-12-20T12:59:58.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2021-02-19T07:25:26.000Z (about 5 years ago)
- Last Synced: 2025-03-17T22:56:26.623Z (about 1 year ago)
- Topics: javascript, svelte, umd
- Language: JavaScript
- Homepage:
- Size: 2.88 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
[//]: # "NOTE: The URL for the JS library is automatically updated by semantic-release."
# Firstclasspostcodes
 [](https://dashboard.cypress.io/projects/hu4kvr/runs)
Our browser plugin is compatible with all modern browsers and IE9+ _(polyfills required)_.
This simple to use plugin helps you to get started quickly, allowing you to add postcode lookup to any address form in minutes.
> **Note:** Are you looking for the [Svelte](https://svelte.dev) documentation? [See here](/NPM.md)
## Documentation
See [@firstclasspostcodes/plugin](https://docs.firstclasspostcodes.com/js/plugin) for detailed usage, guides and examples.
## Installation
Add the plugin directly into your HTML with:
```html
```
**Note on older browsers:** You will need to use a polyfill service, the following example covers all of the required language features:
```html
```
### Add the client library
We do not bundle the client library with the plugin, so you will need to add a separate script tag to require the JS client:
```html
```
All JS library versions are available on the [@firstclasspostcodes/js](https://github.com/firstclasspostcodes/firstclasspostcodes-js/releases) releases page.
### Security
Where the libary is loaded on pages including sensitive information, we recommend using the [Subresource Integrity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) security feature.
Every version of the library is accompanied by an SRI hash file, the hash can be accessed directly using:
```sh
$ curl https://js.firstclasspostcodes.com/plugin/v2.3.1.sri.txt # => "sha256-45tfd... sha384-43567ytr..."
```
You can then update the above `` tag, adding the integrity attribute:
```html
<script src="https://js.firstclasspostcodes.com/plugin/v2.3.1.js"
integrity="sha256-45tfd... sha384-43567ytr..."
crossorigin="anonymous">
```
## Usage
You need to configure the plugin to use your API Key which is available on your [dashboard](https://dashboard.firstclasspostcodes.com/key). Below is a minimal working setup, you can see more guides on how to better customise the plugin by [viewing the documentation](https://docs.firstclasspostcodes.com/js/plugin).
```html
Address Line 1
Address Line 2
County
City
Postcode
FirstclasspostcodesPlugin(
document.getElementById('postcode-lookup-form'),
{
apiKey: '111111111111',
},
);
```
## Configuration
The plugin can be initialized with the same configuration overrides that you can supply for the [@firstclasspostcodes/js](https://github.com/firstclasspostcodes/firstclasspostcodes-js#configuration) library using the `apiOverrides` property (an example of its usage is below).
If you're running the [mock service](https://github.com/firstclasspostcodes/firstclasspostcodes-mock) docker container. You can configure the plugin to talk to it using the example below:
```html
FirstclasspostcodesPlugin(
document.getElementById('postcode-lookup-form'),
{
apiKey: '111111111111',
apiOverrides: {
endpoint: 'http://localhost:2345',
}
}
);
```
## Events
Whilst not necessarily required, if you need to listen to events happening we support attaching event handlers for the following:
| Event Name | Description |
|:-------|:--------|
| `address` | Fired when an address is selected from the drop down. Contains the address detail. |
Events are fired using the [CustomEvent](https://developer.mozilla.org/en/docs/Web/API/CustomEvent) class. Event properties are included inside the `.detail` property.
Event handlers can be attached using the following:
```html
var plugin = FirstclasspostcodesPlugin(...);
plugin.$on('address', (event) => {
console.log(event.detail);
});
```
## Plugin
Our plugin is built using [Svelte](https://svelte.dev) and an instantiated component is returned from the `FirstclasspostcodesPlugin()` function. Therefore, the returned object is compatible with the documented [Client-side component API](https://svelte.dev/docs#Client-side_component_API).