Read Me

Some working examples...

...to make this theme work

Notice how we semantically set the correct elements such as h1 and h2 through the page, but use the class "heading--x" to provide the correct style

Use the link below to scroll down to the right section, using a [data-intercept], or skip straight to that section to read more about intercepts!

Read more

Skip to intercepts

This theme is not a framework

It doesn't aim to make it so that clients can adapt anything on the page at will, the theme is developed around the idea that design is important and that means control over what is displayed on the page and how

While it may be the best solution to incorporate frameworks into this theme on a case by case basis, it is not built to provide complicated grids and layouts out of the box.

What the theme does provide is a set of utilities and shortcuts to outputing content as well as hopefully keeping the templates nice and clean!

This theme's file structure...

...where to look for files to edit!

The structure of the theme is laid out to provide a relatively simple route to finding the files you need to edit without having to trawl through large PHP code. The aim is to employ DRY techniques so that the same code isn't repeated in multiple files.

Files can be found inside the theme folder /home/customer/www/ananas-anam.com/public_html/wp-content/themes/pinatex, and its mian subfolders are described below:

library

Here is where you'll find the files and assets for the theme. In general you should only need to worry about the scss, js, and images folders.

If you do have custom web fonts with a valid license you can add them to the font folder. However remember fonts can be large files and contribute to a site's bandwidth quota.

js

You shouldn't need to change any files that aren't in the root js folder, other files are libraries or utilities that shouldn't need adapting.

scss

The main files you'll want to change are _frontend.scss as well as any extra scss files you create. Please create an scss file for each different template at the very least, if not also for specific parts of pages that are repeated across the site. These can be placed in the modules and pages folders and included into the main stylesheet style.scss

images

Sometimes you'll want to upload images for use in stylesheets, and this is the place for them. For anything larger than icons, especially when jpg files, consider using an ACF field to get the value of an uploaded image, to leverage the responsive image sizing that can bring.

Templates and PHP "parts"

Templates can be found in the folders that begin templates__. You shouldn't need to edit any of the files in the theme root such as header.php or single.php

Use your common sense with these files, and feel free to ask if there are any complex changes you need to make to page templates, such as to the default header and footer

Important snippets of PHP, "parts" also exist in the inc folder under different folders. Please take a moment to review what's present and to gauge what may be useful

SCSS

Take a few minutes to look through the mixins.scss, _base.scss and _frontend.scss to see what kinds of styles and tools are ready out of the box.

Examples of SCSS and CSS classes that make things quicker include:

  • @include hover() { } for quick application of hover styles to focus and tap events.
  • @include fill(); to set a position to absolute and all edges to "0".
  • @include mq-min($size) { } to wrap around content for a quick min-width media query.
  • @include before() { } to create a psuedo element primed with content: "" and display: block; Also available as after().
  • .wrap to constrain areas to a max-width responsively. Also .wrap--large.
  • .fix-inline-gaps forces children to be inline-block with no gaps between their elements. Resets their font size to 1rem in the process.
  • .accessiblyhidden to hide content from the screen but not remove it from screen readers

Advanced Custom Fields (ACF)

This theme heavily uses ACF fields, and you'll see references to ACF variables throughout the theme. Create fields where appropriate to provide a friendly interface to manage content on the page within the defined design.

Some fields are already in place to make it simple to add content, for example the social media page part. There is also a "content rows" group that is used as default on posts for the theme. The styling, present in _frontend.scss may need tweaking but the output and core styling should be present to quickly output posts for the site with minimal effort

[data-ifjs]

This section shows a [data-ifjs] attribute in action.

By adding this attribute with the value "transition" and a [data-ifjs-class] attribute to provide a css class that is added, a css driven transition is performed when the element scrolls in to view

  • We can also use the "cascade" value...
  • ..To bring elements in one after the other...
  • ...in quick succession!

Remember that you can create your own transitions, in transitions.js.

Simple Example

Using data-ifjs="transition" you can add your own class to [data-ifjs-class], such as "spin". Simply adding the following code to modules/_transitions.scss may trigger a spin transformation on the element when it comes in to view.

.spin {
	@include transition(all 1s);

	&-hold {
		opacity: 0;
		@include transform(rotate(0deg));	
	}

	& {
		opacity: 1;
		@include transform(rotate(360deg));
	}
} 

Advanced Example

Setting [data-ifjs] to something other than cascade or transition requires you to create your own function in transitions.js, prefixed with "ifjs_".

If you wanted to create a new function, ifjs_shake() that did more complicated changes than cascade or transition try copying the ifjs_transition function and renaming it and altering the code in the ifjs_core_trigger() callback.

You would then just need to define a class with [data-ifjs-class] as appropriate as per the simple example above to help provide the styling!

[data-parallax] and adding images

This section shows a [data-parallax] attribute in action, it also shows how to add an image

At its simplest adding something like data-parallax="-0.5" to an element will force it to absolute and make move in parallax with other content. It is currently best used added to an image.

There are other niche uses that can also be leveraged, such as using [data-parallax-hide] to fade content in and out at the same time, and [data-parallax-axis] to experiment with making the content transform on the Z Axis.

Further documentation can be found in the utils/parallax.js file in library

Adding an image

Images can be complicated, so I want adding them to be as simple as possible. The recommended route for adding an image is to create an ACF field to hold it and output its value as an Array. This value can then be passed into a PHP include to output it on page.


<?php 
	$image = get_field('image');
	include(inc('images/image.php')); 
?>

However this is its most simple application, a more compicated version might be...


<?php 
	//Get the main image
	$image = get_field('image'); 

	//Get a different image for smaller widths (usually square or slightly portrait)
	$mobile = get_field('image_mobile'); 

	// Fit the image to the container, like background-size: cover
	$fit = true; 

 	//Make the image parallax
	$parallax = -0.5;

	//Add a class to the picture
	$classes = "picture-1"; 

	//Set sizes that the browser can use to responsively get the right image to display
	$sizes = "(min-width: 60em) 50w, 100vw" 

	//As above, but for the portrait version
	$sizes_p = "(min-width: 60em) 50w, 100vw"

	//Add itemprops where you're providing correct schema.org properties
	$itemprops = 'itemprop="logo"';

	//Add alt text to the image
	$alt_text = get_field('image_alt');

	include(inc('images/image.php')); 
?>

The image provided doesn't have to be an array, it can also be a string. This is especially useful for SVGs where you may provide a URI to an SVG and it will embed the SVG into the page as HTML.

It's worth noting you can always use .object-fit on something, especially an image, to make it stretch to fill its container. There is also code in place to provide a fallback for older browsers.

[data-intercept]

TBC, for now see utils/intercepts.js in library

Sliders

TBC

Leveraging CSS Grid

If you haven't already, check out the CSS Grid cheatsheet on CSS Tricks

CSS Grids are awesome

You can use them in a really simple way...

...creating rows and columns...

...But that's no fun!

Check out grid-template-areas for REAL power

However we're in the early days of CSS Grid support, and this means that very recent versions of Safari and Internet Explorer/Edge don't support grids. Whenever we leverage CSS Grid, we must ALWAYS progressively enhance.

Using SCSS this is easy...

	.grid-element {
		//Normal code for non-CSS Grid compliant browsers
		display: inline-block;
		width: 50%;

		@include css-grid-only() {
			//CSS Grid compliant browser code here
			width: 100%;
		}
	}

This will output @supports (display:grid) conditionals that ensure only browsers that can deal with CSS Grids try to implement the code.

Any questions?

This is very much a work in progress and an evolving theme. If you find any bugs then let me know (especially if you already have a fix!). If you are left wondering how something should work or if something should be more simple to use, lets talk about it and improve the theme

Last updated: 12th October 2017

Future Todo List:

  • Move certain elements of code into plugins rather than theme functions