Skip to content

Commit 6c28b37

Browse files
committed
docs(README): Enhance documentation for DotCmsHelper and update content handling examples
- Added new section for SDK utilities, detailing the DotCmsHelper class and its methods. - Updated content handling examples to reflect object properties usage instead of arrays. - Clarified the representation of ContainerPage and Contentlet in the API reference.
1 parent 4865c7b commit 6c28b37

1 file changed

Lines changed: 72 additions & 37 deletions

File tree

README.md

Lines changed: 72 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -244,16 +244,16 @@ if ($page->vanityUrl !== null) {
244244
// Access containers and contentlets
245245
foreach ($page->containers as $containerId => $container) {
246246
echo "Container ID: " . $containerId . "\n";
247-
echo "Max Contentlets: " . ($container->maxContentlets ?? 0) . "\n";
247+
echo "Max Contentlets: " . $container->maxContentlets . "\n";
248248

249249
if (!empty($container->contentlets)) {
250-
foreach ($container->contentlets as $uuid => $contentletArray) {
251-
foreach ($contentletArray as $contentlet) {
250+
foreach ($container->contentlets as $uuid => $contentlets) {
251+
foreach ($contentlets as $contentlet) {
252252
echo "Contentlet type: " . $contentlet->contentType . "\n";
253253
echo "Contentlet title: " . ($contentlet->title ?? 'N/A') . "\n";
254254

255-
// Access additional fields using array access
256-
foreach ($contentlet as $fieldName => $fieldValue) {
255+
// Access additional fields using object properties
256+
foreach ($contentlet->getAdditionalProperties() as $fieldName => $fieldValue) {
257257
if (is_scalar($fieldValue)) {
258258
echo "$fieldName: $fieldValue\n";
259259
}
@@ -301,6 +301,44 @@ function processNavigation($navItem, $level = 0) {
301301
processNavigation($nav);
302302
```
303303

304+
### Using SDK Utilities
305+
306+
The SDK includes a `DotCmsHelper` class with common functions for rendering and working with DotCMS content:
307+
308+
```php
309+
use Dotcms\PhpSdk\Utils\DotCmsHelper;
310+
use Dotcms\PhpSdk\Model\Content\Contentlet;
311+
312+
// Generate HTML attributes from an associative array
313+
$attrs = [
314+
'class' => 'my-class',
315+
'data-id' => '123',
316+
'disabled' => true
317+
];
318+
$htmlAttrs = DotCmsHelper::htmlAttributes($attrs);
319+
320+
// Generate simple HTML for a contentlet
321+
$contentlet = new Contentlet(
322+
identifier: 'abc123',
323+
inode: 'inode123',
324+
title: 'My Content',
325+
contentType: 'Banner'
326+
);
327+
$html = DotCmsHelper::simpleContentHtml($contentlet->jsonSerialize());
328+
329+
// Extract accept types from container structures
330+
$acceptTypes = DotCmsHelper::extractAcceptTypes($containerStructures);
331+
332+
// Extract contentlets from container page
333+
$contentlets = DotCmsHelper::extractContentlets($containerPage, $uuid);
334+
```
335+
336+
These utilities help with common tasks like:
337+
- Generating HTML attributes safely
338+
- Rendering contentlets with basic HTML
339+
- Working with container structures and contentlets
340+
- Extracting data from container pages
341+
304342
## API Reference
305343

306344
### DotCMSClient
@@ -356,52 +394,49 @@ Represents a complete page asset from dotCMS.
356394
| `site` | Site | The Site object |
357395
| `template` | Template | The Template object |
358396
| `layout` | Layout | The Layout object |
359-
| `containers` | Array | Array of Container objects |
397+
| `containers` | array<ContainerPage> | Array of ContainerPage objects |
360398
| `urlContentMap` | Contentlet\|null | Content map for generated pages |
361399
| `viewAs` | ViewAs | Visitor context information |
362400
| `vanityUrl` | VanityUrl\|null | Optional vanity URL configuration |
363401

364-
### VanityUrl
402+
### ContainerPage
365403

366-
Represents a vanity URL configuration in dotCMS.
404+
Represents a container page from dotCMS.
367405

368406
| Property | Type | Description |
369407
|----------|------|-------------|
370-
| `pattern` | string | The URL pattern to match |
371-
| `vanityUrlId` | string | The unique identifier for the vanity URL |
372-
| `url` | string | The vanity URL path |
373-
| `siteId` | string | The site identifier |
374-
| `languageId` | int | The language ID |
375-
| `forwardTo` | string | The URL to forward to |
376-
| `response` | int | The HTTP response code |
377-
| `order` | int | The order of the vanity URL |
378-
| `forward` | bool | Whether to forward the request |
379-
| `temporaryRedirect` | bool | Whether to use temporary redirect |
380-
| `permanentRedirect` | bool | Whether to use permanent redirect |
381-
382-
### NavigationItem
383-
384-
Represents a navigation item from the dotCMS Navigation API.
408+
| `container` | Container | The Container object |
409+
| `containerStructures` | array<ContainerStructure> | Array of ContainerStructure objects |
410+
| `rendered` | array<string, string> | Rendered content keyed by UUID |
411+
| `contentlets` | array<string, array<Contentlet>> | Contentlets keyed by UUID |
412+
413+
### Contentlet
414+
415+
Represents a content item from dotCMS.
385416

386417
| Property | Type | Description |
387418
|----------|------|-------------|
388-
| `code` | ?string | The code of the navigation item |
389-
| `folder` | ?string | The folder identifier |
390-
| `host` | string | The host identifier |
391-
| `languageId` | int | The language ID |
392-
| `href` | string | The URL of the navigation item |
393-
| `title` | string | The title of the navigation item |
394-
| `type` | string | The type of the navigation item (folder, htmlpage, etc.) |
395-
| `hash` | int | The hash of the navigation item |
396-
| `target` | string | The target attribute for links (_self, _blank, etc.) |
397-
| `order` | int | The order of the navigation item |
419+
| `identifier` | string | The content identifier |
420+
| `inode` | string | The content inode |
421+
| `title` | string | The content title |
422+
| `contentType` | string | The content type |
423+
| `additionalProperties` | array<string, mixed> | Additional content properties |
398424

399425
| Method | Description | Return Type |
400426
|--------|-------------|-------------|
401-
| `isFolder` | Check if this navigation item is a folder | `bool` |
402-
| `isPage` | Check if this navigation item is a page | `bool` |
403-
| `hasChildren` | Check if this navigation item has children | `bool` |
404-
| `getChildren` | Get the children as NavigationItem objects | `?array` |
427+
| `getAdditionalProperties` | Get additional properties | `array<string, mixed>` |
428+
| `jsonSerialize` | Convert to array for JSON serialization | `array<string, mixed>` |
429+
430+
### DotCmsHelper
431+
432+
Utility class for common DotCMS operations.
433+
434+
| Method | Description | Parameters | Return Type |
435+
|--------|-------------|------------|-------------|
436+
| `htmlAttributes` | Generate HTML attributes | `array<string, mixed>` | `string` |
437+
| `simpleContentHtml` | Generate simple HTML for content | `array<string, mixed>` | `string` |
438+
| `extractAcceptTypes` | Extract accept types from structures | `array<ContainerStructure>` | `string` |
439+
| `extractContentlets` | Extract contentlets from container | `ContainerPage, string` | `array<Contentlet>` |
405440

406441
## Error Handling
407442

0 commit comments

Comments
 (0)