Upgrade Your Drupal Skills

We trained 1,000+ Drupal Developers over the last decade.

See Advanced Courses NAH, I know Enough
Apr 25 2019
Apr 25

My former Drupal mentor, László Csécsy (boobaa) often says "If there is a task that you need to perform more than once and it can be easily automated then it should be automated."

We would like to introduce a new tool called Rector that could speed up an upgrade process and can reduce upgrade costs. We run a proof of concept for the possible use cases in which Rector can be beneficial for Drupal developers - including but not limited to the automated update to Drupal 9.

Drupal 9 is coming and according to the promises, the upgrade from Drupal 8 will be easy because Drupal 9 is built in Drupal 8.

What does "the upgrade to Drupal 9 will be easy" promise means precisely for developers? From the drupal.org post, Plan for Drupal 9:

Drupal 9 will simply be the last version of Drupal 8, with its deprecations removed.

Releasing Drupal 9 will only depend on removing deprecated functionality and upgrading Drupal's dependencies, such as Symfony.

The Drupal 8 change records show numerous classes and methods marked as "deprecated" in every release.

Depending on the size of a module's or a site's codebase, removing all deprecated APIs can require from a couple of development hours up to months. The process can be postponed until Drupal 9 is out, or it can happen in smaller batches after every Drupal 8 minor release. Either way, keeping a codebase up to date and ready for Drupal 9 upgrade requires resources.

Identifying deprecated API usages</a>

Yes, there are already several different ways for identifying deprecated API usages in a Drupal 8 codebase. For example, if automated tests are available on a project, developers can run deprecation testing on the codebase. Other alternatives are static code analyzers like Matt Glaman's excellent PHPstan Drupal integration or PHPStorm's built-in code inspection.

PHPstan found deprecated API usages

All these tools are great, but they can only tell what deprecated API usages a codebase contains. They leave the actual work to developers: having to fix these depreciation issues one by one.

Applying the same changes several times is definitely a repetitive task. There is a PHP library that can help to automate these kinds of upgrade processes, it is called Rector.

What is Rector?

Rector is a tool created by Tomas Votruba and according to its description on Github:

Rector is a reconstructor tool - it does instant upgrades and instant refactoring of your code.

Why is Rector awesome? Because it:

  • uses AST (Abstract Syntax Tree) to parse PHP code instead of tokens 1,
  • comes with built-in automation for upgrading to new PHP- or framework versions (ex.: Symfony, Laravel, etc.),
  • can also automatically migrate your code from one framework to another or one test runner to another,
  • can improve your code with automated code style and code quality fixes,
  • is open-source.

If you would like to learn more about Rector before you continue, Tomas created an introduction series:

Introducing Rector for Drupal 8

Rector already supported various frameworks, but it did not have support for Drupal 8 yet. This is the reason why Rector for Drupal 8 was born.

The Rector for Drupal 8 0.1.0 development version provides examples for the following possible use cases.

Instant code quality fixes and PHP 7.1 upgrade

Rector comes with numerous rector rules. Some of these rules are framework specific but most of them can run on any PHP code. The rules can be organized into prepared sets. Rector for Drupal 8 contains two prepared sets with all the built-in rectors that work on Drupal 8 codes. The drupal8 set only contains rectors that work on all PHP versions, including < PHP 7.0 versions that are still supported by Drupal core. For example: enforcing strict value comparison, normalizing conditions, removing dead code, etc. The drupal71 instantly updates any PHP 5 code to PHP 7.1 in a way that it still follows the Drupal 8 coding standards. I may include rectors in the future that make changes that require PHP 7.1 or above, ex.: add type to functions and methods parameters, etc.

Autocorrect framework specific mistakes and ensure best practices

All frameworks have their own list of best- and bad practices, so does Drupal 8. In Drupal 8, it is a best practice to use "const" instead of "define" to define constants, because it is better for performance. The DefineToConstRector can fix all constant definitions according to this best practice. As an example of bad practices, there are several traits in Drupal 8 that define a property and method with the same name. Probably the MessengerTrait is one of the most commonly used trait in Drupal core and contrib modules. Let's use this as an example. The $this->messenger property is not set by default, its value should be initialized in a class' constructor with Dependency Injection. If the property is set, then the $this->messenger() method calls the injected Messenger service. If not, then it calls the global Drupal static service container, retrieves the Messenger service from that and sets the property's value. The problem with this default behavior is that it hides an issue caused by the uninitialized property. If the property is not initialized and a valid method is being called on the property, like $this->messenger->addStatus() it causes a WSOD. Sadly, issues like this only reveal themselves in runtime. The only safe way to avoid this kind of issue is always using the method instead of the property. The PropertyToMethodCallRector rector can automatically fix any code from this kind of common pitfall.

Get rid of deprecated code without writing code

Because Tomas already implemented various kinds of automated code upgrades and framework migrations, Rector already contains rectors that can be leveraged to remove deprecated Drupal 8 API usages from a codebase. They only need to be configured. A built-in rector, called MethodNameReplacerRector, can automatically replace all usage of deprecated methods that used to generate a URL or a link for an entity. This rector can also ensure the entityTypeManager object is used everywhere instead of the deprecated entityManager object. Another common change in Drupal 8 core API is that global constants get replaced with class constants. The ConstToClassConstFetchRector rector that I created can replace all usage of a deprecated global constant with the new class constant.

Architectural refactoring

The majority of Drupal 8 API changes are more complex than simple renames. Classes, interfaces, traits, and methods get deprecated and replaced by new ones. These are the types of architectural changes where Rector can demonstrate its real power. The deprecation of the UrlGeneratorTrait is one of the best examples for a significant architectural change. A trait with a protected property and non-static methods got replaced with a class with static methods. Properly removing UrlGeneratorTrait from a Drupal 8 codebase is a risky task because several steps need to be performed and therefore it requires great concentration from a developer. However, with Rector the complete replacement process can be automated, this is what UrlGeneratorTraitRector demonstrates.

Demo time!

I configured Travis CI to run Rector for Drupal 8 on several Drupal modules. The test builds include Drupal core modules (node, system) and contrib modules like Commerce or the Apigee Edge module. The following screenshots showcase some of the fixes that Rector for Drupal 8 applied on these modules.

Rector replaced method calls to deprecated methods from the UrlGenerator trait and also removed dependency to the trait:


Rector replaced one of the most commonly used deprecated function in contributed modules - drupal_set_message():


Rector eliminated a possible bad flow caused by calling a method on a possible null property:


Rector replaced deprecated global constants with the new class constants:


What is next?

We hope this blog post gave you a good idea about the capabilities of the Drupal8-Rector project. Undoubtedly, its primary contribution to the Drupal community is the automated or at least semi-automated deprecated API removal from Drupal core and from contrib modules. The Rector library provides the framework and some good examples, but it requires a community effort to build new rectors or configure existing ones to address Drupal 8 core deprecations. There is still much work to do until all deprecated APIs since Drupal 8.0 are covered.

Please contribute to the Drupal8-Rector project if you see the potential in this proof of concept.

Apr 20 2017
Apr 20

As part of our work to make Drupal 8 the leading CMS for developer portals, we are implementing a mechanism to import the OpenAPI (formerly known as Swagger) specification format. This is a crucial feature not only for dedicated developer portals, but also for all Drupal sites that are exposing an API. Now that it has become much easier to create a RESTful API service in Drupal 8, the next step is to make it more straightforward to create its API reference documentation. That is why we think our work will be useful for site builders, and not just for technical writers and API product owners.

Swagger is a REST API documentation tool, it provides a specification language for describing the APIs and also a set of support tools. One of those tools is Swagger UI, which generates an appealing and readable layout for API endpoints and methods. The Drupal community is considering using the Swagger specification to document Drupal 8 core web services, and Swagger tool adaptations can be found in several contributed modules. In this blogpost we will introduce some of these modules and explain how we want to go beyond the shallow integration that most of them have done, to take full advantage of Drupal’s architecture. But before diving into the technical details, we want to list the features that we seek in the ultimate API reference CMS.

6 features that make the difference between a good and a great API reference system

The following are 6 technical developer portal features that customers have requested from us in the past 2 years working with Apigee’s developer portal. They provide functionality that go beyond what most API management platforms provide.

Developer Portal: Components Series In this series we give a thorough overview of the documentation components used on developer portals.

Read more

This feature list is based on our investigations of existing developer sites, our practical experience from creating developer portals and architecture workshops we’ve held.

1. Storing multiple API versions: versioning

As API services can have multiple supported versions (e.g. v1, v2) in parallel, a Developer Portal should provide a clear user experience that gives visitors the option to choose which version they would like to read about (but still default to the latest supported stable one).

2. Track changes in the documentation of each API version: revisioning

Most developer portal platforms rebuild the documentation as part of an automated build process, Drupal’s revisioning system allows editors and site maintainers to make and track changes in specific versions of the API documentation. While this is less important for the developers that use the documentation, it is an editorial feature that can be useful for technical writers and site owners.

3. Possibility to attach conceptual content to the API reference

API references are very technical and factual. Sometimes developers need more verbose documentation that provides a longer explanation of the context an API operates in. That is why, several of our customers have asked us to add conceptual documentation to their imported content - about domain language, underlying architecture, data models, or code samples that surround an API call.

4. Access control for individual API methods

In order to restrict the visibility of certain API methods (e.g. for partner APIs), a Developer Portal must allow site maintainers to set granular access permissions/restrictions for specific versions, endpoints or other parts of the documentation.

5. Trying out API calls on the Developer Portal’s UI

Integrating a system with an API service can be accelerated by a Try it out feature, that helps developers to decide which API endpoint with what parameters to use in order to get the expected result.

6. Importing reference documentation from a version control system

Recently technical writers have also started using the online collaboration and versioning tools that developers work with. Documentation is now often committed into code repositories, especially when developers contribute to the writing process. One key problem with this approach is that, apart from the API reference documentation where most teams use the Swagger specification, there is no obvious standard to store the content and layout of documentation. We’ve been working with markdown topics, and manifest files to allow technical writers to store conceptual documentation and their navigation structure (what we used to organize in a book hierarchy in Drupal) separate from the API specification. This way all the documentation can be stored in the version control system (e.g. a GitHub or GitLab repository).

Existing Swagger modules in Drupal

The Swagger API documentation toolset covers the entire publishing process: building (Swagger Codegen), documenting, and visualizing (Swagger Editor, Swagger UI). Existing Drupal modules typically focus on the building and visualization steps.

As usual Drupal.org has some modules that seem to be abandoned, but there are two Swagger docs related modules that have been maintained in the past year. One is the Swagger UI Field Formatter module, it renders fields with valid Swagger source file using the Swagger UI tool. The other is Swagger php module (sandbox only), it can generate JSON formatted Swagger code based on annotations and it can render that code using the Swagger UI.

Both of these modules use the Swagger UI project to generate a human readable output from the specification. Swagger UI only needs a valid source file to generate the output and the ‘Try it out’ section (for sending requests to the endpoints); it is useful if you only need to publish the content, but it has its limitations.

Free and Open Source API Documentation Tools

If you are interested in other free and open source API documentation generators, check out our blog post about other solutions.

Read more

The problem we see with this solution and most other API documentation tools is that API providers usually need access control, search, and conceptual documentation for their API descriptions. These functions demand a different approach.

Don’t just show it, integrate it!

After careful evaluation, we came to the conclusion that the currently existing Swagger tools can’t support the 6 advanced API documentation features our customers request from us. To make the API documentations fieldable, revisionable and to be able to apply custom access control on all components of them in Drupal, a more robust API integration is needed. No open-source module is available for Drupal 8 that does this, so we decided to make it a key contribution we would work on with our team.

Since there are other specification languages (such as RAML or I/O Docs) that are widely used and that store similar information as the OpenAPI format, we take great care to make sure that our architecture would be extendable and reusable.

Mapping Swagger objects into Drupal data types

To get a flexible system that can be extended and altered with proper Drupal 8 solutions, we designed custom Drupal 8 entities and field types for every piece of a Swagger source file. The first step was to observe the individual Swagger specification elements and to decide the most suitable Drupal 8 data types for storing them.

We just finished the planning phase of the entity architecture, the overall structure won’t change much, but there might be some small changes during the implementation period.

The below image describes a small part of the planned entity architecture. We defined a vendor independent API documentation as a content entity (basically the root entity) which might have bundles, providing the ability to extend the base system with vendor specific formats other than Swagger (e.g. I/O Docs or Raml). Based on this concept, each specification language format makes a new bundle with vendor specific fields. By default the Swagger 2.0 specification format bundle is provided. Each piece of content in a bundle represents a different API version, so multiple versions (e.g. v1, v2) can be made available in parallel on the Developer Portal (feature 1).

API documentation

type: content entity

has bundles: yes

label: string

version: string

...

endpoints: ER list (endpoint)

security schemes: ER list (security scheme)

[Not supported by viewer]Swagger 2.0

type: entity bundle

parent: API documentation

description: string

...

[Not supported by viewer]Consumes

type: trait

consumes: ER (MIME types)

[Not supported by viewer]UsesProduces

type: trait

produces: ER (MIME types)

[Not supported by viewer]UsesMIME types

type: vocabulary

Terms: application/json, application/xml, ...

[Not supported by viewer]

References

References

References

ReferencesEndpoint

type: content entity

has bundles: yes

URI: URI/string

[Not supported by viewer]

References

References

All of the documentation components are tied to the properties or references of an API documentation entity. For example API endpoints form another content entity type, which can get referenced from the root (API documentation) entity. Moreover, as we are planning to use fieldable entities, any additional information can be attached to them easily (feature 3).

Thanks to the OOP nature of Drupal 8, reusable properties and methods can be attached to entity classes through traits. For example, base field definitions of the consumes and the produces specification properties can be defined in traits and used in multiple entities, as they can be attached to the API documentation entity or to an API method/operation (overriding the default global settings of these properties). The consumes and the produces properties in the Swagger source are technically MIME types (such as application/json), so they can be collected into a vocabulary as taxonomy terms.

Thinking in traits will also enable us to extend the default API specification with custom properties (e.g. extend Swagger specification objects with ‘x-’ properties). Code snippets could for example be included for different programming languages (such as Java, PHP, Python), these might help the readers to understand the API reference.

With the above architecture we can map specification languages into a Drupal entity system where basic revisioning is supported by default (feature 2). Although custom access control can also be added to any type of entity and its fields (feature 4), it’s not as powerful as Drupal’s node access control system. There is already a Drupal core issue that tries to expand the node access grants system to a generic entity grants system, and we are trying to contribute to it while working on our Drupal Developer Portal.

Importing the data into the Drupal system

For the import process we leverage Drupal 8’s Migrate API to import any type of API specification formats to our custom entities and to store them in a unified way. Source files can be either uploaded in the UI or imported from a Github repository (feature 6) through a documentation importer that we are building to support editorial workflows that rely on code repositories and that automatically publish to Drupal as part of a continuous integration process.

If you are interested in our GitHub importer and Migrate processing solution, join our Developer Portal mailing list to receive notifications about blog posts on the subject.

Why Drupal?

We chose Drupal 8 as the framework for our Developer Portal, because it already had a large number of features that our customers need. With a 10 year long history in Drupal, we are obviously somewhat biased, but even if we disregard our prior expertise, we believe that Drupal is one of the best CMSs for building documentation and developer portals.

That is why we decided to extend the existing solutions, with a sufficiently complex system that would enable us to address all the needs our customers have. Some of our code is still in stealth mode, the developer portal market is a relatively small niche, and we need to make sure we can find a sustainable way to give back to the Drupal community. That is why in parallel to our development, we are working on a new business model for our distribution to make sure we will be able to continue sharing our work with the wider community. We are committed to the open source community and credo, but we want to prevent some of the failures we have seen with previous Drupal distributions, more about that in a later post...

Pronovix Logo

Are you building a developer portal? Interested in a shortcut? As a devportal specialist, Pronovix has created developer portals for 40+ customers in the past 4 years. Talk with us to learn how our SaaS developer portal can accelerate and simplify your launch.

Read More about our Devportal Solutions Contact us >
Mar 23 2017
Mar 23

Introduction

Web APIs are not just useful when making headless sites in Drupal: large Drupal sites often hold valuable information that could also be useful outside the site's context. Media companies might want to expose historical media content, community sites could show data about their community activities, e-commerce sites tend to open an API for their affiliates and partners.

While it is possible to use Drupal 7 and Drupal 8 as an API backend, a lot of functionalities that describe a mature API service do not come out of the box. In this post we will explain what key concepts you have to keep in mind when designing an API service, why they are important and how APIgee Edge can make it easier to build a full-featured API webservice in Drupal successfully.

Designing APIs: the API first strategy

In a large part of the software development industry, API first thinking is replacing a user interface design approach. API first design is about planning and documenting your API before it would be implemented in code. If you set up your backend service this way, you can use it with different clients regardless of the way they were implemented. API first strategy allows you to diversify user interfaces: UI developers can work without knowing how your backend service works.

Building good backend services is not easy, there are plenty of pitfalls on the road and most of them only reveal themselves during development. Your responsibilities as a service provider grow with the number of clients:

  • maintaining the security of your services (especially if you are providing paid services),
  • handling compatibility problems between client apps and different app versions,
  • ensuring that your services are able to handle unexpected loads.

You can’t handle all of these tasks without monitoring the services. Especially for monetization, monitoring is crucial.

Features to keep in mind for building good API backend services

Security

Security is one of the most important trust signals of a mature API. A multi-layered protection system should be able to hide your non-public services from the public, handle the authorization processes, and protect the original resources from attackers.

Compatibility

Compatibility issues are the nightmares of service providers: versioning your APIs is your first step to harmony.

Scalability

Successful services have to handle an enormous number of requests every second and your services have to scale with the number of your new clients. Sometimes moving your backend to better hardware does not help, because the root of the problem is in the initial architectural decisions or implementations.

Monitoring

You need exact analytics about the usage of your API: it is indispensable for monetization purposes, plus you could use analytics data to improve your service and to understand your users' behavior.

Documentation

Good documentation is an essential part of the API service, as this is the first line of support for developers trying to understand and learn how to use the API. Developer portals often have different kinds and levels of supporting material from getting started pages to various guides, case studies, playbooks, and tutorials.

Monetization

You will need an authorization and monitoring system to efficiently track and bill customers for using your services. Exposing different resources of your APIs individually or grouped, and setting up usage limits based on these “API products” can be a time consuming task.

Companies specialized in API management solutions

You can choose from many API management technologies to build an API service, but each technology stack has its own limitations. Some companies have specialized to help you solve (a part of) the problems that might occur. Our non-exhaustive list of such companies as an example (company descriptions are from Crunchbase):

  • 3scale’s API management platform empowers API providers to easily package, distribute, manage and monetize APIs.
  • Apiphany provides API management and delivery solutions that enable organizations to leverage the mobile, social and app economy.

  • Layer 7 Technologies provides security and management products for API-driven integrations spanning the extended hybrid enterprise.
  • MuleSoft
 provides integration software for connecting applications, data and devices. MuleSoft's software platform enables organizations to build application networks using APIs.
  • Mashery is a TIBCO company providing API management services that enable companies to leverage web services as a distribution channel.

  • StrikeIron offers a cloud-based data quality suite offering web-based infrastructure to deliver business data to internet-connected systems.
  • Apigee is the leading provider of API technology and services for enterprises and developers.

The rest of this article will focus on Apigee (recently acquired by Google). Disclaimer: Pronovix is an Apigee partner, so we are somewhat biased. However, even if we wouldn’t be partners, we believe they are probably the best API management service provider for Drupal projects. They are not only a market leader in the space, they have also invested in a Drupal integration: Apigee Edge.

Apigee Edge: a Drupal integration for API services

Built in JAVA, Apigee Edge is able to replace or enhance complicated parts of your services. API proxies will protect your services from direct customer access (as they guard the backend code), and add the above mentioned 6 key features to your APIs. Apigee Edge manages these features in a specific way.

Policies

Apigee Edge enables you to control the behavior of your APIs (without writing a single line of code) via policies. A policy is similar to a module that implements a specific, limited function that is part of the proxy request/response flow. You can add various types of management features to an API by using policies.

Traffic management policies

With cache policies you can set up traffic quotas and concurrent rate limits on your API proxies.

Mediation policies

Mediation policies let you do custom validation and send back custom messages and alerts to your clients, independently from your backend services. Moreover, you do not need to implement separate xml serialization in your services to accept requests or send responses in XML, because the JSON to XML and XML to JSON policies are capable to do automatic conversions between these formats.

Security policies

Security policies give access control management to your APIs with different types of authorization methods and protection features.

Extension policies

If you haven’t found an existing policy for a special task, you can implement your own policy in Java, Javascript or Python with the help of the Extension policies, which also contain policies for external logging and statistics collecting.

Developer portals

A great developer experience is crucial for API adoption. Apigee Edge has a developer portal solution that is built in Drupal 7 with API documentation, forums and blog posts that come out of the box. API developer portals done well are your power tools to help the adoption of your API and build strong communities. Apigee's dev portals could be hosted either on cloud or on-premises with Apigee Edge for Private Cloud.

We hope this introduction gave you some insight into building high-performance API web services.

Disclaimer: When we specialised Pronovix in API documentation and developer portals we started a partnership with Apigee, and we do extensive work customising the Apigee developer portal.

Pronovix Logo

Are you building a developer portal? Interested in a shortcut? As a devportal specialist, Pronovix has created developer portals for 40+ customers in the past 4 years. Talk with us to learn how our SaaS developer portal can accelerate and simplify your launch.

Read More about our Devportal Solutions Contact us >
Feb 10 2017
Feb 10

Traditionally CMSs use SQL databases that are really fast when you need all the information stored together in a record row, but are a bad fit when you need to search for relationship patterns that are not already stored together in your database. A significant performance penalty is incurred for every additional table that needs to be joined for a query. That is why SQL databases are notoriously bad at deducting relationships from datasets. Graph databases, however, are really good at this task.

In a talk we did at FOSDEM ‘17, Tamás Demeter-Haludka and I discuss potential application areas of graph databases in existing open source CMSs like Drupal.

We believe graph databases could make a big difference when used in key areas where traditionally CMSs would fail:

We've created a basic integration that makes it possible for non-developers to work with Neo4j. Combined with Drupal’s content modelling capabilities we believe it could be a powerful tool for people to explore graph databases using a GUI. There is also a case to be made for the use of graph databases in the Drupal ecosystem: sites that already use Drupal could benefit from its capabilities.

CMS as GUI of graph db

What are the possibilities if you combine graph databases with the tools and functionalities CMSs already provide?

For the video recording, click here.

Table of content:

  • Introduction (0:00)
  • Module demo (5:18)
  • CMSs as a GUI for a graph database (9:40)
  • Q&A (19:40)

Interested in AI? Subscribe to our AI & Docs mailing list, where we send notifications when we publish similar content.

Jan 13 2017
Jan 13

Intro to Neo4j

SQL databases are really fast when you need all the information stored together in a record row, but they are a bad fit when you need to search for relationship patterns that are not already stored together in your database. A significant performance penalty is incurred for every additional table that needs to be joined for a query. That is why SQL databases are notoriously bad at deducting relationships from datasets. Graph databases however are really good at this task.

Neo4j, a very popular open source graph database stores its data in a property graph, as described in Graph Databases for Beginners on the project’s website:

  • Property graphs contain nodes (data entities) and relationships (data connections).
  • Nodes can contain properties (tech lingo: key-value pairs).
  • Nodes can be labeled with one or more labels.
  • Relationships have both names and directions.
  • Relationships always have a start node and an end node.
  • Like nodes, relationships can also contain properties.

In combination with a graph query language called Cypher that is optimised for between-record pattern recognition, this storage pattern makes it easy to write queries that search for new patterns in a database and for objects that have a specified relationship with another object.

This makes graph databases excel at a number of tasks:

Why we built the module

We wanted to create a basic integration that makes it possible for non-developers to work with Neo4j. Combined with Drupal’s content modelling capabilities we believe it could be a powerful tool for people to explore graph databases using a GUI. There is also a case to be made for the use of graph databases in the Drupal ecosystem: sites that already use Drupal could benefit from its capabilities.

Drupal already had a module for Neo4j, that was originally built by Peter Arato, a former colleague. The module, developed a few years ago, however used the HTTP-only connector, and not the superior bolt connector. That is why we decided to reimplement the module, under a separate namespace.

With the bolt connector the new modules we created for Drupal 7 and 8 have a better performance. For both Drupal versions, the base module is an API module that provides settings for the connection and that supplies other modules with the connection object. This way developers can use the API module to build their own integrations (e.g. for applications that are contributed to the open source community or for integrations specific to an organisation).

Compatibility with Drupal 7 & Drupal 8

The module has support for both Drupal 7 and Drupal 8, however the versions have slightly different feature sets. Out of the box both versions have a page logging functionality that can help you discover browsing patterns of your visitors. The main difference is currently the rules support, as at this point we found it to be too much work to create a rules integration for Drupal 8. In the long term however there will be more possibilities with the Drupal 8 version, because it offers much richer APIs, allowing module developers to do even more.

At present the Drupal 8 integration only provides the default page logging functionality that stores the browsing journeys of your site’s visitors. It can however also be extended with a custom module to store other data. The Drupal 7 module has this page logging functionality and the Rules integration.

Link & Installation Instructions

The module is available on Drupal.org. For both versions, the PHP library dependencies are specified in a composer.json file. For D7, use Composer Manager, for D8, you can manage the composer dependencies globally. Consult the Drupal documentation on composer for more information.

Integration with the Rules module

Rules is a powerful Drupal module that enables site builders to define actions that will be executed when they get triggered by an event and when their conditions are met. With the help of Rules, it is possible to set up complex site behavior without having to write code. In other words, Rules turns clickers into developers. By building the Drupal connector module with a Rules integration, we’ve added a powerful content modelling tool to the Neo4J ecosystem that empowers non-coders to do complex things with graph databases.

For now the Rules integration in the Neo4J module requires you to execute a custom Cypher query as an action. In the future we could imagine creating a GUI that lets you compose the query so you could select the data sources and the way you want to store them in the database. This is something we could do if there is sufficient demand for it. At this point you can use data sources from Drupal by including the appropriate tokens as query parameters. You could for example use the {node__nid} token to refer to the currently active page context (more details in the example below). Using tokens, the Rules module allows you to hook into a wide range of processes that happen in Drupal, that can trigger almost any data available in the Drupal context to be stored in a graph database.

Try out the module

In our tutorial we’ve used the Drupal 7 module, since it has for now more interesting capabilities.

First, download the module into your local Drupal installation, and install the connector with composer. Download Neo4j, install, start it, open the web-interface on localhost:7474 and set the initial password. After you have enabled the Neo4j module, go to the configuration page, and enter the details for the connection.

After enabling the module, go to the Configuration page and click on Neo4j.

On the “General” tab, enter the credentials for your database. We recommend using the bolt protocol instead of http if it is available.

To enable page logging, check the “Page log” checkbox on the “Logging” tab and click on the “Save Configuration” button.

The page log feature will save 3 types of graph nodes: Page, User and Visit. The Page contains very basic information about the page itself. The User contains the user ID. These two are only recorded once. The Visit node contains data for the specific page visit, like the timestamp or the user’s IP address. The visit nodes are also connected for the same user, storing the user’s path on the site.

To set up the rules example, go to the rules admin page and create a new rule.

Add an event. For this example, use a content view of a content type.

When you add an action, select “Run cypher query”, and in the settings, enter the following query:

MERGE (e:Entity { entity_id: {node__nid}, entity_type: "node" })
WITH e
MATCH (v:Visit) WHERE id(v) = {visit}
CREATE (v)-[:SEEN]->(e)

This query uses two parameters. The first one {node__nid} is generated from Drupal’s replacement tokens. The second one, {visit} is a special pattern that references the id of the Visit node in the graph database (not the Drupal node), so it is easy to connect future nodes in the graph database to the current visit. To get the full list of available parameters (like {node__title} or field values), open the “Replacement patterns” fieldset.

In this example, MERGE (get-or-create) ensures that there is a node in the graph database for the Drupal node that is being visited, and that a connection is created between that node and the current visit.

After visiting a site with this plugin enabled, the graph that is created will look something like this:

How to create an integration module

The following tutorial shows how to create a simple module for Drupal 7. The Drupal 8 version of the API module is very similar, the main difference is that the Neo4j client object is available through a service, not as a global function.

Our example module will recommend content based on user data.

Create a directory called neo4j_hello_world in sites/all/modules/custom, and a file called neo4j_hello_world.info.

name = Neo4j Hello World package = Neo4j core = 7.x dependencies[] = neo4j

In the module file, create the info hook for the block

/** 
* Implements hook_block_info().
*/
function neo4j_hello_world_block_info() {
return [
'neo4j_recommendation' => [
  'info' => t('Neo4j content recommendation'),
  'cache' => DRUPAL_NO_CACHE,
 ],
];
}    

Following that, implement the block view hook

/**
 * Implements hook_block_view().
 */
function neo4j_hello_world_block_view($delta = '') {
 $block = [];

 switch ($delta) {
  case 'neo4j_recommendation':
    $block['subject'] = t('Recommended content');
    $block['content'] = [];
    if (($page_node = menu_get_object()) &&   !empty($page_node->nid)) {
    $recommended_nodes = 
_neo4j_hello_world_get_recommendations($page_node->nid);
      $links = array_map(function ($node) {
        return l($node->title, "node/{$node->nid}");
      }, $recommended_nodes);

      $block['content'] = [
        '#theme' => 'item_list',
        '#items' => $links,
      ];
    }
    break;
  }

  return $block;
}

This block only has content on node pages. The helper function _neo4j_hello_world_get_recommendations() returns the list of node objects, and the list gets transformed into links by array_map().

Finally implement the recommendation function that executes the Cypher query to get the recommended pages from the Neo4j database:

/**
* Retrieves a list of nodes that are usually visited by users who visit node/$nid.
*
* @param $nid
*   Page node id.
* @return array
*   List of recommended nodes.
*/
function _neo4j_hello_world_get_recommendations($nid) {
  $client = neo4j_get_client();

  if ($client) {
    try {
      $res = $client->run("
        MATCH (p:Page)<-[:OF]-(:Visit)-[:SEEN]->(pe:Entity { entity_type: {entity_type}, entity_id: {entity_id} })
        MATCH (p)<-[:OF]-(:Visit)-[prev:PREV*..10]-(:Visit)-[:SEEN]->(e:Entity)
        WHERE NOT e = pe AND e.entity_type = {entity_type}
        RETURN e.entity_id AS entity_id, avg(size(prev)) AS distance
        ORDER BY distance ASC
        LIMIT 10
      ", [
        'entity_id' => $nid,
        'entity_type' => 'node',
      ]);

      $nids = [];

      foreach ($res->records() as $record) {
        $nids[] = $record->get('entity_id');
      }

      $nodes = node_load_multiple($nids);

      $ordered_nodes = [];
      foreach ($nids as $nid) {
        $ordered_nodes[] = $nodes[$nid];
      }

      return $ordered_nodes;
    } catch (Exception $e) {
      watchdog_exception('neo4j hw', $e);
    }
  }

  return [];
}

In this function, first we make sure that the client is available. Then make sure that when you interact with the client object, you wrap the code in a try-catch block.

The most interesting part of this function is the recommendation-query itself. Let's have a look at the graph model again.

MATCH (p:Page)<-[:OF]-(:Visit)-[:SEEN]->(pe:Entity { entity_type: {entity_type}, entity_id: {entity_id} })

First it matches all pages for the Drupal node we're currently visiting which we already have visit nodes in the database.

MATCH (p)<-[:OF]-(:Visit)-[prev:PREV*..10]-(:Visit)-[:SEEN]->(e:Entity)

The second match matches the entities (Drupal nodes) that can be connected to the pages from the previous match with a distance of maximum 10 page visits.

WHERE NOT e = pe AND e.entity_type = {entity_type}

The WHERE statement filters the results from the previous matches, excluding the current entity, and narrowing the results to nodes.

RETURN e.entity_id AS entity_id, avg(size(prev)) AS distance

In the RETURN statement, a simple weight is generated, from an average of the distance between the entities. This weight will be too simple for most real world applications, but to keep things simple, it is sufficient for the scope of this example.

ORDER BY distance ASC
LIMIT 10

Finally order by the distance and take the first 10 items.

In an example graph starting from Entity 1 on the left, all these Entities (2,3,4) on the right would be returned as recommendations:

After the query, a foreach loop takes a list of node ids, and with a node_load_multiple() we load the nodes from the database that are then resorted.

Closing Thoughts

These were very basic examples of how the module can be used to start building a graph database. Please try it out and let us know how you would like to use the module, we would love to hear about any applications you think this could be used for. Also if you run into any errors you can report them in the project’s issue queue on Drupal.org</a>.

Neo4j is already used in production on Drupal sites, but all those implementations were one-off integrations. We hope that this project could be the start of a community effort for a full featured Neo4j integration that enables even complex use cases without much coding.

We at Pronovix are a Drupal consultancy, if you need a deeper integration, or if you would like to extend the functionality of the module please let us know us. We are specialised in documentation systems and developer portals, systems that need to deliver content in the context of a user’s activities and problems.

That is why we started working with Neo4J because we want to use it to deliver personalised help content proactively. We would like to become the go-to company for organisations that need help with their Neo4j project on Drupal. That is why we invest in this module and actively share knowledge about interesting problems graph databases can solve in the CMS world. If you want to get notified when we publish a new blogpost, sign up for our Documentation Automation & Personalisation, AI, And Graph Databases mailinglist.

If you want to chat with us, you can find us on the #neo4j-drupal channel in the neo4j.com/slack. Our company’s site is at https://pronovix.com. You can also contact us through our contact form, or connect with Kristof on Linkedin.

Thanks to my colleague Tamás Demeter-Haludka for co-authoring.

Jun 09 2016
Jun 09

When a problem arises in today’s attention deprived world, we can’t expect our customers to go search for a solution in the documentation. Documentation sites can be complex, they often store the documentation for multiple products and each of the products might have many features. In the best case you will frustrate your customer, in the worst case they might simply give up before finding the information they need.

That is why we developed the Walkhub Help Widget to help site owners guide their visitors to the right documentation content - right inside an application or web site. The simplest way to try out WalkHub Help Widgets is embedthedocs.com, but you can also set up your own widget creation interface easily if you have basic knowledge of web development. In this blogpost, we will guide you through the steps you need to take to replicate the functionality of EmbedTheDocs using Drupal as a content store.

EmbedTheDocs, the free UI for creating Help Widgets

In April we launched EmbedTheDocs.com, a service that lets you create an embeddable Help Widget. Our goal was to make it so simple that you should be able to create one under 2 minutes. Our widget allows users to list a series of online help content (such as technical documentation, articles, blog posts, videos, walkthroughs... anything linkable) relevant to a user’s context, that will open in the same browser window in a separate iframe. Once created on embedthedocs.com, the widget can be placed on any site via its unique embedcode. Anyone can freely try it out on our site after a quick registration.

Step-by-step tutorial: generating widgets from your own Drupal site

EmbedTheDocs is sufficient if you only need to create a few Help Widgets. In case you need something more complex, you want to have your own interface, add custom functionality to your widgets, or generate the content for the widget automatically in reaction to the user’s context, this article is for you.

As the EmbedTheDocs site is written on top of Drupal 8 CMS, it is possible to replicate the widget creation feature on other Drupal 8 sites, too. In this section, you will be guided through the process of replicating the widget creation feature, as on embedthedocs.com.

The following steps can be implemented either on an existing Drupal 8 site, or on a newly installed instance. If you don’t have a Drupal 8 site yet, you can install Drupal 8 on your localhost or a dedicated server (we recommend to test the features first on a local server) by following the standard Drupal installation instructions.

I. Setting up the widget elements with Paragraphs

The WalkHub Help Widget contains 3 different types of elements: groups, links and walkthroughs. Groups can be used as dividers for links and walkthroughs, but it’s not obligatory to add one. Links can target any content on the web. The YouTube video links will receive a YouTube icon in the widget and the video goes full screen when you click on its title. The third element is the WalkHub walkthrough, which can be added to the widget using its unique URL after you created one on next.walkhub.net. It’s free to add as many walkthroughs as you want on this site. Also, as WalkHub is open-source, you can fork or download it from GitHub.
Paragraphs module is a very powerful implementation of Drupal’s entity system. With the pre-defined paragraph types it is easy to compose content (e.g landing pages). So you could create other types of paragraphs that let you add different elements to your widgets (e.g. a video paragraph, with a proprietary video not hosted on Youtube).

Example widget with groups, links and walkthroughs
  1. Install the Paragraphs module with its dependencies (if you have Drush, use drush en paragraphs), go to /admin/structure/paragraphs_type and click on Add paragraph type. Type “Group” in the label field, then click on Save and manage fields. Group paragraph type
  2. Add a new plain text field with the label “Group name”. Then save the settings of the paragraph type. Group name field in group paragraph type
  3. Navigate back to /admin/structure/paragraphs_type where you can now see your first paragraph type listed. Paragraph type list with group
  4. Next create the second paragraph type. This paragraph’s label should be “Link” and will contain 3 fields: description (plain text), link (link) and title (plain text), the last two fields have to be required. The field list of the link paragraph type should look like this: Field list of link paragraph type
  5. The last paragraph type’s label is “Walkthrough” with one “Walkthrough link” field (link), which has to be set as required. Field list of walkthrough paragraph type
  6. Now you have all three necessary paragraph types: Group, Link, Walkthrough. Paragraph type list

Important! When adding the paragraph types and their fields, the machine names play key roles. The system will only work properly if you use the correct machine names for the paragraph types and fields.

II. Creating the Widget content type

  1. Go to /admin/structure/types and click Add content type. The new content type’s name should be “Widget” (the other settings can remain in the default state). Add widget content type
  2. Delete the automatically added “Body” field, and add a new one of the Paragraph type and label it “Widget elements”. The allowed number has to be unlimited so that users can add as many help items to a widget as they want to. Widget content type settings
  3. No other fields are needed for the widget creation, so let’s add a new node of this content type. Go to node/add/widget and feel free to add as many Widget elements as you want. The result should look like the following:
New widget node

III. Making the widget come alive

If you followed the steps in chapters I and II, you should now have a widget content type with one multiple value field for the three paragraph types. In the third chapter of this tutorial we install a complementary module for adding the content processing feature.

  1. Install the auxiliary module from https://www.drupal.org/sandbox/kittiradovics/2738613 into /module folder or in any subfolder of /module. Get more info on installing sandbox projects.
  2. Enable the Help Widget data processor module via /admin/modules, then go back to your previously created test widget node. This module’s first main function is to transform the paragraph elements’ content to a special JSON format, which can be processed by the WalkHub server in order to generate the widget iframe from the widget node. The Help Widgets are generated with the assistance of WalkHub, a microservice written in GO and React.js. The Drupal 8 site generates the resource in JSON, then WalkHub processes and displays it. For more information on the relationship, check our previous blogpost on EmbedTheDocs. You can also set up your own WalkHub server so that you can create walkthroughs on a system you control. This also lets you use your own server to display the widget iframe instead of ours.
  3. The content’s URL looks like /node/{nid} (replacing {nid} with the content’s id). If you modify this url to /json/{nid}, you will get the raw JSON formatted output of the test widget content (processable by the WalkHub server). The JSON output of the example is the following: JSON output of widget node The output is generated by helpwidget_data_processor/src/Controller/JSONOutputController.php. This file fetches the paragraph elements and their fields and pushes the text contents in an array. Then the JSON formatted output is generated by the JsonResponse class. The path for the text is defined in helpwidget_data_processor/helpwidget_data_processor.routing.yml file.
  4. In order to get the WalkHub server to process the JSON formatted output and render the widget, an embed code is needed. Go to admin/structure/block, scroll down to the Content region and click on the Place block button, choose Generated embed code block. You can use the default settings. Place Generate embed code block The block is created by helpwidget_data_processor/src/Plugin/Block/EmbedCodeBlock.php, which composes the embeddable code and also inserts it into the page’s source code so that the user can see the result after every modification in the bottom right corner of the widget node.
  5. The WalkHub server uses CORS headers when receiving the JSON formatted output. Drupal has an excellent module for sending CORS headers. Download and install the CORS module (or use drush en cors) and go to /admin/config/services/cors. Paste the following string in the domains field: *|http://next.walkhub.net|OPTIONS,POST,GET|Origin,Content-Type,Accept,X-CSRF-Token|true CORS module settings
  6. Go back to your widget node, and now you can see the embeddable code and the rendered widget in the bottom right corner. If you copy and paste the embed code into any of your sites’ HTML source, you will get the same button as on the widget node’s page.

If the result is not as expected, try to solve it by clearing the Drupal cache in /admin/config/development/performance. Feel free to extend the features or theme the widget node’s page.

Got stuck somewhere? Do you need help? Contact us for support!

How to choose between Embedthedocs.com and your own Drupal 8 site?

EmbedTheDocs.com is a convenient way to try out what the Help Widgets offer. If what you need are only a few widgets, EmbedTheDocs.com will suffice.
Your own, private Help Widgets system can offer some extras that proprietary and/or confidential materials may even require:

  • Store your help contents on the server of your choice, with your security and permission settings.
  • Have full control over access and management of your custom data stored in the Drupal system.
  • Customize the appearance of the widget nodes (Drupal enables easy theming).
Jun 07 2016
Jun 07

Part 1: Architecture summary
Part 2: Installation & Configuration
Part 3: Video & Playlist Management
Part 4: Including Videos & Playlists in Drupal content

In this multi-part blog post, we are covering the various aspects of the new Brightcove Video Connect module for Drupal 8. The first part consisted of an architecture summary and discussed the technical approach used during the development of the module. The second part detailed the installation & configuration steps required to get the module up and running properly. The third part illustrated the management of videos & playlists and discussed some of the changes compared to the Drupal 7 version of the module. This fourth part demonstrates how to add Brightcove videos & playlists into Drupal content.

This posts reads as a step-by-step guide for the following tasks:

Add Brightcove Video field

We will go through step by step how to add Brightcove videos into Drupal content. The same steps apply to Brightcove playlists.
Once we created the Brightcove Video and Playlist entities (or synchronised Drupal with Brightcove in case of an already-existing Brightcove account), we can include them in any other content type. We can do this via a new field: we add a new field to the chosen content type referring to the Brightcove Video or Playlist Entity.

Navigate to Structure > Content types and choose Manage fields.

Content types

Add field.

Manage fields

From Add a new field select Reference / Other.... Label this new field, then Save and continue.

Manage fields save

From Type of item to reference select Brightcove Video. Choose the Allowed number of values from the drop-down, then Save field settings.

Manage fields save field settings

You can edit further settings and add help text. Once done, Save settings again.
Our new field is ready to go: we can now include Brightcove videos in our content. To do this, we navigate to Content and Add new content (or select the existing content) of the type where we just included the Brightcove Video field.

Autocomplete field

By default, our new field uses the Autocomplete widget - so we can browse videos by starting to type in their names.

What if we have hundreds of videos on our Brightcove account? Then we might have trouble selecting them using the standard autocomplete widget for entityreference fields. Entity Browser module to the rescue! With this module, we can create our custom widget via Views to browse our videos. Let’s see how it works!

Browse Brightcove Videos using the Entity Browser module

First we need to download and enable the Entity Browser module: in Extend, find and choose Entity Browser via its checkbox then Install. You can find instructions on how to install modules in the Drupal 8 documentation.

Now we can set up our custom view that we will use for browsing our videos. Navigate to Structure > Views and Add new view. Give View name. From View settings select to show Brightcove Video then Save and edit.

In this example we will use the Table format and we Add the following fields: Name, Created, Thumbnail and Entity browser bulk select form. To add this Entity browser bulk select form is very important, otherwise we cannot select our videos. The rest of the fields are all a matter of taste, you can add whichever fields you need.
For now, we will use here a mini pager and display 3 items per page.

Click +Add in the Displays section and choose Entity browser, then Save.

Then choose Add in the Fields section and choose Entity browser bulk select form. We are automatically switched to the form's configuration. Once you applied your settings, Save the Display section again.

The next step is to set up the entity browser widget, which we will use instead of the standard autocomplete widget for browsing our Brightcove Videos. This form depends on Chaos tool suite (ctools) module, so make sure it is installed and enabled. Navigate to Configuration and select Entity browsers in the Content Authoring section.

Click Add Entity browser.

Enter a Label for the entity browser. Select Modal from Display plugin. Select the Single widget selector plugin for now - we will discuss another solution in the browse and upload new Brightcove video section!
Choose No selection display as the default Selection display plugin. Feel free to play around with the other options. Click Next.

Next, we get to the configuration settings for the modal display plugin’s width and height - we can go with the default settings. Give a Link text for the button link and then go to the Next step.

There are no available configuration options for the next two steps (Widget selector and Selection display), so just click Next in both cases. In the final configuration step, choose View from the Add widget plugin dropdown. Give it a Label. Finally, select the newly created entity browser from the View display list, then hit Finish.

We are almost done! We still have to tell Drupal that we want to use our entity browser (instead of the default autocomplete) to select our videos for the Brightcove video field (in whichever content type we included it in).
Navigate to Structure > Content types and this time choose Manage form display from Operations on your relevant content type.

Change the widget settings: choose Entity browser instead of Autocomplete for our freshly created Brightcove video field.

There is no entity browser selected yet. We select via the configuration icon of the field.

Select Brightcove video browser widget (or whatever name you chose for your entity browser) as the Entity browser. Choose Entity label for Entity display plugin. Update and then Save settings.

Our Brightcove video browser widget is all set up and ready to be used for adding videos into our Drupal content.
Navigate to Content and Add content (or select an existing one) of the type that includes the Brightcove video field.
We can see the new Select videos button (that is the label we gave), instead of the autocomplete field.

Let’s click on Select videos: we get a pop-up where we can browse our uploaded videos more conveniently. We see the fields we set up in our custom widget view for each video, in this example that was Name, Created, Thumbnail and we get a checkbox for each. You select via checkboxes then affirm by clicking Select videos.

After selecting the videos for the Drupal content, we can Remove and Edit each. To finalize this video addition to the content, Save and publish.

Upload Brightcove Videos from Drupal content using the Inline Entity Form module

It's even possible to upload Brightcove Videos and Playlists into your Brightcove account from Drupal content with the Inline Entity Form module. This feature is already included in the Brightcove module, we just need to do some configuration.
Navigate to Structure > Content types and choose Manage form display from the Operations on the video-containing content type.

Instead of the Entity browser widget, this time we want to choose the Brightcove Inline entity form - Complex widget. It is preconfigured, we only have to Save.

Navigate to Content and Add content, the Brightcove video field now shows the Add new brightcove video button.

Click on it, and we can see the same interface showing up as in part 3's Video upload and edit chapter.

Follow the steps in the “Video upload and edit” section then Save. We are done, the video is included in our content (both in Drupal and in Brightcove, as they are synced).

What if we want to be able to browse existing videos and upload new ones in the same field? Is that possible in D8? Yes, it is. All we need to do is to enable the Entity Browser IEF (Inline Entity Form) submodule, and do some configuration. Let’s see how it works!

Browse and upload from the same field in your Drupal content, using the Entity Browser IEF submodule

Navigate to Extend and enable the Entity Browser IEF submodule.

Navigate to Configuration and select Entity browsers from Content Authoring. It is a prerequisite to have the entity browser, you find its setup guidance in the Browse Brightcove Videos using the Entity Browser module chapter of this blog post. In the following steps we will do some changes to that configuration.
Choose to Edit the entity browser.

Change the Widget selector plugin from Single widget to Tabs.

Hit Next until you get to the last configuration page (before Finish). In the Add widget plugin choose the now available Entity form. Give it a Label then change its Entity type and its Bundle both to Brightcove Video. Click Finish.

Navigate to Structure > Content types and choose Manage form display from Operations on your relevant content type. Change the widget settings to Entity browser, the same way we did in the Browse Brightcove Videos using the Entity Browser module chapter of this blog post.

Now navigate to Content and Add content (or select an existing one) of the type that includes the Brightcove video field and click on the Select videos button.

We can see that the new Upload tab appears next to the Select tab, and if we click on it the same form comes up like in this blog post's part 3's Video upload and edit chapter. We fill the form and then click Select videos in the end.

And that’s it, we can select our existing videos and upload new ones in the same place. We can even do this from CKEditor!

Browse and upload Brightcove Videos from CKEditor

Download and enable the Entity Embed and Embed modules, and of course the CKEditor module if it is not enabled yet.

Navigate to Configuration and in the Content authoring section, select Text editor embed buttons.

Choose to Add embed button.

Enter a Label for the embed button. In Embed type select Entity. In Entity type select Brightcove Video. Select the entity embed display plugins that you want to allow - we will leave it empty to allow them all. In Entity browser select the browser you configured. If it is not created yet, please follow the instructions in the Browse Brightcove Videos using the Entity Browser module chapter of this blog post. Upload Button icon for easier distinction.

Before we continue, we need to adjust our entity browser. We must change the Display plugin from Modal to iFrame. CKEditor dialogs are always modal and currently Drupal 8 cannot handle subsequent modal calls, which is a known issue - until that's fixed, we use the iFrame Display plugin.
Navigate to Configuration > Entity browsers in the Content authoring section and choose to edit the browser widget. Change the Display plugin to iFrame. Click through Next until the final configuration page then hit Finish.

Now go back to Configuration and this time choose Text formats and editors in the Content Authoring section.

Choose to Configure the text format where you want to add the entity embed button. For Text editor set CKEditor. In the Toolbar configuration section drag and drop the previously created button from the Available buttons row to the Active toolbar. You can create a new group for it if you want to, like in this example we added the Entity browsers group. In the Enabled filters checklist opt in Display embedded entities then Save configuration.

Navigate to Content > Add content, choose your content type. Give it a Title. In the Body section, select the Text format where you previously added the Entity Embed button. Click on the embed button (if there are more buttons, hovering over them will reveal their functionality).

A modal display will show up to select videos.

We can browse our existing videos and choose them via their checkboxes.

Alternatively, we can upload new Brightcove videos the same way as we did in the Browse and upload from the same field in your Drupal content, using the Entity Browser IEF submodule chapter of this blog post.

Once the video(s) are selected, we can set the way we want to display it (Display as), the View mode, Align_ment and we can also add a _Caption. The default view mode on these configuration options usually contains all properties of the video. We can customize this by creating a new view mode for the Brightcove Video entity then configuring its display. When everything is set, hit Embed.

Our Brightcove video is embedded in the text field, we can Save and publish our content.

This fourth part concludes the blog series. We hope the information provided will prove useful to everybody setting up Brightcove Video Connect in Drupal 8.

Part 1: Architecture summary
Part 2: Installation & Configuration
Part 3: Video & Playlist Management

May 27 2016
May 27

Part 1: Architecture summary
Part 2: Installation & Configuration
Part 3: Video & Playlist Management
Part 4: Including Videos & Playlists in Drupal content

In this multi-part blog series, we are covering the various aspects of the new Brightcove Video Connect module for Drupal 8. Part 1 consisted of an Architecture summary and discussed the Technical approach used during the development of the module. Part 2 detailed the Installation & Configuration steps required to get the module up and running properly. This third part illustrates the management of Videos & Playlists and discusses some of the changes compared to the Drupal 7 version of the module.

Video listing

Once videos have been “imported” from Brightcove or uploaded through Drupal, a listing becomes available in an intuitive interface (with a similar layout to Brightcove’s own Studio interface) located in a tab right next to Drupal’s main Content tab:

Brigthcove Videos list in admin_content

The new listing pages allow you to manage videos in a streamlined manner - something that wasn’t possible in the previous Drupal 7 versions as the video listings were limited and only accessible through an overlay while Attaching a video to a node.

Video upload and edit

When uploading a new video (or editing an existing one), a major improvement over previous Drupal versions is that the upload/edit screen is no longer presented in an overlay - but in the same layer as the other configuration screens:

Add/Edit Brigthcove Video

As can be seen above, tags now include an autocomplete feature. The Related Link URL now also includes autocomplete, letting you search for Drupal nodes:

Autocomplete related link URL

The video upload section has been improved by allowing a wider variety of audio and video container formats, and both the video and image source files can now be replaced with new files on existing assets:

Video upload section

The Availability section has also been improved with a new calendar dropdown:

Video availability section

Finally, not only can videos be uploaded and edited in an efficient manner, but also deleted (deleting Brightcove videos wasn’t possible in the previous Drupal 7 versions):

Video delete

Playlist listing

A listing similar to the Brightcove Video is also available for Playlists:

Playlist listing

Smart Playlist edit

Tags are also autocompleting in the Smart Playlist edit screen as can be seen below:

Smart Playlist tag autocomplete

Manual Playlist edit

Manual Playlists also feature an autocompleting field - this time for the individual videos to be included in the playlist:

Manual Playlist tag autocomplete

Part 4 of this multi-part blog series will demonstrate how to include Brightcove Videos & Playlists in Drupal content.

Part 1: Architecture summary
Part 2: Installation & Configuration
Part 4: Including Videos & Playlists in Drupal content

May 19 2016
May 19

Part 1: Architecture summary
Part 2: Installation & Configuration
Part 3: Video & Playlist Management
Part 4: Including Videos & Playlists in Drupal content


In this multi-part blog series, we are covering the various aspects of the new Brightcove Video Connect module for Drupal 8. Part 1 consisted of an Architecture summary and discussed the Technical approach used during the development of the module. This second part details the Installation & Configuration steps required to get the module up and running properly.

The only element in common between the 8.x-1.x version and the previous 7.x-6.x version of the Brightcove module is the PHP-API-Wrapper library used to assist in the communication between Drupal and the Brightcove API. Installing the PHP library in the previous 7.x-6.x version required downloading and extracting the library into sites/all/libraries, followed by a “composer install.” This is no longer necessary in the 8.x-1.x version because the PHP library is included as a dependency in the module’s composer.json file.

Installation steps

The following steps require Drush and will install the Brightcove module as well as all of the module’s dependencies, including the PHP library...

1. Download the Brightcove module $ drush dl brightcove

2. Install the library dependency (PHP-API-Wrapper)

The recommended method for installing the library dependency is to reference the Brightcove module's composer.json inside the extra section of the root composer.json file as described in Managing dependencies for a custom project.

After adding the brightcove/composer.json path to the merge-plugin section (in the extra section) of the root composer.json, it should look similar to this:

        "merge-plugin": {
            "include": [
                "core/composer.json",
                "modules/brightcove/composer.json"
            ],
            "recurse": false,
            "replace": false,
            "merge-extra": false
        }

After the extra section has been modified, run composer update in the root folder to install the required libraries. (note: composer is required)

For more information, see Using Composer with Drupal

3. Enable the Brightcove module (this will also install all dependencies) $ drush en brightcove

Configuring permissions

The module includes a list of permissions which should be configured if non-admin users will require privileges to manage the Brightcove API credentials, videos or playlists:

configuring permissions to manage Brightcove API credentials, videos or playlists

Configuring API credentials

Once the module and all it’s dependencies have been installed, you can enter your Brightcove API credentials into the Brightcove API Clients configuration page - which is linked from Drupal’s Configuration page:

Brightcove API Clients configuration page

The Brightcove API Clients page lists the configured API credentials and allows you to add new credentials:

Brightcove API Clients list

After clicking Add Brightcove API Client above, the following screen will appear where you can enter your Brightcove Client ID, Secret Key and Account ID:

Brightcove API Clients new credentials

If the Client ID, Secret Key and Account ID entered above pass verification from Brightcove, then the API Client will be saved successfully:

Brightcove API Clients successfully added new client

Synchronization

The most significant difference between the Drupal 8 and previous versions of the module is that videos are now synchronized between Brightcove and Drupal, using Brightcove as the source of truth. This allows users to “import” all of their existing Brightcove videos into Drupal after the module is configured. Not to worry, the actual video files will not be downloaded from Brightcove into Drupal - only the metadata and images associated with the videos. The synchronization option is available in the Brightcove Status Overview page which is linked from the Drupal Reports page:

Drupal Reports page

The Brightcove Status Overview displays the synchronization status of all the various entities, and also includes buttons for managing the queues:

Brightcove Status Overview via Reports page

Clicking “Sync all” above will synchronize all listed Brightcove entities into Drupal - which is useful in order to do an initial batch sync. Synchronizing the entities manually is not necessary, however, as the synchronization will run in the background through Drupal’s cron.

Brightcove Status Overview via Reports page after sync

Part 3 of this blog series will illustrate the management of Videos & Playlists and discuss some of the changes compared to the Drupal 7 version of the module - especially the new video listing interface (with a similar layout to Brightcove’s own Studio interface) and autocompleting tags feature.


Part 1: Architecture summary
Part 3: Video & Playlist Management
Part 4: Including Videos & Playlists in Drupal content

May 08 2016
May 08

In this multi-part blog series, we will be covering the various aspects of the new Brightcove Video Connect module for Drupal 8. This first part consists of an Architecture summary and the Technical details surrounding the config and content entities.

Part 1: Architecture summary
Part 2: Installation & Configuration
Part 3: Video & Playlist Management
Part 4: Including Videos & Playlists in Drupal content

Architecture summary

The Drupal 8 version of the Brightcove Video Connect module was rewritten from scratch in order to take advantage of the architectural changes in Drupal 8, especially the new Entity Data Model. Drupal 8 core and its contrib modules handle many of the functions that had to be custom-written for the Drupal 7 module. This new Drupal 8 module actively utilizes the Inline Entity Form module and there is support for Entity Browser, therefore fitting nicely into Drupal 8's entity system architecture. Since Drupal 8 core also includes well rounded Views support out of the box, most of the module development was attributed to the module’s data synchronization via Brightcove’s API.

Designed around the new entity system in Drupal 8, the new Brightcove module seamlessly integrates video publishing into the Drupal editorial workflow and interface. This alleviates the fragmented editorial experience typically associated with 3rd party video hosting services.

Technical details

The Drupal 8 version of the Brightcove Video Connect module sports a number of config and content entities. The three major building blocks are:

  • API Client config entity: holds all the data needed to connect to the Brightcove API utilizing the PHP wrapper library.

  • Brightcove Video content entity: a required entity reference to the API Client config entity, all the data that is supported by the Brightcove API and the PHP wrapper library but the video file itself, and possibly other Drupal-only fields as this entity type is (Drupal-) fieldable.

  • Brightcove Playlist content entity: a required entity reference to the API Client config entity, all the data that is supported by the Brightcove API and the PHP wrapper library, a multiple-value entity reference field to Brightcove Videos in case of a manual playlist, and possibly other Drupal-only fields as this entity type is also (Drupal-) fieldable.

There are various other smaller content entities, but they're mostly hidden from the user, such as:

  • Custom field content entity: this stores the definitions about the custom fields for each API Client. These fields are dynamically generated on the Video entity’s form, and handled through API calls, like the default value, description or the saved value. The custom field values are also stored on the Video entity.

  • Player content entity: Stores some minimal information about the player config, like width and height. These values are applied to the player display if possible.

  • Text Track entity: Holds all metadata about the text tracks, after the ingestion the uploaded file is removed.

Synchronization of content between Brightcove and Drupal is a two-way thing.

  • When a change is made to a Brightcove-related Drupal entity on the Drupal site/side, the module pushes those changes to Brightcove immediately.

  • The module has a built-in mechanism to "download" changes from the Brightcove site to the Drupal site, which may occur by three different triggers.

    • First of all, the module uses Drupal's cron system to download changes from Brightcove to Drupal when the last change dates are different on any given content entity. When all changes have been downloaded to the Drupal site, the synchronization starts over again.

    • Secondly, the site administrator can initiate finishing the current synchronization in a batch process, initiate a completely new synchronization, or stop the currently running one from the admin interface (see below).

    • Thirdly, when the user wants to edit a Brightcove-related content entity on the Drupal site and the last change date of that entity is newer at Brightcove, a message is shown to the user with a link that downloads the latest data from Brightcove to Drupal before the user makes changes to it. It also checks if the video was deleted from Brightcove Studio, in this case the user can delete the local version or recreate it (however the video file won’t be available).

  • For more detailed information about the content synchronization from Brightcove to Drupal, see the comment for the _brightcove_initiate_sync() function in the code.

For various tasks, several already-existing Drupal (contrib) modules are used.

  • The Time Formatter module is nothing more than displaying a number of seconds (either an integer or a float) in fancy formats like "16h58m17s".

  • The Entity Browser module can be used eg. for selecting videos for a manual playlist.

  • The Inline Entity Form module is used for creating and storing informations about the text tracks, currently only new text tracks can be created or deleted, but it is not possible to edit them for now through Drupal.

Part 2: Installation & Configuration
Part 3: Video & Playlist Management
Part 4: Including Videos & Playlists in Drupal content

The new Drupal 8 module was developed by Tamás Nagy and me, CSÉCSY László.
Jan Mashat was the project manager and László Brindza was responsible for testing.

Apr 21 2016
Apr 21

The video recordings of the lectures held on the Documenting APIs mini-conference are now available on our dedicated event page.

On March 4, 2016 we helped organise a special whole-day meetup in London on the Write The Docs conference, in which the community discussed the tools and processes used to document APIs.

We recorded the sessions, mashed them up with tweets and summaries and published them.

On the page you will find the following content:

  • James Stewart, Director of Technical Architecture at GDS: Intro and welcome to GDS
  • Rosalie Marshall, Tech Author at GDS: Understanding the needs of API documentation users
  • Ellis Pratt, Technical Communicator and director at Cherryleaf: Aye, Aye, API - What makes Technical Communicators uneasy about API documentation, and what can we do about it?
  • Christian Vogel, RAML: A Quick Introduction to RAML
  • Ole Lensmar, Chairman of the Open API Initiative and CTO of SmartBear Software: Swagger
  • Kristof Van Tomme, CEO Pronovix: Code sample libraries in Drupal, using the GitLab field module
  • Alexander Browne, HMRC product manager: The HMRC developer portal
  • Andrew Marshall, technical author: The potential of API docs to evolve technical architecture and API design (TBC)
  • Paul Mackay, Technical Lead for the DCLG Local Waste Service Standards Project: Local digital standards for waste service in government
  • Chris Smith, lead technical architect at Companies House: Introducing Swaggerly
  • Kyle Fuller, API Blueprint: Documenting APIs for Humans
  • Kim Stebel, Tech Author: Interactive API documentation
  • Roger Sheen, Information Architect & DITA Open Toolkit Collaborator, Documentation Maintainer, Infotexture: “API Docs in DITA”

To stay informed about the London WTD events, click here.

If you think your followers would be interested in the sessions, please, send a tweet, share us on Facebook, or LinkedIn. We are looking for people interested in API documentation for similar future events in the Write the Docs community.

We are planning an event on May 22nd in Portland and another one in Washington DC some time in October. Want to get notified about events like this?

Apr 18 2016
Apr 18

While in the past accessibility was often only perceived as a nice extra, it is quickly becoming the norm: in most countries legislation dealing with accessibility currently only affects web pages, but PDF documents might follow soon. With good cause: worldwide approximately 285 million people are visually impaired and have difficulties to read online documents without assistive technologies.

As an addition to our PDF in Drupal series (PDF in Drupal part 1 and part 2), we researched the subject of accessible PDFs: how can writers create content in a way that it becomes accessible to users with disabilities? We’ll highlight checking mechanisms and tools and end with listing three types of the available assistive technologies that make content accessible.

What is an accessible PDF?

PDF, the Portable Document Format, is a widely used standard document type on the internet. Users can convert electronic documents and scanned images into a PDF file, and distribute it easily via email. When implemented properly, PDF content becomes accessible to users with disabilities such as blindness and low vision or of a cognitive or learning nature (e.g. dyslexia).

How to make PDF accessible

Document authors can choose from a range of possibilities to create accessible PDFs. A few examples.

Tags

Tags contain little pieces of metadata creating a hidden structured, textual representation of the content, thus becoming available for screen reader programs and other assistive software. Tagging doesn’t influence the visual integrity of a PDF file: the look of the document remains the same. By adding tags, the content creator defines the exact order of reading, which makes it easier for users to interpret the document structure and navigate through the content.

Alternate text (alt text)

Alternate text provides text-based information about the hyperlinked web page or the inserted image. If an image is not visible due to software errors or because the user is visually impaired, the alt text will provide a text equivalent to the missing information. The example shows an alternate text that describes an image, taken from the blogpost Publishing a code sample book from Stackoverflow to LeanPub using Drupal and GitLab.

Other tips to improve accessibility:

  • Show the logical structure of a document by inserting headers
  • Add navigation labels, such as headings
  • Choose software that creates accessible documents (if this is for a web application, you could integrate an open source library like iText that supports accessible PDF)

Checking accessibility

Ideally, checking the accessibility of a PDF document should the last phase in its creation process. Most PDF creating software provide this possibility.

Software applications like PAC 2 offer possibilities to check the accessibility state of your document.

According to Adobe's guide about creating accessible PDFs, accessibility issues often appear in

  • documents containing only scanned images of text (and without content available to screen readers)
  • documents without tags
  • documents without alt text on images or on links

Assistive technologies to access and check content

Authors can use the same assistive technologies that are used by their audience to test the accessibility of a created document.

Text-to-speech software provides auditory feedback for documents or website content:

  • The Read and Write for Google Chrome extension helps users with cognitive or learning difficulties access Google Docs documents and webpages.
  • Balabolka is downloadable TTS software. It has a portable version that can save on-screen text as WAV or MP3 files.

Speech-to-text (voice recognition) software takes and transcribes audio content into written words.

    Available for Windows 7, 8, 10 and OS X.

Screen magnifier software makes it possible to enlarge screen content and provide auditory feedback.

    Windows, OS X and Linux-based operating systems have built-in screen magnifiers.

Conclusion

The goal of accessibility is to ensure that every person, with or without disabilities, has equal chances and possibilities to access your content. Creating accessible PDF files can help to reach that goal. With quickly changing technology the creation process of accessible documents gets more complex, but the need to provide them grows at the same time.

We’d like to highlight some sources providing information and tools:

Apr 15 2016
Apr 15

Even though it has become much easier to create embedded help experiences, many software products still do very little to integrate their help content into their application. In this post we will explain why embedded help leads to better experiences, why we built our Help Widget, and give you an overview of its architecture.

Why you should embed your help content

Printed documentation manuals are a thing of the past, or are they?
Very few projects take full advantage of the new capabilities that a connected world is offering. Most documentation efforts for web applications follow the paradigms developed in a time when documentation was a stand-alone printed deliverable, prepared as a reference source that customers would use to solve their problems.

If your documentation is not readily accessible from your application this is a missed opportunity: your customers are getting a worse experience and your support team is paying the price. Bombarded by an ever increasing torrent of information and impulses, people's average attention span is getting shorter. Users are impatient, expecting just enough information right when and where they need it.

Embedded help anticipates a user’s need for help and supports through examples or a walkthroughs in situ - or just the relevant morsels from the documentation - with the least disruption to workflow and focus. It is only a breadcrumb trail that leads back to the original action.

Actual manuals only come into play once the same users want to learn a complex new skill or process, gain a deeper understanding and confidence by having a reference.

Relevant help content embedded in the interface saves time, improves user experience and reduces support calls.

There are a few paradigms of embedding help content into a web application, you can read our overview about them in this previous blogpost. Take into account that your app will be changing, because it well should and will change: inline help needs rewriting, walkthroughs may break.

The embed help widget we created is your quick and simple solution to your UX problems without/while redesigning your app. A widget that opens on top of your application or website: you can pop up text, walkthroughs, videos etc. You can link in the relevant parts of your evolving documentation, explain complexities without crowding the app's UI. The widget's content is rendered by our Drupal CMS, so while it looks part of your interface the help content can be edited independently on the fly.

Embed any kind of online help resource into your webpage or web application. Serve contextual links from your documentation system.

Why we built the WalkHub Help Widget

We announced this January that Walkhub had been rewritten: it now uses Go and React.js. We also introduced our brand new WalkHub help widget and our intention to set up a Drupal 8 site where registered users will be able to create their own widgets. This site, embedthedocs.com is the result.

We created the EmbedTheDocs freemium community service for the purpose of allowing everyone (even those who are not familiar with web development) to create their custom instances of Help Widget for embedding documentation, including but not at all limited to walkthroughs. With this tool you can generate a widget in no time as it does the dirty work for you.

create: register/log in, create help widget, add content via form, save and test; embed: copy js embedcode, embed in your app, your widget is live; iterate: edit widget's content anytime

You can read more information about the Walkhub Help Widget in our previous blogpost and on EmbedTheDocs.com itself.

If you're curious about how widgets are generated technically with the assistance of EmbedTheDocs or if you'd like to do some fine-tuning, the next section will be interesting for you.

How it works

Drupal 8 provides the content and the Walkhub server processes it

widget created: drupal saves widget form, drupal transforms content into json, every json outpur receives unique url, url is accessible to anyone; code embedded: js code connect with walkhub server, walkhub server receives json output via its url, walkhub server builds widget content from json output; content iterated: widget's content mirrors any changes made in the form

We have separated the widget generation into two fundamental pillars: the user specific content elements (groups, links and WalkHub walkthroughs) and the engine, which generates the widget itself.

After registering and logging into the site, you can freely start adding a custom Help Widget, which is technically a node created of our widget content type in the Drupal 8 system. This content type has a simple multiple value paragraph field, which allows people to add their group-, link- or walkthrough elements as they wish:

How to create a widget

After saving the content, it is processed in the background by our custom module which uses Drupal 8’s impressive controller and routing system to generate a special JSON output of the paragraph field values. Finally the rendered JSON file can be reached through the embedthedocs.com/json/{nid} url. Our module also creates a block with the embed code, which already contains the generated JSON file’s path, so it’s ready for use. After saving the widget content you can instantly see how your widget is going to look like on the bottom right corner of the content’s page.

The WalkHub Help Widget

Once you are finished creating your own widget node on our Drupal site, you only need to copy and paste the generated embed code in your website’s source code. The code also contains the WalkHub Record button by default, so you can create walkthroughs easily on the target site. If you don’t want the Record button to be generated into the code, simply uncheck its box when editing your widget node. You can of course generate as many widgets as you need. In a Drupal system the easiest way to embed the widget’s code is to create a custom block and paste the code into the block’s body (it only works with text formatters that allow div and script tags). Once you are successfully done with this part, you can see the orange “Get help” button in the bottom-right corner of your site. You can also relocate the button easily by altering the data-position attribute of the div tag (bottom-right, bottom-left, top-right and top-left positions are available).

Your help widget is actually generated by the Walkhub engine. The server receives the JSON formatted file from the embedded code in the data-list-url attribute, and creates an HTML iframe object with the assistance of the client.js and embed.js JavaScript files (the generated embedcode already contains them) . Then it extracts the information from the data-list-url attribute for building the content for the widget using React.js components. The browser uses CORS headers for verification.

It should also be noted that thanks to Drupal’s flexible content editing feature, an existing widget's content can be edited anytime on the fly. The widget adapts to content-changes immediately on every site where its code has been embedded: the JSON formatted source file mirrors the widget-node’s content.

How to serve widgets from your own Drupal 8 site

You don’t necessarily need EmbedTheDocs to create Help Widgets, you could also generate them from your own Drupal 8 site on your own server.

This is where things get really exciting! With your own site you could serve documentation content that is targeted for a specific user, or make a widget that automatically recommends relevant content depending either on the page that a user is visiting or on their role. You could add a support chat, or a search function that looks for relevant documentation, ...

The Help Widget is generated using the WalkHub engine which is part of the project that we open sourced previously. We haven’t created a feature with the configurations to make a Help Widget module but this shouldn’t be too much work. If there is sufficient interest we will make a package that explains how it is done.

If you are interested in creating your own server for aggregating and serving your documentation, let us know here!

Apr 06 2016
Apr 06

The paragraphs module makes it easy to arrange content on your site, but it limits your creative freedom. First, we’ll explain how we use the module and then why creative constraints are actually a good thing, because they make you more productive, and paradoxically help you be more creative...

What is the Paragraphs Module ?

Previously, we listed some tips on targeted web content. Here, we want to share what we’ve learned building landing pages using the paragraphs module in Drupal.

“The Paragraphs module comes with a new "paragraphs" field type that works like Entity Reference’s. Simply add a new paragraphs field on any Content Type you want and choose which Paragraph Types should be available to end-users. They can then add as many Paragraph items as you allowed them to and reorder them at will. Paragraphs module does not come with any default Paragraph Types but since they are basic Drupal Entities you can have complete control over what fields they should be composed of and what they should look like through the typical Drupal Manage Fields and Manage Display screens.” (drupal.org)

Paragraphs can be anything you want, e.g. an image with a text block, a headline with a call to action, a slideshow. Paragraphs are predefined and you can use them independently from one another.

Developers create paragraphs depending on the customer’s needs. The number of paragraph types is usually limited to increase workflow efficiency, but can be extended at will.

We’ve been using paragraphs to create long form landing pages, with the kind of single page responsive layouts that gained prominence in the startup world. With this technology it is quick and easy to set up layout formats starting from your textual content.

For Pronovix.com, currently we use these paragraph types to construct a landing page:

Paragraph types for pronovix.com landing pages

Let’s take a closer look at three examples: 1. “Hero shot with a call to action”, 2. “Three Column Benefits”, 3. “Tips”.

  1. The paragraph type “Hero shot with a call to action” helps you to grab the attention of your readers and to activate them. For this paragraph, we can fill out the following fields:
  2. Example of a Hero shot with a call to action paragraph from the WalkHub landing page.
  3. The “Three Column Benefits” paragraph type shows three advantages of your product side-by-side. The benefits are brief and to the point, in three columns, combined with catchy icons. For pronovix.com, we’ve built a bootstrap icon library into our paragraphs implementation, you can use any of the glyphicons without having to search and upload them into the site. This single feature saves us a lot of time.
  4. Example of a Three Column Benefits paragraph from the WalkHub landing page.
  5. When we select “Tips” we can combine an icon with a headline and a short text to point out specific characteristics of the product. Within this paragraph type we have an icon field - a headline field - a text field. The icon field contains entity references. We can choose icons from the already uploaded icon collection, but it is also possible to create a new icon entity and add it to the existing collection.
  6. Example of a Tips paragraph from the WalkHub landing page.

Intelligent Constraints = Increasing Efficiency

When we got the green light for our Apigee Developer Portals Workshop, there were only three weeks left before the event. We had to construct a landing page quickly to be able to announce the workshop in time.

By then we already had our workflow refined for creating a simple landing page:

  1. Collect and organize the relevant information, then fill out our landing page content form.
  2. Pick a paragraph type for each chunk of content on the fly.
  3. Add the design elements required by each paragraph form.
  4. Rearrange/change/edit paragraph entities if needed.

Once we have this, creating the actual landing page is mostly filling forms: the configuration options and required fields for each paragraph type are predefined. Just enough to create a visually pleasing result - all the while dramatically shortening the process by limiting the options, leaving the focus on content. Because of this workflow, all parties involved are less reluctant to run further iterations on the copy and the layout/design elements.

Limited options that lead to a creativity boost

With too many options to choose from, people find it very difficult to choose at all (The Paradox of Choice - TED Talk). Embracing our constraints (Creative constraints can lead to amazing work, Boosting creativity through constraints, Embracing constraints) may indeed boost our creativity. Though even MacGyver would need more than his Swiss knife to make a landing page, the principle remains… Having less options sharpens your mind: it makes you efficient.

Combining possibilities and limitations

The paragraphs module...

  • … helps you to focus. Too much choice can paralyze you - the module guides you through your ideas.
  • ... will help you to meet that deadline.
  • ... fits into the corporate style guide. This saves editing time and fastens the publication process.
  • ... helps you to be efficient.

At Pronovix, we use the paragraphs module almost every day to create new web pages. We continuously evaluate and improve our landing page creation process: we were already able to shorten the feedback process and reduce the number of editing rounds before publishing. Two remarks, though. 1. The paragraphs module claims to be giving back the power to the content editors. But without developer skills editors are not able to change the paragraph types to meet their needs themselves. Close co-operation between developer and editor is still necessary to define and customize the paragraph types that will be available to editors on your site. 2. Post-editing could use a handier interface. Now several of the same paragraph types on one page are indistinguishable in edit mode unless unfolded.

We are working on an audience-focused landing page canvas (that we will publish under a Creative Commons license in the near future) to complement the form we published earlier. To be continued…

Do you also use the paragraphs module? Leave us a comment!

Mar 17 2016
Mar 17

Most SaaS integration services that synchronise user accounts, do a one-way sync that copies over to new accounts. PieSync, from Ghent, Belgium, has developed a two-way sync platform, with various sync settings, so you can sync contact information between your favorite cloud apps. Unlike many other sync account companies, PieSync:

  • offers full sync in both (or multiple) apps
  • weeds out duplicates
  • brings all existing information together, also the data that existed before you started using PieSync
  • automatically reflects changes and updates that occur in one app, in the other(s).

Concrete: By using PieSync, you can integrate all or part of your Google Contacts data in Mailchimp and the other way round. When you make a change in one of these apps, the other app will be updated immediately. No messing around curating data, so you save time.

Syncing between Drupal and Google Contacts

We’ve been talking with Piesync about creating a module to sync user profiles between Drupal and Google Contacts, your CRM and other cloud apps. The tricky part is that in Drupal the user profile can be arbitrarily extended, and when you have additional fields you probably also want to synchronise them. So, a Piesync module will need to be able to map user fields to an object that is synced with PieSync (default PieSync object and you map the fields to that, then two-way syncing). Drupal sites operate in an environment with increasingly specialised SaaS platforms (e.g. invoicing with Xero, contacts in Google Contacts, Salesforce as a cloud CRM) that are not interrelated, so a sync module will save you from manually importing all that data across these apps, ensuring accuracy and saving you time. The added bonus is that this sync will make Drupal a central base that keeps data consistent across your apps.

PieSync already provides syncing possibilities between many SaaS apps:

Syncing with PieSync: connections currently available.

Why use a commercial service for syncing? The APIs (application program interface) of SaaS and Cloud apps change regularly. Even popular projects that integrate with third party APIs, e.g. the Hybridauth module, or Facebook Connect, sometimes break when the module is not updated in time to follow API changes. Ideally it would be the responsibility of the API owner to maintain their Drupal integrations, but not everyone does this, and most site owners don’t have the budget or skills to follow these API changes.

We want to partner with Piesync who will guarantee API functionality.

Another advantage of Piesync is that it becomes easier to change apps, because you can seamlessly sync your data. This would also allow you to postpone choosing certain cloud services that interact with your user data, until after you have finished your site building project.

Would you use PieSync’s Drupal module? Tell us how you would use it and we will let you know as soon as the module is out!

About Drupal Sun

Drupal Sun is an Evolving Web project. It allows you to:

  • Do full-text search on all the articles in Drupal Planet (thanks to Apache Solr)
  • Facet based on tags, author, or feed
  • Flip through articles quickly (with j/k or arrow keys) to find what you're interested in
  • View the entire article text inline, or in the context of the site where it was created

See the blog post at Evolving Web

Evolving Web