Commit 20808ee9 authored by Shane Eckenrode's avatar Shane Eckenrode

Add initial documentation for alternate theming

parent 23bd9af4
Pipeline #80307 passed with stages
in 9 minutes and 20 seconds
# utils-theming # utils-theming
This library was generated with [Nx](https://nx.dev). # Setup for Alternate Theming
## Running unit tests ## Prerequisites
Run `nx test utils-theming` to execute the unit tests. - Install @psu/components, @psu/utils, @psu/palette
- Install node-sass and node-sass-tilde-importer as Dev Dependencies
- Application must be setup to use scss and recommended to adhere to the following scss styling structure
- If not already existing, you must have the following files within the src directory at the **_root of the application_**
- `_app-theme.scss`: Import all application, internal application libraries, or external libraries that have theming here and include them within a mixin named `@mixin app-theme($theme)`.
- `_theme.scss`: Set up the primary application theme variables here. This file should import the theme palette from `@psu/palette` and set up the base theme colors. It should follow the structure from the snippet below
```scss
@import '~@psu/palette/beaver-blue';
// Setting Theme Colors
$primaryPalette: mat-palette($primary, 700, 50, 900);
$secondaryPalette: mat-palette($secondary);
$errorPalette: mat-palette($error);
$appBackground: #f5f5f5;
```
- `_typography.scss`: Set up the application typography variables here. Follow the structure from the snippet below. More information can be found in the [typography section](https://git.psu.edu/ais-swe/ux/theme-lib#typography) of the theme utils readme.
```scss
// Setting Typography for all themes
$titleFont: 'Roboto Slab';
$bodyFont: 'Open Sans';
$titleRegularWeight: 400;
$titleBoldWeight: 700;
$bodyRegularWeight: 400;
$bodyBoldWeight: 600;
```
- Import each of the above files into `styles.scss` and follow instructions for [theme generation](https://git.psu.edu/ais-swe/ux/theme-lib#theming) and [typography generation](https://git.psu.edu/ais-swe/ux/theme-lib#typography) from theme utils readme.
## Application-Specific Setup
1. Copy the following snippet into a new file named `build-themes.sh` and place in the `tools` directory. The tools directory should be located at the root of the project.
```sh
#!/bin/bash
DEST_PATH=apps/ui/src/assets
INPUT_PATH=$DEST_PATH/alternate-themes/
echo Building custom theme scss files.
# Get the files
FILES=$(find apps/ui/src/assets/alternate-themes -name "*.scss")
for FILE in $FILES
do
FILENAME=${FILE#$INPUT_PATH}
BASENAME=${FILENAME%.scss}
$(npm bin)/node-sass --importer=node_modules/node-sass-tilde-importer $FILE > $DEST_PATH/$BASENAME.css
done
echo Finished building CSS.
```
2. Create the `alternate-themes` directory at the path `apps/ui/src/assets`. This is where you will add your alternate theme scss files. These scss files should follow the following structure:
```scss
@import '~@psu/theme-lib/md2/md2'; // Import the theming utilities
@import '~@psu/palette/nittany-navy'; // Import the alternate theme palette
@import '../../app-theme'; // Import the app-theme mixin to propagate the alternate theme to all angular material, application, and library components
// Setting Theme Colors
$primaryPalette: mat-palette($primary, 700, 50, 900);
$secondaryPalette: mat-palette($secondary);
$errorPalette: mat-palette($error);
$appBackground: #f5f5f5;
// Generate the new alternate theme and propagate it to all components
$theme: generate-material-light-theme(
$primaryPalette,
$secondaryPalette,
$errorPalette,
$status-colors,
$appBackground-light
);
@include angular-material-theme($theme);
@include app-theme($theme);
```
3. In the `angular.json`, add the following code to the assets array of the application's build object. Path should be close to: `projects`
```json
{
"glob": "*.css",
"input": "apps/ui/src/assets",
"output": "./alt-themes/"
}
```
4. Add the `build-themes` script to the package.json and update existing scripts to call that script first.
5. Add the `STYLE_MANAGER_CONFIG` to `app.module.ts`'s providers array. Ex:
```ts
{
provide: STYLE_MANAGER_CONFIG,
useValue: [
{
name: 'beaver-blue',
primary: '#316cae',
isDefault: true
},
{
name: 'nittany-navy',
primary: '#143372'
},
{
name: 'dark',
primary: '#0d0d0d',
isDark: true
}
]
}
```
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment