Senior Backend Engineer
Always looking for a challenge, Marc tries to add something new to his toolbox for every project and build — be it a new CSS technology, creating custom APIs, or testing out new processes for development.
October 15, 2024
For higher ed institutions and nonprofits, Localist is a powerful resource that provides a valuable means of centralizing your organization’s events into a single branded calendar. However, integrating that event data into a Drupal website in a seamless way can pose a significant challenge.
At Four Kitchens, we recently completed a custom module for a client that can regularly import events from Localist into their higher ed site. After finishing the project, it dawned on us that the Drupal community could benefit from our work. In keeping with our commitment to sharing knowledge with our community, we rebuilt it as a contrib module, so it’s available for your organization, too.
During this rebuild, there were several lessons that we thought were valuable to share to aid other developers who also build custom modules.
Setting functional goals
Before we get into the challenges and lessons we learned, let’s talk about what this module does and how it can help your organization import event data from Localist.
The Localist platform offers an API, but it requires time and development resources to create a custom Drupal module that satisfies your organization’s data requirements. This module simplifies the work needed to import event data from Localist into Drupal by using Drupal’s plugin architecture. Fundamentally, this module uses Drupal’s migration APIs to handle all of the heavy lifting. However, we needed to add custom plugins and functions to handle the Localist API specifically.
Additionally, migrations in Drupal are usually a one-time import — for example, migrating data from an older Drupal 7 site to a newer Drupal 11 site. With event data, importing needs to happen regularly, so this module is designed to import data roughly every hour.
Finally, we decided to build a UI, include optional installable examples (using Drupal’s new Recipes initiative!), and include a code generator that guides a developer to quickly get started building their own event migrations required to import the data.
The information imported from Localist is then stored in fields on a Drupal content type to display however you’d like. If your organization already uses Localist to manage events, you can now display that information in a consistent way on your own website.
Shifting a custom solution to a community contribution
Transforming a client-specific module into a contrib module for the wider Drupal community required extra work, but those efforts are true to our values of sharing knowledge and enabling others to benefit from our research.
Remember the last time you went searching for a module to perform a specific functionality, found it, and installed it? Not only did that experience save you development time, but it also showed the power of the open source community.
Shared modules provide ready-made solutions to common challenges, allowing developers to focus on innovation rather than reinventing the wheel.
Challenges and lessons in developing a community-ready module
When building a custom module, you develop with many assumptions in place because the config and code are already in place for a known environment. When building for the community, you have to consider a multitude of scenarios and edge cases. You have to factor in how the module may be used, how it may interact with other modules, and other unknowns.
Additionally, sometimes there can be some very client-specific requirements that don’t make sense for a contributed module. For the client we originally built this for, we built in special functions to handle the formatting and styling of the event dates. To translate this module into a contrib module, that functionality had to be removed, as we can’t make those same assumptions for everyone. We just want to ensure the baseline functionality is in place so your team can then build off that foundation — ultimately saving you time.
Of course, these modifications work both ways. Your organization may need this type of contrib module, but perhaps its functionality doesn’t align with your website’s requirements. Four Kitchens can work with your organization to tailor the module to your needs. Just let us know how we can help.
Translating a custom module for broader use
Rebuilding this custom module to a contrib version required extra time, planning, and testing to suit the broader Drupal community’s needs. It ultimately helped us learn that in the future, we may want to flip the script and try to develop a contrib module first, and then override in our own code to customize per client. In this way, the base functionality is available to all.
If you are a developer who creates custom modules, think about the goals of your module and ask yourself if your idea would also benefit the community as a whole. Building a contrib module from the get-go may be far more efficient than taking a custom module and turning it into a contrib module later.
Below, we’ll share some examples of a few changes we made as part of the rebuild of the Localist module and the reasoning behind the change. We hope this helps other developers think outside the box and determine if a contrib module may be a better idea as a starting place.
| Functionality | Client project | Contrib module |
| Preflight and prerequisite checks | Did not exist. We assumed all of the config, fields, and taxonomies were in place. | We incorporated additional functions to verify that the right connections are in place and that config was correctly set up and working. A green check displays before the user proceeds with any data imports from the Localist database. This is important to make the module future-proof. |
| User interface changes | The settings form only had one field for the API URL and one field for the group. All of the other settings were hard-coded in the codebase, which made things simple to configure for the client, but inflexible for the community. | The module now features a visual status area displaying preflight checks. Below, additional fields allow the user to supply custom migrations. The settings page also includes the ability to create an example migration. |
| Structural changes | The location of the settings form was in a custom area, and permissions were integrated with client-specific permissions. | The settings form was moved to a standard Drupal location with module-specific permissions added. Additionally, a more robust Drupal service was created to allow some methods to be used outside of this module if needed. |
| Migration examples | None | Since Drupal migrations can be difficult to understand, we provide an optional installable example to show how the module works to help a developer get started. |
| Documentation | Minimal. The original custom module included just enough to learn about the custom plugins and how to extend the existing built-in migrations. | Extensive. Documentation describes in detail how to override and create new migrations, usage of the custom plugins, installation, and troubleshooting. |
| Default configuration | Already in place as part of a client project, so the module assumes the config was there. | This module not only gives the default settings when it is installed for some needed processes, but also lets you add more settings for the examples. All of these settings must be different and not conflict with an existing environment. |
| Custom client-only functionality | A lot of custom code was written to support specific use cases for the client’s website. | Some of this custom code was removed for the contrib version of this module. Some details, such as formatting dates, satisfy very specific use cases, and generally it is best not to make any assumptions when developing for the community. |
The value of contributing to the Drupal community
Contributing to the Drupal ecosystem through contributed modules benefits the entire Drupal community. By making our work available to others, we collectively elevate the capabilities of the platform and empower developers worldwide.
While this specific rebuild required a bit of extra time, it fosters a culture of knowledge exchange and mutual support. Each contribution, no matter how small, adds to the platform’s versatility and appeal.\We hope that by sharing our experience of moving a module from custom to contrib, we empower other developers to consider building contrib first to give back to the community, collaborate with others on additional features, build more robust and better documented modules, and hopefully save a little time in the end.
Making the web a better place to teach, learn, and advocate starts here...
When you subscribe to our newsletter!