@bostonuniversity/bu-prepress

BU PrePress

A plugin for handling all prepublishing functionality for BU Editorial properties.

Modifying PrePress styles in a theme

You can import PrePress styles in a custom theme and override many of the default styles easily. Import PrePress as an Node dependency, add a loadPath to your preferred Sass setup for cleaner partial imports, and import files for any parts you plan on custom styling. You can also use PrePress as-is, without modifying any of the styles.

Dependencies

You'll need to import prepress-global/functions at the top of your custom theme styles, where you would normally put other libraries and dependencies. This file is needed for the prepress-get function, which all base stylesheets use. The prepress-get Sass function makes it easy to get a PrePress setting for the correct map, no matter how many times or places it's been overridden.

Options for importing

You can import PrePress Sass as-is by importing the component Sass partial directly, or you can modify it by importing the component-base partial and supplying your own PrePress configuration maps. r-editorial is an excellent example of extensive PrePress theming that uses base partials to its advantage to style three publications in the same stylesheet.

Theming PrePress styles

You can control PrePress styles at three levels: globally (WordPress level), the publication level, or at the component level. All of these are controlled by Sass maps which have a scope key that affects where the styles are applied.

** Overriding global PrePress styles **

You can control how everything in PrePress looks at a global level. PrePress comes with sensible defaults, any and all of which can be overridden in a custom theme. Simply redeclare $prepress-config in your custom theme before any PrePress partials and use wp as your scope.

** Overriding PrePress styles by publication **

In most cases, your child theme will only be handling one publication at a time, so you can likely just overridde global PrePress styles. However, if your child theme has to handle multiple publications in the same stylesheet, overriding by publication can be done. Just as with global styles, you'll redeclare $prepress-config, but instead of doing it in a global partial, we recommend doing it in a publication- specific partial - and calling that partial as needed throughout your blocks before each base partial you need to modify. Set the scope here to your-publication-name on each publication you need to modify styles for. See r-editorial for a detailed example of this setup.

Although this was built for publications, you can use this system to override styles for any kinda-global context that isn't WordPress by changing the scope in $prepress-config to whatever you like, as long as that class is added to the component. PrePress doesn't print classes for anything besides WordPress block and publication name by default, so you'll need to add these classes yourself. Possibilities include styles by page template or post type.

** Overriding PrePress styles at the component level **

In certain situations, you may need to override all styles - global and publication-specific - at the component level. For example, on the audio block, you may always want the play button to be perfectly circular, regardless of the default or publication-level border-radius setting. In that case, each component in PrePress has its own map that you can override in your theme. All maps are named with the PrePress name, and can be overridden with a map that's named $prepress-name-theme. For example, the $prepress-block-audio map can be modified using $prepress-block-audio-theme. You only need to redeclare the settings you want to change - PrePress takes care of the rest! In this example, you would only need to change the border-radius. Then, all audio players, regardless of where they are or what publication they belong to, would get the round button.

Running Code Climate locally

Prerequisites

To run code climate locally, grab an existing plugin or theme's .codeclimate.yml file:

• For plugins, use the one from the sample plugin repo.
• For themes, use the one from the responsive framework's child-starter.

Next, follow the instructions listed on the Code Climate repo , or continue by installing the prerequisites that are listed:

• Docker, or use Docker for Mac for macOS.
• Homebrew (only if on macOS)

Installation

Note: All of this information is available on the Code Climate repo . To continue, make sure you have Docker, or Docker for Mac for macOS.

To run Code Climate reports locally, the Docker image must be installed on your machine.

Run the following command in a Terminal session to pull down the Docker image:

docker pull codeclimate/codeclimate

This will download the Docker image that code climate will use to run its analysis tools.

After that finishes, code climate can now be run using the following example command:

docker run \
  --interactive --tty --rm \
  --env CODECLIMATE_CODE="$PWD" \
  --volume "$PWD":/code \
  --volume /var/run/docker.sock:/var/run/docker.sock \
  --volume /tmp/cc:/tmp/cc \
  codeclimate/codeclimate help

But since that's a burden to type each time, it is preferred to use Code Climate's wrapper scripts.

Install script for macOS using Homebrew

The easiest way to install the codeclimate command on macOS is with the homebrew package manager. Install homebrew before continuing. Otherwise, continue on to the next step.

In a Terminal session, run the following commands:

1. brew tap codeclimate/formulae
2. brew install codeclimate

Install script for any os (Windows, Linux, etc)

If on Windows or another operating system, run the following commands:

1. curl -L https://github.com/codeclimate/codeclimate/archive/master.tar.gz | tar xvz
2. cd codeclimate-* && sudo make install

Example commands

If using the wrapper scripts, the codeclimate command should be available. Test it by running codeclimate version.

A list of commands is available on the Code Climate GitHub page. The following commands can be run in the root of your repository:

Analyze the entire repo

codeclimate analyze

Analyze just one file

codeclimate analyze includes/functions.php

Validate the contents of your codeclimate file

codeclimate validate-config

Setup for development

Steps

1. Download Repo + BU-Blocks Repo
2. Run npm install with node v10 or older
3. Run npm install in bu-blocks repo locally if you haven't already
4. In bu-blocks directory run npm link to register bu-blocks globally on your system as available for linking.
5. In bu-prepress directory run npm link @bostonuniversity/bu-blocks to "link" your local repo copy of bu-blocks with bu-prepress
6. run npm start to compile JS/SASS/etc during dev and grunt as well for additional files to be compiled.
7. run npm run build to create a minified shippable build version of the JS & CSS when creating a release.

KSS Errors:

This repo was setup on an old version of KSS. Until we have time to update it and get it working with a newer version we have to keep an old version of KSS installed. grunt-kss will attempt to install a newer version and you may end up getting an error like:

``$ grunt Loading "kss.js" tasks...ERROR

SyntaxError: Unexpected token { Warning: Task "kss" not found. Use --force to continue.

Aborted due to warnings. `` To fix this ensure that this version of kss is in your dev dependencies of package.json. "kss": "3.0.0-beta.23" 3.0.0-beta-23 is the latest version that appears to work. We originally build the plugin using beta 17. KSS is at 3.0.1 now and throws errors with our setup. Tattoine:bu-prepress acketon$ grunt