Skip to main content

Step-by-Step Guide

For the initial integration of MindKey Web Components, no development knowledge is necessary. However, a complete integration will require a basic understanding of CSS. CSS, which dictates the visual aspects of a webpage (such as colors, spacing, font size, etc.), is essential for seamlessly incorporating the Web Components into your site.

Target Audience

This guide is tailored for non-developers and developers making their first steps with the MindKey Web Components.

Non-developers can use page builders like WordPress, WebFlow, etc., to construct websites that incorporate MindKey Web Components.

Throughout this guide, we will walk you through the integration process for three key Web Components:

  • Vacancy List
    • Shows a list of available vacancies.
    • Links to the "Vacancy Detail" Web Component.
    • Links to the "Application Form" Web Component.
  • Vacancy Detail
    • Shows a single vacancy in detail.
    • Links to the "Application Form" Web Component.
  • Application Form
    • Shows a form for a vacancy for the applicant to apply.

To enhance the guide's versatility across various page builders, it doesn't provide instructions on specific clicks within your website's page builder interface. Instead, it offers detailed guidance on how to locate and execute equivalent functions within your specific page builder, ensuring a seamless integration experience.

Prerequisites​

Before starting the integration process, gather the following essential information:

MindKey Customer ID​

To find your Customer ID, consult the Web Components documentation.

Website URL​

Take note of the website URL where the Web Components will be integrated. This is the address you type into your browser's bar to access the site. For instance, if your website URL is https://example.com/company, focus on the https://example.com part. In this guide, we'll use https://example.com as an illustrative URL; however, ensure to replace it with your actual website URL during the integration.

Security Setup​

MindKey access is safeguarded through CORS (Cross-Origin Resource Sharing). To enable Web Components to access MindKey data, CORS configuration is required.

Refer to the instructions in "Update your CORS settings in MindKey", utilizing the website URL obtained in the previous step.

Vacancy List​

Let's proceed with integrating the first Web Component into your website.

  1. Create a new page in your website builder and give it a meaningful name, such as "Available Jobs."

  2. Add a block in your website builder that allows the insertion of custom HTML commands. Please consult the "Website Builders" section for detailed information on locating a block that supports custom HTML commands.

  3. For each Web Component, insert two HTML commands. You have the flexibility to either include both commands within a single custom HTML block or use two separate custom HTML blocks—choose the approach that suits your preference. There is no inherent advantage or disadvantage with either method.

Loading the Web Components​

The initial HTML command we'll employ is for loading the MindKey Web Components. This command remains consistent across all other Web Components. It retrieves the Web Components from MindKey's server but doesn't render anything.

Within your custom HTML block, include the following line:

<script src="https://recruiting.mindkey.com/mk-recruiting-components.js"></script>

Optional: Load the basic styles​

Optional, but recommended, is to load the structure.css which contains some very basic styling instructions, e.g. it adds the common asterisk symbol (*) for required fields. The structure.css is not required. You can style the Web Components however you want. It just provides a common starting point for the integration.

If you want to use it, please add the following line to the custom HTML block above:

<link
  rel="stylesheet"
  href="https://recruiting.mindkey.com/structure.css"
/>

Display the Vacancy List​

The second HTML command is dedicated to displaying one of the Web Components, specifically the Vacancy List.

In your custom HTML block, add the following line after the previous one:

<mk-vacancy-list
  customer-id="your-customer-id"
  language="en-US"
></mk-vacancy-list>

Let's provide a brief explanation for the preceding line:

  • mk-vacancy-list is the name of the displayed Web Component.
  • customer-id is an HTML attribute (or parameter).
  • "your-customer-id" represents the value assigned to the customer-id HTML attribute.
  • language is also an HTML attribute.
  • "en-US" denotes the value of the customer-id HTML attribute.

Parameters enable modifications to the display and behavior of Web Components. Each component has its unique set of parameters, which can be found here for the vacancy list.

All Web Components share two common parameters:

  • customer-id: The value from the pre-requirement step.
  • language: The language used for specific texts and the actual data requested from your MindKey data. Refer to "Language & Culture" for more details.
language parameter

Please set the value of the language parameter to the language you want to request. Otherwise, you may run into an error.

Please see the "Language & Culture" for more details or consult the FAQ if you see the error "Application Form Type not found" in the browser's console.

For each Web Component used, replace your-customer-id with the actual value from the pre-requirement step. For instance, if your customer ID is abababab-abab-abab-abab-abababababab, the corresponding HTML command appears as follows:

<mk-vacancy-list
  customer-id="abababab-abab-abab-abab-abababababab"
  language="en-US"
></mk-vacancy-list>

At this point you can save your page and preview it.

Congratulations! You have successfully completed your initial integration!

If you encounter issues such as not seeing your data or having a blank display, please consult Common Errors for additional guidance.

Styling

You might observe that the Web Component lacks visual appeal. This is intentional, as we do not include styling with the Web Components to facilitate seamless integration into any website. To achieve a visually pleasing integration, it is necessary to write your own CSS, as mentioned at the beginning of this guide.

Nevertheless, we offer some very basic styling that does not define colors but includes spacings and visual adjustments. Refer to styling for more details.

For this guide, the use of styling is optional.

You can either utilize the HTML attributes to refine the Vacancy List display, or you can proceed with the integration of the Vacancy Details Web Component below.

Vacancy Details​

The Vacancy Details component displays detailed information about a single vacancy.

The steps for integration are identical to those for the Vacancy List. Once completed, we will configure both components to enable the Vacancy List to generate a link to the Vacancy Details Web Component. This link allows potential candidates to click on an open vacancy in the list and access detailed information.

To begin, create a new page and give it a meaningful name, such as "Vacancy Detail." Next, follow the same steps outlined in "Loading the Web Components" to load the Web Components.

Display Vacancy Details​

In your HTML block, add the following line:

<mk-vacancy-details
  customer-id="your-customer-id"
  language="en-US"
></mk-vacancy-details>

Again, replace your-customer-id with your MindKey customer ID.

Before proceeding, your page builder will likely provide a permanent link for the created page. That is the address you would send any external person in order the view the created page. Make a note of it. For this guide, we assume it's https://example.com/vacancy-details.

The Vacancy Details Web Component can either permanently display a specific vacancy via an id HTML attribute or dynamically display a vacancy based on a user's click in the list.

In this guide, we'll utilize dynamic display.

To comprehend how this works, let's revisit the concept of a Website URL. As mentioned earlier, it's the address entered into your browser's address bar, like https://example.com.

To inform the Web Component about which vacancy to load, we need a Query Parameter.

Consider this website URL: https://example.com/vacancy-details?id=great-vacancy. In this URL, observe the id=great-vacancy part:

  • id: represents a query parameter.
  • great-vacancy: signifies the value of the id query parameter.

Now, let's address two key tasks:

  1. The Vacancy Details needs to recognize the query parameter to read its value.
  2. The Vacancy List also needs awareness of the query parameter to write its value.

Setting the Vacancy Details Query Parameter Attribute​

Modify the HTML block of the Vacancy Details page and incorporate the query-parameter HTML attribute:

<mk-vacancy-details
  customer-id="your-customer-id"
  language="en-US"
  query-param="id"
></mk-vacancy-details>

You only need to add query-param="id"; everything else is already there from "Display Vacancy Details". This HTML attribute instructs the Vacancy Details Web Component to read the query parameter with the name id.

Update the Vacancy List Web Component​

Now, we need to modify the Vacancy List Web Component.

Open its HTML block and include the HTML attribute details-href-prefix. The value of this parameter should be /vacancy-details?id=.

Let's implement the change first, and then we'll delve into why this value is chosen and how to set your own:

<mk-vacancy-list
  customer-id="your-customer-id"
  language="en-US"
  details-href-prefix="/vacancy-details?id="
></mk-vacancy-list>

In the previous section, we mentioned that the website builder provides a permanent link for the Vacancy Details page, which is https://example.com/vacancy-details. We are interested in everything that comes after https://example.com, which is /vacancy-details. As defined in "Setting the Vacancy Details query parameter attribute", the query parameter is named id.

Now, combining all these elements, the value for the details-href-prefix is /vacancy-details?id=. Note that it starts with a / and ends with a =, both of which are important.

The Vacancy List will use this value to create a link from the list to the details page and append the ID of a vacancy that the user clicked on after the = sign. Therefore, the actual link the user clicks on could be something like https://example.com/vacancy-details?id=great-vacancy.

At this point, publish both pages to a preview state and try it out.

Page not found

If you encounter an error like "Page not found" or something similar when clicking on a vacancy in the list, please double-check that:

  • The HTML attribute details-href-prefix is written correctly.
  • You have written all special characters like ", ?, = according to the examples.
  • You have the correct value set to link to the Vacancy Details page.

Application Form​

The Application Form Web Component presents a form for potential candidates to fill out when applying for a vacancy.

The good news is: Now, we know everything needed to add the Application Form Web Component. There is nothing new, and we can simply repeat the same steps with the Application Form.

First, create a new page again and give it a meaningful name, like "Application Form." Second, follow the exact same steps to load the Web Components as you did in "Loading the Web Components".

Display Application Form​

In your HTML block, add the following line:

<mk-application-form
  customer-id="your-customer-id"
  language="en-US"
  query-param="id"
></mk-application-form>

Before we proceed, in your page builder, locate the permanent link for the created page and make a note of it. For this guide, we assume it's https://example.com/application.

The Application Form Web Component can either permanently display a specific vacancy via an id HTML attribute or dynamically display a vacancy based on a potential candidate's click in the list via the query-param attribute.

In this guide, we'll utilize dynamic display, functioning the same way as Vacancy Details.

The HTML block above already includes the query-param="id". The only action needed is to replace your-customer-id with your MindKey customer ID.

To link to the Application Form, we need to:

  • Update the Vacancy List page.
  • Update the Vacancy Details page.

Update the Vacancy List​

Open the HTML block for the Vacancy List Web Component; we're going to add the HTML attribute form-href-prefix. The value of that parameter will be /application?id=. It works exactly the same as before; we are just linking to a different page.

This will be the final HTML block for the Vacancy List:

<mk-vacancy-list
  customer-id="your-customer-id"
  language="en-US"
  details-href-prefix="/vacancy-details?id="
  form-href-prefix="/application?id="
></mk-vacancy-list>

For better readability, we've changed the code into multiple lines. You can also do this in your HTML block if you want; it's perfectly valid.

Update the Vacancy Details​

Last, open the HTML block for the Vacancy Details Web Component; we're going to add the HTML attribute form-href-prefix. The value is the same as before: /application?id=.

This will be the final HTML block for the Vacancy Details:

<mk-vacancy-details 
    customer-id="your-customer-id" 
    language="en-US" 
    query-param="id" 
    form-href-prefix="/application?id="
></mk-vacancy-details>

Save everything and publish all the pages we've created to test them.

You should be able to:

  1. Visit the page with the Vacancy List.
  2. Click on a vacancy, which opens the Vacancy Details.
  3. From the Vacancy Details, click the apply link to open the Application Form.
  4. From the Vacancy List, click the apply link to open the Application Form as well.

Next steps​

Congratulations! You've successfully completed the very first integration!

Your next steps from here are: