Documentation.

Welcome to Inti Foundation! This documentation is represents our best effort at explaining some of the basics of the framework, particularly those elements that might not be obvious or are not specifically related to either WordPress or Foundation 6.

For help with WordPress issues please visit the WordPress codex.

For help with Foundation issues, the Foundation docs are an excellent resource.

This documentation assumes you know how to do things in WordPress such as:

  • add custom types or custom taxonomies
  • add or remove actions and filters
  • overwrite a parent’s template in a child theme

It assumes your front end development skills include experience with:-

  • using Gulp to compile Sass
  • using Foundation 6 and things like its Grid system

Getting started.

  • Setting up

    Gulp

    Inti Foundation and its child themes come configured with a Gulp file that will compile your Sass and code changes for you with its watch function. (If your workflow doesn’t include Gulp, please review this file to see what library elements need to be compiled into a final CSS file with your own tools).

    The best way to customize Inti Foundation is to create a child theme. Consider doing that before making edits to the parent theme.
    LevelUpTuts provide a free tutorial on Gulp that we’d highly recommend… Watch Here

     

    Activating

    Inti Foundation (and a child theme) should be uploaded to wp-content/themes and activated.

    If you immediately visit the site, you’ll see the homepage is not displaying any content and that there is no menu set up. We need to set up the initial settings.

  • Initial Settings

    Front Page and Blog Index

    The majority of sites require a Home Page and a Blog Index page. In the WordPress Dashboard, publish a page called Home and another called Blog. In Settings->Reading in the WordPress Dashboard, set ‘Home’ as the front page and ‘Blog’ as the blog page.

     

    Theme Options

    inti-optionsBy default, the front page template, displays a loop of posts underneath. It will display that no posts are found by default. This is because we need to set up the default Theme Options (if your theme doesn’t need this, feel free to delete it or override in a child theme).

    Take time to review each tab of Inti Options in the Dashboard and configure as needed. Here you’ll generally find settings that are more to do with how the site works and what it contains rather than how the site looks.

     

     

    Customizer

    As well as an integrated theme options page, Inti Foundation supports the WordPress customizer. Here we include options to configure how the site looks — things that might benefit from an immediate visualization of what’s being changed. Some settings overwrite CSS values or HTML templates. Feel free to remove theses options.

    customizer

    When adding your own options, consider if you’d prefer them to be in Theme Options or in the Customizer… or simply remove one altogether.

     

    Menus

    No menu will appear on the site until you create and assign one in Appearance->Menus

Finding your way around.

  • Theme Structure

    Theme Structure

    /

    • framework (The core, integrate all WordPress functionality here)
      • content (things we add to hooks on templates, usually conditional)
      • customizer (all code relating to Customizer-based options)
      • extensions (functionality that extends an otherwise basic theme)
      • functions (functions that make the theme work)
      • metaboxes (add new metabox functionality here)
      • post-types (add new post types and their taxonomies here)
      • shortcodes (all code relating to the shortcodes)
      • theme-options (those options outside of the Customizer interface)
      • widgets (all code for custom widgets is found here)
      • inti.php (the class that creates the theme)
    • library (our Sass files, compiled files and vendor files)
      • dist (files compiled for distribution, will only exist when you run gulp build for the first time)
      • src (source but useless files until you start using gulp build or watch functions) 
        • webfonts (any webfonts go here then get added from a CSS file added to the CSS directory)
        • js (app javascript, or additional vendor files for webpack, if this is preferred over individual WP loaded scripts)
        • scss (this is life, half of everything you do will happen here or in the child theme equivalent)
    • loops (where the long loops reside)
    • page-templates (where you can add custom templates for pages)
    • post-formats (WordPress post format templates)
    • template-parts (bits of template not part of WordPress)
    • functions.php (Turn on and off parts of the framework, and provide parameters while doing so)

     

    TL,DR

    Damn right. You really need to browse through each directory and each file to see what it’s for. You’ll find comments throughout explaining what’s what.

    But let’s explain some key concepts…

    LIBRARY is where all your CSS/JS goes and gets compiled to, then gets added to the theme from FRAMEWORK/EXTENSIONS/scripts.php and styles.php

    FRAMEWORK is home to functionality that isn’t directly related to visible site templates. All the framework’s features are found here, organized again into sub-directories. Should one of these sub-systems require admin-side JS or CSS, this is always contained within the sub-system’s own directory.

    In FRAMEWORK/CONTENT you’ll find bits and pieces of content… from menus, to breadcrumbs, to footer elements, to post meta that doesn’t have a specific set place in any template. Instead, these pieces of content are attached to the hooks that are found throughout the theme, allowing a developer to control where they appear on multiple templates from one single place.

  • Main Menu

    The main menu is one of three declared by default in functions.php

    By default it is a Foundation 6 Drop Down Menu.

     add_theme_support( 'inti-menus', array('dropdown-menu', 'off-canvas-menu', 'footer-menu') );

    It is then declared and configured in FRAMEWORK/EXTENSIONS/menus.php

    function inti_register_menus() {
      $menus = get_theme_support( 'inti-menus' );
      if ( !is_array( $menus[0] ) ) { return; }
      // This is the main menu visible on larger screens
      if ( in_array( 'dropdown-menu', $menus[0] ) ) {
        register_nav_menu('dropdown-menu', __( 'Main Desktop Menu', 'inti'));
      }
    }
    add_action('init', 'inti_register_menus'); 

    function inti_get_dropdown_menu() {
      $defaults = wp_nav_menu(array(
        'container' => false, 'echo' => false, // Remove nav container
        'menu_class' => 'dropdown menu', // Adding custom nav class
        'items_wrap' => '%3$s',
        'theme_location' => 'dropdown-menu', // Where it's located in the theme
        'depth' => 5, // Limit the depth of the nav
        'fallback_cb' => false, // Fallback function (see below)
        'walker' => new Dropdown_Menu_Walker() )
      ); 
      return apply_filters('inti_filter_dropdown_menu', $defaults);
    } 

    You’ll then find it used in FRAMEWORK/CONTENT/content-header.php

    Here it is placed into a Foundation 6 Top Bar

  • Off Canvas Menu

    The Foundation 6 Off Canvas menu is used, by default, as the menu for small mobile devices. It too is declared in functions.php

    By default it is a Foundation 6 Drill Down Menu.

     add_theme_support( 'inti-menus', array('dropdown-menu', 'off-canvas-menu', 'footer-menu') );

  • Site Banner

    We call the header area where the logo or hero banner image is displayed, the “site banner”. Depending on where the main menu is hooked, it might appear below or above the main menu. There are a number of options for this that can be set in Customizer, and the code can be found and modified in one of the banner variations in TEMPLATE-PARTS/part-banner-*.php

  • Breadcrumbs

    Breadcrumbs can be turned on and off in the theme options and their functionality controlled from FRAMEWORK/EXTENSIONS/breadcrumbs.php

  • Content

    The layout of the content area of a page or a post can be set in two ways;

    1. Through Customizer, setting a default site-wide layout
    2. For each individual page when editing through the Dashboard

    The available layouts, by default, are:

    • One Column (A single column occupying the 12 Foundation grid columns)
    • Two Columns, Left (A sidebar is displayed, the content to the left, the sidebar to the right)
    • Two Columns, Right (A sidebar is displayed, the content to the right, the sidebar to the left)
    • One Column, Thin (The content column is displayed at the same width as if there was a sidebar, centered)

    You can see what measurements columns are given with relation to the Foundation Grid by examining the template files such as single.php, page.php, archive.php etc.

    These will generally either display a loop as found in LOOPS/ or a post format as found in POST-FORMATS/

     

  • Sidebar

    Three types of sidebar are declared by default in functions.php

    add_theme_support('inti-sidebars', array('primary', 'frontpage', 'footer'));

    The sidebars are then registered and configured in FRAMEWORK/EXTENSIONS/sidebars.php

    Inti Foundation comes with two example widgets. These can be found and expanded upon in FRAMEWORK/WIDGETS

Child Themes

Creating a Child Theme is the best way to create a unique theme of your own while preserving the integrity of Inti Foundation if you’d like to keep your theme up to date with any new features that are added or bugs that are fixed.

There are two types of child theme you can create. A basic one, where you’re really just interested in overriding a couple of templates or styles, and a full-on one, where you replace the entire library with a local one, recompiling Foundation 6 Sass files, Inti’s Sass files, your own Sass files, and adding new vendor files.

  • Blank Child Theme

    The blank child theme, available to download here, is the most basic child theme you can use. The settings found in functions.php are all overwritten (see ‘Turn on/off Features‘ below). The library still comes from the parent theme. All the templates and framework files come from the parent and are overwritten one by one by recreating the directory structure and creating a file with the same name.

  • Kitchen Sink Child Theme

    The kitchen sink theme recreates the entirely library locally in the child theme. The scripts and styles from the parent theme are not longer applied to the website, which now uses those from the local library. This allows you to add entirely customized Foundation 6 base settings, rework any Inti Foundation base styles, and use and add to the vendor scripts as you require, all while maintaining and being able to expand upon all of Inti Foundations WordPress functionality.

  • ACF Pro Child Theme

    Like the Kitchen Sink, theme recreates the entirely library locally in the child theme. As with Kitchen Sink, the scripts and styles from the parent theme are not longer applied to the website, which now uses those from the local library. This allows you to add entirely customized Foundation 6 base settings, rework any Inti Foundation base styles, and use and add to the vendor scripts as you require, all while maintaining and being able to expand upon all of Inti Foundations WordPress functionality.

    What’s the difference? It’s Built for Advanced Custom Fields Pro (ACF)

    ACF PRO is a WordPress plugin that allows developers to rapidly develop backends with complex custom fields without having to manually code them or their interfaces.

    This theme contains block templates using repeatable fields from ACF but also Gutenberg Blocks.

  • Turn on/off Features

    In functions.php, a number of calls to add_theme_support() exist that can turn features on and off throughout the theme and pass values to set some of these features up.

    add_theme_support(
    'inti-menus',
    array('dropdown-menu', 'off-canvas-menu', 'footer-menu')
    ); add_theme_support(
    'inti-sidebars',
    array('primary', 'frontpage', 'footer')
    ); add_theme_support(
    'inti-layouts',
    array('1c', '2c-l', '2c-r', '1c-thin')
    );

    You may want to overwrite the above, or rework it, but at it’s simplest, you can just remove one and that feature will stop working throughout the theme.

  • Overriding Functionality

    There are multiple ways to do this, with varying levels of extremity.

    Completely vaporize a file with locate_template()

    require_if_theme_supports('inti-menus', locate_template('/framework/extensions/menus.php'));

    Adding a file in your child theme called menus.php, while placing it in a recreated structure of FRAMEWORK/EXTENSIONS will completely replace the file and absolutely everything inside it. You might want to copy and paste its contents into your own menus.php

    What to expand on that file without replacing it? Create a new file called child-menus.php and add a new require_if_theme_supports() for it in your functions file.

     

    Remove actions from hooks

    Inti Foundation template files and functions are full of hooks and filters. The hooks allow you to output some form of content to one or multiple places, usually after having molded what this would be with complex conditional statements or formatting. For example, in FRAMEWORK/CONTENT/content-footer.php we have a function that gets the Google Analytics ID from theme options and outputs the completed javascript in the footer of the page.

    function inti_do_footer_analytics() {
    $analytics_id = stripslashes(get_inti_option('analytics_id', 'inti_footer_options'));
    if ( $analytics_id ) { ?>
    <!-- Google Analytics -->
    <script>
    ...
    </script>
    <!-- End Google Analytics -->
    <?php
    }
    }
    add_action('inti_hook_footer', 'inti_do_footer_analytics', 2);

    Don’t want this here? Do you use a plugin for the same purpose? Then remove it…

    function child_remove_actions(){
    remove_action('inti_hook_footer', 'inti_do_footer_analytics');
    }
    add_action( 'after_setup_theme', 'child_remove_actions', 0 );

    What to remove it so you can write it again differently, perhaps with different conditions? Then create a new function and re-add it.

    function my_own_much_better_do_footer_analytics() {
    $analytics_id = stripslashes(get_inti_option('analytics_id', 'inti_footer_options'));
    if ( $analytics_id && $someothercondition ) { ?>
    <!-- Google Analytics -->
    <script>
    ...
    </script>
    <!-- End Google Analytics -->
    <?php
    }
    }
    add_action('inti_hook_footer', 'my_own_much_better_do_footer_analytics', 2);

    Google recommends adding its Analytics code in the header. Inti Foundation prefers it in the footer so it loads at the end. Is Google right? Then remove the action as above, then re-add it on a hook you prefer…

    function child_remove_actions(){
    remove_action('inti_hook_footer', 'inti_do_footer_analytics');
    add_action('inti_hook_head', 'inti_do_footer_analytics');
    }
    add_action( 'after_setup_theme', 'child_remove_actions', 0 );

     

    Pluggable functions

    Some of the functions in the parent theme that do things that don’t lend well to filters have been made plugable.

    if ( !function_exists( 'inti_get_dropdown_social_links' ) ) {
    function inti_get_dropdown_social_links() { ...     } }

    In your own code, you can simply recreate this function with the same name. Since the child theme is initialize first, your function will be the one that runs, while the parent theme function will be prevented from running by the function_exists() condition.

  • Overriding Templates

    We’ve covered how to overwrite framework files, or just parts of them, above. But we also have to deal with templates the structure how the content is outputted.

    Files such as page.php, single.php, archive.php, header.php etc are pretty standard WordPress fare. As with any child theme, by simple adding a version of these files with the same name into your child theme, you overwrite them completely.

    The same is true of all the template parts, loops and custom page templates organized into directories such as LOOPS, PAGE-TEMPLATES, POST-FORMATS, TEMPLATE-PARTS etc. Just create your own versions in the child theme and adapt them as needed.

Options

The theme can be configured (and more options can be added as you develop your own theme) with either an Options page or with Customizer in live preview mode. Both methods have been added by default in Inti Foundation so that you can choose which you’d prefer to you for your own options. By default, options that are more to do with global settings have been added to an Options page called “Inti Options” and options that are more to do with visual elements have been added in Customizer. Feel free to modify these as you see fit.

 

  • Have a look around

    Have a look around and set the options activate elements in the theme. Perhaps the most important area is found in the Customizer and relates to the header area.

Shortcodes

Foundation 6 has a tonne of components built in and these are made available in Inti Foundation as WordPress shortcodes.

  • Turn them on

    Inti Foundation shortcodes

    You can turn shortcode picker tool on and off in functions.php

    add_theme_support('inti-shortcodes');

     

  • Expansion in Child Themes

    Creating your own shortcodes, or overwriting the default Inti Foundation ones is simple.

    Inti Shortcodes theme structure New shortcodes you create must contain two files, PHP and JS.

    The PHP file contains a function for the shortcode output (what is displayed to the public visiting the website) and a form template for adding options to the shortcode picker (available wherever the WP_Editor is). It also contains functions to enqueue the JS file.

    The JS file contains two event watchers. One detects the change on the selected shortcode in the picker to display the options form, one detects a click on the insert button and builds a valid shortcode tag from the options form.