City of Helsinki - KASKO Drupal project

KASKO, short for kasvatus ja koulutus, is the site for the department responsible for childhood and education in the city of Helsinki. The site includes multiple unit searches and a bit complex system built using the Group contrib module for upper secondary schools.

Environments

Env	Branch	Drush alias	URL
development	*	-	https://helfi-kasko.docker.so/
production	main	@main	TBD

Requirements

You need to have these applications installed to operate on all environments:

• Docker
• Stonehenge
• For the new person: Your SSH public key needs to be added to servers

Create and start the environment

For the first time (new project):

$ make new

And following times to start the environment:

$ make up

NOTE: Change these according of the state of your project.

Login to Drupal container

This will log you inside the app container:

$ make shell

Instance specific features

The KASKO instance has multiple React searches and features provided by the Group module.

Custom paragraphs

After-school activity search (after_school_activity_search)

This search paragraph lists TPR units that are tagged with the unit_type vocabulary term After-school activity.

• The filter search is a View (after_school_activity_search) with exposed filters. The View configuration can be found in here.
• No React front.
• The paragraph has editable title and description fields
• Can be added to landing pages and the lower content region of standard pages.

Daycare search (daycare_search)

This search paragraph lists TPR units that are tagged with the unit_type vocabulary term Daycare.

• The filter search is a View (daycare_search) with exposed filters. The View configuration can be found in here.
• No React front.
• The paragraph has editable title and description fields
• Can be added to landing pages and the lower content region of standard pages.

Group news (group_news)

The Group news paragraph lists latest news of a selected group. The block uses a View called latest_group_news that has two displays for different amount of news listed.

The number of news items to be displayed can be selected from the paragraph field field_group_news_number_of_news. This selection determines the View display to be used. The related logic can be found in the hdbt_subtheme under the group news paragraph template here.

Additionally, the paragraph has a field called field_group_news_group_id that is used to identify the group whose news should be displayed, and a field called field_group_news_archive where you can define the landing page to which the paragraph should link. The paragraph also includes editable fields for the title and description.

You can add the paragraph to landing pages and the higher and lower content regions of standard pages.

Group news archive (group_news_archive)

The Group news archive is simple paged list of all news the selected group has. The paragraph includes only one field called field_group_news_group_id that is used to identify the group whose news should be displayed. The list is a View called group_news_archive and its configuration can be found here. You can add the paragraph to landing pages.

High school search (high_school_search)

The High school search lists high schools, also referred to as upper secondary schools in this instance. This search was one of the first implementations of the unit searches, and it has a slightly different structure compared to the After-school activity search, Daycare search, and Playground search.

The units are selected manually in the paragraph field field_hs_search_units, and the View filters the TPR units to display based on the field's content. It is also possible to change the form's submit button text by writing the desired text in the field_hs_search_meta_button field. The results are displayed in two tabs, allowing users to either list schools or display them on a map.

The exposed form has additional functionality provided by high-school-search.js, which makes it possible to select a value only for the Emphasis or Mission drop-down. This helps avoid searches that yield no results.

• The filter search is a View (high_school_search) with exposed filters. The View configuration can be found in here.
• The results can be displayed as a list or on a map.
• No React front.
• The paragraph has editable title, description, units and search button fields.
• Can be added to landing pages and the higher and lower content regions of standard pages.
• The javascript high-school-search.js can be found here.

Playground search (playground_search)

This search paragraph lists TPR units that are tagged with the unit_type vocabulary term Playground.

• The filter search is a View (playground_search) with exposed filters.
• No React front.
• The paragraph has editable title and description fields
• Can be added to landing pages and lower content regions of standard pages.

School search (school_search)

The School search paragraph provides a tabbed interface that allows users to either find the nearest school by entering a street address or find any school by filtering through the school's information. The search results are displayed in a tabbed format, offering both a list view and a map view.

This search functionality is built with React and utilizes a Views listing (comprehensive_school_search) as a fallback when JavaScript is disabled. All React-based searches are located in the hdbt theme, where most of the related logic is implemented.

• The fallback listing is a View called (comprehensive_school_search) and it doesn't have any filters. The fallback View configuration can be found in here.
• The search has a React front and the code can be found here.
• The paragraph has editable title and description fields.
• Can be added to landing pages.

Vocational School Search (vocational_school_search)

The Vocational school search was created based on the High school search, so it has similarities in the implementation details.

The units are selected manually in the paragraph field field_vs_search_units, and the View filters the TPR units to display based on the field's content. It is also possible to change the form's submit button text by writing the desired text in the field_vs_search_meta_button field.

• The filter search is a View (vocational_school_search) with exposed filter. The View configuration can be found in here.
• No React front.
• The paragraph has editable title, description, units and search button fields.
• Can be added to landing pages and the higher and lower content regions of standard pages.

Custom roles

Daycare editor

This user role grants administrative access to daycare TPR units on the site. Permissions are provided by the helfi_kasko_content module. Users can enrich TPR unit content categorized under daycare. The category assignment is based on the ontologyword_ids associated with the TPR units. Read more about TPR unit categorization here.

Playground editor

This user role grants administrative access to playground TPR units on the site. Permissions are provided by the helfi_kasko_content module. Users can enrich TPR unit content categorized under playground. The category assignment is based on the ontologyword_ids associated with the TPR units. Read more about TPR unit categorization here.

Comprehensive school editor

This user role grants administrative access to comprehensive school TPR units on the site. Permissions are provided by the helfi_kasko_content module. Users can enrich TPR unit content categorized under comprehensive school. The category assignment is based on the ontologyword_ids associated with the TPR units. Read more about TPR unit categorization here.

Upper secondary school editor

This user role is designated for the upper secondary school editor. However, it does not provide direct permissions to edit nodes. To gain these permissions, users must be assigned to an upper secondary school group, which grants the necessary editing rights for nodes within the group. This group grants other required permissions such as to use media entities and access to TPR units and services entities. More information about groups can be found here.

Groups

KASKO has the Group contrib module enabled. This module restricts upper secondary school editors’ access to a specific set of nodes and allows them to create dedicated website for their school within the KASKO instance. Groups are used only for upper secondary schools and the groups can have standard pages, landing pages, news items and announcements inside the group content.

There is also a custom module called helfi_group that modifies group menus, alters the standard translation features for nodes under group control, and allows TPR unit entities to be managed within the group.

• The custom module helfi_group can be found from here.

News feature

Since groups can have their own news items, the news feature is enabled in the KASKO instance, but it is limited to upper secondary schools. Each school can publish its own news, which is displayed within the school’s specific area. Other KASKO-related news is created in the Etusivu instance in the same manner as other news, and the enabled news feature does not affect this process.

Common issues

The list of all groups (/admin/group) is empty even there is multiple groups in the database:

Only users with Administrator role (not even Super administrators currently) are able to see all groups and assign members to groups that they are not members themselves. If you are a member of a certain group, but you don't have the Administrator role, you can see the group that you belong to on the listing.

Group news

Each of the upper secondary school groups can have news specific to their school. The news items are functionally the same as those used in the Etusivu instance, but they are limited to the school's designated area. News is displayed in two different paragraphs: Group News and Group News Archive.

News items also have the Override Node Options feature enabled, which is not part of the standard installation. This allows upper secondary school editors to override the News Item Published option without needing permissions to create news items outside the group they belong to. The override node options functionality is provided by the override_node_options contrib module.

Group menus

Each upper secondary school (high school) has their own group menu. This group menu is used on subpages of the school, and it can be edited by the group members under the group configuration. The basic functionality of the Group modules group menu has been customized in the helfi_group custom module. The group menu is displayed using a block that is assigned to the First sidebar region and has been restricted to Group type Upper secondary school.

• Read more about the customizations here.

Customizations

TPR unit template overrides

The basic TPR unit template is overridden in hdbt_subtheme so that different kinds of school cards are rendered in a specific way. You can check the template in here.

Also the TPR unit ontology word details template is overridden in hdbt_subtheme in a more detailed way. Check out the template here.

TPR unit categorization

In KASKO instance the TPR units are categorized based on some of the ontology IDs they have in the TPR API. The categories are then saved to a field called Categories in the helfi_kasko_content custom module in this file. The categories are then used on role assignment based on unit category and as search filters.

• Read more about the implementation from the helfi_kasko_content custom module here.

TPR unit custom fields

KASKO has some additional fields on TPR units.

Categories (field_categories)

Field categories is used to save the TPR unit categorization that is done based on the ontologyword_ids. Read more about it in the TPR unit categorization section.

Announcements for user with role "comprehensive school editor"

Comprehensive school editor (peruskoulun sisällöntuottaja) can create, edit, translate and delete their own announcements. They can also see all unpublished announcements. An form alter has been created for announcement node. It prevents comprehensive school editor from creating a site wide announcement.

[DEPRECATED] High school front page (field_hs_front_page)

Reference field where the upper secondary school (high school) front page used to be added. Appears to be unused and possibly deprecated field.

Ontologyword details (field_ontologyword_details)

This field is used to save language program and weighted curriculum education information for TPR units. If the information is present it is shown on the TPR unit entity page. This field is also used in filtering the High school search results. The field rendering is done in the hdbt theme here.

Study field (field_study_field)

Taxonomy term reference field that is used to categorize the vocational schools. The field is used in filtering the Vocational school search.

Globally available TPR unit fields with customizations

The following fields are available globally for all instances to use, but in KASKO, they are customized compared to the standard format.

Hide description (hide_description)

This is a simple boolean field that determines if Description field is shown on the TPR unit page. The field is used in the hdbt theme here.

Contact details of daycare centre groups (subgroup)

As the human-readable name suggests, this field includes contact details of daycare centre groups. The information is displayed on the TPR unit page if there is data in the field and the unit is of type daycare. The field rendering is done in the hdbt theme here.

News item pattern

The news item pattern in KASKO is customized compared to the standard format. In KASKO, news items are always related to an upper secondary school and are displayed within the school’s designated area. The pattern is designed to accommodate this setup. The customization is done in custom module called helfi_kasko_config. You can check the code in here.