Using Acquia Cohesion on an existing website
In this guide:
- Introduction and before you get started
- Getting started and set-up
- Using Acquia Cohesion to provide content authors with a drag and drop page builder and content editor.
- Rebuilding your existing website theme using Acquia Cohesion.
You can use Acquia Cohesion on your existing Drupal 8 websites. This guide provides steps to take and links to relevant information within the main user guide.
Important: This guide assumes that you are already familiar with Acquia Cohesion’s site-building and content authoring features and require specific content for using it on an existing Drupal 8 website. Please refer to the main user guide and training videos if you are not familiar with Acquia Cohesion.
Before you get started
You first need to consider what you want to use Acquia Cohesion for. This will affect the approach you take and, importantly, the resources you will require.
- The most common reason to use Acquia Cohesion on an existing site is to provide a drag and drop page builder and content editor for creating rich and varied content. This is also by far the simplest way to get started using Acquia Cohesion. If this is your requirement, the steps are straightforward and included within this short user guide, starting here.
- You can also use Acquia Cohesion to completely replace your traditional theme with one built using Acquia Cohesion. You might do this to replace your current website design while retaining your existing content. This requires more planning and technical support, as you need to fully understand your website theme requirements and Acquia Cohesion’s theme building tools. The steps you need to take will depend on your website. This guide provides some help and guidance here but cannot provide you with a full implementation plan.
- Finally, you might use Acquia Cohesion to progressively switch from your traditional theme to one built with Acquia Cohesion. This is possible but requires a robust plan as you move parts of your website from one theme to another. We don’t recommend this approach and cannot provide you with a full implementation plan, but this guide provides some help and guidance here.
Getting started - Installing and enabling Acquia Cohesion
Before you can use Acquia Cohesion on your existing website, you need to install and enable it by following the steps below.
Step 1 - Enable your existing theme to use Acquia Cohesion
To use Acquia Cohesion you need to make two small modifications to your existing theme:
- To enable Acquia Cohesion on your theme you must add cohesion: true to your themes .info.yml file.
- To use Acquia Cohesion styles you need to add <cohesion-placeholder></cohesion-placeholder> within the <head> tag of your theme.
Step 2 - Install Acquia Cohesion on your website
To use Acquia Cohesion on your website you must first install the Cohesion modules. Refer to our user guide for more information on installing the Cohesion modules using the Drupal interface or installing using composer.
Step 3 - Connect to the Acquia Cohesion API
Once you have installed the Cohesion modules, you need to connect to the Acquia Cohesion API. Refer to our user guide for more information on connecting your existing website to the Acquia Cohesion API.
Step 4 - Run the Cohesion rebuild
After you have completed steps 1 to 3, you need to run the Cohesion rebuild process. The rebuild is required to generate some default CSS used by Acquia Cohesion. Navigate to Acquia Cohesion > Developer tools > Rebuild and click the Rebuild button.
Initial set-up and configuration
Once you have installed and enabled Acquia Cohesion, there’s some additional configuration required, regardless of how you intend to use it within your website.
Configure image and media browsers
You need to tell Acquia Cohesion which image or media browser to open when inserting an image into the content. It’s a good idea to choose the same image or media browser you use for other content. Refer to our user guide for more information on using image and media browsers with Acquia Cohesion.
Configure your Google maps API key (Optional)
If you intend to use Acquia Cohesion Google maps element, you will need to provide your Google maps API key. Refer to our user guide for more information adding your Google maps API key.
Configure your website grid and responsive media queries
Your existing website will likely have media queries (breakpoints) already set-up for your website CSS. Acquia Cohesions layout elements will not use these as they rely on their system for managing a 12 column website grid with responsive media queries.
When using Acquia Cohesion on an existing website, it's recommended that you match the settings within the Responsive grid settings to those set within your current website theme. Refer to our user guide for more information on configuring your responsive grid.
Configure your base unit settings
Acquia Cohesion allows you to manage your base font size. By default, it sets it to 16px. If your existing theme also sets the base font size, you will need to prevent Acquia Cohesion from also doing so as this will override the value set within your theme.
This is achieved simply with a toggle on Acquia Cohesion’s base unit setting page. Refer to our user guide for more information on configuring the base unit size.
Using your theme's CSS styles or Acquia Cohesions style builder
Your website's existing theme will already include the CSS required to style your site. If built with a clean and modular way, you can use this to style content created with Acquia Cohesion. Alternatively or in addition to, you can use Acquia Cohesions visual style builder to create new CSS styles.
Before using your existing theme styles or creating new styles using Acquia Cohesion, it’s important to understand and consider the following points:
- Any styles generated by Acquia Cohesion will be loaded after your theme’s existing styles. They will extend or override styles using the same selector.
- Does your CSS already provide styles for base Html elements like the <p> tag, <a> tag etc? If so, you should probably not create these within Acquia Cohesion as they will be extended or overwritten by the Acquia Cohesion styles and affect the appearance of your entire website.
- If you want to use classes or IDs from your existing theme CSS you should be confident that the styles have been created in a clean and modular way so that they can easily be used on Cohesion elements. For example: Are classes easy to identify and use? Are they modular so that they can be reused, or do they rely on a lot of inheritance?
Using your existing themes CSS styles
You can apply your existing theme’s CSS to elements used by Cohesion in two ways:
- Inheritance - Elements using Acquia Cohesion will automatically inherit styles within your CSS that target the particular element. For example, if your CSS provides a style for the <p> tag, when you use the Paragraph element in Cohesion it will use this style.
- Manually application - If you know the names of classes, IDs or attributes within your stylesheet, you can apply these directly to Acquia Cohesion elements. Refer to our user guide for further information on applying classes, IDs and attributes to elements.
Creating styles using Acquia Cohesions style builder
Acquia Cohesion provides a visual style builder for creating styles for base elements, classes and other selectors. You should consider using the style builder if your existing theme stylesheet does not provide all the styles you require, or you want an easier way to create and apply styles to Acquia Cohesion elements.
If you intend to create styles with the style builder, you will need to configure these additional settings first:
Configure your website color palette
The color palette manager allows you to create color SCSS variables using a visual interface. These colors are then used to populate a color picker for use when adding colors to styles or providing content authors color options. Refer to our user guide for more information on creating your color palette.
Configure your website fonts
The font manager allows you to import and manage font stacks using a visual interface. These are required if you want to apply specific fonts to styles created with the style builder.
Important: If your existing theme stylesheet already imports fonts, you should not import the same fonts again using the font manager, as this will increase load times. Instead, you should only set up the font stacks, ensuring that you use the same font names defined in your existing style sheet. Setting up the font stacks will make it easy for you to select and apply fonts to styles within the style builder. Refer to our user guide for more information on setting up your font libraries.
Configuring your website icon fonts
Acquia Cohesion provides an icon picker widget to make it easy to select and apply icon fonts to styles using the style builder. If you want to use the icon picker to apply icons to styles you will need to set up icon fonts using the icon font manager.
Important: If your existing theme already uses icon fonts, importing an additional icon font family will increase your website load times. For this reason, you should avoid importing additional icon fonts if possible. Refer to our user guide for more information on setting up icon fonts.
Using Acquia Cohesion to provide content authors with a drag and drop page builder and content editor.
The most common use for Acquia Cohesion on an existing website is to provide content authors with a drag and drop page builder, also referred to as the Layout canvas.
Adding the layout canvas field to a content type
The layout canvas is a Drupal field that can be added to any content entity bundle. The most common use is on content types for creating nodes, for example, your basic page content type.
Before adding the Layout canvas, it’s important to understand the following points:
- As the Layout canvas is just a field, content added to it will be displayed within the content region of your website, as defined in your website theme.
- Content added to the Layout canvas in the form of components is all stored within the Layout canvas as a single blob of unstructured content. You cannot trim this content for use in other view modes.
- The Layout canvas can either be used as the only field on a content type to take over the entire content region or used alongside other fields.
- You should use other fields alongside the Layout canvas to provide additional structured content. For example, content to be queried by a Drupal view or displayed in different view modes where the Layout canvas content is not appropriate.
To add the Layout canvas field to your content type, refer to our user guide for more information about adding the layout canvas to content entities.
Creating drag and drop components
Acquia Cohesion does not come with out-of-the-box components to use with the layout canvas because these can be built easily using the Acquia Cohesion component builder. They typically need to be created for your website's specific content and design requirements. Refer to our user guide for more information about components and creating components.
Common questions and challenges?
Can I make the layout canvas content fill the full width of my page?
Content added to the layout canvas field will be contained to the width of the content region defined within your existing website theme. If this is not set to the full width of the screen, you will either need to change this in your theme (Note: this will affect all content across all pages) or add a new full-width content region to your theme to use on content types where this is desired.
Can I use the layout canvas content in my teaser view modes?
Technically, yes. However, the layout canvas content is likely to be formatted for the full page display. There is no easy way to trim or reformat the content for use within a teaser view mode. This is usually solved by adding an additional field to your content types for teaser content.
Rebuilding your existing website theme using Acquia Cohesion.
Acquia Cohesion is an end-to-end website builder. You can use it to build your entire website theme, including headers, footers, menus, views, content templates, as well as page content.
If you intend to use Acquia Cohesion for both your content and your website theme you have three choices.
- Rebuild your website from scratch and migrate structured content from your old website to your new website. This is the cleanest build approach as you can start with a clean environment. If you choose to go for this option, refer to our user guide for more information on creating a new website with Acquia Cohesion.
- Rebuild your existing website theme using Acquia Cohesion. This requires more planning and consideration but allows you to maintain your existing structured content. You should consider that any content that you want to manage using the drag and drop layout canvas will need to be recreated.
- Partially rebuild your existing website theme using Acquia Cohesion. You may consider this so that you can transition to Acquia Cohesion over time. Although this may sound like an attractive option, you should consider the added complexity and planning required to run two themes simultaneously on your website. This approach is not recommended in most cases.
If you choose to go with option 2 or 3, you will need to create a robust upgrade plan to move from your existing website theme to a theme created using Acquia Cohesion. This plan will differ from one website to another as it will relate closely to the sites existing theme and functionality.
Considerations when forming a plan to rebuild an existing theme as an Acquia Cohesion theme.
The following points may help form a plan to rebuild an existing website theme using Acquia Cohesion. This is not a replacement for creating a detailed plan.
Forming a robust plan:
- Identify the areas of the site that gain the most value from being rebuilt in Acquia Cohesion and that is likely to cause the least difficulties. For example, rebuilding the header, footer and navigation systems are likely to provide less value and be more difficult than rebuilding templates for structured content.
- Identify content types and content that will benefit from being repurposed using the drag and drop layout canvas. For example, landing pages or brochureware pages are likely to benefit more from the layout canvas than simple text pages or articles.
- Identify any content or functionality on the website that is complex or required a lot of custom development to build. Highly interactive content, web forms, integrations or logic-based functionality cannot be built using Acquia Cohesion, although it can often be styled using Acquia Cohesion. You should identify this content and form a plan for how it will be maintained and included within your Acquia Cohesion website.
- If you are attempting to transition to Acquia Cohesion gradually, you will need to consider how your current themes CSS will work alongside the styles you will create using Acquia Cohesion. Fortunately, Acquia Cohesion prefixes all classes with .coh-style- to prevent conflicts with styles in a theme. However, you will need to consider the implications of creating styles for base elements and other selectors as these will override or extend your theme’s styles.
- Identify and language or internationalization requirements of your website. Acquia Cohesion provides support for multilingual content, but your plan should consider your website’s specific requirements.
Typical re-theming steps in order of priority
- Install and enable the Cohesion Modules. Refer to our user guide for more information on installing the Cohesion modules using the Drupal interface or installing using composer.
- Connect to the Acquia Cohesion API. Refer to our user guide for more information on connecting your existing website to the Acquia Cohesion API.
- Configure the media browser to use for images and media. Refer to our user guide for more information on using image and media browsers with Acquia Cohesion.
- If you are attempting a gradual transition, you will need to modify your existing theme to enable it for use with Cohesion. Refer to our user guide for more information on modifying your existing theme to work with Acquia Cohesion.
- If you are replacing your existing theme, set the Cohesion minimal theme or a sub-theme of it as your website theme. When you do this, your website will no longer use your existing theme and will look unstyled.
- Set-up your websites fonts, colors, icon fonts, base font settings, base unit size and responsive grid settings within Acquia Cohesions website settings manager. Refer to our user guide for more information on defining your website settings.
- Recreate all of your themes base element styles using the Acquia Cohesion style builder. Refer to our user guide for more information on creating base styles.
- Recreate your theme CSS classes using the Acquia Cohesion style builder. These will all be prefixed with coh-style-(style name), so they won't apply to any elements unless added to them. Refer to our user guide for more information on creating custom classes.
- Recreate your templates for both full-page display and other displays like teasers. Refer to our user guide for more information on creating content templates.
- Recreate templates for Drupal views. Refer to our user guide for more information on creating templates for Drupal views.
- Recreate your navigation systems. Refer to our user guide for more information on creating templates for Drupal menus.
- Recreate your site template, including headers and footers. Refer to our user guide for more information on creating master templates.
- Build components for use with the drag and drop content editor. Refer to our user guide about components and creating components.
- Add the layout canvas field to content types where you want to repurpose content using the drag and drop page builder. Refer to our user guide for more information on adding the Layout canvas field to content types.