Skip to content

Commit 8a52b4c

Browse files
cklei-carlycklei-carly
committed
update docs
1 parent d8e6b3d commit 8a52b4c

2 files changed

Lines changed: 161 additions & 9 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ InspireCMS Core is the foundation library that powers the InspireCMS platform. T
1414
- [Requirements](./docs/Requirements.md)
1515
- [Installing](./docs/Installing.md)
1616
- [Updating](./docs/Updating.md)
17-
- [CONTRIBUTING](.github/CONTRIBUTING.md)
17+
- [Contributing](.github/CONTRIBUTING.md)
1818
- [Core]()
1919
- [Overview](./docs/CoreConcepts.md)
2020
- [Configuration](./docs/Configuration.md)

‎docs/Templating.md‎

Lines changed: 160 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,8 @@
1-
# Templating in InspireCMS
1+
# Templating
22

33
InspireCMS templates allow you to define reusable layouts and components for your content.
44

55
## Theme Management
6-
76
### Creating a Theme
87
1. Navigate to `/cms/settings/templates`
98
2. Click `Create theme` or `Clone theme`
@@ -15,16 +14,18 @@ InspireCMS templates allow you to define reusable layouts and components for you
1514
2. Click `Change theme`
1615
3. Select your desired theme
1716

18-
> [!NOTE]
17+
> [!TIP]
1918
> You can view the current theme by running `php artisan inspirecms:about`
2019
2120
## Template Creation
2221

2322
1. Navigate to `/cms/settings/document-types`
24-
2. Select your target **Document Type**
25-
3. Create or edit an existing template for that **Document Type**
23+
2. Select your target document type[^1]
24+
3. Create or edit an existing template for that document type[^1]
25+
26+
InspireCMS uses [Blade](https://laravel.com/docs/11.x/blade) and automatically binds `$content` and `$locale`.
2627

27-
InspireCMS uses [Blade](https://laravel.com/docs/11.x/blade) and automatically binds `$content`. Example:
28+
Example:
2829

2930
```php
3031
@php
@@ -36,9 +37,159 @@ InspireCMS uses [Blade](https://laravel.com/docs/11.x/blade) and automatically b
3637
</x-cms-template>
3738
```
3839

40+
## Adding Fields to Template
41+
42+
InspireCMS allows you to add custom fields to your templates that content editors can use to populate pages.
43+
44+
### Defining Template Fields
45+
46+
When creating or editing a template, you can define fields in the "Fields" section:
47+
48+
1. Navigate to `/cms/settings/document-types`
49+
2. Select your document type[^1]
50+
3. Add fields using the form to input all required form group data, e.g.
51+
- Define field name, label, type, and validation rules
52+
- Organize fields into logical groups if needed
53+
- Set default values and configuration options
54+
- etc.
55+
56+
### Field Types
57+
58+
For detailed information about available field types and their configuration options, please see the [Custom Fields documentation](./docs/CustomFields.md).
59+
60+
### Using Fields in Templates
61+
62+
InspireCMS provides several directives to access your field data:
63+
- `@property()` - For basic field access
64+
- `@propertyArray()` - For accessing array fields (repeaters, content pickers, etc.)
65+
- `@propertyNotEmpty()` - For conditional rendering based on field content
66+
67+
#### Access Patterns
68+
69+
Fields can be accessed using different patterns depending on your needs:
70+
71+
- **Simple access**: `@property('fieldGroup', 'fieldName')`
72+
Returns the field value directly from `$content` and automatically names the variable `$fieldGroup_fieldName`.
73+
74+
- **Array access**: `@propertyArray('fieldGroup', 'fieldName')`
75+
Returns the field value as a PHP array that you can manipulate.
76+
77+
- **Conditional access**: `@propertyNotEmpty('fieldGroup', 'fieldName')`
78+
Creates a conditional block with an auto-generated variable containing the field value.
79+
80+
- **Custom DTO access**: `@property('fieldGroup', 'fieldName', null, $customDTO)`
81+
Gets the property value from a custom DTO object instead of the default `$content`.
82+
83+
- **Custom variable naming**: `@property('fieldGroup', 'fieldName', 'custom_var')`
84+
Retrieves the property value but assigns it to a variable named `$custom_var` instead of the default naming pattern.
85+
86+
- **Combined custom naming and DTO**: `@property('fieldGroup', 'fieldName', 'custom_var', $customDTO)`
87+
Gets the property from a custom DTO and assigns it to a variable with a custom name.
88+
89+
```php
90+
<!-- Examples -->
91+
@property('hero', 'title')
92+
<!-- Value is from $content, variable available as $hero_title -->
93+
94+
@property('hero', 'image', 'hero_img')
95+
<!-- Value is from $content, variable available as $hero_img -->
96+
97+
@property('blog', 'category', null, $blogDTO)
98+
<!-- Value is from $blogDTO, variable available as $blog_category -->
99+
100+
@property('blog', 'author', 'post_writer', $blogDTO)
101+
<!-- Value is from $blogDTO, variable available as $post_writer -->
102+
```
103+
104+
105+
#### Field Type-Specific Notes
106+
107+
Different field types return different data structures:
108+
- **Repeater**: Return arrays that can be iterated with `@foreach` directive
109+
- **Content Picker**: Return array of objects with methods like `getUrl()` and `getTitle()`
110+
- **File/Image**: Return associative arrays with metadata like 'disk', 'path', 'directory', etc.
111+
- **Rich Text**: Return rendered HTML content
112+
113+
> [!NOTE]
114+
> For detailed information about specific field types and their access patterns, please refer to the [Custom Fields documentation](docs/CustomFields.md).
115+
116+
#### Example
117+
118+
1. Basic Field Access
119+
120+
```php
121+
<h1>@property('hero', 'title')</h1>
122+
123+
<p>@property('hero', 'subtitle')</p>
124+
125+
@propertyArray('document_content', 'categories')
126+
<!-- Loop through array items -->
127+
@foreach ($blog_content_categories ?? [] as $category)
128+
<div class="categories">
129+
<span class="category">{{ $category }}</span>
130+
</div>
131+
@endforeach
132+
```
133+
134+
2. Conditional Field Access
135+
```php
136+
<!-- Check if field exists or has data -->
137+
@propertyNotEmpty('hero', 'image')
138+
<img src="{{ $hero_image }}" alt="@property('hero', 'image_alt')">
139+
@endif
140+
141+
<!-- Alternative syntax -->
142+
@propertyNotEmpty('document_content', 'sections')
143+
<!-- $document_content_sections is automatically available here -->
144+
@foreach ($document_content_sections as $section)
145+
<div class="section">{{ $section->getPropertyData('title')?->getValue() }}</div>
146+
@endforeach
147+
@endif
148+
```
149+
150+
3. Building a Page with Sections
151+
152+
```php
153+
<x-cms-template :content="$content" type="page">
154+
<header class="page-header">
155+
<h1>@property('page_basic', 'title')</h1>
156+
@propertyNotEmpty('page_basic', 'subtitle')
157+
<p class="subtitle">{{ $page_basic_subtitle }}</p>
158+
@endif
159+
</header>
160+
161+
<section class="intro">
162+
<div class="container">
163+
@property('intro', 'text')
164+
</div>
165+
</section>
166+
167+
@propertyNotEmpty('content_blocks', 'blocks')
168+
@foreach ($content_blocks_blocks as $block)
169+
@php
170+
$extraBlockStyle = $block->getPropertyData('style')?->getValue();
171+
@endphp
172+
<section class="content-block {{ $extraBlockStyle }}">
173+
<div class="container">
174+
<h2>{{ $block->getPropertyData('heading')?->getValue() }}</h2>
175+
<div class="content">
176+
{{ $block->getPropertyData('content')?->getValue() }}
177+
</div>
178+
@if($block->getPropertyData('has_button')?->getValue() ?? false)
179+
<a href="{{ $block->getPropertyData('button_link')?->getValue() }}" class="btn">
180+
{{ $block->getPropertyData('button_text')?->getValue() }}
181+
</a>
182+
@endif
183+
</div>
184+
</section>
185+
@endforeach
186+
@endif
187+
</x-cms-template>
188+
```
189+
39190
## Implementation Examples
40191

41-
Let's assume you've created a theme named "abc".
192+
Let's assume you've created a theme named "**abc**".
42193

43194
### Approach 1: Using Components
44195

@@ -281,6 +432,7 @@ Learn more about [layouts using inheritance in Blade](https://laravel.com/docs/1
281432
@endsection
282433
```
283434

284-
## Adding Fields to Template
435+
[^1]: Document types define the structure and behavior of content in InspireCMS. For detailed information, see the [Document Type](../docs/docs/references/DocumentType.md).
436+
285437

286438
TBC...

0 commit comments

Comments
 (0)