# Sonic Site Docs
## New Site Set Up
### Site Settings
* We’ll need the preamp/cohesion config files set up, likely this was handled during the repo initialization.
* Update the readme with the CircleCI Build URL. This should follow the format of: https://app.circleci.com/jobs/github/HigherEducation/{Repo Name} - Replacing {Repo Name} with the whatever follows “HigherEducation” within the GitHub URL for the repo.
* Publisher Config - You’ll need to add three props to the Publisher Config file (publisher.config.yml) namely:
* appExperienceURL
* This should be discoverable by going to the site as it currently exists, interacting with a widget and grabbing the url you’re directed to.
* schoolSearchLogo
* This should always be ‘logo-header.svg’ unless for some reason you need to use a different file name for your specific site.
* cookieConsent
* In most cases, you should be able to find this on the current live site. If you open the live site up, and open the inspector, all you should have to do is search for "OneTrust". You should be able to find a div that looks like this:
* `<script src="https://cdn.cookielaw.org/scripttemplates/otSDKStub.js" type="text/javascript" charset="UTF-8" data-domain-script="5efef9a9-2f10-42a7-87ee-82ffcbbb4d3e"></script>`
* The resulting cookie consent value is the same as the data-domain-script contents, or in this case: `5efef9a9-2f10-42a7-87ee-82ffcbbb4d3e`
* This may take a little extra work to hunt down, but if you go to the current site, open the inspector and look for a comment with in the head labeled “OneTrust Cookies Consent Notice” the following script should have a url that ends with the domain, followed by `-test.js`
* For example, on CJDS I was able to find this snippet:
* `<!-- OneTrust Cookies Consent Notice (Staging, criminaljusticedegreeschools.com, en-US) start --><script src="https://optanon.blob.core.windows.net/consent/88f91872-9098-4274-a08f-42c14f8da2e9-test.js" type="text/javascript" charset="UTF-8"></script><script type="text/javascript">function OptanonWrapper(){}</script><!-- OneTrust Cookies Consent Notice (Staging, criminaljusticedegreeschools.com, en-US) end -->`
* The resulting ID in this instance is: `88f91872-9098-4274-a08f-42c14f8da2e9`

### Site Styles Initial Setup
* The first step to customizing a Sonic Child theme is to set up your site specific variables. Usually, this will mostly be colors, and fonts with the possibility of overriding default values where necessary.
* Setting these up is fairly simple, here is an example of a completed file: https://github.com/HigherEducation/NurseJournal.org-Sonic/blob/master/web/app/themes/sonic-theme-child/assets/src/scss/styles.scss

## Theme Assets

### Templates Build Out
* For each of the templates listed and customized within the projects Figma file, you’ll want to create a new layout within `/web/app/themes/sonic-theme-child/views/layouts/`. Each of these should match one of the layouts within the parent theme’s directory of the same name. You’ll only want to create one though if the design requires custom markup, or a change to the default markup. If the only differences are minor visual changes, then this step is unnecessary, and all adjustments should be made through CSS.

### Component Files
* Components follow a very similar workflow to templates. Ideally, all changes can be made through styling updates, but in some cases you’ll want to create a custom component for the child theme that adds or removes things from the base component.
* Custom components should be made here: `/web/app/themes/sonic-theme-child/views/components/`

### Styling
* Sonic comes with a lot of styling taken care of out of the box. These base styles are set up within two locations:
* `/web/app/themes/sonic-theme/assets/src/scss/`
* `/node_modules/@highereducation/sonic-design/`
* You won’t ever write code within either of these directories, but if you need to figure out how something is set up, those are the two best places to check.
* To write up new CSS for your child theme, you can add files to any of the folders within the child themes scss folder. Your new SCSS should follow the same structure as the parent theme has.
* Once you’ve created a new scss file, you’ll want to do two things:
* Add the file to the styles.scss file so that it can be built.
* Add these to the beginning of the new file. This will allow you to reference theme variables:
* `@use '../../../../../../../../node_modules/@highereducation/sonic-design/dist/sonic.scss’;`
* `@use '../sonic-theme/assets/src/scss/theme';`
* Beyond these standards, you have quite a bit of flexibility to implement things how best you see fit. Sonic does come with quite a bit baked in though, so when possible try to leverage what has already been set up for you. Full sonic-design docs can be viewed here - https://design.highereducation.com/.

### URL Updates
In order to work on updating permalinks across the site, you’ll need to:
* Login to the WP Admin
* Go to Plugins
* Activate “*Permalink Manager Lite*”
* Documentation for the plugin can be found here - [Permalink Manager Lite – WordPress plugin | WordPress.org](https://wordpress.org/plugins/permalink-manager/)

Once you have this plugin enabled you have a few methods to go about handling Permalink Updates.

If you click on Permalink within the sidebar, you’ll be able to see a full suite of functionality for handling permalink updates across multiple pages at once.

If you simply need to update specific pages, that can be accessed from within a posts own editing screen. In order to update one specific post:
* Find the post within the admin
* Scroll the right hand sidebar down to the bottom
* Find the section labeled *Permalink Manager*.
* Edit the content of the “Current URI Field” to match what you desire the permalink to be.

#### Setting trailing slash to always show
Because we use a plugin named Permalink Manager, the usual Settings > Permalinks section of WordPress no longer matters.

If you go into the Permalink Manager plugin settings however, you will be able to find a setting labeled “Trailing Slashes”. Modifying this should handle the settings site wide.

## HubPages

## Reassigning posts to new hub page:

1) Edit the post, ie: https://url-rebuild-he-bestcounselingdegrees-net-sonic.pantheonsite.io/wp/wp-admin/post.php?post=17132&action=edit
2) Deselect the existing term association. In this example you'd uncheck the Rankings box under "Information Hub": 

3) Add or select the new term. For example, if you're adding this post to Careers you'd click "Careers" and then check the box next to the term you want this to appear under: 

3b) If the term doesn't exist yet you'd click "Add New Category" under Careers, enter the name, and click "Add New Category".

These steps also apply for assigning a post to Degrees, you'd just do step 3/3b under "Degrees" instead of "Careers".

4) Click the "Update" button to save the post.

#### Notes
##### Update HubPage name/labels
In order to udpate a hubpages name, you'll need to hop into the Pages section of the WP Admin, find the Hub you want to update, and change the title. The title of that page is what determines what is displayed globaly. Both within the pages hero, and within the admins categories.

## Implement Stepped Flow
One of the easiest parts of Sonic!
* To start, within the WP Admin go into Pages
* Add a new page named “School Search”
* Set the template to “School Search”
* Hit Publish
* Done!

## Setting up Navigation
Navigation is set up through the appearance editor.

Easiest way to access this is through the Admin, towards the middle of the sidebar you should see an “Appearance” item. You can either hover, and click “Customize” in the pop out menu, or click through and then click the customize button right below “Sonic Child Theme”.

Once you’ve clicked through, you’ll see a few different options.
* Site Identity
* Menus
* Homepage Settings
* Additional CSS

The one we’re interested in is “Menus”. Click through on that!

Assuming you’re starting from scratch this menu should be mostly empty. The next step is to add 3 new menus.

* Primary
* Footer
* Auxiliary

The links and structure you create within primary will show up within the header, footer will show up within the body of the footer, and auxiliary will show up at the very bottom of the footer.

#### Notes
##### Simplified Menu System
If you'd like to utilize a simpler system for menus, you can add a line to the child themes functions.php file.

`add_theme_support( 'menus' );`

Doing so will allow you to edit your menus by going through the admin, hover over appearance, and click on menus.

This is likely a faster method for setting menus up in the first place.

Also, if you need to expose additional options for the links you're adding, open up the screen options menu appearing in the top right. This should allow you to edit a links classes, title attribute, and any other available parameters.

##### View All Links
In order for view all/see all links to display correctly, you can add a built in sonic class of "view-all" to them. This should update the styling appropriately.

##### Issues
If you run into issues when adding links, I'd reccomend publishing what you have, closing the appearence editor and reopening.

##### Columns
In order to set columns for a secondary link within the header, you'll need to customize the link after adding it, and add a class of `columns-#` # being however many columns you want. If you wanted four, itd be `columns-4`.

## How to add Preamp to a Sonic Site
Publisher config should be the only file you need to update here.

## How to install Plugins in Sonic
### Most Plugins

The ole handy dandy composer.json require section is going to be your best friend here.

The majority of the time, you’ll want to review other sites on Sonic to see if they have the plugin in question listed within their composer.json. If they do, copy that over and mirror the same line. Run `composer install` on a branch, test things out and push it up so the PR can be reviewed.

If you’re going to add something that isn’t available on another site using sonic, check wpackagist for plugins. If they’re available there, you can simply add a line to composer.json and bing bang boom your in business.

You will want to re-run `composer install` after making any additions.

### Proprietary Plugins

If its a proprietary RV plugin, you’ll first need to grab the plugin, and then toss the unzipped plugin folder into `web/app/plugins` .

You’ll also need to update the .gitignore file to ensure that the plugin is able to be pushed up and tracked by GitHub.

### OKTA Plugin

This plugin fits into the second category, its a proprietary RV plugin. It does have a few extra steps to correctly set up though. So why don’t we both recap how to install RV plugins, as well as walk through the rest of the steps to set up OKTA on a Sonic Site:

1. Create a local branch
2. Grab the latest plugin release here - https://github.com/RedVentures/wordpress-jwt-okta-auth/releases
3. Dig into your local project, and navigate to `/web/app/plugins/`
4. Drop the uncompressed plugin into the above folder.
5. Update your .gitignore file to prevent the resulting folder from being ignored. If you’re using version 1.6.2, the line you’d need to add would look like this: `!web/app/plugins/wordpress-jwt-okta-auth-v1.6.2`
6. Commit and push your changes up to a branch that can be reviewed.
7. Once your staging site has been spun up by Pantheon, try logging into the WP Admin and activating the plugin.
#### Now here’s where the extra steps come into play:
9. Once Active

## Add Images to Cloudinary
This ticket is a bit of a misnomer, as we are no longer using wloudinary for image hosting.

Images need to be added to media library within WP.

Before dropping them in, grab a copy of [ImageOptim — better Save for Web](https://imageoptim.com/mac) , hopefully this ticket will also contain a link to a zip of the top 100 article images.

Assuming it does, toss them into ImageOptim and run. Once optimized, you can upload these directly to the WP Media Library with in the admin.

Once added, now for the fun part. The image zip should also contain a list of urls, and Getty ID’s, this is what you’ll have to use as a reference for updating posts appropriately. Each intended image should be set as each intended pages Featured Image within the posts sidebar.

## Add Dynamic badge Component
Check parent theme for Badge Component, verify with Kelsey

Grab from College Choice child theme

## Add Monetization to Pages
This is one can really vary. You’ll want to discuss this with the relevant stakeholder on the project and find out a few things.

* What is the primary editorial listings component we want to use
* What should its default title/subheading be.

Once this is figured out, you’ll want to leverage the Better Search and Replace plugin locally to update each of these across the sites content.

Beyond that, review the Figma file, specifically the different content templates and what monetization elements are desired to precede, and follow the body content.

## Mass updating URLs and Tagging Posts
By hand is likely the method

## Create Preamp Asset to Turn Off OIM
Reference College Choice Preamp Asset

## Home Page
Pretty simple!
* Create a new Page
* Name it “Home”
* Set up Yoast Title/Meta description
* Under Page Attributes, set Template to Home Template
* Publish!

## Editorial Listing Preamp Test with Launch of Redesign
WIP

## Content Find/Replace

This has to be done locally due to permissions settings with plugins so we’ll want to follow a specific process.

If doing this at a point where other people may be making edits within the WP Admin, request a content freeze ahead of time to ensure that no work is overwritten.

Assuming you have your local environment set up, follow these steps:

1. Push current database to the test environment to sure that you have a usable, easy to merge back in backup in case you run into any issues.
2. Open the local project up within your terminal
3. `lando pull`
4. `lando restart`
5. Ensure that you have the latest content.
6. open site locally go to plugins > add new
7. find better search replace. Install. Activate
8. go to tools > search replace
9. enter search text and replace text
10. select all tables
11. dry run and if it works uncheck box
12. run
13. deactivate plugin and delete it
14. lando push