Skip to content

Commit 7616aca

Browse files
committed
feat(docs): Update README for DotCMS examples with SDK utilities
- Enhanced README files for both Laravel and Symfony examples to include usage of DotCmsHelper utilities. - Documented key functions like getContainerData, htmlAttributes, and simpleContentHtml for better clarity. - Improved code snippets in the documentation to reflect the latest implementation changes.
1 parent 9b64d8d commit 7616aca

2 files changed

Lines changed: 53 additions & 42 deletions

File tree

examples/dotcms-laravel/README.md

Lines changed: 9 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -145,13 +145,15 @@ These registrations ensure the DotCMS service provider is loaded during applicat
145145

146146
### 2. Create Helper Functions
147147

148-
Create helper functions for DotCMS rendering in `app/Helpers/DotCmsHelpers.php`:
148+
Create helper functions for DotCMS rendering in `app/Helpers/DotCmsHelpers.php`. This implementation leverages the helper utilities provided by the PHP SDK:
149149

150150
```php
151151
<?php
152152

153153
namespace App\Helpers;
154154

155+
use Dotcms\PhpSdk\Utils\DotCmsHelper;
156+
155157
class DotCmsHelpers
156158
{
157159
/**
@@ -163,17 +165,7 @@ class DotCmsHelpers
163165
*/
164166
public function getContainersData($containers, $container)
165167
{
166-
if (empty($containers) || empty($container)) {
167-
return null;
168-
}
169-
170-
$identifier = $container['identifier'] ?? null;
171-
172-
if (!$identifier || !isset($containers[$identifier])) {
173-
return null;
174-
}
175-
176-
return $containers[$identifier];
168+
return DotCmsHelper::getContainerData($containers, $container);
177169
}
178170

179171
/**
@@ -184,23 +176,7 @@ class DotCmsHelpers
184176
*/
185177
public function htmlAttr($attributes)
186178
{
187-
if (empty($attributes)) {
188-
return '';
189-
}
190-
191-
$html = '';
192-
193-
foreach ($attributes as $key => $value) {
194-
if (is_bool($value)) {
195-
if ($value) {
196-
$html .= ' ' . $key;
197-
}
198-
} else {
199-
$html .= ' ' . $key . '="' . htmlspecialchars($value, ENT_QUOTES, 'UTF-8') . '"';
200-
}
201-
}
202-
203-
return $html;
179+
return DotCmsHelper::htmlAttributes($attributes);
204180
}
205181

206182
/**
@@ -224,17 +200,16 @@ class DotCmsHelpers
224200
}
225201
}
226202

227-
// Default rendering with title
228-
$title = $content['title'] ?? $content['name'] ?? 'No Title';
229-
return '<div class="content-wrapper"><h3>' . htmlspecialchars($title, ENT_QUOTES, 'UTF-8') . '</h3></div>';
203+
// Fall back to the SDK simple HTML renderer
204+
return DotCmsHelper::simpleContentHtml($content);
230205
}
231206
}
232207
```
233208

234-
The DotCMSHelpers class provides three key functions:
209+
The DotCMSHelpers class provides three key functions, all leveraging the SDK's `DotCmsHelper` utility class:
235210
- `getContainersData`: Retrieves container content from the DotCMS page structure
236211
- `htmlAttr`: Safely generates HTML attributes from arrays, handling special cases like boolean attributes
237-
- `generateHtmlBasedOnProperty`: Renders content intelligently by looking for type-specific templates or falling back to defaults
212+
- `generateHtmlBasedOnProperty`: Renders content intelligently by looking for type-specific templates or falling back to the SDK's default renderer
238213

239214
Create a service provider to share the helpers with all views in `app/Providers/DotCmsHelpersServiceProvider.php`:
240215

examples/dotcms-symfony/README.md

Lines changed: 44 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,47 @@ dotcms-symfony/
4646
└── activity.twig
4747
```
4848

49+
## Using SDK Utilities
50+
51+
This example leverages the utility helpers provided by the DotCMS PHP SDK. The SDK includes a `DotCmsHelper` class with common functions for rendering and working with DotCMS content:
52+
53+
- `getContainerData()`: Retrieves container data by identifier
54+
- `htmlAttributes()`: Generates HTML attributes from an associative array
55+
- `simpleContentHtml()`: Provides fallback HTML rendering for content types
56+
57+
These utilities are used in the Twig extension (`DotCMSExtension.php`) to simplify templating:
58+
59+
```php
60+
<?php
61+
62+
namespace App\Twig;
63+
64+
use Dotcms\PhpSdk\Utils\DotCmsHelper;
65+
use Twig\Extension\AbstractExtension;
66+
use Twig\TwigFunction;
67+
68+
class DotCMSExtension extends AbstractExtension
69+
{
70+
// ...
71+
72+
public function htmlAttr(array $attrs): string
73+
{
74+
return DotCmsHelper::htmlAttributes($attrs);
75+
}
76+
77+
// ...
78+
79+
public function generateHtmlBasedOnProperty(array $content): string
80+
{
81+
// Try to use Twig templates first
82+
// ...
83+
84+
// Fall back to the SDK's simple content HTML renderer if no template is found
85+
return DotCmsHelper::simpleContentHtml($content);
86+
}
87+
}
88+
```
89+
4990
## Installation
5091

5192
1. Clone this repository or create a new Symfony project:
@@ -258,6 +299,7 @@ use Twig\Extension\AbstractExtension;
258299
use Twig\TwigFunction;
259300
use InvalidArgumentException;
260301
use RuntimeException;
302+
use Dotcms\PhpSdk\Utils\DotCmsHelper;
261303
262304
class DotCMSExtension extends AbstractExtension
263305
{
@@ -278,13 +320,7 @@ class DotCMSExtension extends AbstractExtension
278320
279321
public function htmlAttr(array $attrs): string
280322
{
281-
return implode(' ', array_map(
282-
fn($key, $value) => is_bool($value)
283-
? sprintf('%s="%s"', $key, $value ? 'true' : 'false')
284-
: sprintf('%s="%s"', $key, htmlspecialchars((string)$value, ENT_QUOTES)),
285-
array_keys($attrs),
286-
$attrs
287-
));
323+
return DotCmsHelper::htmlAttributes($attrs);
288324
}
289325
290326
public function getGridClass(int $position, string $type = 'start'): string
@@ -311,7 +347,7 @@ class DotCMSExtension extends AbstractExtension
311347
};
312348
313349
if (empty($template)) {
314-
return '';
350+
return DotCmsHelper::simpleContentHtml($content);
315351
}
316352
317353
try {

0 commit comments

Comments
 (0)