feat: add docs

baumrock · Mar 31, 2023 · 3ffc68e · 3ffc68e
1 parent e8ea6b6
commit 3ffc68e
Show file tree

Hide file tree

Showing 19 changed files with 485 additions and 7 deletions.
diff --git a/docs/alfred/readme.md b/docs/alfred/readme.md
@@ -0,0 +1 @@
+# ALFRED Frontend Editing
diff --git a/docs/asset-tools/readme.md b/docs/asset-tools/readme.md
@@ -1 +1,173 @@
-# Asset Tools
+# Asset Tools
+
+Working with site assets can be tedious.
+
+In your HTML markup the browser expects file urls whereas PHP expects system paths for several file operations. Converting from one to another can quickly lead to errors like forgetting to add/remove a slash somewhere. Or you forget to add a cache busting mechanism and waste time fixing bugs that do actually not exist just because your browser is serving an outdated version...
+
+That's why RockFrontend comes with a dedicated PHP class that provides several neat helpers for working with scripts and styles.
+
+## Usage
+
+Typically you'd add styles and scripts in your `_main.php` file:
+
+```php
+/** @var RockFrontend $rockfrontend */
+$rockfrontend->styles()
+  ->add("/site/templates/uikit/src/less/uikit.theme.less")
+  ...
+  ->addDefaultFolders() // autoload styles in sections, partials, etc
+  ->minify(!$config->debug);
+
+$rockfrontend->scripts()
+  ->add("/site/modules/RockFrontend/scripts/rf-scrollclass.js", "defer")
+  ->add("/site/templates/uikit/dist/js/uikit.min.js")
+  ->add("/site/templates/scripts/main.js", "defer")
+  ->minify(!$config->debug);
+```
+
+<div class="uk-alert uk-alert-warning">Note that we only add assets, but we do NOT echo anything here!</div>
+
+## AssetsArray
+
+If you call `$rockfrontend->styles()` RockFrontend will return a `StylesArray` object. If you call `$rockfrontend->scripts()` you'll get a `ScriptsArray`. Both are instances of the base class `AssetsArray`, which provides helper methods for quick and easy working with your sites assets.
+
+Technically you can create as many AssetArrays as you want:
+
+```php
+// all examples are the same for ->scripts()
+$rockfrontend->styles('head')
+$rockfrontend->styles() // short version of the above!
+
+$rockfrontend->styles('foo')
+$rockfrontend->styles('bar')
+$rockfrontend->styles('baz')
+```
+
+Note though that only the `head` scripts and styles will be rendered automatically. They will be rendered into the `<head>` of your website. All other AssetArrays can be rendered manually wherever you want:
+
+```html
+<html>
+  <head>...</head>
+  <body>
+  <?= $rockfrontend->scripts('body')->add('foo.js')->render(); ?>
+  </body>
+</html>
+```
+
+## Adding files
+
+You can either add single files:
+
+```php
+$rockfrontend->styles()->add('path/to/your/file.css');
+```
+
+Or you can add all files within a directory:
+
+```php
+$rockfrontend->styles()->addAll('path/to/your/files');
+```
+
+You can also use the `addDefaultFolders()` shortcut to add all styles in `site/templates/ layouts | less | sections | partials`
+
+You can also add files only if a condition is met:
+
+```php
+$rockfrontend->scripts()->addIf(
+  'foo.js',                  // filename
+  $page->template == 'home', // condition
+  'defer'                    // optional suffix
+);
+```
+
+## Rendering Scripts
+
+```php
+$rockfrontend->scripts()->add('foo.js')->add('bar.js');
+
+// renders the following
+<script src='foo.js'></script><!-- _main.php:17 -->
+<script src='bar.js'></script><!-- _main.php:17 -->
+```
+
+If debug mode is enabled RockFrontend will add notes about where the script was added - in our case both scripts were added in line 17 of `_main.php`.
+
+### Defer / Suffix
+
+When adding scripts to your site you often want them to be loaded after the dom content to be non-blocking. This can be done by adding the `defer` suffix to your `add()` call:
+
+```php
+$rockfrontend->scripts()->add('foo.js', 'defer');
+```
+
+Note that you can use any string you want as suffix:
+
+```php
+$rockfrontend->scripts()->add(
+  'https://code.jquery.com/jquery-3.6.4.min.js',
+  'integrity="sha256-oP6HI9z1XaZNBrJURtCoUT5SUnxFr8s3BzRl+cbzUq8=" crossorigin="anonymous"'
+);
+
+// renders to
+<script src='https://code.jquery.com/jquery-3.6.4.min.js' integrity="sha256-oP6HI9z1XaZNBrJURtCoUT5SUnxFr8s3BzRl+cbzUq8=" crossorigin="anonymous"></script>
+```
+
+## Rendering Styles
+
+Rendering styles is very similar to rendering scripts. The only notable difference is that you can provide multiple LESS files and RockFrontend will automatically parse and merge them to one single CSS file.
+
+### Less Parser
+
+```php
+$rockfrontend->styles()
+  ->add('/site/templates/uikit/src/less/uikit.theme.less')
+  ->add('/site/modules/RockFrontend/uikit/defaults.less')
+  ->add('/site/modules/RockFrontend/uikit/offcanvas.less')
+  ->add('/site/modules/RockFrontend/less/defaults.less')
+  ->add('/site/modules/RockFrontend/less/boxed-layout.less')
+  ->add('/site/modules/RockFrontend/less/sticky-footer.less')
+  ->add('/site/modules/RockFrontend/less/headlines.less')
+  ->addDefaultFolders() // finally autoload styles in sections, partials, etc
+  ->minify(!$config->debug);
+```
+
+Renders to the following:
+
+```html
+  <!-- DEBUG enabled! You can disable it either via $config or use $rf->styles()->setOptions(['debug'=>false]) -->
+  <!-- rockfrontend-styles-head -->
+  <!-- loading /site/templates/uikit/src/less/uikit.theme.less (_main.php:7) -->
+  <!-- loading /site/modules/RockFrontend/uikit/defaults.less (_main.php:8) -->
+  <!-- loading /site/modules/RockFrontend/uikit/offcanvas.less (_main.php:9) -->
+  <!-- loading /site/modules/RockFrontend/less/defaults.less (_main.php:10) -->
+  <!-- loading /site/modules/RockFrontend/less/boxed-layout.less (_main.php:11) -->
+  <!-- loading /site/modules/RockFrontend/less/sticky-footer.less (_main.php:12) -->
+  <!-- loading /site/modules/RockFrontend/less/headlines.less (_main.php:13) -->
+  <!-- loading /site/templates/layouts/home.less (_main.php:14) -->
+  <!-- loading /site/templates/less/_global.less (_main.php:14) -->
+  <!-- loading /site/templates/less/hooks.less (_main.php:14) -->
+  <!-- loading /site/templates/sections/docs.less (_main.php:14) -->
+  <!-- loading /site/templates/sections/footer.less (_main.php:14) -->
+  <!-- loading /site/templates/sections/header.less (_main.php:14) -->
+  <link href='/site/assets/RockFrontend/css/head.css?m=1680272932' rel='stylesheet'><!-- LESS compiled by RockFrontend -->
+```
+
+## Cache Busting
+
+All rendered assets will automatically get a cache busting timestamp based on the file modification date:
+
+```html
+<link href="/site/assets/RockFrontend/css/head.css?m=1680273513" rel="stylesheet">
+```
+
+This makes sure that the browser does not load an outdated version of your assets.
+
+## Minify
+
+RockFrontend can automatically minify your assets. Simply call `->minify()` on the assets array. You can also provide a parameter of `true` or `false` - usually I do this:
+
+```php
+->minify(!$config->debug)
+```
+
+This tells RockFrontend to minify assets if debug mode is OFF (which is typically the case on production environments) but it will not minify if debug mode is ON during development.
diff --git a/docs/asset-tools/scripts/readme.md b/docs/asset-tools/scripts/readme.md
diff --git a/docs/asset-tools/styles/readme.md b/docs/asset-tools/styles/readme.md
diff --git a/docs/layouts/readme.md b/docs/layouts/readme.md
@@ -0,0 +1 @@
+# Layouts
diff --git a/docs/left.md b/docs/left.md
@@ -1,9 +1,9 @@
-##### Getting started
+## Getting started
 
 - Index
 - Quickstart
 - Module Config
 
-##### Features
+## Features
 
 [features]
diff --git a/docs/live-reload/livereload.png b/docs/live-reload/livereload.png
diff --git a/docs/live-reload/readme.md b/docs/live-reload/readme.md
@@ -0,0 +1,66 @@
+# Live-Reload
+
+Good bye refresh-button, hello RockFrontend Live-Reload! 😎
+
+To enable the live-reload feature you just need to add this to your site's config:
+
+```php
+// make RockFrontend watch for changes every second
+$config->livereload = 1;
+```
+
+<div class="uk-alert uk-alert-danger">ATTENTION: Make sure that you disable livereload on production!</div>
+
+Then refresh your page and open the developer tools. In the console you should see `RockFrontend is listening for file changes...` which shows that live-reload is working.
+
+<div class="uk-alert">
+<div class="uk-margin-small">Note that LiveReload does only reload the page if the tab is open!</div>
+<div class="uk-text-small">This is to make sure that when using RockMigrations you don't get multiple migration runs at the same time because of multiple open browser tabs.</div>
+</div>
+
+## Config
+
+If you do a `bd($rockfrontend->getLiveReload());` you can see the default setup:
+
+<img src=livereload.png class=blur>
+
+I've never had the need to do that, but you can optionally customize the config of LiveReload:
+
+```php
+$config->livereload = [
+  // interval to watch for changes
+  'interval' => 1, // 1s = default
+
+  // user defined include paths
+  'include' => [
+    '.*/foo/bar',
+  ],
+
+  // you can reset default include paths
+  'includeDefaults' => [],
+
+  // user defined exclude regexes
+  'exclude' => [
+    '.*/site/my-ignored-folder',
+  ],
+
+  // you can reset default excludes
+  'excludeDefaults' => [],
+];
+```
+
+## How does it work?
+
+RockFrontend starts an SSE stream once you visit a page. In that SSE stream it triggers LiveReload::watch() in the configured interval (usually every second). If it finds a file that has changed since the page has been visited it triggers a reload via JavaScript.
+
+## Debugging
+
+If you get unexpected reloads check the `livereload` log in the PW backend. Whenever RockFrontend detects a changed file in the LiveReload stream it will log the filename in the livereload log.
+
+## Browser Support
+
+Note that Firefox will always jump to the top of the page while Chrome will keep the scroll position!
+
+## DDEV
+
+If using DDEV make sure you have a correct webserver type otherwise the reloads might be buggy and slow! You need to have `webserver_type: apache-fpm`
diff --git a/docs/magic-paths/readme.md b/docs/magic-paths/readme.md
@@ -0,0 +1,32 @@
+# Magic Paths
+
+RockFrontend supports `magic paths` in several places, for example when adding files to a `ScriptsArray` or `StylesArray` or when using `$rockfrontend->render(...)`.
+
+```php
+// all of them will work
+$rockfrontend->render('sections/foo')
+$rockfrontend->render('sections/foo.latte')
+$rockfrontend->render('/site/templates/sections/foo')
+$rockfrontend->render('/site/templates/sections/foo.latte')
+```
+
+## Subfolder Installations
+
+Magic Paths make it possible to define paths relative to the PW root or relative to the templates folder.
+
+For example if you had a PW installation in the `foo` subfolder and you defined your scripts like this:
+
+```php
+$rockfrontend->scripts()->add('/site/templates/scripts/foo.js');
+$rockfrontend->scripts()->add('scripts/foo.js');
+```
+
+Both versions would work and would result in the following tag (note the `/foo` at the beginning of `src`):
+
+```html
+<script src="/foo/site/templates/scripts/foo.js?m=1680038677"></script>
+```
+
+## Extensions
+
+The short version without providing the file extension works for `php` and `latte` files.
diff --git a/docs/postcss/readme.md b/docs/postcss/readme.md
@@ -0,0 +1,66 @@
+# postCSS
+
+<div class='uk-alert'>Note: You need to enable the `postCSS` feature in the module's settings!</div>
+
+## rfGrow
+
+This is one of my favourite features!! It's hard to explain why it is so great - you need to try it and see for yourself 🤩
+
+Be sure to check out the video about the `rfGrow` feature aka fluid font sizes:
+
+<a href='https://www.youtube.com/watch?v=6ld4daFDQlY'><img src=rfgrow.png></a>
+
+See this example:
+
+```css
+.my-section {
+  padding: rfGrow(20px, 100px) 0;
+}
+```
+
+Here we add a vertical padding of 20px on mobile and 100px on desktop.
+
+By default RockFrontend will use `360px` as the mobile screen with and `1440px` as desktop screen with. You can adjust these settings in your `config.php`:
+
+```php
+$this->wire->config->growMin = 250;
+$this->wire->config->growMax = 1920;
+```
+
+You can also provide the min/max settings directly in the method call:
+
+```css
+.foo {
+  font-size: rfGrow(20px, 50px, 500, 1000);
+}
+```
+
+This means that we have a font-size of 20px on screens up to 500px width that grows up to 50px on 1000px screen width. It converts to this css rule:
+
+```css
+.foo {
+  font-size: clamp(20px, 20px + 30 * ((100vw -  500px) / ( 1000 -  500)), 50px);
+}
+```
+
+## rfShrink
+
+The shrink feature works just like the grow feature but in different direction:
+
+```css
+.hero {
+  padding-left: rfShrink(100px, 10px);
+}
+```
+
+That means we get 100px padding on mobile that shrinks down to 10px on desktop screens.
+
+## PX -> REM
+
+Whenever you write a value as `pxrem` instead of just `px` RockFrontend will convert that value from pixels to rem units.
+
+```css
+div {font-size: 16pxrem;}
+/* converts to */
+div {font-size: 1rem;}
+```
diff --git a/docs/postcss/rfgrow.png b/docs/postcss/rfgrow.png
diff --git a/docs/readme.md b/docs/readme.md
@@ -1,3 +1,9 @@
-# RockFrontend 🚀🚀 The Powerful Frontend Development Toolbox for ProcessWire
+# The Powerful Frontend Development Toolbox for ProcessWire 🚀🚀
 
-Awesome Docs for RockFrontend - coming soon!
+Check out the video about RockFrontend on YouTube:
+
+<a href='https://www.youtube.com/watch?v=7CoIj--u4ps'><img src=thumb.jpg></a>
+
+## API
+
+RockFrontend will register the `$rockfrontend` API variable and its shorthand `$rf`. Both variables will be available in all your ProcessWire template files or in files rendered via `$rockfrontend->render()`.
diff --git a/docs/render/readme.md b/docs/render/readme.md
@@ -0,0 +1 @@
+# The render() method
diff --git a/docs/seo/readme.md b/docs/seo/readme.md
@@ -0,0 +1 @@
+# SEO Tools