# CP-COMPAS: Site Administration & User Guide Welcome to the CP-COMPAS Drupal site! This document serves as a guide for site administrators and content creators. It assumes you are already familiar with standard Drupal concepts (like Nodes, Taxonomies, Menus, and Blocks) but explains the specific conventions, workarounds, and content architectures used exclusively on this site. --- ## 1. Content Architecture The site uses a specific relationship between content types and taxonomy to manage exams: - **Exam Type (Taxonomy)**: The high-level category representing the brand of the credential (e.g., *COMPAS-A1*, *COMPAS-PY1*). - **Exam (Node)**: A specific, schedulable instance of an exam. These contain a detailed text **Description**, actual dates (`field_exam_date`), fees, and registration links. They act as the individual events categorized under an Exam Type. - **Certificate Record (Node)**: The permanent database records tracking the actual credentials awarded. These securely link a Drupal User to the exact Exam they passed, including the `field_issue_date`, `field_certificate_id` (serial number), and the PDF `field_certificate_file`. - **Page (Node)**: Used to create general content pages, including the main landing pages for each Exam Type and their subsequent sub-pages (e.g., "Registration Steps", "Testing Environment"). --- ## 2. Guide: Creating a New Exam Category When CP-COMPAS launches a new exam (e.g., *COMPAS-Java*), you must follow these exact steps to ensure the sidebar navigation and page layouts match the site's conventions. ### Step 1: Create the Exam Type 1. Go to **Structure > Taxonomy > Exam Type**. 2. Add a new term for the exam (e.g., "COMPAS-Java"). Upload an image icon if necessary. ### Step 2: Create the Landing Page 1. Go to **Content > Add content > Page**. 2. Title it appropriately (e.g., "COMPAS-Java"). 3. Assign it to the `COMPAS-Java` term using the `field_exam_type` field. 4. Set a URL alias (e.g., `/service/compas-java`). ### Step 3: Set Up the Sidebar Navigation Menu We use native Drupal menus to generate the sidebars for each exam. **Do not use Views to build these sidebars.** 1. Go to **Structure > Menus > Add menu**. 2. **Title**: Name it clearly (e.g., "COMPAS-Java Menu"). 3. **Menu system name**: Use the convention `exam-[exam_type]` (e.g., `exam-compas-java`). ### Step 4: Add Subpages to the Menu Create the supporting pages for the exam (e.g., "How to Apply", "Environment Setup"). 1. Go to **Content > Add content > Page**. 2. Under **Menu settings** (in the right sidebar), check "Provide a menu link". 3. **Parent item**: Select the newly created menu ("COMPAS-Java Menu"). 4. **URL Alias**: Ensure they follow a logical nested path (e.g., `/service/compas-java/flow`). ### Step 5: Display the Menu Block To make the new sidebar appear only on the relevant pages: 1. Go to **Structure > Block layout**. 2. Scroll down to the **Sidebar First** region and click **Place block**. 3. Search for your menu ("COMPAS-Java Menu") and place it. 4. **Visibility Rules (Crucial)**: Under the **Pages** tab, restrict the block to only show on the paths for this exam. - Example: ```text /service/compas-java /service/compas-java/* ``` 5. Ensure the block title is hidden if you don't want it displaying above the menu links. --- ## 3. Theme & UI Conventions The site uses a custom sub-theme (`compas`) running over the `basecore` base theme. We have established several strict UI conventions to maintain a clean, modern aesthetic: ### Navigation & Header - **Sticky Header**: The main site navigation (containing the logo and main menu) is sticky. It uses pure CSS (`position: sticky`) rather than the base theme's JavaScript implementation. *Note: If you add elements to the `page-top-container`, they will not stick. Only the header container sticks.* - **Hero Banners**: Hero banners intentionally scroll away and do not stick to the top of the viewport to maximize vertical reading space. ### Active Menu States - **Sidebar Highlighting**: When a user is on a specific sidebar page, the menu item automatically highlights with a light red background and a thick red left border. - **Main Menu**: Active top-level items receive a similar light red background but use a red bottom border. - **No Manual Classes Needed**: You never need to manually add `.active` classes to menu items. Drupal's native `.is-active` class handles the highlighting automatically via `style.css`. - **Chevrons**: We have globally disabled default bullet points and chevron icons `(>)` in sidebar menus to maintain a clean, block-based look. ### CSS Variables The site colors are strictly controlled via CSS variables defined at the top of `/web/themes/custom/compas/css/style.css`. If you need to adhere to brand colors, use the variables rather than hardcoding hex values: - `var(--accent)`: The primary deep red brand color. - `var(--accent-l)`: The light red background color used for active highlight states. - `var(--bg3)`: A neutral gray used for subtle borders (like the line under the main header). --- ## 4. Development & Deployment Reminders - **Configuration Sync**: Any structural changes (like creating the `exam-compas-java` menu or placing its block) must be exported! Remember to run `ddev drush cex` to sync the configuration to `/config/compas/` and commit those YAML files to Mercurial. - **Content Changes**: If you create a highly specific node that the configuration relies on, remember to document it in `DEPLOYMENT.md` so it isn't lost during deployments. - **Mercurial**: We use `hg`, not `git`. Use `hg addremove`, `hg commit`, and `hg push` for version control.