Skip to content

Commit 3c5ac7e

Browse files
thewebartisan7thewebartisan7
committed
Readme updated
1 parent 19ef893 commit 3c5ac7e

File tree

1 file changed

+258
-0
lines changed

1 file changed

+258
-0
lines changed

‎readme.md

+258
Original file line numberDiff line numberDiff line change
@@ -241,12 +241,270 @@ With namespaces you can define a top level root path to your components like sho
241241

242242
### Slots
243243

244+
Your components can inject code in specific slots you define, and then you can fill this content when you use the component.
245+
Find below a simple example.
246+
247+
Create the component:
248+
249+
```html
250+
<!-- src/modal.html -->
251+
<div class="modal">
252+
<div class="modal-header">
253+
<slot:header></slot:header>
254+
</div>
255+
<div class="modal-body">
256+
<slot:body></slot:body>
257+
</div>
258+
<div class="modal-footer">
259+
<slot:footer></slot:footer>
260+
</div>
261+
</div>
262+
```
263+
264+
Use the component:
265+
266+
```html
267+
<!-- src/index.html -->
268+
<x-modal>
269+
<fill:header>Header content</fill:header>
270+
<fill:body>Body content</fill:body>
271+
<fill:footer>Footer content</fill:footer>
272+
</x-modal>
273+
```
274+
275+
Result:
276+
277+
```html
278+
<!-- dist/index.html -->
279+
<div class="modal">
280+
<div class="modal-header">
281+
Header content
282+
</div>
283+
<div class="modal-body">
284+
Body content
285+
</div>
286+
<div class="modal-footer">
287+
Footer content
288+
</div>
289+
</div>
290+
```
291+
292+
By default the content is replaced, but you can also prepend or append the content, or keep the default content by not filling the slot.
293+
294+
Add some default content in the component:
295+
296+
```html
297+
<!-- src/modal.html -->
298+
<div class="modal">
299+
<div class="modal-header">
300+
<slot:header>Default header</slot:header>
301+
</div>
302+
<div class="modal-body">
303+
<slot:body>content</slot:body>
304+
</div>
305+
<div class="modal-footer">
306+
<slot:footer>Footer</slot:footer>
307+
</div>
308+
</div>
309+
```
310+
311+
```html
312+
<!-- src/index.html -->
313+
<x-modal>
314+
<fill:body prepend>Prepend body</fill:body>
315+
<fill:footer append>content</fill:footer>
316+
</x-modal>
317+
```
318+
319+
Result:
320+
321+
```html
322+
<!-- dist/index.html -->
323+
<div class="modal">
324+
<div class="modal-header">
325+
Default header
326+
</div>
327+
<div class="modal-body">
328+
Prepend body content
329+
</div>
330+
<div class="modal-footer">
331+
Footer content
332+
</div>
333+
</div>
334+
```
335+
244336
### Stacks
245337

338+
You can push content to named stacks which can be rendered somewhere else in another place. This can be particularly useful for specifying any JavaScript or CSS required by your components.
339+
340+
First of all define a `<stack>` anywhere in your code, for example:
341+
342+
```html
343+
<!-- src/index.html -->
344+
<html>
345+
<head>
346+
<stack name="styles"></stack>
347+
</head>
348+
<body>
349+
350+
<x-modal>
351+
<fill:header>Header content</fill:header>
352+
<fill:body>Body content</fill:body>
353+
<fill:footer>Footer content</fill:footer>
354+
</x-modal>
355+
356+
<stack name="scripts"></stack>
357+
</body>
358+
</html>
359+
```
360+
361+
Then in modal components, or any other child components, you can push content to this stack.
362+
363+
```html
364+
<!-- src/modal.html -->
365+
<div class="modal">
366+
<div class="modal-header">
367+
<slot:header></slot:header>
368+
</div>
369+
<div class="modal-body">
370+
<slot:body></slot:body>
371+
</div>
372+
<div class="modal-footer">
373+
<slot:footer></slot:footer>
374+
</div>
375+
</div>
376+
377+
<push name="styles">
378+
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.2.2/dist/css/bootstrap.min.css" rel="stylesheet">
379+
</push>
380+
381+
<push name="scripts">
382+
<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.2.2/dist/js/bootstrap.bundle.min.js"></script>
383+
</push>
384+
```
385+
386+
The output will be:
387+
388+
```html
389+
<!-- dist/index.html -->
390+
<html>
391+
<head>
392+
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.2.2/dist/css/bootstrap.min.css" rel="stylesheet">
393+
</head>
394+
<body>
395+
<div class="modal">
396+
<div class="modal-header">
397+
Header content
398+
</div>
399+
<div class="modal-body">
400+
Body content
401+
</div>
402+
<div class="modal-footer">
403+
Footer content
404+
</div>
405+
</div>
406+
<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.2.2/dist/js/bootstrap.bundle.min.js"></script>
407+
</body>
408+
</html>
409+
```
410+
411+
The `once` attribute allows you to push content only once per rendering cycle. For example, if you are rendering a given component within a loop, you may wish to only push the JavaScript and CSS the first time the component is rendered.
412+
413+
Example.
414+
415+
```html
416+
<!-- src/modal.html -->
417+
<div class="modal">
418+
<!-- ... -->
419+
</div>
420+
421+
<!-- The push content will be pushed only once in the stack -->
422+
423+
<push name="styles" once>
424+
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.2.2/dist/css/bootstrap.min.css" rel="stylesheet">
425+
</push>
426+
427+
<push name="scripts" once>
428+
<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.2.2/dist/js/bootstrap.bundle.min.js"></script>
429+
</push>
430+
```
431+
432+
By default the content is pushed in the stack in the given order.
433+
If you would like to prepend content onto the beginning of a stack, you should use the `prepend` attribute:
434+
435+
```html
436+
<push name="scripts">
437+
<!-- This will be second -->
438+
<script src="/example.js"></script>
439+
</push>
440+
441+
<!-- Later... -->
442+
443+
<push name="scripts" prepend>
444+
<!-- This will be first -->
445+
<script src="/example-2.js"></script>
446+
</push>
447+
```
448+
246449
### Props
247450

451+
TODO...
452+
248453
### Attributes
249454

455+
Your can pass any attributes to your components and this will be added to the first element of your component.
456+
By default `class` and `style` are merged with existing `class` and `style` attribute of the first element of your component.
457+
All others attributes are override by default.
458+
Only attribute not defined as `props` will be processed.
459+
460+
As already seen in basic example:
461+
462+
``` html
463+
<!-- src/button.html -->
464+
<script props>
465+
module.exports = {
466+
label: 'A button'
467+
}
468+
</script>
469+
<button type="button" class="btn">
470+
{{ label }}
471+
</button>
472+
```
473+
474+
Use the component:
475+
476+
``` html
477+
<!-- src/index.html -->
478+
<x-button type="submit" class="btn-primary" label="My button"></x-button>
479+
```
480+
481+
Result:
482+
483+
``` html
484+
<!-- dist/index.html -->
485+
<button type="submit" class="btn btn-primary">My button</button>
486+
```
487+
488+
As you may notice the `label` attribute is not added as attribute, since it's defined as a `props`.
489+
490+
If you are familiar with Laravel Blade, this is also how Blade handle this.
491+
492+
As said early, class and style are merged by default, if you want to override them, just prepend `override:` to the attributes:
493+
494+
``` html
495+
<!-- src/index.html -->
496+
<x-button type="submit" override:class="btn-custom" label="My button"></x-button>
497+
```
498+
499+
Result:
500+
501+
``` html
502+
<!-- dist/index.html -->
503+
<button type="submit" class="btn-custom">My button</button>
504+
```
505+
506+
You can add custom rules how attributes are parsed, as behind the scene it's used [posthtml-attrs-parser](https://github.com/posthtml/posthtml-attrs-parser) plugin.
507+
250508
## Migration
251509

252510
## Contributing

0 commit comments

Comments
 (0)