This page documents the changes and customisations made to the WordPress theme. Although based on Picostrap5, we've primarily used it for SASS compilation, with most aspects significantly modified.
All changes have been made to picostrap5-child-base.
The 404.php file shares code with a page located at /redirect-404/, which uses the page-redirect-404.php page template. This shared code is found in /includes/redirect.php. This setup exists because Sitesucker does not capture a 404 page. By using this structure, we can demonstrate most of the functionality within the WordPress environment and generate a static page. The static page is renamed to 404.html during the publishing process.
archive.php is used to display a keyword listing page. This code iterates over each page, retrieving custom field terms via the SCF plugin. It skips pages that have terms containing the word "Archive" and outputs the title and excerpt for each remaining page.
footer.php
In addition to outputting markup for the Ask the Library panel, the Acknowledgement of Country, and the RMIT footer, footer.php also includes links to JavaScript files:
/js/main-body.js - Handles the hamburger menu, embed mode, and dark mode switcher. (Note: Some dark mode code is located in header.php to expedite the display of dark mode.)
/js/iframeResizer.min.js - Handles resizing of iframes on the page.
https://rmitlibrary.github.io/cdn/libraries/js/iframeResizer.contentWindow.min.js - Manages the page being resized by others in embed mode.
functions.php
The functions.php file is a key component in any WordPress implementation. For the Learning Lab, it contains 150 lines of code used by either the theme or plugins. Beyond that, there are a series of functions written specifically for the Learning Lab:
formatAfterTheColon: Capitalises text after the first colon in a string.
doContextMenuAccordion: Creates an accordion menu for the hamburger menu.
doChildrenList: Lists the page's children as links.
prepend_slash_to_relative_urls: Adds slashes to relative URLs.
custom_remove_pagination_limit: Removes pagination limits for certain queries.
custom_order_archives_by_title: Orders archive posts alphabetically by title.
picostrap_all_excerpts_get_more_link: Appends '...' to excerpts and sets excerpt length to 50 words.
Disable wptexturize: Prevents WordPress from converting straight quotes to curly quotes in content, titles, and comments to avoid issues in code blocks and shortcodes.
In addition, there are links to two files located in the /includes/ folder: redirect.php and json-export.php, as well as a link to _main.php located in the /custom-shortcodes/ folder.
There is scope to divide this file further and distribute code among files in the /includes/ directory.
header.php
The header.php file sets up the head and initial body sections of each page, including the top navigation bar and navigation menu.
Head Section:
Executes wp_head() to include meta tags, styles, and SEO scripts via plugins.
Adds meta tags for author, geo-location, and Dublin Core metadata.
Includes tracking scripts for Microsoft Clarity and Google Analytics.
Implements a style fix for WordPress admin bar overlap.
Contains a script for managing dark mode based on user or system preferences.
Body Section:
Outputs the top navigation bar and navigation menu.
Uses doContextMenuAccordion to display main sections within the menu. Note that page IDs may vary and need updating for different WordPress setups.
Includes a hard-coded "Subject support" accordion for specialised links, grouped to avoid overcrowding the menu and homepage.
Provides a theme switcher to toggle between system, light, and dark themes.
Additionally, a variant named header-style-site.php exists, using different page IDs for doContextMenuAccordion.
page.php
The page.php file serves as the default page template for content pages on the Learning Lab site. It includes the header and footer through calls to get_header() and get_footer(), respectively. The template contains the following elements:
Content, including the title.
Right navigation, added via a get_sidebar() call to sidebar.php.
Previous and next page buttons.
An HTML content area for additional resources and links.
Keywords.
The code for keywords, previous and next page buttons, and additional resources is located in the /page-templates/includes/ directory.
page-home.php
The page-home.php file is a custom template used for the homepage. All of its content resides in the template file.
In WordPress, custom templates can be created by naming them page-{slug}.php or page-{ID}.php, where {slug} is the page's slug and {ID} is the page's ID. This allows for specific styling and functionality tailored to the homepage.
page-redirect-404.php
page-redirect-404.php file is a custom template used for handling 404 errors. This template is part of a setup where the 404 error page shares code with a page located at /redirect-404/, using the page-redirect-404.php template. The shared code resides in /includes/redirect.php. This approach is used because Sitesucker does not capture a 404 page. By structuring it this way, most WordPress functionality can be demonstrated, and a static page is generated and renamed to 404.html during publishing.
page-search.php
The page-search.php file is a custom template used for the search page. Similar to other page templates, it is named following the WordPress template hierarchy system, allowing for specific design and functionality for displaying both the search and the search results.
The search feature utilises a library called fuse.js to conduct fuzzy searches. This process requires generating a JSON file that represents all the content across the site.
The sidebar.php file create the right nav on content pages. Here's how it works:
Sidebar Navigation Panel:
It generates a sidebar navigation panel (<nav class="right-nav">) based on the page's hierarchy level. There are four scenarios for displaying the navigation, depending on the presence of great-grandparent, grandparent, and parent pages:
Third-level page: Displays headings for both great-grandparent and grandparent, and lists siblings of the current page.
Second-level page: Displays headings for grandparent and parent, and lists siblings and children of the current page.
Top-level page: Displays the heading for the parent and lists children of the current page or siblings if no children exist.
Landing/subject area page: Displays the heading for the current page and lists its direct children.
Functions:
outputChildNav(): Recursively builds and displays a list of child pages for a given parent page. It uses a WordPress query to fetch and display pages in a hierarchical order.
doNavHeading(): Constructs HTML for navigation headings (<h2> or <h3>) with links, marking them as selected if applicable.
Navigation Display:
The navigation items are displayed as links, with selected items highlighted. The formatAfterTheColon() function is used to format titles by removing text before a colon.
Folders
css-output
The CSS output is the result of compiling the .scss styles located in the sass folder. The compiled CSS file is named bundle.css.
custom-shortcodes
This folder contains all the code for the various shortcodes used to output HTML across the Learning Lab. The _main.php file is referenced from functions.php and includes the following files:
accordion.php: Handles ll-accordion and transcript functionality.
nav_panel.php: Manages the nav-panel shortcode.
image.php: Supports the ll-image shortcode.
video.php: Supports the ll-video shortcode.
alert_banner.php: Manages the alert-banner shortcode.
landing.php: Handles landing-banner and landing-list features.
code_example.php: Supports the code example shortcode.
layout.php: Manages grid, image-text, and icon-text layouts.
highlight-text.php: Supports highlight text functionality.
redirect-listing.php: Allows listing of every redirect via a shortcode.
The _main.php file also contains functions and content filters designed to remove empty <br> and <p> tags, which can disrupt layouts within shortcodes.
fonts
The fonts directory contains a woff2 file for Museo 700. This is referenced in /sass/_theme_variables.scss.
includes
This folder is referenced from functions.php. It includes code for redirects and exporting to json. There is scope to divide function.php further and distribute code among files in this directory.
js
The js folder contains the following JavaScript files:
bootstrap.bundle.min.js: Includes Bootstrap's compiled JavaScript plugins.
custom.js: Not used.
iframeResizer.min.js: Resizes iframes within the page.
main-body.js: Handles the hamburger menu, embed mode, and dark mode switcher (some dark mode code is located in header.php to expedite the display of dark mode).
search-home.js: Processes the search box and redirects to search from the home and 404 pages.
search.js: Executes search requests.
The footer.php file includes links to these JavaScript files to ensure they are loaded appropriately.
page-templates
There are a number of page templates that can be selected via the page attributes box in the WordPress editor. Content is displayed at 856px wide for wide screens unless otherwise noted.
page-templates/empty.php: Rarely used; title needs to be added manually. Content width is 1296px for wide screens.
page-templates/first-content-page.php: Used for initial pages in a sub-section; omits the previous button.
page-templates/landing.php: For landing pages, shortcodes landing-banner and landing-list used in the content area to provide layout. Content width is 1296px for wide screens.
page-templates/last-content-page.php: For final pages in a section; omits the next button.
page-templates/no-side-nav.php: Alternative to Landing page; it omits the side nav and prev/next buttons. Content width is 856px for wide screens.
sass
The sass directory contains several.scss files that are compiled into bundle.css, located in css-output. The main.scss file is the primary file and includes various .scss files:
design-system/colour.scss: Sets up colour variables used in Bootstrap. Declaring these first simplifies the implementation of dark mode.
bootstrap-loader.scss: Loads Bootstrap styles and includes theme_variables.scss, where settings like fonts are configured.
Theme Styles: Includes wp_basic_styles.scss, picostrap.scss, and woocommerce.scss. These styles relate to the admin section, and some may be removable.
Design System Styles: Consists of several .scss files located in the design-system folder. These styles are first developed in a separate repository on the libraries GitHub also named design-system. These styles are documented at RMIT Library Design System.
Visual Language Styles: e.g. typography.scss and links.scss
Simple Components: e.g. button.scss and blockquote.scss
Complex Components: e.g. top-nav.scss and video-image.scss
Learning Lab Styles: All files are in the learning-lab subfolder. This includes old-site-styles.scss, which contains legacy styles from the old site that should be phased out over time.