Merge pull request #247 from UCDavisLibrary/sp-js-build

Dist build and zip script

.gitignore

@@ -7,4 +7,5 @@ node_modules
 /assets/css
 /theme/acf-json
 .DS_Store
-/src/public/lib/icons/ucd-public.html
+/src/public/lib/icons/ucd-public.html
+/dist/io

dist/Dockerfile

@@ -0,0 +1,31 @@
+ARG NODE_VERSION=18
+FROM node:${NODE_VERSION}
+
+ARG THEME_TAG
+
+WORKDIR /theme
+
+# Get fresh copy of theme
+RUN git clone https://github.com/UCDavisLibrary/ucdlib-theme-wp.git
+WORKDIR /theme/ucdlib-theme-wp
+RUN git checkout ${THEME_TAG}
+RUN git pull
+
+# Install dependencies
+RUN cd src/public && npm install
+RUN cd src/editor && npm install
+
+# Build assets
+RUN cd src/public && npm run dist
+RUN cd src/editor && npm run dist
+
+# remove node_modules
+RUN cd src/public && rm -rf node_modules
+RUN cd src/editor && rm -rf node_modules
+
+WORKDIR /theme
+
+COPY container-scripts scripts
+
+ENTRYPOINT [ "bash", "-c" ]
+CMD ["echo 'Use command arg to specify a script to run.'"]

dist/cmds/build.sh

@@ -0,0 +1,17 @@
+#! /bin/bash
+
+###
+# Process for building theme image
+###
+
+set -e
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
+cd $SCRIPT_DIR/..
+
+THEME_TAG=${1:-main}
+echo "Building theme image with tag: $THEME_TAG"
+docker build \
+  -t localhost/local-dev/ucdlib-theme-wp:$THEME_TAG \
+  --build-arg BUILDKIT_INLINE_CACHE=1 \
+  --build-arg THEME_TAG=${THEME_TAG} \
+  .

dist/cmds/zip.sh

@@ -0,0 +1,21 @@
+#! /bin/bash
+
+###
+# Build and zip up theme and save to io directory
+###
+
+set -e
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
+cd $SCRIPT_DIR/..
+
+THEME_TAG=${1:-main}
+./cmds/build.sh $THEME_TAG
+IMAGE=localhost/local-dev/ucdlib-theme-wp:$THEME_TAG
+
+# check if io directory exists, create if not
+if [ ! -d "./io" ]; then
+  mkdir ./io
+fi
+
+echo "Zipping up theme image with tag: $THEME_TAG"
+docker run --rm -v $(pwd)/io:/theme/io $IMAGE ./scripts/zip.sh

dist/container-scripts/zip.sh

@@ -0,0 +1,11 @@
+#! /bin/bash
+set -e
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
+cd $SCRIPT_DIR/..
+
+THEME_TAG=$(cd ucdlib-theme-wp && git rev-parse --abbrev-ref HEAD)
+ZIP_FILE=ucdlib-theme-wp-$THEME_TAG.zip
+
+echo "Zipping up theme image with tag: $THEME_TAG"
+tar -czvf io/$ZIP_FILE ucdlib-theme-wp
+

dist/readme.md

@@ -0,0 +1,5 @@
+# Dist Build
+
+For every release of a theme, a version with the built dist js/css should be zipped up and uploaded to the releases page.
+
+run `./cmds/zip.sh <tag>`, which will place a zip file in the `io` directory.

readme.md

@@ -3,26 +3,48 @@
 This is a Wordpress theme that uses the styles from [UCD IET's Sitefarm One theme](https://bitbucket.org/ietwebdev/sitefarm-pattern-lab-one/src/redesign/docs/). It is used by the [main UC Davis Library website](https://github.com/UCDavisLibrary/main-wp-website), but can also be used by other Wordpress sites that need UC Davis branding. 
 
 
-## Deployment
-To use this theme, you can download it and place it in your Wordpress's `themes` folder. [Timber 2.0](https://upstatement.com/timber/) is a dependency, so you have to [install it via composer](https://timber.github.io/docs/v2/installation/manage-timber-with-composer/) before activating the theme. You must also build the js by running `npm install && npm run dist` in the `/src/public` and `/src/editor` directories. TODO: Just make a release with timber and the JS zipped up.
+## Using This Theme
+With a little bit of setup, this theme can be used in any Wordpress site.
 
-Alternatively and preferrably, check out these repositories for patterns on deploying via Docker:
-- [main-wp-website](https://github.com/UCDavisLibrary/main-wp-website)
-- [main-wp-website-deployment](https://github.com/UCDavisLibrary/main-wp-website-deployment)
+First, [Timber 2.0](https://upstatement.com/timber/) is a dependency, so you have to [install it via composer](https://timber.github.io/docs/v2/installation/manage-timber-with-composer/) before activating the theme. This can be done by extending the Wordpress docker image and running a few additional commands:
+```Dockerfile
+RUN curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer
+ENV COMPOSER_ALLOW_SUPERUSER=1;
+COPY composer.json .
+RUN composer install
+```
 
-## Development
+Next, you have to decide whether you want to build the JS and CSS assets yourself or use a prebuilt version.
+
+### Prebuilt Version
+
+To use the prebuilt version, TODO explain how to download zip file, point to example.
+
+### Custom Build
+
+This approach is necessary if you want to extend the block components in a custom plugin or create a single js bundle for your site. To build the JS and CSS yourself: 
+1. clone this repository,
+2. npm link the two js directories in `/src/public` and `/src/editor`
+3. import them with `import "@ucd-lib/brand-theme"` and `import "@ucd-lib/brand-theme-editor;` into your custom plugin, respectively. 
+
+For an example, check out the [main library website](https://github.com/UCDavisLibrary/ucdlib-wp-plugins/tree/main/ucdlib-assets), which loads the theme and all custom plugin assets into a single dynamically-loaded code-splitted bundle.
+
+**IMPORTANT NOTE**
+- This theme is highly opinionated since it enables many [dynamically-generated](https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/creating-dynamic-blocks/) custom blocks that correspond to the "atoms" and "molecules" of the UC Davis brand. If you build your content using these blocks, and then want to change to a different theme, that theme will not know how to render these blocks. You will have to write a migration script that converts all these blocks into html before changing themes. 
+
+## Contributing
 In Worpress, [best practices](https://developer.wordpress.org/themes/getting-started/what-is-a-theme/#what-is-the-difference-between-a-theme-and-a-plugin) are:
 - a theme controls the presentation of content (CSS styles and template routing); whereas
 - a plugin is used to control the behavior and features of your WordPress site.
 
-So, if you need to alter the behavior of the site, use the [ucdlib-plugins repository](https://github.com/UCDavisLibrary/ucdlib-wp-plugins).
+Moreover, this theme should stay as closely aligned to UC Davis style specifications as possible.
 
 After setting up your local docker environment, 
 1. Set the `UCD_THEME_ENV` environmental variabled to `dev`, which will make sure the non-minified JS/CSS assets are loaded.
 2. To start the block-editor watch process, run `npm run watch` in `/src/editor`. More details can be found in the readme in that directory.
 3. To start the public js/scss watch process, run `npm run watch` in `/src/public`. More details can be found in the readme in that directory.
 
-## Reference and Documentation
+### Reference and Documentation
 The following are very helpful resources when developing this theme:
 - [Wordpress Theme Handbook](https://developer.wordpress.org/themes/)
 - [Wordpress Block Editor Handbook](https://developer.wordpress.org/block-editor/)
@@ -31,4 +53,4 @@ The following are very helpful resources when developing this theme:
 - [Timber Reference](https://timber.github.io/docs/v2)
 - [Twig Reference](https://twig.symfony.com/doc/3.x/)
 - [htm Package Readme](https://www.npmjs.com/package/htm)
-- [ReactJs Main Concepts](https://reactjs.org/docs/hello-world.html)
+- [ReactJs Main Concepts](https://reactjs.org/docs/hello-world.html)