Thorough documentation review

Author: dgvirtual

docs/building_admin_modules/index.md

@@ -1,10 +1,51 @@
-# Bonfire - Building Admin Modules
-
-- [Creating an Admin Modules](creating_an_admin_module.md)
-- [View Components](view_components.md)
-- [Filters](filters.md)
-- [Recycler](recycler.md)
-- [Resource Tabs](resource_tabs.md)
-- [Search](search.md)
-- [Widgets](widgets.md)
-- [Dashboard Cells](dashboard_cells.md)
+# Building Admin Modules
+
+Any application admin panel will need more than just user management capabilities. Your app might need page, tag, product management. This section deals with extending Bonfire admin are with your own modules and integrating them into the admin panel.
+
+## Creating an Admin Module
+
+Learn how to create new modules of code for the admin area, centered around a single task or resource, like Users, Photos, etc. This guide covers the basics of creating a `Module.php` file, configuring module locations, and adding menu items.
+
+[Read more about Creating an Admin Module](creating_an_admin_module.md)
+
+## View Components
+
+View Components allow you to create custom HTML elements to use within your views. This section lists the components available within the default `Admin` theme and provides examples of their usage.
+
+[Read more about View Components](view_components.md)
+
+## Filters
+
+Filtering allows you to specify which columns can be filtered and then pass your model to a view cell that handles the display of the filters. This ensures a consistent look and functionality in the UI while providing the least amount of work when creating a UI.
+
+[Read more about Filters](filters.md)
+
+## Recycler
+
+The Recycler provides an area where users can browse objects that have been deleted and either restore or purge them. The models for these resources must have soft deletes enabled. This section covers registering a resource, localizing column names, and modifying the Recycler query.
+
+[Read more about the Recycler](recycler.md)
+
+## Resource Tabs
+
+Resource tabs are the tabs displayed when editing a resource, like an individual User or User Group. They make it possible to easily integrate other tabs onto a user without editing the core theme.
+
+[Read more about Resource Tabs](resource_tabs.md)
+
+## Search
+
+Bonfire provides a flexible search system that is highlighted on all areas of the admin area. This section covers integrating your module into the search results, adding filters for the Advanced Search form, and providing search results.
+
+[Read more about Search](search.md)
+
+## Widgets
+
+Widgets are elements that display information on the dashboard. They can be small informational cards or charts. This section covers adding new widgets, configuring them, and displaying them on the dashboard.
+
+[Read more about Widgets](widgets.md)
+
+## Dashboard Cells
+
+Customize the dashboard with the use of view cells. This section covers specifying which cells to display, creating the cell, and displaying it on the dashboard.
+
+[Read more about Dashboard Cells](dashboard_cells.md)

docs/building_sites/alerts.md

@@ -3,7 +3,7 @@
 Bonfire uses [Tatter\Alerts](https://github.com/tattersoftware/codeigniter4-alerts) to provide support for
 simple alerts. The usage is simple: 
 
-```
+```php
 alert('success', 'Your message goes here.');
 ```
 
@@ -15,7 +15,7 @@ and can be a single string or an array of strings to apply multiple alerts.
 Additionally, you can use flash messages in the session to trigger alerts. 
 This would typically be used during a redirect: 
 
-```
+```php
 return redirect()->back()->with('message', 'It worked!');
 return redirect()->back()->with('error', 'Did not work');
 return redirect()->back()->with('error', ['not good', 'nope', 'cannot do it']);

docs/building_sites/assets.md

@@ -1,33 +1,22 @@
-# Asset Management
+# Including Assets
 
-Bonfire provides a simple assets system that was created to solve two main challenges:
-
-1. We should be able to serve CSS/JS assets from anywhere. While this is primarily for use by themes, it could serve many purposes.
-2. How to easily handle browser caching/cache-busting with updated assets.
-
-And try to do this in the simplest way possible.
-
-For the examples, we will link to assets for the Admin theme.
+ As elaborated in [Assets Management](../modules/assets.md), Bonfire provides a simple assets system that was created to serve CSS/JS assets from anywhere and to easily handle browser caching/cache-busting with updated assets.
 
 ## Linking to assets
 
 Within your views you can link to assets anywhere within your project with the `asset()` or `asset_link()` helper function.
 `asset_link()` takes two arguments. The first is the path to the file to load. The first segment of this path must be one of the defined
-`$folders` in the configuration file. The rest of the path would be based on the actual file structure within that
-location. For the `Admin` theme, a folder has been defined called `admin`. Both the `Auth` and `App` themes have
-similar folders already defined.  
+`$folders` in the configuration file `Assets.php`. The rest of the path would be based on the actual file structure within that
+location. For the `App` theme, a folder has been defined called `app`.
 
-The second argument is the type of asset being loaded. This tells it how the resulting link should be formed.
-Currently, it only supports `css` and `js` files.
+The second argument is the type of asset being loaded. Currently, it only supports `css` and `js` files.
 
 ```php
-<?= asset_link('admin/css/admin.css', 'css') ?>
-<?= asset_link('admin/js/admin.js', 'js') ?>
+<?= asset_link('app/css/admin.css', 'css') ?>
+<?= asset_link('app/js/admin.js', 'js') ?>
 ```
 
-The `asset()` function is similar, except it only returns the URL. This is helpful as the function also inserts
-a string within the filename that helps browsers cache the file, but that will change when the file is updated
-so the browser knows to grab a fresh copy of the file.
+The `asset()` function is similar, except it only returns the URL only.
 
 ```html
 <link rel="stylesheet" href="<?= asset('admin/css/admin.css', 'css') ?>" />
@@ -36,61 +25,4 @@ so the browser knows to grab a fresh copy of the file.
 
 ## Configuration
 
-The `Config\Assets` class has a handful of settings to customize the experience.
-
-### $bustingType
-
-When a link is generated it includes a string within the filename for cache-busting reasons. This would look something
-like: `https://localhost:8080/admin/css/admin~~213264216523.css`. The config setting, `$bustingType` defines how this
-string is derived. It has two possible values, either `file` or `version`.
-
-The `file` setting will examine the requested file and use the file modified date/time as the basis, and convert it
-to a Unix timestamp. This is the easiest value to use as it is automatically updates itself based on the file. However,
-it does force an extra file read, and the overhead needed to get the information from the file. On many small to medium
-sites this is likely just fine. However, large sites, or sites that require every ounce of performance, may want to
-use the `version` method.
-
-The `version` method requires the developer to set a new version in the configuration file whenever new code is ready
-to deploy to staging or production environments. See the next setting for details. To make this easier during development
-the current timestamp is used in testing/development environments ensuring that no caching will happen. In other
-environments it inserts the version number that was specified.
-
-### $separator
-
-The `$separator` setting allows the app to detect the part of the asset file name that was 
-added for cache-busting purposes. It can be a single web-safe non-reserved character or 
-a combination of such characters (characters that are allowed in a URI, but do not have 
-a reserved purpose) that DOES NOT OCCUR in your asset file names (like `~`, `-` 
-or `_` or any combination of ASCII letters and numbers). Separator will be inserted 
-before the file version/timestamp, in between the file name and file extension.
-
-### $versions
-
-The `$versions` setting allows you to define the version number for `css` and `js` separately. This value is used
-as the cache-busting string when the `version` busting type is used.
-
-```php
-public $versions = [
-    'css' => '1.0',
-    'js' => '1.0',
-];
-```
-
-### $folders
-
-This values is where you define the folders that are looked in linking to an asset. Folders for all themes and
-the vendor folder are setup by default.
-
-```php
-public $folders = [
-    'app' => ROOTPATH.'themes/app',
-    'admin' => ROOTPATH.'themes/Admin',
-    'auth' => ROOTPATH.'themes/Auth',
-    'other' => ROOTPATH.'vendor',
-];
-```
-
-## Route Conflict Warning
-
-To make this all work, a route is specified at `/assets/(:any)` to capture the request. The assets system will not
-work if you override this route in your own application. I think for most sites this should not be a problem.
+Configuration of assets is detailed in the [Assets Management](../modules/assets.md) page of **Modules** section.

docs/building_sites/common_functions.md

@@ -1,6 +1,6 @@
 # Common functions
 
-Bonfire provides a few helper functions that are always available for your use.
+Bonfire provides a helper function that is always available for your use.
 
 **app_date($date)**
 
@@ -32,4 +32,3 @@ You can further include the timezone by passing `true` as the third argument.
 echo app_date($date, true, true);
 // outputs: 01/15/2021 3:35 PM CST
 ```
-

docs/building_sites/components.md

@@ -2,7 +2,7 @@
 
 View Components (or just Components) allow you to create custom HTML elements to use within your views. 
 
-## Self-Closing Tags
+## Self-Closing Tag Components
 
 At their most basic, components serve as dynamic templates that allow you to reduce the typing in your 
 application. This can help boil longer, complex sections down to a single HTML tag. This is especially
@@ -15,7 +15,7 @@ application's, `app/Components` directory.
 
 A simple avatar image might look something like this: 
 
-```
+```php
 // app/Components/avatar.php
 <img
   src="<?= $src ?? '' ?>"
@@ -27,15 +27,15 @@ A simple avatar image might look something like this:
 
 When using the component within a view, you would insert a tag with `x-` prepended to the filename: 
 
-```
+```php
 <x-avatar src="<?= $user->avatarUrl() ?>" alt="<?= $user->name ?>" />
 ```
 
 Any attributes provided when you insert the component like this are made available as variables within 
 the component view. In this case, the `$src` and `$alt` attributes are passed to the component view, resulting
 in the following output: 
 
-```
+```html
 <img
   src="http://example.com/avatars/foo.jpg"
   class="rounded-circle shadow-4"
@@ -44,15 +44,15 @@ in the following output:
 /> 
 ```
 
-## Tags With Content
+## Components With Opening and Closing Tags
 
 You can include the content within the opening and closing tags by inserting the reserved `$slot` variable: 
 
-```
+```html
 <x-green-button>Click Me!</x-green-button>
 ```
 
-```
+```php
 // app/Components/green-button.php
 <button class="btn btn-success">
     <?= $slot ?>
@@ -72,3 +72,86 @@ The data you pass will be available within the class as it's `$data` property (t
 A `famous-qoutes` component would have a view called `famous-quotes.php` and a controlling class called
 `FamousQuotesComponent.php`. The class must extend `Bonfire\View\Component`. The only requirement is that you
 implement a method called `render()`.
+
+Below are example files of a usable `famous-quotes` component, that can be included in any of these three ways:
+
+```html
+<x-famous-quotes />
+<x-famous-quotes seconds="30" />
+<x-famous-quotes seconds="30">Famous Quotes</x-famous-quotes>
+```
+
+It's controlling class file `FamousQuotesComponent.php`:
+
+```php
+namespace App\Components;
+
+/**
+ * This example controlled component allows to retrieve a random famous quote
+ * from the ZenQuotes API and cache it for a specified number of seconds.
+ * Number of seconds can be passed as a parameter to the component.
+ * If you want to add a title to the component, you can pass it as a $slot variable.
+ */
+class FamousQuotesComponent extends \Bonfire\View\Component
+{
+    protected $defaultNoOfSeconds         = 600;
+    protected string $famousQuotesAPINode = 'https://zenquotes.io/api/random';
+
+    public function render(): string
+    {
+        return $this->renderView($this->view, $this->getFamousQuote());
+    }
+
+    public function getFamousQuote(): array
+    {
+        helper('cache');
+
+        if (isset($this->data['seconds']) && is_numeric($this->data['seconds'])) {
+            $this->data['seconds'] = (int) round($this->data['seconds'], 0);
+        } else {
+            $this->data['seconds'] = $this->defaultNoOfSeconds;
+        }
+
+        $cacheKey = 'famous_quote';
+
+        if ($cachedQuote = cache($cacheKey)) {
+            return $cachedQuote;
+        }
+
+        $response  = file_get_contents($this->famousQuotesAPINode);
+        $quoteData = json_decode($response, true);
+
+        if (isset($quoteData[0])) {
+            $this->data['quote'] = [
+                'text'   => $quoteData[0]['q'],
+                'author' => $quoteData[0]['a'],
+            ];
+
+            cache()->save($cacheKey, $this->data, $this->data['seconds']);
+        } else {
+            $this->data['quote'] = [
+                'text'   => 'Sucking at something is the first step to becoming sorta good at something.',
+                'author' => 'Jake (from "Adventure Time")',
+            ];
+        }
+
+        return $this->data;
+    }
+}
+```
+
+And it's view file `famous-quotes.php`:
+
+```php
+<div class="card mb-3">
+    <div class="card-header">
+        <?= esc($slot ?? '') ?>
+    </div>
+    <div class="card-body mt-3">
+        <p class="card-text text-center"><?= esc($quote['text']) ?></p>
+        <footer class="blockquote-footer text-center"><em><?= esc($quote['author']) ?></em></footer>
+    </div>
+    <div class="card-footer" style="font-size:10px;">Cached for <?= esc($seconds) ?> seconds</div>
+</div>
+```
+