All the things

Author: Tam

.editorconfig

@@ -0,0 +1,16 @@
+root = true
+
+[*]
+indent_style = tab
+indent_size = 4
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.{yml, json}]
+indent_style = space
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

.gitattributes

@@ -0,0 +1,8 @@
+README.md           export-ignore
+CHANGELOG.md        export-ignore
+/resources          export-ignore
+.gitignore          export-ignore
+.gitattributes      export-ignore
+.editorconfig       export-ignore
+/docs               export-ignore
+docker-compose.yml  export-ignore

.gitignore

@@ -0,0 +1 @@
+.idea

CHANGELOG.md

@@ -0,0 +1,2 @@
+## 1.0.0 - 2020-02-12
+- Initial release 🎉

README.md

@@ -1,2 +1,104 @@
-# atom
+# Atom
 Adding enhanced modularity to Craft CMS Twig templating
+
+## Installation
+
+```shell
+$ composer require ether/atom
+```
+
+## Usage
+
+Create a folder called `_atoms` in your `templates` directory (this can be 
+customised, see [Config](#config)).
+
+### Basic
+
+In this folder you can create re-usable twig templates, or atoms (a.k.a. 
+modules, components, molecules). You can access the atoms in twig using the 
+following syntax:
+
+```twig
+{% x:my-atom %}
+```
+
+The above will include `_atoms/my-atom` in your template. If `my-atom` 
+doesn't exist then nothing will be output.
+
+### Parameters
+
+You can pass parameters to your atom which will be exposed within the atom. The
+current template context is NOT passed to the atom, so any global variables will
+have to be passed manually.
+
+```twig
+{% x:my-atom { heading: "Hello world!" } %}
+```
+
+In the above example, `my-atom` will be given access to the `heading` variable.
+If `heading` isn't passed then the variable will be undefined. You'll want to 
+check variable availability with `is defined` or `|default`.
+
+### Children
+
+Children can also be passed to atoms:
+
+```twig
+{% x:my-atom { heading: "Hello world!" } %}
+	<p>This is my atom</p>
+	<p>There are many like it, but this is mine</p>
+	<p>{{ myVariable }}</p>
+{% endx %}
+```
+
+Children are rendered in the parent context, not the atoms. This means any 
+variables you pass to the atom will not be available in the children (unless 
+they are also available in the parent context).
+
+Children are rendered within the atom using the `children` variable, which will
+contain the rendered contents of the children or `null` if no children are 
+defined.
+
+```twig
+{# Contents of `_atoms/my-atom` #}
+<div>
+	<h1>{{ heading }}</h1>
+	{{ children }}
+</div>
+```
+
+### Nested
+
+Atoms can be nested inside other atoms!
+
+```twig
+{% x:my-atom %}
+	{% x:another-atom %}
+{% endx %}
+```
+
+### Sub-folders
+
+You can store atoms in folders within your `_atoms` directory. For example, if
+you had an atom at `_atoms/cards/news`, you could access it using the following
+syntax:
+
+```twig
+{% x:cards/news %}
+```
+
+### Dynamic Atoms
+
+You can render atoms with dynamic names by wrapping the atom name in square 
+brackets:
+
+```twig
+{% set myVar = 'example-atom' %}
+
+{% x:[myVar] %}
+```
+
+## Config
+
+You can configure Atom by creating a `atom.php` file in your `config` folder.
+See [config.php](./src/config.php) for the available settings.

composer.json

@@ -0,0 +1,31 @@
+{
+  "name": "ether/atom",
+  "description": "Adding enhanced modularity to Craft CMS Twig templating",
+  "version": "1.0.0",
+  "type": "craft-plugin",
+  "license": "MIT",
+  "minimum-stability": "dev",
+  "require": {
+    "craftcms/cms": "^3.5.0"
+  },
+  "autoload": {
+    "psr-4": {
+      "ether\\atom\\": "src/"
+    }
+  },
+  "support": {
+    "email": "[email protected]",
+    "docs": "https://docs.ethercreative.co.uk/atom",
+    "source": "https://github.com/ethercreative/atom",
+    "issues": "https://github.com/ethercreative/atom/issues"
+  },
+  "extra": {
+    "handle": "atom",
+    "name": "Atom",
+    "developer": "Ether Creative",
+    "developerUrl": "https://ethercreative.co.uk",
+
+    "class": "ether\\atom\\Atom",
+    "schemaVersion": "1.0.0"
+  }
+}

src/Atom.php

@@ -0,0 +1,73 @@
+<?php
+
+namespace ether\atom;
+
+use Craft;
+use craft\base\Plugin;
+use ether\atom\web\twig\Extension;
+use Twig\Error\LoaderError;
+use Twig\Error\RuntimeError;
+use Twig\Error\SyntaxError;
+use Twig\Markup;
+use yii\base\Exception;
+
+class Atom extends Plugin
+{
+
+	private static $_config = [];
+
+	public function init ()
+	{
+		parent::init();
+
+		self::$_config = require __DIR__ . '/config.php';
+		if (file_exists(CRAFT_BASE_PATH . '/config/atom.php'))
+		{
+			self::$_config = array_merge(
+				self::$_config,
+				require CRAFT_BASE_PATH . '/config/atom.php'
+			);
+		}
+
+		Craft::$app->getView()->registerTwigExtension(
+			new Extension()
+		);
+	}
+
+	/**
+	 * Renders an atom
+	 *
+	 * @param string      $handle
+	 * @param array       $variables
+	 * @param string|null $children
+	 *
+	 * @throws Exception
+	 * @throws LoaderError
+	 * @throws RuntimeError
+	 * @throws SyntaxError
+	 */
+	public static function renderAtom (
+		string $handle,
+		array $variables = [],
+		string $children = null
+	) : void {
+		$view = Craft::$app->getView();
+
+		$template = self::$_config['atoms'] . '/' . $handle;
+
+		$variables['children'] = new Markup($children, 'utf8');
+
+		if (!$view->doesTemplateExist($template))
+		{
+			Craft::error(
+				"Error locating template: {$template}",
+				__METHOD__
+			);
+
+			return;
+		}
+
+		echo $view->renderTemplate($template, $variables);
+	}
+
+}

src/config.php

@@ -0,0 +1,12 @@
+<?php
+
+return [
+	/**
+	 * ### Atoms Root
+	 *
+	 * _Defaults to `_atoms`_
+	 *
+	 * The location of your atoms, relative to your `templates` directory.
+	 */
+	'atoms' => '_atoms',
+];

src/web/twig/Extension.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace ether\atom\web\twig;
+
+use ether\atom\web\twig\tokenparsers\AtomTokenParser;
+use Twig\Extension\AbstractExtension;
+
+class Extension extends AbstractExtension
+{
+
+	public function getTokenParsers (): array
+	{
+		return [
+			new AtomTokenParser(),
+		];
+	}
+
+}

src/web/twig/nodes/AtomNode.php

@@ -0,0 +1,39 @@
+<?php
+
+namespace ether\atom\web\twig\nodes;
+
+use ether\atom\Atom;
+use Twig\Compiler;
+use Twig\Node\Expression\ArrayExpression;
+use Twig\Node\Node;
+use Twig\Node\NodeCaptureInterface;
+
+class AtomNode extends Node implements NodeCaptureInterface
+{
+
+	public function compile (Compiler $compiler)
+	{
+		$isVariableName = $this->getAttribute('isVariableName');
+		$handle = $this->getAttribute('handle');
+		/** @var ArrayExpression $data */
+		$data = $this->getAttribute('data');
+		$value = $this->getNode('value');
+
+		$compiler
+			->addDebugInfo($this)
+			->write('ob_start();' . PHP_EOL)
+			->subcompile($value)
+			->write(Atom::class . '::renderAtom(');
+
+		if ($isVariableName)
+			$compiler->subcompile($handle);
+		else
+			$compiler->write('\'' . $handle . '\'');
+
+		$compiler
+			->write(', ')
+			->raw($data->compile($compiler) . ', ')
+			->raw('ob_get_clean());' . PHP_EOL);
+	}
+
+}