From f057c17aa2e6c220b944b2770e35b068ef75374c Mon Sep 17 00:00:00 2001 From: kenjis Date: Wed, 1 Nov 2023 09:00:07 +0900 Subject: [PATCH 1/5] docs: add section "Simple and Controlled Cells" --- user_guide_src/source/outgoing/view_cells.rst | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/user_guide_src/source/outgoing/view_cells.rst b/user_guide_src/source/outgoing/view_cells.rst index 09b62bcad16a..ffca2d4bab69 100644 --- a/user_guide_src/source/outgoing/view_cells.rst +++ b/user_guide_src/source/outgoing/view_cells.rst @@ -4,12 +4,20 @@ View Cells Many applications have small view fragments that can be repeated from page to page, or in different places on the pages. These are often help boxes, navigation controls, ads, login forms, etc. CodeIgniter lets you encapsulate the logic for these presentation blocks within View Cells. They are basically mini-views that can be included in other views. They can have logic built in to handle any cell-specific display logic. They can be used to make your views more readable and maintainable by separating the logic for each cell into its own class. -CodeIgniter supports two types of View Cells: simple and controlled. Simple View Cells can be generated from any class and method of your choice and does not have to follow any rules, except that it must return a string. Controlled View Cells must be generated from a class that extends ``Codeigniter\View\Cells\Cell`` class which provides additional capability making your View Cells more flexible and faster to use. - .. contents:: :local: :depth: 2 +*************************** +Simple and Controlled Cells +*************************** + +CodeIgniter supports two types of View Cells: simple and controlled. + +**Simple View Cells** can be generated from any class and method of your choice and does not have to follow any rules, except that it must return a string. + +**Controlled View Cells** must be generated from a class that extends ``Codeigniter\View\Cells\Cell`` class which provides additional capability making your View Cells more flexible and faster to use. + .. _app-cells: ******************* From 44806d844c1ddddb9cdd44921db0fe3a94f99465 Mon Sep 17 00:00:00 2001 From: kenjis Date: Wed, 1 Nov 2023 09:01:25 +0900 Subject: [PATCH 2/5] docs: improve explanation for "Calling a View Cell" --- user_guide_src/source/outgoing/view_cells.rst | 6 ++++-- user_guide_src/source/outgoing/view_cells/001.php | 5 +++++ 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/user_guide_src/source/outgoing/view_cells.rst b/user_guide_src/source/outgoing/view_cells.rst index ffca2d4bab69..acd2d3b0f86c 100644 --- a/user_guide_src/source/outgoing/view_cells.rst +++ b/user_guide_src/source/outgoing/view_cells.rst @@ -26,11 +26,13 @@ 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 (1) *the name of the class and method* (Simple Cell) or (2) *the name of the class* (Controlled Cell) to call, +and the second parameter is an array of parameters to pass to the method: .. 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. +The string that the Cell returns will be inserted into the view where the +``view_cell()`` function was called. Namespace Omission ================== diff --git a/user_guide_src/source/outgoing/view_cells/001.php b/user_guide_src/source/outgoing/view_cells/001.php index 2a9e4361796e..57a4fdc425dc 100644 --- a/user_guide_src/source/outgoing/view_cells/001.php +++ b/user_guide_src/source/outgoing/view_cells/001.php @@ -1,2 +1,7 @@ // In a View. + +// Simple Cell 'value1', 'param2' => 'value2']) ?> + +// Controlled Cell + 'value1', 'param2' => 'value2']) ?> From c99c118cfe666e9b1e3a9ab7942d9a0501d8319c Mon Sep 17 00:00:00 2001 From: kenjis Date: Wed, 1 Nov 2023 09:02:40 +0900 Subject: [PATCH 3/5] docs: add empty lines for readability --- user_guide_src/source/outgoing/view_cells.rst | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/user_guide_src/source/outgoing/view_cells.rst b/user_guide_src/source/outgoing/view_cells.rst index acd2d3b0f86c..da60d6644d8a 100644 --- a/user_guide_src/source/outgoing/view_cells.rst +++ b/user_guide_src/source/outgoing/view_cells.rst @@ -77,8 +77,10 @@ Controlled Cells .. versionadded:: 4.3.0 -Controlled cells have two primary goals: to make it as fast as possible to build the cell, and provide additional logic and -flexibility to your views, if they need it. The class must extend ``CodeIgniter\View\Cells\Cell``. They should have a view file +Controlled cells have two primary goals: (1) to make it as fast as possible to build the cell, and (2) provide additional logic and +flexibility to your views, if they need it. + +The class must extend ``CodeIgniter\View\Cells\Cell``. They should have a view file in the same folder. By convention, the class name should be in PascalCase suffixed with ``Cell`` and the view should be the snake_cased version of the class name, without the suffix. For example, if you have a ``MyCell`` class, the view file should be ``my.php``. @@ -89,7 +91,9 @@ should be ``my.php``. 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: +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: .. literalinclude:: view_cells/008.php @@ -118,7 +122,9 @@ You can specify a custom view name by setting the ``view`` property in the class 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: +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: .. literalinclude:: view_cells/012.php From 7a04c51aa25f492369880ab5adca7147cf09a48b Mon Sep 17 00:00:00 2001 From: kenjis Date: Wed, 1 Nov 2023 09:03:08 +0900 Subject: [PATCH 4/5] docs: add return types in sample code --- user_guide_src/source/outgoing/view_cells/014.php | 2 +- user_guide_src/source/outgoing/view_cells/016.php | 2 +- user_guide_src/source/outgoing/view_cells/018.php | 2 +- user_guide_src/source/outgoing/view_cells/019.php | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/user_guide_src/source/outgoing/view_cells/014.php b/user_guide_src/source/outgoing/view_cells/014.php index 29378e1199ab..7aa1ad4c9d8c 100644 --- a/user_guide_src/source/outgoing/view_cells/014.php +++ b/user_guide_src/source/outgoing/view_cells/014.php @@ -12,7 +12,7 @@ class AlertMessageCell extends Cell protected $message; private $computed; - public function mount() + public function mount(): void { $this->computed = sprintf('%s - %s', $this->type, $this->message); } diff --git a/user_guide_src/source/outgoing/view_cells/016.php b/user_guide_src/source/outgoing/view_cells/016.php index 4b2c10ef0cc6..54d9d7d994a4 100644 --- a/user_guide_src/source/outgoing/view_cells/016.php +++ b/user_guide_src/source/outgoing/view_cells/016.php @@ -10,7 +10,7 @@ class RecentPostsCell extends Cell { protected $posts; - public function linkPost($post) + public function linkPost($post): string { return anchor('posts/' . $post->id, $post->title); } diff --git a/user_guide_src/source/outgoing/view_cells/018.php b/user_guide_src/source/outgoing/view_cells/018.php index 3f64e68464e9..8767af1b40a2 100644 --- a/user_guide_src/source/outgoing/view_cells/018.php +++ b/user_guide_src/source/outgoing/view_cells/018.php @@ -8,7 +8,7 @@ class RecentPostsCell extends Cell { protected $posts; - public function mount() + public function mount(): void { $this->posts = model('PostModel')->orderBy('created_at', 'DESC')->findAll(10); } diff --git a/user_guide_src/source/outgoing/view_cells/019.php b/user_guide_src/source/outgoing/view_cells/019.php index df78ab0acec5..db1b12b56b54 100644 --- a/user_guide_src/source/outgoing/view_cells/019.php +++ b/user_guide_src/source/outgoing/view_cells/019.php @@ -10,7 +10,7 @@ class RecentPostsCell extends Cell { protected $posts; - public function mount(?int $categoryId) + public function mount(?int $categoryId): void { $this->posts = model('PostModel') ->when( From b0534cc2e587c5fefae57dd19a4a31e190fdccf0 Mon Sep 17 00:00:00 2001 From: kenjis Date: Wed, 1 Nov 2023 17:25:59 +0900 Subject: [PATCH 5/5] docs: fix incorrect description Co-authored-by: Michal Sniatala --- user_guide_src/source/outgoing/view_cells.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/user_guide_src/source/outgoing/view_cells.rst b/user_guide_src/source/outgoing/view_cells.rst index da60d6644d8a..f940bc99ea17 100644 --- a/user_guide_src/source/outgoing/view_cells.rst +++ b/user_guide_src/source/outgoing/view_cells.rst @@ -26,8 +26,8 @@ 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 (1) *the name of the class and method* (Simple Cell) or (2) *the name of the class* (Controlled Cell) to call, -and the second parameter is an array of parameters to pass to the method: +The first parameter is (1) *the name of the class and method* (Simple Cell) or (2) *the name of the class and optional method* (Controlled Cell) to call, +and the second parameter is an array or string of parameters to pass to the method: .. literalinclude:: view_cells/001.php