docs: extract source files and fix some bugs

Author: kenjis

user_guide_src/source/outgoing/view_cells.rst

@@ -18,10 +18,9 @@ Calling a View Cell
 
 No matter which type of View Cell you are using, you can call it from any view by using the ``view_cell()`` helper function.
 
-The first parameter is the name of the class and method to call, and the second parameter is an array of parameters to pass to the method.
-::
+The first parameter is the name of the class and method to call, and the second parameter is an array of parameters to pass to the method:
 
-    <?= view_cell('App\Cells\MyClass::myMethod', ['param1' => 'value1', 'param2' => 'value2']) ?>
+.. literalinclude:: view_cells/001.php
 
 The Cell method must return a string, which will be inserted into the view where the ``view_cell()`` function was called.
 
@@ -30,57 +29,35 @@ Namespace Omission
 
 .. versionadded:: 4.3.0
 
-If you do not include the full namespace for the class, it will assume in can be found in the ``App\Cells`` namespace. So, the following example would attempt to find the ``MyClass`` class in **app/Cells/MyClass.php**. If it is not found there, all namespaces will be scanned until it is found, searching within a **Cells** subdirectory of each namespace.
-::
+If you do not include the full namespace for the class, it will assume in can be found in the ``App\Cells`` namespace. So, the following example would attempt to find the ``MyClass`` class in **app/Cells/MyClass.php**. If it is not found there, all namespaces will be scanned until it is found, searching within a **Cells** subdirectory of each namespace:
 
-    <?= view_cell('MyClass::myMethod', ['param1' => 'value1', 'param2' => 'value2']) ?>
+.. literalinclude:: view_cells/002.php
 
 Passing Parameters as Key/Value String
 ======================================
 
 You can also pass the parameters along as a key/value string:
-::
 
-    <?= view_cell('MyClass::myMethod', 'param1=value1, param2=value2') ?>
+.. literalinclude:: view_cells/003.php
 
 ************
 Simple Cells
 ************
 
 Simple Cells are classes that return a string from the chosen method. An example of a simple Alert Message cell might look like this:
-::
-
-    namespace App\Cells;
 
-    class AlertMessage
-    {
-        public function show(array $params): string
-        {
-            return "<div class="alert alert-{$params['type']}">{$params['message']}</div>";
-        }
-    }
+.. literalinclude:: view_cells/004.php
 
 You would call it from within a view like:
-::
 
-    <?= view_cell('AlertMessage::show', ['type' => 'success', 'message' => 'The user has been updated.']) ?>
+.. literalinclude:: view_cells/005.php
 
 Additionally, you can use parameter names that match the parameter variables in the method for better readability.
-When you use it this way, all of the parameters must always be specified in the view cell call::
-
-    // In a View.
-    <?= view_cell('Blog::recentPosts', 'category=codeigniter, limit=5') ?>
+When you use it this way, all of the parameters must always be specified in the view cell call:
 
-    // In a Cell.
-    public function recentPosts(string $category, int $limit)
-    {
-        $posts = $this->blogModel->where('category', $category)
-                                 ->orderBy('published_on', 'desc')
-                                 ->limit($limit)
-                                 ->get();
+.. literalinclude:: view_cells/006.php
 
-        return view('recentPosts', ['posts' => $posts]);
-    }
+.. literalinclude:: view_cells/007.php
 
 .. _controlled-cells:
 
@@ -103,26 +80,12 @@ Creating a Controlled Cell
 ==========================
 
 At the most basic level, all you need to implement within the class are public properties. These properties will be made available to the view file automatically. Implementing the AlertMessage from above as a Controlled Cell would look like this:
-::
-
-    // app/Cells/AlertMessageCell.php
-    namespace App\Cells;
-
-    use CodeIgniter\View\Cells\Cell;
 
-    class AlertMessageCell extends Cell
-    {
-        public $type;
-        public $message;
-    }
+.. literalinclude:: view_cells/008.php
 
-    // app/Cells/alert_message.php
-    <div class="alert alert-<?= esc($type, 'attr') ?>">
-        <?= esc($message) ?>
-    </div>
+.. literalinclude:: view_cells/009.php
 
-    // Called in main View:
-    <?= view_cell('AlertMessageCell', 'type=warning, message=Failed.') ?>
+.. literalinclude:: view_cells/010.php
 
 .. _generating-cell-via-command:
 
@@ -138,181 +101,63 @@ You can also create a controlled cell via a built in command from the CLI. The c
 Using a Different View
 ======================
 
-You can specify a custom view name by setting the ``view`` property in the class. The view will be located like any view would be normally.
+You can specify a custom view name by setting the ``view`` property in the class. The view will be located like any view would be normally:
 
-::
-
-    namespace App\Cells;
-
-    use CodeIgniter\View\Cells\Cell;
-
-    class AlertMessageCell extends Cell
-    {
-        public $type;
-        public $message;
-
-        protected $view = 'my/custom/view';
-    }
+.. literalinclude:: view_cells/011.php
 
 Customize the Rendering
 =======================
 
-If you need more control over the rendering of the HTML, you can implement a ``render()`` method. This method allows you to perform additional logic and pass extra data the view, if needed. The ``render()`` method must return a string. To take advantage of the full features of controlled Cells, you should use ``$this->view()`` instead of the normal ``view()`` helper function.
-::
-
-    namespace App\Cells;
-
-    use CodeIgniter\View\Cells\Cell;
+If you need more control over the rendering of the HTML, you can implement a ``render()`` method. This method allows you to perform additional logic and pass extra data the view, if needed. The ``render()`` method must return a string. To take advantage of the full features of controlled Cells, you should use ``$this->view()`` instead of the normal ``view()`` helper function:
 
-    class AlertMessageCell extends Cell
-    {
-        public $type;
-        public $message;
-
-        public function render(): string
-        {
-            return $this->view('my/custom/view', ['extra' => 'data']);
-        }
-    }
+.. literalinclude:: view_cells/012.php
 
 Computed Properties
 ===================
 
-If you need to perform additional logic for one or more properties you can use computed properties. These require setting the property to either ``protected`` or ``private`` and implementing a public method whose name consists of the property name surrounded by ``get`` and ``Property``.
-::
-
-    // In a View. Initialize the protected properties.
-    view_cell('AlertMessageCell', ['type' => 'note', 'message' => 'test']);
-
-    // app/Cells/AlertMessageCell.php
-    namespace App\Cells;
-
-    use CodeIgniter\View\Cells\Cell;
-
-    class AlertMessageCell extends Cell
-    {
-        protected $type;
-        protected $message;
-        private $computed;
-
-        public function mount()
-        {
-            $this->computed = sprintf('%s - %s', $this->type, $this->message);
-        }
+If you need to perform additional logic for one or more properties you can use computed properties. These require setting the property to either ``protected`` or ``private`` and implementing a public method whose name consists of the property name surrounded by ``get`` and ``Property``:
 
-        public function getComputedProperty(): string
-        {
-            return $this->computed;
-        }
+.. literalinclude:: view_cells/013.php
 
-        public function getTypeProperty(): string
-        {
-            return $this->type;
-        }
+.. literalinclude:: view_cells/014.php
 
-        public function getMessageProperty(): string
-        {
-            return $this->message;
-        }
-    }
-
-    // app/Cells/alert_message.php
-    <div>
-        <p>type - <?= esc($type) ?></p>
-        <p>message - <?= esc($message) ?></p>
-        <p>computed: <?= esc($computed) ?></p>
-    </div>
+.. literalinclude:: view_cells/015.php
 
 .. important:: You can't set properties that are declared as private during cell
     initialization.
 
 Presentation Methods
 ====================
 
-Sometimes you need to perform additional logic for the view, but you don't want to pass it as a parameter. You can implement a method that will be called from within the cell's view itself. This can help the readability of your views.
-::
-
-    // app/Cells/RecentPostsCell.php
-    namespace App\Cells;
-
-    use CodeIgniter\View\Cells\Cell;
-
-    class RecentPostsCell extends Cell
-    {
-        protected $posts;
+Sometimes you need to perform additional logic for the view, but you don't want to pass it as a parameter. You can implement a method that will be called from within the cell's view itself. This can help the readability of your views:
 
-        public function linkPost($post)
-        {
-            return anchor('posts/' . $post->id, $post->title);
-        }
-    }
+.. literalinclude:: view_cells/016.php
 
-    // app/Cells/recent_posts.php
-    <ul>
-        <?php foreach ($posts as $post): ?>
-            <li><?= $this->linkPost($post) ?></li>
-        <?php endforeach ?>
-    </ul>
+.. literalinclude:: view_cells/017.php
 
 Performing Setup Logic
 ======================
 
-If you need to perform additional logic before the view is rendered, you can implement a ``mount()`` method. This method will be called just after the class is instantiated, and can be used to set additional properties or perform other logic.
+If you need to perform additional logic before the view is rendered, you can implement a ``mount()`` method. This method will be called just after the class is instantiated, and can be used to set additional properties or perform other logic:
 
-::
-
-    namespace App\Cells;
-
-    use CodeIgniter\View\Cells\Cell;
-
-    class RecentPostsCell extends Cell
-    {
-        protected $posts;
-
-        public function mount()
-        {
-            $this->posts = model('PostModel')->getRecent();
-        }
-    }
+.. literalinclude:: view_cells/018.php
 
-You can pass additional parameters to the ``mount()`` method by passing them as an array to the ``view_cell()`` helper function. Any of the parameters sent that match a parameter name of the ``mount`` method will be passed in.
-::
-
-    // app/Cells/RecentPostsCell.php
-    namespace App\Cells;
-
-    use CodeIgniter\View\Cells\Cell;
+You can pass additional parameters to the ``mount()`` method by passing them as an array to the ``view_cell()`` helper function. Any of the parameters sent that match a parameter name of the ``mount`` method will be passed in:
 
-    class RecentPostsCell extends Cell
-    {
-        protected $posts;
+.. literalinclude:: view_cells/019.php
 
-        public function mount(?int $categoryId)
-        {
-            $this->posts = model('PostModel')
-                ->when($categoryId, function ($query, $category) {
-                    return $query->where('category_id', $categoryId);
-                })
-                ->getRecent();
-        }
-    }
-
-    // Called in main View:
-    <?= view_cell('RecentPostsCell', ['categoryId' => 5]) ?>
+.. literalinclude:: view_cells/020.php
 
 ************
 Cell Caching
 ************
 
 You can cache the results of the view cell call by passing the number of seconds to cache the data for as the
-third parameter. This will use the currently configured cache engine.
-::
+third parameter. This will use the currently configured cache engine:
 
-    // Cache the view for 5 minutes
-    <?= view_cell('App\Cells\Blog::recentPosts', 'limit=5', 300) ?>
+.. literalinclude:: view_cells/021.php
 
 You can provide a custom name to use instead of the auto-generated one if you like, by passing the new name
-as the fourth parameter::
+as the fourth parameter:
 
-    // Cache the view for 5 minutes
-    <?= view_cell('App\Cells\Blog::recentPosts', 'limit=5', 300, 'newcacheid') ?>
+.. literalinclude:: view_cells/022.php

user_guide_src/source/outgoing/view_cells/001.php

@@ -0,0 +1,2 @@
+// In a View.
+<?= view_cell('App\Cells\MyClass::myMethod', ['param1' => 'value1', 'param2' => 'value2']) ?>

user_guide_src/source/outgoing/view_cells/002.php

@@ -0,0 +1,2 @@
+// In a View.
+<?= view_cell('MyClass::myMethod', ['param1' => 'value1', 'param2' => 'value2']) ?>

user_guide_src/source/outgoing/view_cells/003.php

@@ -0,0 +1,2 @@
+// In a View.
+<?= view_cell('MyClass::myMethod', 'param1=value1, param2=value2') ?>

user_guide_src/source/outgoing/view_cells/004.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace App\Cells;
+
+class AlertMessage
+{
+    public function show(array $params): string
+    {
+        return "<div class=\"alert alert-{$params['type']}\">{$params['message']}</div>";
+    }
+}

user_guide_src/source/outgoing/view_cells/005.php

@@ -0,0 +1,2 @@
+// In a View.
+<?= view_cell('AlertMessage::show', ['type' => 'success', 'message' => 'The user has been updated.']) ?>

user_guide_src/source/outgoing/view_cells/006.php

@@ -0,0 +1,2 @@
+// In a View.
+<?= view_cell('Blog::recentPosts', 'category=codeigniter, limit=5') ?>

user_guide_src/source/outgoing/view_cells/007.php

@@ -0,0 +1,20 @@
+<?php
+
+// In a Cell.
+
+namespace App\Cells;
+
+class Blog
+{
+    // ...
+
+    public function recentPosts(string $category, int $limit): string
+    {
+        $posts = $this->blogModel->where('category', $category)
+            ->orderBy('published_on', 'desc')
+            ->limit($limit)
+            ->get();
+
+        return view('recentPosts', ['posts' => $posts]);
+    }
+}

user_guide_src/source/outgoing/view_cells/008.php

@@ -0,0 +1,13 @@
+<?php
+
+// app/Cells/AlertMessageCell.php
+
+namespace App\Cells;
+
+use CodeIgniter\View\Cells\Cell;
+
+class AlertMessageCell extends Cell
+{
+    public $type;
+    public $message;
+}

user_guide_src/source/outgoing/view_cells/009.php

@@ -0,0 +1,4 @@
+// app/Cells/alert_message.php
+<div class="alert alert-<?= esc($type, 'attr') ?>">
+    <?= esc($message) ?>
+</div>