Application Launcher

Site Studio

Advanced select field capabilities

Site Studio

Advanced select field capabilities

Two new options have been added for the Select form field in the form builder in Site Studio 7.5.0.

The previous two options have been renamed as described:

Manually set options - previously "Custom select field"
Options from existing select field - previously "Existing select field"
Options from external data source - new
Options from custom function - new

Selecting "Options from external data source" will display a new field "External URL". You must enter a url endpoint that returns JSON data in the correct format.

Selecting "Options from custom function" will display a new field "Function name". You must enter the name of a function that is globally available that returns the data in the correct format (or a promise that resolves to the correct data).

An example module (example_custom_select) is also included to further outline usage expectations.

Demo

Enable this module from /admin/modules

Drupal route

Create a new Component by navigating to: admin/cohesion/components/components/add
Add a Select field to the Component form builder
Double-click the new Select field and choose Options from external data source as the

Two new options have been added for the Select form field in the form builder in Site Studio 7.5.0.

The previous two options have been renamed as described:

Manually set options - previously "Custom select field"
Options from existing select field - previously "Existing select field"
Options from external data source - new
Options from custom function - new

Selecting "Options from external data source" will display a new field "External URL". You must enter a url endpoint that returns JSON data in the correct format.

An example module (example_custom_select) is also included to further outline usage expectations.

Demo

Enable this module from /admin/modules

Drupal route

Create a new Component by navigating to: admin/cohesion/components/components/add
Add a Select field to the Component form builder
Double-click the new Select field and choose Options from external data source as the

Two new options have been added for the Select form field in the form builder in Site Studio 7.5.0.

The previous two options have been renamed as described:

Manually set options - previously "Custom select field"
Options from existing select field - previously "Existing select field"
Options from external data source - new
Options from custom function - new

Selecting "Options from external data source" will display a new field "External URL". You must enter a url endpoint that returns JSON data in the correct format.

An example module (example_custom_select) is also included to further outline usage expectations.

Demo

Enable this module from /admin/modules

Drupal route

Create a new Component by navigating to: admin/cohesion/components/components/add
Add a Select field to the Component form builder
Double-click the new Select field and choose Options from external data source as the

Enter /sitestudio/select-options to use the Drupal route supplied by this example module

Observe the dynamic values supplied by this endpoint in the Default value options.

Create a new Component by navigating to: admin/cohesion/components/components/add
Add a Select field to the Component form builder
Double-click the new Select field and choose Options from custom function as the Type
Enter exampleGetOptions1 to use the Javascript function supplied by this example module
Observe the dynamic values supplied by this endpoint in the Default value options.

This module provides an example of both the Drupal and Javascript implementations of this feature.

Drupal route - defines an endpoint for returning JSON.
Controller - returns JSON data.

Javascript library definition - defines a custom JS library.
Javascript library - return JSON data.
module file - attaches library during entity create/edit.
Service definition - defines the EventSubscriber service.
Event Subscriber - attaches library during Page Builder load.

Note: an Event subscriber must be utilised to ensure a custom Javascript library is attached during Page Builder interaction.

When writing a function to retrieve options for the Select form element, it is crucial to adhere to specific guidelines to ensure consistency and compatibility. This documentation provides a set of rules and examples for creating a valid options retrieval function.

Rules for a Valid Options Retrieval Function

Return Type:
- The function must return an array of objects representing options.
- Each object in the array should have a label property and a value property.

// Valid Example
[
  { label: 'Option 1', value: 'option1' },
  { label: 'Option 2', value: 'option2' },
  // ...
]

Optional Grouping:
- Optionally, an object can have a group property to categorize options.

// Valid Example
[
  { label: 'Option 1', value: 'option1', group: 'Group A' },
  { label: 'Option 2', value: 'option2', group: 'Group B' },
  // ...
]

Function Structure:
- The options retrieval function must be a callable function and the function must be globally available (on the Window object.)

// Valid Example
const validOptionsFunction = function () {
  return [
    { label: 'Option 1', value: 'option1' },
    { label: 'Option 2', value: 'option2' },
    // ...
  ];
};
window.getOptions = validOptionsFunction;

Using a Promise (asynchronous):

window.exampleGetOptions = async function () {
  return new Promise((resolve) => {
   setTimeout(() => {
     resolve([
       { label: 'Foo', value: 'foo' },
       { label: 'Bar', value: 'bar' },
       { label: 'Wut', value: 'wut', group: 'Other' },
     ]);
    }, 1000); // Simulate a delay of 1 second
  });
};

Using a synchronous function:

window.exampleGetOptions1 = function () {
  return [
   { label: 'Foo', value: 'foo' },
   { label: 'Bar', value: 'bar' },
   { label: 'Wut', value: 'wut', group: 'Other' },
  ];
};

Not returning an array:

window.exampleGetOptions2 = function () {
   return 'This is not an array of options.';
};

Not being a callable function:

window.exampleGetOptions3 = [
  { label: 'this is not a function', value: 'this is not a function' },
];

Invalid object properties:

window.exampleGetOptions4 = async function () {
  return [
    { label: 'Foo', value: 'foo' },
    { label: 'Bar', value: 'bar' },
    { label: 'Wut', foo: 'Other' }, // Invalid property 'foo'
  ];
};

Creating a valid custom URL

When retrieving options from a URL it is crucial that the data returned from the URL is in the correct format and is returned as JSON data.

Return Type:
- The URL must return an array of objects representing options.
- Each object in the array should have a label property and a value property.

[
  { "label": "Option 1", "value": "option1" },
  { "label": "Option 2", "value": "option2" }
]

Optional Grouping:
- Optionally, an object can have a group property to categorize options.

[
  { "label": "Option 1", "value": "option1", "group": "Group A" },
  { "label": "Option 2", "value": "option2", "group": "Group B" }
]

Did not find what you were looking for?

If this content did not answer your questions, try searching or contacting our support team for further assistance.

Enter /sitestudio/select-options to use the Drupal route supplied by this example module

Observe the dynamic values supplied by this endpoint in the Default value options.

Create a new Component by navigating to: admin/cohesion/components/components/add
Add a Select field to the Component form builder
Double-click the new Select field and choose Options from custom function as the Type
Enter exampleGetOptions1 to use the Javascript function supplied by this example module
Observe the dynamic values supplied by this endpoint in the Default value options.

This module provides an example of both the Drupal and Javascript implementations of this feature.

Drupal route - defines an endpoint for returning JSON.
Controller - returns JSON data.

Javascript library definition - defines a custom JS library.
Javascript library - return JSON data.
module file - attaches library during entity create/edit.
Service definition - defines the EventSubscriber service.
Event Subscriber - attaches library during Page Builder load.

Note: an Event subscriber must be utilised to ensure a custom Javascript library is attached during Page Builder interaction.

Rules for a Valid Options Retrieval Function

Return Type:
- The function must return an array of objects representing options.
- Each object in the array should have a label property and a value property.

// Valid Example
[
  { label: 'Option 1', value: 'option1' },
  { label: 'Option 2', value: 'option2' },
  // ...
]

Optional Grouping:
- Optionally, an object can have a group property to categorize options.

// Valid Example
[
  { label: 'Option 1', value: 'option1', group: 'Group A' },
  { label: 'Option 2', value: 'option2', group: 'Group B' },
  // ...
]

Function Structure:
- The options retrieval function must be a callable function and the function must be globally available (on the Window object.)

// Valid Example
const validOptionsFunction = function () {
  return [
    { label: 'Option 1', value: 'option1' },
    { label: 'Option 2', value: 'option2' },
    // ...
  ];
};
window.getOptions = validOptionsFunction;

Using a Promise (asynchronous):

window.exampleGetOptions = async function () {
  return new Promise((resolve) => {
   setTimeout(() => {
     resolve([
       { label: 'Foo', value: 'foo' },
       { label: 'Bar', value: 'bar' },
       { label: 'Wut', value: 'wut', group: 'Other' },
     ]);
    }, 1000); // Simulate a delay of 1 second
  });
};

Using a synchronous function:

window.exampleGetOptions1 = function () {
  return [
   { label: 'Foo', value: 'foo' },
   { label: 'Bar', value: 'bar' },
   { label: 'Wut', value: 'wut', group: 'Other' },
  ];
};

Not returning an array:

window.exampleGetOptions2 = function () {
   return 'This is not an array of options.';
};

Not being a callable function:

window.exampleGetOptions3 = [
  { label: 'this is not a function', value: 'this is not a function' },
];

Invalid object properties:

window.exampleGetOptions4 = async function () {
  return [
    { label: 'Foo', value: 'foo' },
    { label: 'Bar', value: 'bar' },
    { label: 'Wut', foo: 'Other' }, // Invalid property 'foo'
  ];
};

Creating a valid custom URL

When retrieving options from a URL it is crucial that the data returned from the URL is in the correct format and is returned as JSON data.

Return Type:
- The URL must return an array of objects representing options.
- Each object in the array should have a label property and a value property.

[
  { "label": "Option 1", "value": "option1" },
  { "label": "Option 2", "value": "option2" }
]

Optional Grouping:
- Optionally, an object can have a group property to categorize options.

[
  { "label": "Option 1", "value": "option1", "group": "Group A" },
  { "label": "Option 2", "value": "option2", "group": "Group B" }
]

Did not find what you were looking for?

If this content did not answer your questions, try searching or contacting our support team for further assistance.

Demo

Drupal route

Demo

Drupal route

Demo

Drupal route

Javascript function

Example code

Drupal route

Javascript function

JSON format

Rules for a Valid Options Retrieval Function

Examples

Valid Examples

Invalid Examples

Creating a valid custom URL

Overview

Did not find what you were looking for?

Javascript function

Example code

Drupal route

Javascript function

JSON format

Rules for a Valid Options Retrieval Function

Examples

Valid Examples

Invalid Examples

Creating a valid custom URL

Overview

Did not find what you were looking for?