ARCHIVED - Development Kit for Custom Elements in Kentico Cloud

⚠️

Archive Notice

This repository is no longer being maintained for compatibility with the latest version of the product. Examples in this repository refer to the previous product name, Kentico Cloud, rather than the new product name, Kentico Kontent.

This repository contains several custom content elements for the Kentico Cloud platform.

If you want more information on Kentico Cloud, head here, or contact us via email.

If you're familiar with the CMS, but would like to know more about custom elements, you might find this interesting.

How to use this repository

Scripts

npm start will start the server script in default configuration. For more info about configuration run npm start -- --help (For npm wants the argument vector for the command it's running after --.)

npm run start-watcher will start the node server and a compiler watching for changes in the files compiled for the client-side. This is useful when you're trying to create or debug your custom elements.

If you leave this running on a publicly accessible server, you'll be able to use all the elements served by the server in the cloud. The URL is in this format: <the root to your instance>/custom-elements/<element name>. However this is not recommended for security reasons.

What <element name> stands for is dealt with below, read on.

npm run tslint is here to give a bit of culture to the code and avoid unnecessary mistakes.

npm run typecheck is here to simply check for type errors when you're ready to do so.

npm run typewatch is your friend, when you want to have the type-check result ready all the time.

Adding custom elements

Put very simply, just follow the example. The "sheets" elements was the first one here and it serves as a reference.

Step by step:

1. Create a folder in /client/custom-elements. Give it a name, you want your element to have. The folder name will be used in the element's URL, hence avoid white spaces or special characters.

2. In the folder, you have just created, create index.pug. Ideally make it extend the layout located in ../../../server/views/custom-element-layout relatively to the just created index.pug.

   If you decide to extend the provided layout, don't forget to specify the block content in order to provide the HTML basis for your custom element.

3. Create a typescript file. Best practice is to name the file after the extension (e.g. sheets.ts).

4. If you need additional NPM packages, install them to the root of the devkit project.

5. If you need to have more typescript files, place them into a sub-folder.

6. Create stylesheets in '.less', '.styl' (stylus) or '.css' format. Import them from within any typescript file, in order for them to get compiled into a css file. If you're going to use an approach, that does not rely on an output css file, you don't need to do this.

7. (Optional) If you'd like to use Kentico provided custom-element.css along with Kentico icon-set, just import the provided client/shared/custom-module.css in your typescript file. The icon-set is linked from within there in a way that allows it to be loaded by the browser.

   If done from the entry-point piece of script the line will likely look like this: import '../../shared/custom-module.css';. This will ensure the bundler includes the styles and copies the font into the built folder, so that both are available to your custom element.

8. (Optional) If you'd like to load an initial value to your custom element, when debugging locally (when not in an iFrame), create a file called initialValue.json in your element's folder. It will be given as a string to your element when initialized.

   Same goes for the element's configuration. Create config.json and the object described there will be given to your custom element when initialized.

9. Start the server using npm start -- -hw. This will start a https: server on your machine on the port 3000. The address of your custom element is then: https://localhost:3000/custom-elements/

10. You can also view your custom element the way it would look in Kentico Cloud on the address https://localhost:3000/custom-elements/<element-name>/wrap

    The sheets element looks like this in the wrapper:

    

    Pay attention to the browser console, as the mocked API for local debugging logs saved values and also makes an object representation of the custom element available in the variable window.customElement.

This will result in a structure built according to several conventions:

1. One element's files are located in <root>/client/custom-elements/<element name>/

2. There's a view file in the '.pug' format called index.pug.

3. A typescript file bearing whatever name as long as it ends with '.ts' or '.tsx'.

   If several files are present, it should work in theory, but make sure they don't reference each other. In such case they would probably be included more than once.

4. The stylesheet is in '.less', '.styl' (stylus) or '.css' format and is imported from within the typescript code.

Using React.js

If you wish to use React.js to implement your component, follow these steps:

1. Install react and react-dom in the main folder

2. Create a subfolder within your component folder for all React components (e.g. /client/custom-elements/your-element/components)

3. Implement your custom element as React component. Use tsx suffix for all files that use JSX syntax.

4. In the pug view file create a wrapping element for your React app

extends ../../../server/views/custom-element-layout

block content
	#reactapp

1. In the main ts or tsx file render the React component and hand over necessary properties like CustomElement to ensure the component can save its data into Kentico Cloud (e.g. this.props.customElementApi.setValue(JSON.stringify(dto));).

CustomElement.init((element, _context) => {
  ReactDom.render(<YourComponent disabled={element.disabled} customElementApi={CustomElement} />, document.querySelector('#reactapp'));
});

You can find example of custom element implemented using React.js in this repository: https://github.com/ondrabus/kc-country-selector/

Using a custom element in Kentico Cloud

Of course you'll need to build the elements and start the server before you can use it. From the previous instructions, you know you can do that by running npm start -- -hw(starts a watcher) or npm start -- -hb (only builds once).

If you want to know everything about custom elements, refer to our documentation.

But you can simply test the custom element in Kentico Cloud, by configuring a Content type to have a Custom element linked to your locally hosted element, like this:

Then go to the inventory and create an item based on the type with the custom element.

Using the custom element in production

Once you're happy with your work and your custom element works as intended, you can compile it into one HTML file with the styles and scripts inlined and minified directly in the HTML file. This ensures the browser loads just one file with one swift request. Provided the caching is setup correctly, the browser might not even issue the request.

By running npm start -- -cjsm you'll create the HTML file per element in \built\custom-elements<element-name>\index.html. You can serve this file from any hosting as a static file.

Running this server in production is not recommended, as the HTTPS server is not secure, because it's using a self-signed certificate.

The server and compilation

If you're interested in how this dev-kit works, what is it that the server does and all of the inner works of the compilation, read on here.

Plans

1. Hot reload if possible