Cronofy UI Elements

A suite of embeddable components that access the Cronofy API.

Full documentation can be found here: docs.cronofy.com/developers/ui-elements

Information about installing via npm can be found here: npm.README.md

Developer documentation

To setup the development environment, run:

make init

This package is wrapped up into a single file in the dist folder - this enables us to use any version of the related npm packages and this will not leak outside of the scope of this module. The elements provided can be dropped into a page via an old-fashioned <script> tag or imported as a node module.

Environment setup

You will need to ensure /src/js/env.js is updated with your local development settings. See /src/js/env.example.js for an example of this.

To get the Client ID and Client Secret you can go to your OAuth Client on: https://local.cronofy.com/oauth/applications/{uuid}/dashboard where you will find the Client ID and Client secret.

If you don't have an account sub authorized to your application you can connect one using postman, please follow this guide or the public docs to learn how to authorise with postman.

Make sure to Get New Access Token and authorise your chosen method (for example, authorise your Google account via individual connect). Once you get this access token:

• You can send a GET request to {API}/v1/userinfo endpoint, this will return the sub
• Copy the sub and paste it into the env.js file

Once this is all added, you should see Authorizations within the https://local.cronofy.com/oauth/applications/{uuid}/dashboard page and you should see your email address and related sub. Alternatively, if the Authorizations section does not show up, you can search the authorization with the email address in the https://local.cronofy.com/oauth/applications/{uuid}/support/authorizations

Development

To start development, run:

make dev

If using powprox for local API hosting (our default) you can set an environment variable to tell Node about a custom root CA in your .bash_profile or equivalent:

export NODE_EXTRA_CA_CERTS="$HOME/.powprox/ssl/ca/pow-root-ca.crt"

Alternatively, though not recommended, you can disable all TLS verification:

NODE_TLS_REJECT_UNAUTHORIZED=0 make dev

This will watch the source files and rebuild whenever you save changes. It will also host the demo app (demo/index.ejs) on port 8080

You can make a one-off development build (without watching the files or serving the demo) using:

make build_dev

You can make a production build with:

make build

Compat mode

If you are testing compat mode you may need to build the compatible dist file:

make dev_compat or yarn build_dev_compat

Testing

You can run tests with yarn

yarn test

You can watch tests with

yarn test:watch

And you can see the test coverage with

yarn test:coverage

Releasing

Scripts

To bump a patch version (e.g. from 0.0.1 to 0.0.2) and make a production build, run:

bump_patch

To bump a minor version (e.g. from 0.1.0 to 0.2.0) and make a production build, run:

bump_minor

To bump a major version (e.g. from 1.0.0 to 2.0.0) and make a production build, run:

bump_major

How to

Once you've got a feature branch which has been PR'ed and approved, do the following on the feature branch:

💡 Be sure to have your branch is up to date with master. This is to be sure that when running the following steps, it won't bump the version to an incorrect number

• cd js/elements

• Run make bump_patch , make bump_minor or make bump_major based on the type of release

• Commit the package.json change: git add .; git commit -m"Bump to v<version>"

• Create an annotated tag: git tag -a v<version> -m "summary of changes"

• Push! git push && git push --tags

• Merge the PR

• Go to the monorepos Github Actions and trigger "Elements release": https://github.com/cronofy/cronofy/actions/workflows/elements_release.yml This will build a fresh artifact, push it to S3 and update NPM. There can be a delay before the version shows up on NPM: https://www.npmjs.com/package/cronofy-elements

• Once the version shows up on NPM, add a new entry to the elements_changelog.json and update the version number for elementsVersion in config.json in the Docs project to announce it to the world!

Things that need to be published in order to call a UI Element change "done"

• new build file added to S3 bucket (so that it shows up at this URL: https://elements.cronofy.com/js/CronofyElements.vNEW_VERSION_NUMBER.js)
• publish changes to NPM (checkable here: https://www.npmjs.com/package/cronofy-elements)
• Add changes to docs if user-facing API has changed
• Update v# and changelog in the docs (only do this after the S3 URL is available)