BeAPI FrontEnd Framework (BFF) is an open source framework for WordPress stacks. Mobile-first projects with the latest useful tools for the Frontend Development like Webpack 3, SASS, Favicons and SVG sprite icon generation and custom tools like ComposerJS.
You need to work in a wordpress environnement in order to make the BFF work with webpack for local dev. To do that you need to install Advanced Responsive Images in your plugin folder.
git clone https://github.com/asadowski10/advanced-responsive-images.git
With this plugin you can manage thumbnails with the <picture> tag through differents configurations located in src/conf-img. For more details go to the Responsive images section
You have to install Webpack and Concurrently globaly.
$ npm install webpack@3 concurrently -g
Clone the repository in the WordPress's themes folder. Remove the .git folder in order to work with your own repo.
$ cd wp-content/themes
$ git clone https://github.com/BeAPI/beapi-frontend-framework.git name_of_my_theme
$ cd name_of_my_theme
$ mv build.sh ../../../
$ rm -rf .git
Then install dependencies with NPM.
$ npm install
Or using Yarn.
$ yarn
In the config directory, you can find the Webpack configurations files.
- config.js — the configuration settings (entries, output, port etc…)
- css-loader.js — the common loaders for CSS, SASS and SCSS filetypes
- server.js — the Browser Sync configuration
- webpack.base.js — the basic configuration of Webpack for development and production purpose.
- webpack.dev.js — the configuration of Webpack for development purpose
- webpack.prod.js — the configuration of Webpack for production purpose
First you need to add this following lines in your hosts files :
::1 localhost
You must build the dist folder before lauching the php server :
$ npm run build:dev
Then you can launch a local php server with Browser Sync using :
$ npm start
But in order to work correctly you have to run a build:dev script first (it will generate svg icons sprite)
If you don't need this server you can just compile AND watch styles and scripts (with sourcemap) using :
$ npm run watch
If you want to just build styles and scripts (with sourcemap) use :
$ npm run build:dev
For production purpose, you can compile all of your assets by using :
$ npm run build:prod
If you want to deliver assets for both developpement and production
$ npm run build
If want to bump your WordPress theme version you can add a flag like this :
$ npm run bump -t minor
For example, if you have a 1.2.1 theme version, it will be bumped to 1.3.0. You can replace minor by patch or major.
Generate appicons and favicons from the sources files in src/img/favicons/ by using :
$ npm run favicon
Generate SVG sprite from the icons files in src/img/icons/ by using :
$ npm run icons
Generate JSON image sizes and locations (more details in the Responsive images section) by using :
# you can add csv as argument to generate a CSV file of image locations
$ npm run image [csv]
To prevent WordPress and/or browsers cache issues, you can update the version of style.css in the theme's root. There are 3 kinds of update available : patch, minor or major.
$ npm run bump [-t | -type] [patch | minor | major]
In the case of a multiple themes of a Wordpress project, you can use the previous task in any themes in one command with a bash script. To use the command, you have to be in the Wordpress root path. By the way, you can specify the type of bump wanted.
$ sh build.sh [-t | -type] [patch | minor | major]
We like to present and order our css like this:
.module {
Position properties (z-index, top etc.)
Display properties (padding, margin, border etc.)
Text properties (font-family etc.)
Colors properties (color, background, etc.)
Mixins (transition etc.)
Others (white-space etc.)
@include media($desktop-small) {
Responsive stuffs
}
}
We do not fully respect the BEM css method but we like this kind of OOCSS:
.module-name (.header)
.module-name__element (.header__column, .header__button etc.)
.module-name__element--modifier (.header__element--visible, .header__element--color-2 etc.)
Keep in mind that your class will be more reusable if they are generic enough. If you have too much subelements in your class, there's a problem in your markup.
For example
.entry-metas
.entry-metas__date
.entry-metas__date__month
Should be
.entry-metas
.entry-date
.entry-date__month
Cause date element could be used outside metas. You shouldn't have more than 1 subelement, except in really specifical cases.
We like to keep our code clean and readable. This is why we skip lines between each selectors and add empty line between declarations and includes (like media queries)
// Example
.class,
.class--alt {
attr: value;
@media screen and (min-width: $breakpoint) {
attr: value;
}
}
CSS partials are classified and saved in 6 mains folders
- root. Where you define common base. Variables, Mixins, Fonts, Susy library etc.
- vendor. It's where external ressources are (jQuery plugins fr example).
- components. The basics like button forms elements etc. It's where you can defined you root's styles for button input headings etc.
- wp-plugins. One file by WordPress plugins (Mailpoet, WPForms etc.). in order to define the base style of plugin in the theme. Make specific style in your patterns or pages.
- wp. Specific wp related pattern.
- patterns. it's related to your modules. It's where you defined the basics for your module.
- pages. a css file for each pages. very useful for change module behavior in a specific context.
- All those parts are referenced in src/css/style.scss. Don't forget to add your files here in the correct order.
As said above all JavaScript ressources are compiled with Webpack with a sourcemap for debbugging.
If you need a library, install it with npm.
$ npm install --save my_lib
Then you can require it where you need to use it, like this :
$ import npm_lib from 'npm_lib'
If there is no packages available on npm for the library you need, paste the dist file into js vendor folder. Then you have to require it :
$ import vendor_lib from '../vendor/vendor_lib'
We are using ESLint coding Standard : https://github.com/standard/standard
In order to keep a lightweight stack, you can add extra components that are used most of the time in Web dev. You have to use composerjs
You can add a livingCSS by cloning this repo : https://github.com/BeAPI/living-css
WordPress native thumbnails are not enough for us. We want to build images:
- That can have differents art direction between differents viewports
- That can be displayed in the good resolution
- That can be lazyloaded, but still accessible if no Javascript.
Something like this:
<picture>
<!--[if IE 9]><video style="display: none"><![endif]-->
<source
srcset="data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw=="
data-srcset="img-mobile, img-mobile 2x"
media="(max-width: 375px)" />
<source
srcset="data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw=="
data-srcset="img-tablet, img-tablet 2x"
media="(max-width: 1024px)" />
<source
srcset="data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw=="
data-srcset="img-desktop, img-desktop 2x" />
<!--[if IE 9]></video><![endif]-->
<img src="data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==" class="lazyload" alt="image with artdirection"/>
</picture>
So with the Advanced Responsive Images plugin we can manage a picture tag with different file configuration.
- provide a 2x img with "x" descriptor. perfect for thumbnails. ( srcset="my_image, my_image-HD 2x" )
- provide a range of image depend on viewport with "w" descriptor. ( srcset="my_image-mobile 480w, my_image-tablet 768w, etc." )
You have to build your picture template in src/conf-img/tpl. default-picture.tpl is the main <picture> container. In this tpl we can see the reference for the sources we want, for example in entry-img-01.tpl we want a square image under 1024px viewport, displayed in normal or 2x resolution, for bigger screen a landscape image:
<source data-srcset="%%img-100-100%%, %%img-200-200%% 2x" media="(max-width: 1024px)" %%srcset%% />
<source data-srcset="%%img-300-200%%, %%img-600-400%% 2x" %%srcset%% />
Then run the following command to generate your JSON image locations and sizes :
$ npm run image
Example of src/conf-img/images-sizes.json :
"img-100-100":
{
"width":"100",
"height":"100",
"crop":true
}
Example of src/conf-img/images-locations.json :
"entry-img-01": [
{
"srcsets": [
{
"size": "img-100-100"
},
{
"size": "img-200-200"
},
{
"size": "img-300-200"
},
{
"size": "img-600-400"
}
],
"default_img": "default-300-200.jpg",
"img_base": "img-300-200"
}
]
default_img is used for default image if no image are provoded in WordPress Admin. img_base is used as fallback for older browser.
You can use this Sketch extension to generate default image according to your images-locations.json file. There is a sketch file provided in the src/img/default folder.
Now you can use it in your markup like this:
<?php echo get_the_post_thumbnail( 0, 'thumbnail', array( 'data-location' => 'entry-img-01' ) ); ?>
If you need to add a class to your picture (the lazyload class is added by default):
<?php echo get_the_post_thumbnail( 0, 'thumbnail', array( 'data-location' => 'entry-img-01', 'class' => 'my_class_name' ) ); ?>
We add Lazyload support too! We use Lazysize in addition to picturefill in order to provide responsive image served as fast as possible.
If you don't want this feature you still can set BEA_LAZYSIZE to false in /functions/class-bea-images.php. it will turn the markup to basic img tag with srcset.
Lazysize is also used for displaying background image in different sizes for differents viewports. Look at the Lazysize bgset documentation and the page__header or hero pattern.