Add-ons

Drupal Kit add-ons are extra features designed for specific use cases, such as profile pages for faculty or staff, news, and events. They are not included with the base distribution, but are separate packages that must be added to a site’s codebase by a developer.

Contents

Add-on architecture overview 

Drupal Kit add-ons are Composer-compliant Drupal modules. They contain a base module with a composer.json that allows the package to be retrieved using Composer commands (see next section). An add-on’s sub-modules provide discrete functionality (content types, taxonomies, views) designed to allow developers to extend specific components of the add-on without overwriting code or configuration.

Add-ons use Drupal’s Configuration Management system to install components to the site database. The Profile add-on, for example, includes a utprof_content_type_profile module, which includes a config/install directory that creates the Profile content type and its fields. Importantly, those configuration files represent the parts of site functionality that ITS maintains. It is the responsibility of the developer to avoid directly overriding add-on configuration so that new features and bug fixes can be cleanly applied during Drupal database updates. See “Maintaining and extending add-ons,” below).

Managing add-ons with Composer 

Unlike previous versions of Drupal where additional features were directly downloaded and added to the codebase, Drupal now embraces Composer as a package management tool. A Drupal Kit site codebase includes a top-level composer.json file which defines all components that constitute the codebase.

Accordingly, developers fetch Drupal Kit add-ons by leveraging Composer commands. The recommended commands for including specific add-ons are listed with each add-on, below.

Special cases: Add-ons as starter code 

Note

If a given add-on appears to be a good starting point but would require extensive customization to meet a site’s use case, developers may consider using an add-on as a starting point for full customization. This effectively means that the developer is now wholly responsible for maintaining the code over time. In this scenario, the developer would not use Composer to manage the package (and could disregard the installation instructions below) and instead would retrieve the code from GitHub, locate it in modules/custom, and customize as needed.

GitHub repositories for the add-ons:

Profile: https://github.com/utdk/utprof/releases
News: https://github.com/utdk/utnews/releases
Events: https://github.com/utdk/utevent/releases

Managing user permissions for add-ons 

After enabling an add-on, users must be granted permission to create and configure content. For example, to create News articles, a user must have the “News article: Create new content” permission. Some add-ons provide developer tools to add appropriate permissions to Drupal roles (see below), but permissions can also be managed manually through the UI.

Site managers may set which Drupal roles have specific permissions. Modifying user roles and permissions as needed is an acceptable form of Drupal Kit customization.

Maintaining and extending add-ons 

ITS recommends that developers use Composer to retrieve new features and bug fixes that ITS provides over time (e.g., composer update utexas/utprof). Using this approach, developers should treat add-ons as inherited code and should not directly modify the content types, block types, views, or other configuration bundled with the add-on. For this reason, ITS initially sets Drupal’s configuration interface for these add-ons to be read-only.

Extending code can take different forms. It might mean configuring a new Drupal View that provides a different listing, or adding a new View Mode to style items differently, or simply modifying a theme template. Developers unfamiliar with extending Drupal should talk with the Drupal Kit team before proceeding: email drupal-kit-support@utlists.utexas.edu .

Profile add-on 

The Profile add-on provides the ability to create persona-based content in flexible, templated displays. The most common uses for the Profile include faculty and staff directories, endowed positions, donor lists, and featured students. Read more about the functionality of this add-on at Creating Profiles.

Upon installation, a new content type, “Profile,” will be available for adding individual nodes, as well as a block type, “Profile listing,” for creating lists of Profiles. Both have dependencies on two taxonomies, “Profile Groups,” and “Internal Profile Tags,” used for categorizing profiles and creating scoped lists.

Installing using Composer 

With a properly scaffolded codebase on your local machine (see Scaffolding), run the following command to add the Profile code to your site:

composer require utexas/utprof

Enabling functionality 

After installing a site, enable the modules that come with the add-on:

Block Type - Profile Listing: Provides a block type that displays a View, passing filter values for tags and groups.
Content Type - Profile: Provides a content type component for the ‘Profile’ module.
Profile: Base module that provides the generalized ‘Profile’ supporting components. Does not have functionality on its own.
Vocabulary - Groups: Provides the ‘Groups’ vocabulary component for the ‘Profile’ module.
Vocabulary - Tags: Provides the ‘Tags’ vocabulary component for the ‘Profile’ module.
Demo Content - Profile: Install demonstration profiles for evaluation purposes.

Drush command-line equivalent:

drush -y en utprof utprof_block_type_profile_listing utprof_content_type_profile utprof_view_profiles utprof_vocabulary_groups utprof_vocabulary_tags utprof_demo_content

Applying updates 

Updates to add-ons are announced in the Changelog and release notes. When an update to the Profile add-on is available, the following command will overwrite the version currently installed with the latest minor version release:

composer update utexas/utprof

Major version releases, which would introduce backwards-compatibility breaking changes, will include specific update instructions.

Extending functionality 

There are a number of ways developers can responsibly customize the Profile add-on:

Customize theme-level display by adding targeted CSS overrides in a custom theme.
Modify the display of the Profile node type by copying the template located at modules/utprof_content_type_profile/templates/node--utprof-profile--full.html.twig into a custom theme and modifying the display.
Modify variables sent to the template through a template_preprocess_node() implementation (see modules/utprof_content_type_profile/utprof_content_type_profile.module as a model).
Supplement the display options for “Profile listing” block types. This block type includes 3 default display options: “Prominent,” “Basic,” and “Name only.” These are provided by Drupal view modes. Developers can add display options by creating and configuring new view modes (rather than modifying the 3 defaults).
Modify the display of existing “Profile listing” block type view modes by copying the appropriate template located at utprof/tree/develop/modules/utprof_content_type_profile/templates into a custom theme and modifying as needed.

Profile permissions 

The Profile add-on includes a predefined set of permissions associated with content editing and management of the add-on which can be assigned to any role in the system. This capability, and typical usage, is described in more depth on the Site configuration page.

Developers who use drush may assign these permissions via the command line as follows:

drush utprof:grant --set=manager --role=<machine name of role>
drush utprof:grant --set=editor --role=<machine name of role>

News add-on 

The News add-on provides the ability to create timely content. News articles can be attributed authorship and assigned to top-level categories and open-ended tags.

Installing using Composer 

With a properly scaffolded codebase on your local machine (see Scaffolding), run the following command to add the News add-on to your site:

composer require utexas/utnews

Enabling functionality 

After installation, you can now enable the modules that come with the add-on:

Block Type - News listing: Provides a block type that displays a View, passing filter values for tags and categories.
Content Type - News Articles: Provides the ‘News articles’ content type for the ‘News’ module.
Demo Content - News: Install demonstration news articles for evaluation purposes.
News: Base module that provides the generalized ‘News’ supporting components. Does not have functionality on its own.
View - News Listing Page: Provides the listing page for the ‘News’ module.
Vocabulary - News Authors: Provides the ‘News authors’ vocabulary component for the ‘News’ module.
Vocabulary - News Categories: Provides the ‘News Categories’ vocabulary component for the ‘News’ module.
Vocabulary - News Tags: Provides the ‘Tags’ vocabulary component for the ‘News’ module.

Drush equivalent:

drush -y en utnews utnews_block_type_news_listing utnews_content_type_news utnews_demo_content utnews_view_listing_page utnews_vocabulary_authors utnews_vocabulary_categories utnews_vocabulary_tags

Applying updates 

Updates to add-ons are announced in the Changelog and release notes. When an update to the News add-on is available, the following command will overwrite the version currently installed with the latest minor version release:

composer update utexas/utnews

Major version releases, which would introduce backwards-compatibility breaking changes, will include specific update instructions.

News permissions 

The News add-on includes a predefined set of permissions associated with content editing and management of the add-on which can be assigned to any role in the system. This capability, and typical usage, is described in more depth on the Site configuration page.

Developers who use drush may assign these permissions via the command line as follows:

drush utnews:grant --set=manager --role=<machine name of role>
drush utnews:grant --set=editor --role=<machine name of role>

Events add-on 

The Events add-on provides the ability to create single and recurring events that can be viewed individually and within listing blocks or the events page (/events). Read more about the functionality of this add-on at Creating Events.

Installing using Composer 

With a properly scaffolded codebase on your local machine (see Scaffolding), run the following command to add the Event add-on to your site:

composer require utexas/utevent

Enabling functionality 

After installation, enable the modules that come with the add-on:

Event: Base module that provides the generalized ‘Event’ supporting components. Does not have functionality on its own.
Content Type - Event: Provides the ‘Event’ content type for the ‘Event’ module.
View - Event Listing Page: Provides the listing page for the ‘Event’ module.
View - Event Listing Block: Provides the custom listing block type for the ‘Event’ module.
Vocabulary - Event Location: Provides the ‘Event Location’ vocabulary component for the ‘Event’ module.
Vocabulary - Event Tags: Provides the ‘Tags’ vocabulary component for the ‘Event’ module.
Demo content: - Provides vocabulary terms and nodes that can be used as a starting point to evaluate the capabilities of the Event add-on.

Drush equivalent:

drush -y en utevent utevent_block_type_event_listing utevent_content_type_event utevent_demo_content utevent_view_listing_page utevent_vocabulary_location utevent_vocabulary_tags

Applying updates 

Updates to add-ons are announced in the Changelog and release notes. When an update to the Event add-on is available, the following command will overwrite the version currently installed with the latest minor version release:

composer update utexas/utevent

Major version releases, which would introduce backwards-compatibility breaking changes, will include specific update instructions.

Event permissions 

The Event add-on includes a predefined set of permissions associated with content editing and management of the add-on which can be assigned to any role in the system. This capability, and typical usage, is described in more depth on the Site configuration page.

Developers who use drush may assign these permissions via the command line as follows:

drush utevent:grant --set=manager --role=<machine name of role>
drush utevent:grant --set=editor --role=<machine name of role>