How To Create A Custom Component In Acquia Site Studio

Introduction

Recently, Acquia unveiled a new Site Studio feature, Custom Components. This new feature will significantly alter how Acquia is used and will benefit both developers and designers. 

Custom Components use processes and design patterns to empower end users and scale more effectively. 

What Are Custom Components In Site Studio

Custom components are created using custom code rather than configuration entities, but they operate just like standard Site Studio components. By incorporating custom components, organizations can enhance Site Studio’s functionality to meet their unique needs. With a basic understanding of Drupal development, custom components can be developed in either JavaScript or PHP.

How To Define A Custom Component (File Structure)

The custom Drupal module or theme must contain a subdirectory called ‘custom_components’ to store the custom components. It is easier to separate files by placing each unique custom component into a different subdirectory.

There should be a separate YML-formatted definition file for every custom component. The custom component definition file “name.yml” for ‘custom_component’ must follow the structure of <unique_component_machine_name>. Write the “unique_component_machine_name” in lowercase, without any special characters, and with underscores instead of spaces. Numbers can also be used but only in combination with underscores and letters.

Note: It is important to use distinct component machine names. Even if the components are stored in different folders, Site Studio will only display one custom component if there are multiple ones with the same machine name.

Configuring A Unique Definition File For A Component

Follow the steps given below to configure a Unique Definition file for a Component: 

Step 1: Create The Custom Components Folder

Create a folder named ‘custom_components’ inside the module or theme file. Site studio will only detect custom components placed inside this folder. It is possible to freely arrange the customized components inside the folder.

Step 2: Create The YAML File For The Custom Component

Create a YAML ‘file.yml’ for ‘custom_component’ using the format ‘[your_custom_component_id].’ Every custom component needs its own ID. Site Studio will load only one custom component if there are multiple custom components with the same {custom_component_id} in the code base. Custom components do not load in any specific pattern in the discovery system. 

Step 3: Add The Name Property To The YAML File

Organizations have to add a property called ‘name’ to the YAML file. The name property will be used in the admin in different locations, such as the component list and sidebar browser. 

Step 4: Add the Category Property To The YAML File

The organizations can also add the ‘category’ property to the YAML file. The ID of a Site studio Component category should be the value assigned to this property. Site Studio will place the custom component under the default ‘Uncategorized’ category if it cannot discover the category.

Organizations can define a new category by navigating to the “/admin/cohesion/components/categories” path.  

Note: The component will be placed in the safe default "Uncategorized" category, or “cpt_cat_uncategorized,” if the designated category is empty.

Step 5: Add Custom CSS And Javascript To The YML File

Organizations can also add custom ‘CSS and Javascript’ to the YML file. A custom component can have CSS and Javascript files attached to it, along with references to other Drupal module dependencies. Add a JS, CSS, or dependency to the custom component YAML declaration in order to attach such files.

As all custom component CSS will be stored at the ‘component’ level, the `css` properties for custom components do not require a style type key like base, component, state, or theme. 

Step 6: Describe The Form

Like any other component, organizations can add a form to their custom component. Site Studio offers an interface comparable to components for creating customized component forms. Using this user interface, organizations can modify the form's layout and add new fields. Organizations can also add drop zones to the custom component.

Follow the five steps given below to  include a form into a customized component:

1. Create the form by navigating to ‘admin/cohesion/components/custom-component-builder.’ 
2. Export the ‘.json’ file from the bottom of the page.
3. Place the exported.json file next to the custom component's YAML file.
4. Create a form property in the YAML file and set its value to the path of the form's JSON file.
5. To modify a form, replace the form ‘.json’ file of the custom component with the exported one. 

Step 7: Add Custom Templates And HTML To The YML File

The template attribute will determine the path to the Twig file that will be used to render the custom component. The HTML attribute will specify the path to the HTML file that will be used to render the custom component. A custom component may only use one of these attributes. Traditional Drupal theming makes greater use of the Twig template feature. On the contrary, a developer working with a JavaScript or React-based component would choose the HTML template attribute.

Step-By-Step Guide To Create A React Site Studio Custom Component

Follow the steps given below to create a React Site Studio custom component. 

1. Create a new custom module in the path “modules/custom/custom_site_studio_components.” The “custom_site_studio_components.info.yml” file will enable the custom module from the Drupal CMS. 

2. Create a folder inside “custom_site_studio_components” with the name “custom_components.”

3. Create a YAML  in the ‘react.custom_component.yml’ format within the path "modules/custom/custom_site_studio_components/custom_components/react_component” and define the name, category, preview_image.

4. Create a React component using ‘npx create-react-app myApp’ and install the dependent node modules. Based on the requirement, update the CSS, JS, and “index.html” files. Update the “public/index.html file” with the “<noscript>You need to enable JavaScript to run this app.</noscript><div id="root"></div>” and remove all the elements from that file.

After execution, ‘npm run build’ will create an optimized build of the app in the build folder. Organizations need to define the path of HTML, CSS, and JS path in the ‘react.custom_component.yml’ file.

5. Organizations need to add the final HTML, CSS, and JS path to the ‘react.custom_component.yml’ file.

Note: To see the changes on the component side, organizations must rebuild the cohesion whenever they make changes to anything within the "react.custom_component.yml."

How Axelerant Helped University Of East London Get The Most Out Of Aquia Site Studio

The University of East London, founded in 1898, is ranked in the world’s top 250 young universities. The university’s vision is to advance knowledge and drive innovation for positive change. 

UEL’s website provides information on courses, admissions, careers, and research opportunities. The old website existed on Sitecore, and UEL needed a platform with better system performance, flexibility, and security.

Axelerant helped UEL migrate from Sitecore to the Drupal Platform. Axelerant also utilized Acquia Site Studio to implement low-code page building. The new website offers improved functionalities such as advanced course search, personalization, and a unified content hub. It is equipped to better understand user access and evaluate the site's data, thus enabling student retention through personalization.

Want to implement a similar solution or discuss more about custom components? Reach out to Axelerant’s experts, who have been partnering with Aquia for over a decade. Axelerant was also the first digital agency worldwide to be Site Studio (CohesionDX) certified.