Cohesion DX logo Cohesion DX logo

Technical FAQ

We've put together a list of the most common questions from developers

OVERVIEW

Answers to common questions from developers

We've put together a list of the most common questions that developers ask. If you have a technical question that you would like answered but isn't featured here, then you can get in touch with us at [email protected].

Download Technical FAQ

Download a PDF copy of these questions and answers.

Download

    Panels (including Page Manager)

    The Panels module uses the Layout API to define a set of layouts. These layouts must be pre-defined (created by a developer in YAML code with templates, etc.). Panels then allows you to layout blocks (including field blocks) using these layouts. With this:

    • a site builder is limited to using the predefined layout.
    • a site builder is only able to place blocks or custom content.

    The display of these blocks must be pre-defined in code (Ie. a template and associated styles created by a developer and made available to the site builder). There is no control for end site content editors to modify the layouts or styling of pages from the node edit page. Content editors are limited to creating field data inside a content entity as is normal for all Drupal sites.

    In contrast, DX8 allows a site builder to layout a template for any page using its visual template/style builder. The elements available to the site builder are not limited to Drupal’s core blocks and fields (like Panels is). A site builder can add the raw HTML elements that make up a page, including more complex interactive elements such as sliders, grids, maps and videos as well as Drupal core blocks and fields. The site builder is not restricted to using predefined field templates and can create their own CSS styles and layouts for each page.

    Unlike Panels, DX8 does NOT have a custom rendering engine that is invoked at runtime. DX8 creates twig templates that are consumed by Drupal 8 core as it if they were created by a developer.

    Paragraphs

    Paragraphs is a way to allow end content editors to lay out pre-defined layouts of fields on a page.

    Because these layouts work like entity references, a developer must create them for them to be used. Unlike DX8, the end site editor has no control over styling or conditional visibility.

    Like Paragraphs, DX8 gives the end content editor access to pre-defined “components” that contain a form the editor can fill in. Unlike Paragraphs, DX8 components are created by the site builder in the same way page templates are created (see “Panels/ Page Manager” section above. Components are saved locally as .twig files.

    No, this is designed to achieve a completely different function . The layout initiative is a way to layout blocks and fields (field blocks) via the front end. It’s “Inline” editing for block and field placement. With the layout initiative, the blocks and field output need to be predefined by a developer.

    At it’s core, DX8 allows a site builder to generate .twig template files and .css stylesheets.

    On the front end, all DX8 does is invoke page and library hooks to create template suggestions to the generated .twig files and dynamic library definitions for the generated stylesheets and other library assets.

    There is no custom on-the-fly rendering of layout.

    Because DX8 uses core Drupal twig rendering, all caching is automatically handled by Drupal.

    How does DX8 run within Drupal 8 diagram

    DX8 produces .twig files and .css stylesheets. There is a specific hierarchy of template inheritance:

    • The html.html.twig level template is provided by your theme as normal.
    • The “Master template” is a replacement for the page.twig level template that defines at the page level layout.
    • A content template is the template that controls the layout of any displayable content entity (this is defined per display view on each bundle).

    Within each of these templates, the site builder can bring in Drupal fields (using the fields own display template), blocks, DX8 elements and even the component templates.

    DX8 can also produce views templates, menu templates and breadcrumb templates.

    Generated templates and stylesheets cannot be modified directly by a developer. If changes are made in code, any changes that are then made by the site builder via the DX8 UI will overwrite changes to the template the next time they are built. Custom layout and styling should either be done in blocks, DX8 custom elements or using standard Drupal field templates.

    From a templating point of view, DX8 is designed primarily to generate content entity templates, view templates, breadcrumb templates and menu templates. Support for templating custom controllers (such as the Drupal login page or custom controllers defined by other modules) is limited to applying a wrapping template. There is currently no support to create templates for forms. Developers are advised to use webforms or implement a custom controller and use a DX8 wrapping template.

    Field Formatters

    Field data from content entities can be rendered on a DX8 template either as raw data via tokens, or using the field’s default Field Formatter. If using a Field Formatter, the output will be exactly as defined by the field module. This means DX8 will work seamlessly with core fields and contributed modules that supply their own layout and templates for their field output. Developers are also able to create custom fields with custom formatters and DX8 will render these exactly as the developer has defined.

    Blocks

    The simplest way to inject developer created layout and styling into the DX8 templates is to define them as a standard Drupal block. With that approach you can create any layout you need, bring in blocks defined in drupal.org modules and retain 100% control of the layout of that block.

    Custom DX8 elements

    The downside of using a block is there is no way to give a site builder options from within the DX8 sidebar editor. To do this, you can create your own DX8 element and define its form using the Plugin API.

    To create your own element, you must create a plugin that extends the DX8 “CustomElementPluginBase”. Inside that plugin you needs to define your form. The structure of the form closely resembles Drupal forms, but allows you to give access to all DX8 form element types to your site builder:

    Create your own elements code example

    For example:

    Create your own elements code example

    You then need to define a render function. This function will take the form data as input by the site builder and pass it through to your Plugin. A simple example of a render function that uses a custom .twig template is:

    #elementSettings - contains the form data as input by the site builder.

    #elementMarkup - contains any specific markup settings defined by the site builder.

    #elementClass - this allows your site builder to define .css styles specific to the instance of this element using the DX8 style builder. The DX8 API builds these styles and hands this the class that contains them to you to use however you wish.

    API

    No site specific data is stored on the API.

    We have intentionally made the API completely stateless and all processing done in-memory. JSON schema data is used to generate .twig and .css styles before being transmitted back to your Drupal site on the same request and then immediately discarded.

    For a typical Drupal site, deployment is as follows:

    • Make changes to modules and theme files
    • Make changes to configuration
    • Unlock your filesystem (if using Pantheon or Acquia hosting or similar)
    • Export your configuration.
    • Commit all these changes to version control.
    • Pull the new committed changes down on your live site.
    • Apply the new configuration via a config import.
    • Clear caches

    With this approach, a deployment to a live site does not touch the live content. The only changes that are made are layout and configuration.

    Because DX8 generates template files in the public file system there are two extra steps for an uninterrupted deployment:

    • Make changes to module and theme files and commit those to version control.
    • Make changes to configuration, including DX8 master templates, DX8 view templates, DX8 components, DX8 website settings and DX8 custom styles.
    • Unlock your file system (if using Pantheon or Acquia hosting or similar)
    • Export your configuration (including DX8 config entities as above).
    • Export your DX8 assets using a GUI or Drush system very similar to config export (this includes all the generated .twig and .css files and visual assets specific to your templates).
    • Commit all these changes to version control.
    • Pull the new committed changes down on your live site.
    • Apply the new configuration via a config import.
    • Apply the DX8 assets via the DX8 asset import GUI or Drush system (this moves all .twig, .css and visual assets back into the cohesion:// stream wrapper for immediate use).
    • Clear caches

    With DX8, there is a clear separation between DX8 config and content. For deployment, DX8 config (such as templates and styles) are treated in the same way as templates and styles created by a developer

    The underlying JSON schema and any hardcoded content for each template and style defined by the site builder (Drupal content field data is NOT transmitted).

    • The site UUID
    • The site domain
    • The current user ID and DX8 access permissions (no other user information is transmitted)
    • Your DX8 API keys (for authentication).
    • All inbound and outbound connections to the API are TLS encrypted.

    EXPERIENCE DX8

    Arrange your demo at a time that suits you

    The best way to assess DX8 is to experience it for yourself.
    Book your demo and get access to your own sandbox (so you can have a try), our detailed user
    guide PLUS your unique code that gives you your first licence for free.

    © 2018 Cohesion Web Technologies. All rights reserved. Drupal is a registered trademark of Dries Buytaert.