regionhalland/halland

Halland is a Wordpress theme based on Sage by Roots. Halland is the starting point of websites built by Region Halland.

Halland 🍲

Halland is a Wordpress theme built by Region Halland, based on Sage., _(*1)

<, _(*3)

p>, _(*4)

themes/halland/           # → Root
├── app/                  # → Theme PHP
│   ├── Acf/              # → ACF Fields
│   ├── controllers/      # → Controller files
│   ├── Theme/            # → Enqueue files, register sidebars
│   ├── Traits/           # → Traits used in the theme
│   ├── admin.php         # → Theme customizer setup
│   ├── filters.php       # → Theme filters
│   ├── helpers.php       # → Helper functions
│   └── setup.php         # → Theme setup
├── composer.json         # → Autoloading for `app/` files
├── composer.lock         # → Composer lock file (never edit)
├── dist/                 # → Built theme assets (never edit)
├── node_modules/         # → Node.js packages (never edit)
├── package.json          # → Node.js dependencies and scripts
├── resources/            # → Theme assets and templates
│   ├── assets/           # → Front-end assets
│   │   ├── config.json   # → Settings for compiled assets
│   │   ├── build/        # → Webpack and ESLint config
│   │   ├── fonts/        # → Theme fonts
│   │   ├── images/       # → Theme images
│   │   ├── scripts/      # → Theme JS
│   │   └── styles/       # → Theme stylesheets
│   ├── functions.php     # → Composer autoloader, theme includes
│   ├── index.php         # → Never manually edit
│   ├── screenshot.png    # → Theme screenshot for WP admin
│   ├── style.css         # → Theme meta information
│   └── views/            # → Theme templates
│       ├── layouts/      # → Base templates
│       └── partials/     # → Partial templates
└── vendor/               # → Composer packages (never edit)

<, _(*5)

p> , _(*6)

Requirements

• WordPress >= 4.7
• PHP >= 7.0
• Composer
• Node.js >= 6.9.x
• Yarn

Getting started

1. Clone Halland into the themes directory of your Wordpress installation and install dependencies:

$ cd <your site>/web/app/themes/
$ git clone https://github.com/RegionHalland/halland.git
$ cd halland
$ composer install && yarn

1. Update resources/assets/config.json settings:

- devUrl should reflect your local development hostname, for example http://site.test - publicPath should reflect your WordPress directory structure (/web/app/themes/halland or /wp-content/themes/halland for non-Bedrock installs), _(*7)

1. Build commands

* yarn start — Compile assets when file changes are made, start Browsersync session * yarn build — Compile and optimize the files in your assets directory * yarn build:production — Compile assets for production, _(*8)

Styleguide

Almost all of the CSS on the front-end is defined in our styleguide. Halland uses it by looking for the environment variable COMPONENT_LIBRARY_URI. If the variable can't be found, Halland defaults to the styleguide published on Github Pages., _(*9)

If you want to work with CSS, set up up a local version of the styleguide by following the instructions in it's repo and make your changes there., _(*10)

CORS

Allow requests to your local version of the styleguide by adding the following headers to it's nginx config:, _(*11)

1. SSH into your Homestead server and edit the styleguides nginx config:

$ cd ~/Homestead
$ homestead ssh
$ sudo nano /etc/nginx/sites-enabled/styleguide.test

1. Place the headers in the server block of the nginx config:

# Allow CORS
add_header 'Access-Control-Allow-Origin' '*' always;
add_header 'Access-Control-Allow-Credentials' 'true' always;
add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, OPTIONS' always;
add_header 'Access-Control-Allow-Headers' 'Accept,Authorization,Cache-Control,Content-Type,DNT,If-Modified-Since,Keep-Alive,Origin,User-Agent,X-Requested-With' always;

1. Reload the nginx config.

$ sudo service nginx reload

ACF Fields

Halland uses Advanced Custom Fields to create custom fields and ACF Export Manager to save the field definitions as .php and .json files, so that we can keep them under version control., _(*12)

Importing

The field definitions are imported automatically with ACF Export Manager. The export manager will automatically import all field groups defined in /halland/Acf/Import.php., _(*13)

To be imported, they must first be exported by following the instructions below. ⤵️, _(*14)

Exporting

1. Create your field group in the Wordpress admin panel like you normally would under Fields → Add new., _(*15)

2. Over the Save / Publish button to the right, you will find your field groups unique ID. It looks something like group_5b716c7b279da. Copy the field groups ID and add it to the array defined in /halland/Acf/Import.php:, _(*16)

$acfExportManager->autoExport(array(
    ...
    ...
    'my-new-fieldgroup' => 'group_5b716c7b279da'
));

1. Save / Publish your field group and ACF Export Manager will create a .php and a .json file for your new field group in each respective folder. Make sure to commit these files.

Editing existing field groups

1. First of you need to identify the filename of the field group you want to edit. The easiest way to do this is probably to look at the key-value pairs found in the import array in /halland/Acf/Import.php., _(*17)

2. For minor changes you can edit the field groups directly in code. Remember to edit both the .json and the .php files found in /halland/Acf/<json or php>/my-new-field-group.<json or php>., _(*18)

3. For bigger changes you might want to use the admin panels interface. Go to Fields → Tools and import your field groups .json file (found in /halland/Acf/json/my-new-field-group.json)., _(*19)

4. Edit your field group. When you Save / Publish, the changes will automatically be exported to code. Commit your changes! 🤓, _(*20)

Child themes

TBD, _(*21)