Merge branch 'main' into documents

README.md

@@ -21,7 +21,8 @@ This is not a library but can rather be seen as an initial setup to jumpstart th
 
 ## Documentation
 
-- [Creating Custom Gutenberg Blocks](/docs/blocks.md)
+- [Creating Custom Blocks](/docs/blocks.md)
+- [Enabling Environment Variables](/docs/environment_variables.md)
 - [Enabling Hot Reload](/docs/hot_reload.md)
 
 ## Requirements
@@ -96,9 +97,9 @@ npm run build
 ```
 > See `gulpfile.js` for all tasks.
 
-Create an `.env` filed in the [theme folder directory](wp-content/themes/hozokit). An `.env.example` file is provided as a starting point.
+### Optional Steps
 
-If a `.env` file is not present the site will throw an error.
+Create an `.env` filed in the [theme folder directory](wp-content/themes/hozokit). An `.env.example` file is provided as a starting point. See [related documentation](/docs/environment_variables.md) for details.
 
 [Hot Reloading can be enabled](/docs/hot_reload.md) once the steps above have been followed.
 
@@ -116,6 +117,96 @@ A component will usually live in `/templates/components` unless it is a part of
 
 For instance a `navigation` component could be created by adding the two files mentioned before to `templates/components/navigation`. Then it can be included in pages, become part of other components and be reused as needed.
 
+## Adding data to context
+
+The idea behind this pattern is to separate markup from php logic. To achieve this we use `$context`, a php associative array that holds the data to be used in templates.
+
+The data available to these templates can be scoped to a Wordpress view (`index.php`, `single.php`, `page.php` and so on) or globaly meaning they can be accessed from any template at any time.
+
+To define context for a specific view, we first get the current Timber context and add to it just like adding to any other associative array. Here's an `index.php` as an example:
+
+```php
+<?php
+   // Get Timber's context.
+   $context = Timber::get_context();
+
+   // Add new data to this specific view.
+   // In this case the current instance of the post (userful to get the title of the page for example)
+   // and an array with all posts
+   $context['post'] = new Timber\Post();
+   $context['posts'] = Timber::get_posts();
+
+   // Then the Twig template that should be rendered is specified
+   // and the $context with the new added values is passed to it. 
+   Timber::render( 'index.twig', $context);
+?>
+```
+
+Now all values currently present in `$context` are available to `index.twig` alongside the new `post` and `posts` values we've added in. Here's how to access these values in `index.twig`:
+
+```twig
+  {% block content %}
+    {# Using the post data added to context #}
+    <h2>{{post.title}}</h2>
+    <p>{{post.content}}</p>
+
+    <h3>Posts:</h3>
+    <ol>
+      {# Using the posts data added to context #}
+      {% for post in posts %}
+      <li><a href="{{post.link}}">{{post.title}}</a></li>
+      {% endfor %}
+    </ol>
+  {% endblock %}
+```
+
+Now the values can be accessed through a variable using dot notation, nice!
+
+However, `post` and `posts` won't be available outside `index.twig`. Sometimes it is useful to have values in `$context` that can be accessed in any template. 
+
+This is useful when, for example, it is needed to display dynamic information on a footer, or perhaps there's a menu that shows in all pages, or the user avatar.
+
+To add data to `$context` that can be accessed in any template (globally) we need to make use of a filter. Here's an example in `functions.php`:
+
+```php
+  // Adds additional data to the site context.
+  // This makes it available in the templates.
+  // The filter is required so the data is added at the correct stage.
+  add_filter( 'timber/context', function( $context ) {
+    # Add the new data here.
+    $global_context = array(
+      'example' => 'add new entries to this array to make them available anywhere in any Twig template.',
+      'user_is_admin' => current_user_can('administrator')
+    );
+
+    # Merges your additions with the current context.
+    $context = $context + $global_context;
+    return $context;
+  } );
+```
+
+To use it, we can reference it in our templates the same way as before. Here's an updated example of `index.twig`, notice how `example` is used but it was not added to context via `index.php` but via `functions.php`:
+
+```twig
+  {% block content %}
+    {# Added via index.php #}
+    <h2>{{post.title}}</h2>
+    <p>{{post.content}}</p>
+
+    <h3>Posts:</h3>
+    <ol>
+    {# Added via index.php #}
+      {% for post in posts %}
+      <li><a href="{{post.link}}">{{post.title}}</a></li>
+      {% endfor %}
+    </ol>
+
+    {# Added via functions.php and can be accessed in other templates #}
+    <blockquote>{{example}}</blockquote>
+  {% endblock %}
+```
+
+
 ## Styling the theme and components
 Styles are written in [SCSS](https://sass-lang.com/) files and are then merged and converted into a `style.css` for the browser to understand. There are two strands of files, *base* files that live in `/styles` such as `base.scss` or `palette.scss` which hold rules that multiple elements and components make use of.
 

docs/environment_variables.md

@@ -0,0 +1,65 @@
+# Enabling Environment Variables
+
+Environment variables is a feature that can be optionally enabled in Hozokit.
+
+When enabled, Hozokit will make use of environment variables to configure certain features such as [hot reloading](./hot_reload.md) and change the way assets are bundled (e.g styles and scripts are not minified on a development environment)
+
+Additionally, developers can take advantage of environment variables and access them in `.twig` templates or in their `.php` scripts.
+
+
+## Setup Environment Variables
+
+1. Create an `.env` filed in the [theme folder directory](../wp-content/themes/hozokit). An [`.env.example`](../wp-content/themes/hozokit/.env.example) file is provided as a starting point.
+
+2. Set the app environment. If the value is set to development Hozokit won't minify styles which can be helpful when debugging CSS and JavaScript:
+
+```php
+APP_ENVIRONMENT='development'
+```
+
+Each environment will have its own `.env`. For example, the production server will have its `APP_ENVIRONMENT` set to `'production'`, staging to `'staging'` and so on. Each version of the site can have its own configuration.
+
+## Using environment variables
+
+Developers can take advantage of environment variables by using them in `.twig` templates and `.php` scripts.
+
+1. Add one or more variables to `.env`:
+
+```php
+APP_ENVIRONMENT='development'
+API_KEY='m3dMf6XC9NQ^ao8H3csx'
+UPDATES_ENABLED=true
+```
+
+2. Use a variable on a template. All variables become available to context by accessing `env`:
+
+```twig
+{% block example %}
+  <section class="example">
+    <h1>hozokit</h1>
+    <p>An example component.</p>
+
+    {# Makes use of environment variable to determine if markup should be rendered. #}
+    {% if env.UPDATES_ENABLED %}
+      <ul>
+        <li>New shiny colors!</li>
+        <li>Orders now get delivered right to your door for free.</li>
+        <li>Accounts can be created so users can keep track or their orders.</li>
+      </ul>
+    {% endif %}
+    
+  </section>
+{% endblock %}
+```
+
+3. Use a variable on `functions.php`. In this case a constant is used to get hold of the variable instead:
+
+```php
+$payments_key = $_ENV['API_KEY'];
+setup_payments($payments_key);
+```
+
+## Additional Notes
+
+Hozokit makes use of Vance Lucas' [phpdotenv](https://github.com/vlucas/phpdotenv) to environment variables on the `php` side and Scott Motte's [dotenv](https://github.com/motdotla/dotenv) package to make them available in internal Node scripts (`gulpfile.js`).  
+

docs/hot_reload.md

@@ -6,6 +6,8 @@ Developers might setup their server in many different ways so this needs to be c
 
 > To setup and install Hozokit, please follow the setup section of the README before following this guide.
 
+**This feature requires environment variables to be setup, please [follow the documentation on how to this](./environment_variables.md) if this is not already in place.**
+
 ## Configure your proxy
 
 Follow these steps if hot reloading is something you would like to enable.

wp-content/themes/hozokit/.env.example

@@ -4,5 +4,5 @@ APP_ENVIRONMENT='development'
 # APP_URL='http://localhost:3000'
 
 # Additional environment variables of your choice here can go here.
-# Add them to $context at /plugins/hozokit-functions/index.php
-# to make them available in twig templates.
+# Variables are added automatically to $context at 
+# /plugins/hozokit-core/index.php to make them available in twig templates.

wp-content/themes/hozokit/functions.php

@@ -1,72 +1,38 @@
 <?php
-    // Importing Hozokit Internal Plugins
-    require_once(__DIR__ . '/plugins/index.php');
-
-    // Initializing Timber.
-    require_once(__DIR__ . '/vendor/autoload.php');
-    $timber = new \Timber\Timber();
-    $timber::$dirname = array('templates', 'templates/components/');
-
-    class Site extends Timber\Site {
-      public function __construct() {
-        // Enables admin bar styling.
-	      add_theme_support( 'admin-bar', array( 'callback' => '__return_false' ) );
-        add_theme_support( 'post-thumbnails' );
-        add_theme_support( 'menus' );
-        add_theme_support( 'html5', array( 'comment-list', 'comment-form', 'search-form', 'gallery', 'caption' ) );
-        add_filter( 'timber_context', array( $this, 'add_to_context' ) );
-        // Makes menu locations available.
-        register_nav_menus(array(
-          'primary' => __('Primary'),
-          'footer' => __('Footer'),
-          // 'other' => __('Other'),
-        ));
-        hozokit_plugins_init();
-        parent::__construct();
-      }
-
-      function add_to_context( $context ) {
-        $context['menus'] = array(
-          'primary' => new Timber\Menu('primary'),
-          'footer' => new Timber\Menu('footer'),
-          // 'other' => new Timber\Menu('other'),
-        );
-        $context['site'] = $this;
-        return $context;
-      }
-    }
-    new Site();
-
-    // Insert styles and scripts to be used in the theme.
-    // The stylesheet is compiled from SASS files in /styles, scripts from /scripts using Gulp.
-    function loadStylesAndScripts() {
-      $theme_version = wp_get_theme()['Version'];
-      wp_enqueue_style( 'normalize', get_template_directory_uri() . '/assets/css/normalize.css' );
-      wp_enqueue_style( 'style', get_stylesheet_uri() );
-      wp_register_script( 'script', get_template_directory_uri() . '/assets/scripts/bundle.js', "", $theme_version, true );
-      wp_enqueue_script('script');
-      $translation_array = array( 'templateUrl' => get_template_directory_uri() );
-      //after wp_enqueue_script
-      wp_localize_script( 'script', 'wordpress', $translation_array );
-    }
-
-    // Load styles and scripts (might need wp_head or wp_footer).
-    add_action('wp_enqueue_scripts', 'loadStylesAndScripts');
-
-  // Temporary: Resets metabox data positions.
-  // This needs to be commented out when the ACF field structure becomes permanent.
-  function prefix_reset_metabox_positions(){
-    delete_user_meta( wp_get_current_user()->ID, 'meta-box-order_post' );
-    delete_user_meta( wp_get_current_user()->ID, 'meta-box-order_page' );
-  }
-
-  // Temporary: Remove admin bar in order to avoid extra margins.
-  show_admin_bar(false);
-
-  // Temporary: Keeps Gutenberg from rendering <p> tags on Timber's post.preview.
-  remove_filter( 'the_content', 'wpautop' );
+  /*
+   * Hozokit
+   * The statement below imports Hozokit Core and other internal plugins.
+   * Please keep this require statement at all times at the top.
+   * 
+  */
+  defined( 'ABSPATH' ) || exit;
+  require_once(__DIR__ . '/plugins/index.php');
 
-  /* !IMPORTANT: Only run this one when adding new custom post types.
-   * Remove when related features are added.
+  /*
+   * Functions
+   * Add theme specific functions below.
+   * 
   */
-  // flush_rewrite_rules();
+
+  // Loads bundled styles and scripts into the theme.
+  // This enqueues the files the way Wordpress intends but
+  // if these need to be included a different way, remove this statement and 
+  // use the enqueue functions instead: https://developer.wordpress.org/reference/hooks/wp_enqueue_scripts/#user-contributed-notes
+  // It resets styles by default (with Normalize).
+  Hozokit::load_styles_scripts(
+    array(
+      'reset_styles' => true
+    )
+  );
+
+  // Adds additional data to the site context.
+  // This makes it available in the templates.
+  // The filter is required so the data is added at the correct stage.
+  add_filter( 'timber/context', function( $context ) {
+    $global_context = array(
+      'example' => 'add new entries to this array to make them available anywhere in any Twig template.'
+    );
+
+    $context = $context + $global_context;
+    return $context;
+  } );

wp-content/themes/hozokit/index.php

@@ -1,4 +1,14 @@
 <?php
+   // Get Timber's context.
    $context = Timber::get_context();
+
+   // Add new data to this specific view.
+   // In this case the current instance of the post (userful to get the title of the page for example)
+   // and an array with all posts
+   $context['post'] = new Timber\Post();
+   $context['posts'] = Timber::get_posts();
+
+   // Then the Twig template that should be rendered is specified
+   // and the $context with the new added values is passed to it. 
    Timber::render( 'index.twig', $context);
-?>
+?>

wp-content/themes/hozokit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hozokit",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Wordpress theme template.",
   "main": "index.js",
   "scripts": {