HPC Content Module
This is the drupal 9 codebase for the HPC Content Module site.
HPC Content Module is the content backend for the Humanitarian Actions site.
Content
The main content type for the site is the article
(node) which is mainly
composed of paragraphs. Articles can contain sub-articles (nested articles).
Other content types that have their own pages are the stories
(short text,
video and/or image) and the achievements
. Those are mainly shown inside
articles but have pages for social media sharing purposes.
The paragraphs that can be used inside an articles are:
Achievement
: A reference to anachievement
nodeBottom figures row
: A list of figures with a label and a valueFacts and figures
: A list of images with a short textFurther reading
: A list of external links with their sourceInteractive content
: A graph/table/map embed from datawrapperNeeds and requirements
: A reference to aneeds and requirements
termPhoto gallery
: A gallery with up to 4 photos and a descriptionSection index
: Essentially a table of content with a list of articlesSeparator
: A simple line separatorSignature
: USG's signatureStory
: A reference to astory
nodeSub-article
: A reference to anotherarticle
nodeText
: A text paragraph with optional footnotes
In addition the system has a few taxonmy terms:
Appeals
: Type of appeal like RRP, 3RP etc.Interactive content type
: Graph, Map etc.Needs and requirements
: "People in Need", "People targeted" and "Requirements" figuresSection
: Section an article belongs to, like "Introduction"Story type
: "Story from the field", "Multimedia" etc.
and media types:
Author
: An author with an image, name and titleImage
: An image with a description and creditsVideo
: A youtube video with credits
Paragraphs are arranged inside an article using the layout paragraphs module which provides a more intuitive interface than the default paragraph widget, in addition to its core layout selection feature which is, however, not used.
Languages
The site is multilingual with English as default language and allowing Arabic, French and Spanish translations.
Views
have been created to provide overviews of the publication and
translation status of the different entities (nodes, media, terms) used on the
site with links to create, edit or view those entities in different languages.
Themes
The site uses the DSS common design and views and paragraphs for the content.
Theme customizations are in the Common design subtheme. The site extensively uses CSS components. See the README for more details.
Modules
The main contrib modules for this site are the paragraphs related ones (see composer file.
In addition, the site has several custom modules. Most of the modules prefixed
with gho_
have been inherited from the former GHO site, of which this site
has been forked. The modules prefixed with ncms_
are specific to the
functioning of this site as a content backend.
-
The gho_access module provides granular view permissions for node and media entities as well as handling the access to images on public pages, and a permission to assign roles. This module also controls the visibility of content in a given language based on the
published
andpromoted
status of the homepage in that language. -
The gho_download module provides a route to have permanent download links of the PDF version of an article (when available).
-
The gho_fields module provides various field formatters, widgets and templates for example to format and translate
needs and requirements
figures, embeddatawrapper
graphs etc. -
The gho_figures module provides facilities to import
needs and requirements
figures from a spreadsheet. -
The gho_footnotes module provides extraction and formatting of footnotes from
text
paragraphs andstories
. -
The gho_general module provides tests of the site as well as general customizations like "add content" action links for the different content admin pages (
/admin/content
), a custom translation manager to keep the admin UI in English, blocks for the header and footer and handling of youtube videos embeds. -
The gho_graphql module provides a GraphQL API that allows external access to published content.
-
The gho_layouts module provides addition layouts to use with modules relying on the Layout API to arrange display (ex: layout builder module or layout_paragraphs in the case of GHO). This module provides notably a layout plugin to handle configurable grids with any number of areas. Note: This not really used.
-
The ncms_publisher module provides a "publisher" entity that allows the definition of external content consumers. Defining a "publisher" allows this external service to better integrate its workflow with this site.
-
The ncms_ui module provides UI additions that allow this site to function as a backend-only site. Full page node views are disabled and replaced with modal previews. Login is required for any interaction with the site.
The site has 1 more custom module that could/should be separated from this site codebase to be independent module that other sites could use:
-
Linked Responsive Image Media Formatter
The linked_responsive_image_media_formatter module, in addition to competing for the longest module name, provides a formatter for image media types. This formatter can be used to display the image using responsive image styles and with extended linking options: link to content, link to media, link to image and custom link that can use
tokens
. It also offers the opion to set a customalt
text usingtokens
as well and an option to display the image as background for the link, using thealt
text as text for the link.In the case of this site, this formatter is used to link placeholder images to
datawrapper
pages.
Notes
Some notes related to the initial installation and development are available in the notes.md file.
Local development
HPC Content Module (CM) uses docksal which is a web-development environment based on docker.
Install docksal: https://docksal.io/installation
You will need to create a local environment file in the ./.docksal folder and adjust it to match your local requirements.
touch ./.docksal/docksal-local.env
Refer to ./.docksal/default.docksal-local.env for required environment variables.
Once the above steps are complete, from the project root, run:
fin init-site
This will install all required packages via composer and setup the local settings files.
For docksal to run, you will need to stop any other webserver or service on your system that might bind to port 80.
DATABASE SETUP
A database has been created automatically as part of the stack setup above.
Pull a database dump from here to get a fresh copy and seed your local database.
COMPOSER
Using docksal, you can run any composer command as fin composer {COMMAND}.
DRUSH
Drush commands can be run as fin drush {COMMAND}. Eg:
fin drush cr
Local testing
Run local test via docksal
fin phpunit
You can follow what happens in the selenium controlled browser during functional and javascript tests by going to this url
http://localhost:7901/
Run the tests as they would in GitHub Actions
./.github/tests/test.sh