Flynt

Short Description

Flynt is a WordPress theme for component-based development using Timber and Advanced Custom Fields.

Table of Contents

• Install
  • Dependencies
• Usage
  • Assets
  • Lib & Inc
  • Page Templates
  • Components
  • Advanced Custom Fields
  • Field Groups
  • ACF Option Pages
  • Timber Dynamic Resize
• Maintainers
• Contributing
• License

Install

1. Clone this repo to

   /wp-content/themes

   .
2. Change the host variable in

   flynt/build-config.js

   to match your host URL:

   const host = 'your-project.test'

3. Navigate to the theme folder and run the following command in your terminal:

   # wp-content/themes/flynt
   composer install
   npm i
   npm run build
   

4. Open the WordPress back-end and activate the Flynt theme.
5. Run

   npm run start

   and start developing. Your local server is available at

   localhost:3000

   .

Dependencies

• WordPress >= 5.0
• Node = 12
• Composer >= 1.8
• Advanced Custom Fields Pro >= 5.7

Usage

In your terminal, navigate to

/wp-content/themes/flynt

npm start

localhost:3000

All files in

assets

Components

dist

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

Assets

The

./assets

./dist

The

main.scss

./dist/assets/main.css

The

admin.scss

./dist/assets/admin.css

Lib & Inc

The

./lib

./lib

./lib

The

./inc

functions.php

./inc

For organisation,

./inc

• 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

./inc

./Components

Page Templates

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)

index.twig

Besides the main document structure (in

./templates/_document.twig

Components

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

./Components

after_setup_theme

./functions.php

To render components into a template, see Page Templates.

Advanced Custom Fields

Defining Advanced Custom Fields (ACF) can be done in

functions.php

getACFLayout()

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

Field groups are needed to show registered fields in the WordPress back-end. All field groups are created in the

./inc/fieldGroups

pageComponents.php

postComponents.php

We call the function

getACFLayout()

functions.php

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.

ACF Option Pages

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 Dynamic Resize & WebP Generation

Timber provides a

resize

That's why Flynt provides a

resizeDynamic

Resized images are stored in

uploads/resized

To enable Dynamic Resize and WebP Support, go to Global Options -> Timber Dynamic Resize. ​

Troubleshooting

​ If

resizedDynamic

location ~ "^(.*)/wp-content/uploads/(.*)$" {
  try_files $uri $uri/ /index.php$is_args$args;
}

1. Some plugins (like WPML) manipulate the

   home_url

   in such a way that

   resizeDynamic

   cannot resolve the path to images correctly. In that case, set the relative upload path manually in Global Options -> Timber Dynamic Resize. Example: The relative upload path in Bedrock installs with WPML needs to bet set to

   app/uploads

   .

Troubleshooting

Images

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

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.
});

Browsersync

If browsersync is not working and you are not serving WordPress on https, try changing the

browsersync.https

false

build-config.js

Maintainers

This project is maintained by bleech.

The main people in charge of this repo are: * Steffen Bewersdorff * Dominik Tränklein

Contributing

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.

License

MIT © bleech