Skip to content

Commit aec970e

Browse files
author
Emmanuel Campait
committed
Add many new Bootstrap 5 Cells and reorganize documentation
This release expands the package with a large set of reusable Bootstrap 5 Cells for CodeIgniter 4, adds CI4 helper improvements for forms, validation, and tables, and moves the documentation into a cleaner structured docs/ directory.
1 parent 10bf81e commit aec970e

File tree

116 files changed

+15033
-27
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

116 files changed

+15033
-27
lines changed

‎README.md‎

Lines changed: 25 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -6,14 +6,20 @@
66
[![Psalm](https://img.shields.io/github/actions/workflow/status/domProjects/codeigniter4-bootstrap/psalm.yml?branch=main&label=Psalm)](https://github.com/domProjects/codeigniter4-bootstrap/actions/workflows/psalm.yml)
77
[![PHPStan](https://img.shields.io/github/actions/workflow/status/domProjects/codeigniter4-bootstrap/phpstan.yml?branch=main&label=PHPStan)](https://github.com/domProjects/codeigniter4-bootstrap/actions/workflows/phpstan.yml)
88

9-
Bootstrap 5 asset publisher for CodeIgniter 4.
9+
Bootstrap 5 tools for CodeIgniter 4.
1010

11-
This package adds a Spark command that publishes the Bootstrap distribution files from Composer dependencies into your public directory.
11+
This package currently provides:
12+
13+
- a Spark command that publishes the Bootstrap distribution files from Composer dependencies into your public directory
14+
- reusable CodeIgniter 4 Cells for Bootstrap components
15+
- CI4 helpers for validation-aware form payloads and table payload generation
1216

1317
## Features
1418

1519
- Installs Bootstrap with Composer
1620
- Publishes only the Bootstrap production assets
21+
- Provides reusable Bootstrap component Cells for CodeIgniter 4 views
22+
- Includes helper functions for forms, validation, and tables
1723
- Works with CodeIgniter 4 auto-discovery
1824
- Keeps Bootstrap asset publication explicit and framework-oriented
1925

@@ -81,37 +87,29 @@ Example in a CodeIgniter view:
8187
<script src="<?= base_url('assets/bootstrap/js/bootstrap.bundle.min.js') ?>"></script>
8288
```
8389

84-
## Package Structure
90+
## Documentation
8591

86-
```text
87-
src/
88-
Commands/
89-
PublishBootstrap.php
90-
Publishers/
91-
BootstrapPublisher.php
92-
```
92+
Detailed documentation now lives in the `docs/` directory:
9393

94-
## Local Development
94+
- [Documentation Index](docs/index.md)
95+
- [Getting Started](docs/getting-started.md)
96+
- [Cells Reference](docs/cells/index.md)
97+
- [Cells Reference: Core Components](docs/cells/core-components.md)
98+
- [Cells Reference: Overlays and Navigation](docs/cells/overlays-and-navigation.md)
99+
- [Cells Reference: Forms and Data Display](docs/cells/forms-and-data.md)
100+
- [Helpers Reference](docs/helpers.md)
101+
- [Development Guide](docs/development.md)
95102

96-
If you want to work on the package locally from another project, you can use a Composer `path` repository.
103+
## Included Cells
97104

98-
Example:
105+
The package currently includes reusable Cells for:
99106

100-
```json
101-
{
102-
"repositories": {
103-
"domprojects-codeigniter4-bootstrap": {
104-
"type": "path",
105-
"url": "packages/domprojects/codeigniter4-bootstrap",
106-
"options": {
107-
"symlink": false
108-
}
109-
}
110-
}
111-
}
112-
```
107+
- alerts, badges, buttons, cards, images, figures, breadcrumbs, lists, and pagination
108+
- navigation and overlays such as navbars, dropdowns, tabs, accordions, modals, toasts, and offcanvas panels
109+
- utility components such as progress bars, spinners, placeholders, popovers, tooltips, and scrollspy blocks
110+
- forms, input groups, validation feedback, tables, and data display components
113111

114-
If you also test the automation plugin locally, add a second `path` repository for `packages/domprojects/codeigniter4-bootstrap-plugin`.
112+
See the `docs/` directory for the full component reference and examples.
115113

116114
## Related Package
117115

‎docs/cells/core-components.md‎

Lines changed: 275 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,275 @@
1+
# Cells Reference: Core Components
2+
3+
Use this guide for foundational Bootstrap Cells and simple data display components.
4+
5+
## Alert Cell
6+
7+
```php
8+
<?= view_cell(\domProjects\CodeIgniterBootstrap\Cells\AlertCell::class, [
9+
'message' => 'Profile updated successfully.',
10+
'variant' => 'success',
11+
]) ?>
12+
```
13+
14+
Supported parameters:
15+
16+
- `message`: alias of `content` for simple text alerts
17+
- `content`: alert body content
18+
- `heading`: optional `.alert-heading`
19+
- `variant`: Bootstrap contextual variant like `primary`, `success`, `warning`, `danger`
20+
- `type`: alias of `variant`
21+
- `dismissible`: adds the close button and Bootstrap dismissal classes
22+
- `escape`: escapes `heading` and `content` by default; set to `false` to render trusted HTML
23+
- `classes`: additional CSS classes on the wrapper
24+
- `role`: ARIA role, defaults to `alert`
25+
- `closeLabel`: accessible label for the dismiss button, defaults to `Close`
26+
27+
## Badge Cell
28+
29+
```php
30+
<?= view_cell(\domProjects\CodeIgniterBootstrap\Cells\BadgeCell::class, [
31+
'content' => '99+',
32+
'variant' => 'danger',
33+
'pill' => true,
34+
]) ?>
35+
```
36+
37+
Supported parameters:
38+
39+
- `message`: alias of `content`
40+
- `content`: badge content
41+
- `variant`: Bootstrap contextual variant like `primary`, `secondary`, `success`, `danger`
42+
- `type`: alias of `variant`
43+
- `pill`: adds the `.rounded-pill` utility class
44+
- `classes`: additional CSS classes on the badge
45+
- `escape`: escapes `content` and `hiddenText` by default; set to `false` to render trusted HTML
46+
- `hiddenText`: optional visually hidden text for accessibility
47+
48+
## Button Cell
49+
50+
```php
51+
<?= view_cell(\domProjects\CodeIgniterBootstrap\Cells\ButtonCell::class, [
52+
'content' => 'View profile',
53+
'href' => '/profile',
54+
'variant' => 'secondary',
55+
'outline' => true,
56+
]) ?>
57+
```
58+
59+
Supported parameters:
60+
61+
- `message`: alias of `content`
62+
- `content`: button label/content
63+
- `variant`: Bootstrap contextual variant like `primary`, `secondary`, `success`, `danger`
64+
- `type`: alias of `variant`
65+
- `outline`: switches from `.btn-{variant}` to `.btn-outline-{variant}`
66+
- `size`: `sm` or `lg`
67+
- `href`: when set, renders an anchor button
68+
- `tag`: force `button` or `a`
69+
- `buttonType`: `type` attribute for `<button>`, defaults to `button`
70+
- `disabled`: disabled state for buttons and accessible disabled state for anchors
71+
- `classes`: additional CSS classes
72+
- `escape`: escapes `content` by default; set to `false` to render trusted HTML
73+
- `role`: optional explicit role
74+
75+
## Card Cell
76+
77+
```php
78+
<?= view_cell(\domProjects\CodeIgniterBootstrap\Cells\CardCell::class, [
79+
'title' => 'Featured',
80+
'content' => 'This is a wider card with supporting text.',
81+
]) ?>
82+
```
83+
84+
Supported parameters:
85+
86+
- `message`: alias of `content`
87+
- `content`: main card text rendered in `.card-text`
88+
- `title`: optional `.card-title`
89+
- `subtitle`: optional `.card-subtitle`
90+
- `header`: optional `.card-header`
91+
- `footer`: optional `.card-footer`
92+
- `image`: optional image URL
93+
- `imageAlt`: alt text for the image
94+
- `imagePosition`: `top` or `bottom`
95+
- `classes`: additional CSS classes on the card wrapper
96+
- `bodyClasses`: additional CSS classes on `.card-body`
97+
- `titleTag`: heading tag for the title, defaults to `h5`
98+
- `escape`: escapes textual content by default; set to `false` to render trusted HTML
99+
100+
## Image Cell
101+
102+
```php
103+
<?= view_cell(\domProjects\CodeIgniterBootstrap\Cells\ImageCell::class, [
104+
'src' => '/images/photo.jpg',
105+
'alt' => 'Profile photo',
106+
'thumbnail' => true,
107+
'rounded' => true,
108+
]) ?>
109+
```
110+
111+
Supported parameters:
112+
113+
- `src`: image source URL
114+
- `image`: alias of `src`
115+
- `alt`: image alt text
116+
- `imageAlt`: alias of `alt`
117+
- `fluid`: adds `.img-fluid`, enabled by default
118+
- `thumbnail`: adds `.img-thumbnail`
119+
- `rounded`: `true` for `.rounded` or a custom rounded utility class like `rounded-circle`
120+
- `align`: `start`, `end`, or `center`
121+
- `classes`: additional CSS classes on the `<img>`
122+
- `attrs`: additional `<img>` attributes such as `loading`, `width`, `height`, or `data-*`
123+
- `sources`: optional `<source>` definitions for wrapping the image in a `<picture>` element
124+
125+
## Figure Cell
126+
127+
```php
128+
<?= view_cell(\domProjects\CodeIgniterBootstrap\Cells\FigureCell::class, [
129+
'src' => '/images/photo.jpg',
130+
'alt' => 'Profile photo',
131+
'caption' => 'A caption for the above image.',
132+
'captionAlign' => 'end',
133+
]) ?>
134+
```
135+
136+
Supported parameters:
137+
138+
- `src`: figure image source URL
139+
- `image`: alias of `src`
140+
- `alt`: image alt text
141+
- `imageAlt`: alias of `alt`
142+
- `caption`: figure caption text
143+
- `content`: alias of `caption`
144+
- `message`: alias of `caption`
145+
- `fluid`: adds `.img-fluid` to the figure image, enabled by default
146+
- `thumbnail`: adds `.img-thumbnail` to the figure image
147+
- `rounded`: `true` for `.rounded` or a custom rounded utility class like `rounded-circle`
148+
- `captionAlign`: `start`, `center`, or `end`
149+
- `classes`: additional CSS classes on the `<figure>`
150+
- `imageClasses`: additional CSS classes on the `<img>`
151+
- `captionClasses`: additional CSS classes on the `<figcaption>`
152+
- `attrs`: additional `<img>` attributes such as `loading`, `width`, `height`, or `data-*`
153+
- `sources`: optional `<source>` definitions for wrapping the image in a `<picture>` element
154+
- `escape`: escapes caption content by default; set to `false` to render trusted HTML
155+
156+
## Progress Cell
157+
158+
```php
159+
<?= view_cell(\domProjects\CodeIgniterBootstrap\Cells\ProgressCell::class, [
160+
'value' => 25,
161+
'label' => '25%',
162+
]) ?>
163+
```
164+
165+
Supported parameters:
166+
167+
- `value`: shorthand single progress value
168+
- `label`: shorthand single progress label
169+
- `bars`: array of bars using `value`, `label`, `variant`, `striped`, `animated`, and `classes`
170+
- `height`: optional inline height
171+
- `classes`: additional CSS classes on the wrapper
172+
- `escape`: escapes labels by default; set to `false` to render trusted HTML
173+
174+
## Spinner Cell
175+
176+
```php
177+
<?= view_cell(\domProjects\CodeIgniterBootstrap\Cells\SpinnerCell::class, [
178+
'variant' => 'primary',
179+
]) ?>
180+
```
181+
182+
Supported parameters:
183+
184+
- `type`: `border` or `grow`
185+
- `variant`: optional contextual text color like `primary` or `secondary`
186+
- `size`: `sm` for the small spinner variant
187+
- `label`: accessible loading label, defaults to `Loading...`
188+
- `classes`: additional CSS classes
189+
190+
## Placeholder Cell
191+
192+
```php
193+
<?= view_cell(\domProjects\CodeIgniterBootstrap\Cells\PlaceholderCell::class, [
194+
'items' => [
195+
['width' => 8],
196+
['width' => 6, 'variant' => 'secondary'],
197+
],
198+
]) ?>
199+
```
200+
201+
Supported parameters:
202+
203+
- `items`: placeholder rows using `width`, `variant`, `size`, and `classes`
204+
- `width`: shorthand width for the single default placeholder
205+
- `variant`: optional background variant like `primary`, `secondary`, or `success`
206+
- `size`: `lg`, `sm`, or `xs`
207+
- `animation`: `glow` or `wave`
208+
- `classes`: additional CSS classes on the wrapper
209+
- `itemClasses`: additional CSS classes on the single placeholder item
210+
211+
## Description List Cell
212+
213+
```php
214+
<?= view_cell(\domProjects\CodeIgniterBootstrap\Cells\DescriptionListCell::class, [
215+
'items' => [
216+
['term' => 'Name', 'description' => 'Jane Doe'],
217+
['term' => 'Role', 'description' => 'Admin'],
218+
],
219+
]) ?>
220+
```
221+
222+
Supported parameters:
223+
224+
- `items`: list entries using `term`, `description`, `termClasses`, and `descriptionClasses`
225+
- `classes`: additional classes on the `<dl>`
226+
- `row`: adds Bootstrap `.row`, enabled by default
227+
- `termClasses`: default classes for `<dt>`, defaults to `col-sm-3`
228+
- `descriptionClasses`: default classes for `<dd>`, defaults to `col-sm-9`
229+
- `escape`: escapes terms and descriptions by default; set to `false` to render trusted HTML
230+
231+
## Stats Cards Cell
232+
233+
```php
234+
<?= view_cell(\domProjects\CodeIgniterBootstrap\Cells\StatsCardsCell::class, [
235+
'items' => [
236+
['label' => 'Users', 'value' => '128'],
237+
['label' => 'Revenue', 'value' => '$4.2k', 'description' => 'This month'],
238+
],
239+
]) ?>
240+
```
241+
242+
Supported parameters:
243+
244+
- `items`: cards using `label`, `value`, `description`, `meta`, `variant`, `columnClasses`, and `cardClasses`
245+
- `classes`: wrapper classes, defaults to `row g-3`
246+
- `columnClasses`: default classes for each item column
247+
- `cardClasses`: default classes for each card
248+
- `escape`: escapes content by default; set to `false` to render trusted HTML
249+
250+
## Empty State Cell
251+
252+
```php
253+
<?= view_cell(\domProjects\CodeIgniterBootstrap\Cells\EmptyStateCell::class, [
254+
'title' => 'No projects',
255+
'content' => 'Create your first project to get started.',
256+
]) ?>
257+
```
258+
259+
Supported parameters:
260+
261+
- `title`: heading text, defaults to `Nothing here yet`
262+
- `content`: description text
263+
- `message`: alias of `content`
264+
- `actions`: optional action buttons using `label`, `href`, `variant`, and `classes`
265+
- `classes`: wrapper classes
266+
- `bodyClasses`: classes on the inner content wrapper
267+
- `maxWidth`: max-width style for the content wrapper
268+
- `escape`: escapes content by default; set to `false` to render trusted HTML
269+
270+
## See Also
271+
272+
- [Cells Reference](index.md)
273+
- [Overlays and Navigation](overlays-and-navigation.md)
274+
- [Forms and Data Display](forms-and-data.md)
275+
- [Documentation Index](../index.md)

0 commit comments

Comments
 (0)