Flynt is a WordPress theme for component-based development using Timber and Advanced Custom Fields.
- Clone this repo to
<your-project>/wp-content/themes. - Change the host variable in
flynt/build-config.jsto match your host URL:const host = 'your-project.test' - Navigate to the theme folder and run the following command in your terminal:
# wp-content/themes/flynt
composer install
npm i
npm run build
- Open the WordPress back-end and activate the Flynt theme.
- Run
npm run startand start developing. Your local server is available atlocalhost:3000.
- WordPress >= 5.0
- Node = 12
- Composer >= 1.8
- Advanced Custom Fields Pro >= 5.7
In some setups images may not show up, returning a 404 by the server.
The most common reason for this is that you are using nginx and your server is not set up in the default way. You can see that this is the case, if an image url return a 404 from nginx, not from WordPress itself.
In this case, please add something like
location ~ "^(.*)/wp-content/uploads/(.*)$" {
try_files $uri $uri/ /index.php$is_args$args;
}to your site config.
Other issues might come from Flynt not being able to determine the relative url of your uploads folder. If you have a non-standard WordPress folder structure, or if you use a plugin that manipulates home_url (for example, WPML) this can cause problems when using resizeDynamic.
In this care try to set the relative upload path manually and refresh the permalink settings in the back-end:
add_filter('Flynt/TimberDynamicResize/relativeUploadDir', function () {
return '/app/uploads'; // Example for Bedrock installs.
});In some cases, browsersync may be not working. Usually this is related to WordPress not running on https. In order to fix this issue, change the browsersync.https value to false in the file build-config.js.
In your terminal, navigate to <your-project>/wp-content/themes/flynt and run npm start. This will start a local server at localhost:3000.
All files in assets and Components will now be watched for changes and compiled to the dist folder. Happy coding!
Flynt comes with a ready to use Base Style built according to our best practices for building simple, maintainable components. Go to localhost:3000/BaseStyle to see it in action.
The ./assets folder contains all global JavaScript, SCSS, images, and font files for the theme. Files inside this folder are watched for changes and compile to ./dist.
The main.scss file is compiled to ./dist/assets/main.css which is enqueued in the front-end.
The admin.scss file is compiled to ./dist/assets/admin.css which is enqueued in the administrator back-end of WordPress, so styles added to this file will take effect only in the back-end.
The ./lib folder includes helper functions and basic setup logic. You will most likely not need to modify any files inside ./lib. All files in the ./lib folder are autoloaded via PSR-4.
The ./inc folder is a more organised version of WordPress' functions.php and contains all custom theme logic. All files in the ./inc folder are automatically required.
For organisation, ./inc has three subfolders. We recommend using these three folders to keep the theme well-structured:
customPostTypes
Use this folder to register custom WordPress post types.customTaxonomies
Use this folder to register custom WordPress taxonomies.fieldGroups
Use this folder to register Advanced Custom Fields field groups. (See Field Groups for more information.)
After the files from ./lib and ./inc are loaded, all components from the ./Components folder are loaded.
Flynt uses Timber to structure its page templates and Twig for rendering them. Timber's documentation is extensive and up to date, so be sure to get familiar with it.
There is one Twig function added in Flynt to render components into templates:
renderComponent(componentName, data)renders a single component. For example, in theindex.twigtemplate.
Besides the main document structure (in ./templates/_document.twig), everything else is a component.
A component is a self-contained building-block. Each component contains its own layout, its ACF fields, PHP logic, scripts, and styles.
ExampleComponent/
├── functions.php
├── index.twig
├── README.md
├── screenshot.png
├── script.js
├── style.scss
The functions.php file for every component in the ./Components folder is executed during the WordPress action after_setup_theme. This is run from the ./functions.php file of the theme.
To render components into a template, see Page Templates.
Defining Advanced Custom Fields (ACF) can be done in functions.php for each component. As a best practise, we recommend defining your fields inside a function named getACFLayout() which you can then call in a field group.
For example:
namespace Flynt\Components\BlockWysiwyg;
function getACFLayout()
{
return [
'name' => 'blockWysiwyg',
'label' => 'Block: Wysiwyg',
'sub_fields' => [
[
'label' => __('Content', 'flynt'),
'name' => 'contentHtml',
'type' => 'wysiwyg',
'delay' => 1,
'media_upload' => 0,
'required' => 1,
],
]
];
}Field groups are needed to show registered fields in the WordPress back-end. All field groups are created in the ./inc/fieldGroups folder. Two field groups exist by default: pageComponents.php and postComponents.php.
We call the function getACFLayout() defined in the functions.php file of each component to load fields into a field group.
For example:
use ACFComposer\ACFComposer;
use Flynt\Components;
add_action('Flynt/afterRegisterComponents', function () {
ACFComposer::registerFieldGroup([
'name' => 'pageComponents',
'title' => 'Page Components',
'style' => 'seamless',
'fields' => [
[
'name' => 'pageComponents',
'label' => __('Page Components', 'flynt'),
'type' => 'flexible_content',
'button_label' => 'Add Component',
'layouts' => [
Components\BlockWysiwyg\getACFLayout(),
]
]
],
'location' => [
[
[
'param' => 'post_type',
'operator' => '==',
'value' => 'page'
],
[
'param' => 'page_type',
'operator' => '!=',
'value' => 'posts_page'
]
]
]
]);
});Here we use the ACF Field Group Composer plugin, which provides the advantage that all fields automatically get a unique key.
Flynt includes several utility functions for creating Advanced Custom Fields options pages. Briefly, these are:
Flynt\Utils\Options::addTranslatable
Adds fields into a new group inside the Translatable Options options page. When used with the WPML plugin, these fields will be returned in the current language.Flynt\Utils\Options::addGlobal
Adds fields into a new group inside the Global Options options page. When used with WPML, these fields will always be returned from the primary language. In this way these fields are global and cannot be translated.Flynt\Utils\Options::getTranslatable
Retrieve a translatable option.Flynt\Utils\Options::getGlobal
Retrieve a global option.
Timber provides a resize filter to resize images. This filter creates all images on the page when it's loaded for the first time. If there are many images on one page then this can lead to a very slow load time, or even a complete timeout.
Flynt solves this with the resizeDynamic filter. This filter only generates images when the image is requested, rather than when the page is loaded.
All of the generated images are stored in uploads/dynamic. If you want to manually regenerate all of these images you can delete this folder and the next time an image is requested it will be regenerated.
resizeDynamic also creates a WebP file of each image it resizes. For this to work, it adds a rewrite rule to .htaccess so that Apache will automatically serve the WebP version to all browsers that support it.
You can disable the dynamic resize functionality and WebP generation by using the filters Flynt/TimberDynamicResize/disableDynamic and Flynt/TimberDynamicResize/disableWebp. If you change the enable dynamic resizing again, make sure to flush your permalinks.
This project is maintained by bleech.
The main people in charge of this repo are:
To contribute, please use GitHub issues. Pull requests are accepted. Please also take a moment to read the Contributing Guidelines and Code of Conduct.
If editing the README, please conform to the standard-readme specification.
MIT © bleech