@what3words/javascript-components

What3words Javascript SDK

The what3words javascript sdk extends the JS API and builds custom web components for use in static HTML documents, Angular, ReactJS, Vue and Elm (coming soon).

This project includes:

• Autosuggest Component
• Address Component
• Symbol Component

This is a starter project for building a standalone Web Component using Stencil

Development

Contributing to this project

To contribute to this project, you should create a branch off master and apply your changes there. Before committing and push those changes to the remote repository, you need to bump the version for the SDK in the package.json in this directory, then commit and push. Once this has been pushed, CI should pick up your branch and run the tests on your branch. You should also open a PR so your work can be reviewed by at least one reviewer before merging back to master. Once reviewed and built successfully in CI then you can merge your PR and this will publish your changes against the version you tagged earlier in package.json

We encourage the use of npm run lint and npm run lint:fix commands before committing your work. npm run lint is run as part of the CI build workflow so this will need to pass for your build to pass CI.

Dev server

To start the local dev server, run:

npm start

This will run a local dev server accessible at: http://localhost:8080 and accepts the following query parameters to configure the how to render the component and attributes to pass to the SDK.

Script Tag Parameters

To provide query string parameters to the <script> tag in the dev server pass the follow query string parameters to the dev server page once it is running:

• key=<API_KEY> This will provide the API Key to the SDK in the <script>
• callback=<NAME> This will provide a callback name for the SDK to call once the script loads. You should attach this function to the global window for this to actually call your script.
• baseUrl=<URL> The base url to pass to the SDK to call autosuggest endpoint at. (Useful for mocking in tests or pointing to a different environment.)
• headers=<STRINGIFIED_JSON> You can set headers that the SDK will pass to the backend autosuggest API when making requests against the API. (This is useful for tracking purposes or providing specialised agents, for example)

Navigating to http://localhost:8080?key=API_KEY&callback=NAME&baseUrl=URL&headers={"custom-header":"foo"} will set the above script tag parameters.

Autosuggest Component Attributes

To pass attributes key/value pairs to the autosuggest component on the dev server page, you can pass the attribute name prefixed with the component attribute prefix. The prefix defaults to comp_ so if, for example you wanted to add the initial-value attribute to the component, you would provide the query paramter comp_initial-value=<INITIAL_VALUE>. You can change the prefix using the query parameter:

• componentPrefix=<PREFX> (default is comp_) This will change the prefix for any component attributes.
• comp_<ATTRIBUTE>=<VALUE> This will set the attribute <ATTRIBUTE> on the autosuggest component with value <VALUE>. (This assumes that the prefix has not been changed otherwise you should change comp_ for the <PREFIX> you set it to.)

Custom HTML Input

If you want to have a custom HTML input being wrapped around by the <what3words-autosuggest /> custom component tag, you must first enable this behaviour using the query parameter:

• customInput=true

You can also provide attributes to the input similarly to the autosuggest component attributes above by providing the attribute with the inputPrefix prefixing the attribute key/value pair. For example to set the id and name attributes on the custom input you would do provide the query parameters input_id=my-id&input_name=my-form-elem. You can also change the prefix if you wish by providing the following query paramter:

• inputPrefix=<PREFIX> (default is input_) This will change the prefix for any input attributes.
• input_<ATTRIBUTE>=<VALUE> This will set the attribute <ATTRIBUTE> on the input element with value <VALUE>. (This assumes that the prefix has not been changed otherwise you should change input_ for the <PREFIX> you set it to.)

N.B. - The custom input only works if you have not disabled the autosuggest component.

Disable Autosuggest Component

If you want to disable the Autosuggest component tag, so that the page does not add it at all and just adds the SDK which is accessible via window.what3words then you can provide the following query paramter to disable to the component:

• disableAutosuggest=true

Artifacts

To compile the distributable artifacts for the javascript SDK, run:

npm i
npm run compile

This will create a dist/, loader/, s3/ and www/ directories. The www/ directory can for the most part, be ignored, unless you are running the local dev server as mentioned above.

• The s3/ and dist/ directories are published to the artifacts S3 bucket.
• The dist/ and loader/ directories are published to NPM for @what3words/core.

Testing

Unit Tests

To run the unit tests for the SDK, run

npm i
npm t

E2E Tests

To run the e2e tests for the SDK, you must first have a dev server running locally, see above. Then when that is running, start either Cypress or Percy and Cypress with one of:

## Run/Open Cypress Tests
npm run cypress:run
npm run cypress:open

## Run/Open Cypress Tests with Percy
npm run percy:run
npm run percy:open