# Zephr

A companion plugin to Zephr which is used to integrate sites with Zephr.

## Running builds

Run `npm run build` to build all production assets. Run `npm run dev` for a
development build of assets, which also watches files for changes and
automatically recompiles.

## Slotfills

This plugin is built to use slotfills for all site-specific features. The
slotfill configuration can be found in `slotfills/index.js`. Individual slotfill
sections are located in `slotfills/sections`.

## Saving to Post Meta

In order to save data back to post meta, you need to register the meta first.
Meta fields are registered by adding them to the `config/post-meta.json` file.
There are some examples in this file for Open Graph data.

## Reusable Components

A collection of reusable components is located in `./components`. These
components can be included in a variety of contexts, such as slotfills and
blocks.

## Services

Complex JavaScript logic should be broken out into separate functions, one
function per file, in the `services` directory, grouped into subfolders by type.
See `services/media/get-media-url.js` for an example of this. All services
functions should have associated tests.

## Pathing

This project does not use aliases by default, since aliases can confuse IDEs and
make it harder to navigate through the code to find where something is defined.
You can add them yourself if you prefer.

## Running Tests

Run `npm run test` to run Jest tests against JavaScript files. Run
`npm run test:watch` to keep the test runner open and watching for changes.

Run `npm run lint` to run ESLint against all JavaScript files. Linting will also
happen when running development or production builds.

Run `composer phpcs` to run PHP CodeSniffer tests against PHP files.

## Custom Blocks

Use the block scaffolder to create custom blocks. Create the block definition in
`scaffold/blocks`. Ensure the name of the JSON file is the same as the
non-namespaced block name (e.g., if your block is `zephr/my-block`,
then the JSON file must be `my-block.json`). After creating or updating the JSON
file, run the scaffold command (`npm run scaffold`) to generate or regenerate
assets. Block registration, script creation, etc is handled for you.

## CI/CD Integration

Buddy will automatically run `composer phpcs`, `npm run test`, and
`npm run build` (which includes eslint). If any of these checks fail, the build
will fail.

## Hot Reloading

Still to come. The closest you can get now is running `npm run dev`, which
watches for changes, and reloading the page.

## Built-in Components
- `CSVUploader`: Allows a user to upload a CSV file, which is parsed in the
  browser, converted to a JSON structure, passed through a user specified
  callback function for further transformation, and saved to block attributes.
- `ImagePicker`: Allows a user to select or remove an image using the media
  modal. A wrapper around `MediaPicker` that sets the file type to image.
- `MediaPicker`: Allows a user to select or remove any attachment from the media
  library using the media modal.
- `PostSelector`: A component used for searching for and selecting posts via the
  REST API.