Skip to content

Commit 1624780

Browse files
fmontesfmontes
authored
Merge pull request #16 from dotCMS/improve-frameworks-examples
Improve frameworks examples
2 parents 409373e + 5bb8d66 commit 1624780

31 files changed

Lines changed: 6438 additions & 274 deletions

‎examples/dotcms-symfony/.gitignore‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
1-
21
###> symfony/framework-bundle ###
32
/.env.local
43
/.env.local.php
@@ -18,8 +17,9 @@
1817
.phpunit.result.cache
1918
/phpunit.xml
2019
###< symfony/phpunit-bridge ###
21-
22-
###> symfony/asset-mapper ###
23-
/public/assets/
24-
/assets/vendor/
25-
###< symfony/asset-mapper ###
20+
###> symfony/webpack-encore-bundle ###
21+
/node_modules/
22+
/public/build/
23+
npm-debug.log
24+
yarn-error.log
25+
###< symfony/webpack-encore-bundle ###

‎examples/dotcms-symfony/CLAUDE.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
This is a Symfony 7.2 application that demonstrates integration with DotCMS using the DotCMS PHP SDK. It serves as a headless CMS frontend that dynamically renders pages, layouts, containers, and content from DotCMS.
8+
9+
## Key Architecture Components
10+
11+
### Core Integration Pattern
12+
- **Catch-all routing**: Single controller (`CatchAllController`) handles all page requests via a catch-all route
13+
- **Service layer**: `DotCMSService` wraps the DotCMS PHP SDK client for consistent API access
14+
- **Twig extensions**: `DotCMSExtension` provides template functions for rendering DotCMS content
15+
- **Exception mapping**: DotCMS SDK exceptions are mapped to appropriate Symfony HTTP exceptions
16+
- **UVE integration**: Universal Visual Editor enables content editing capabilities
17+
- **Frontend architecture**: Stimulus controllers handle JavaScript functionality and UVE interactions
18+
19+
### DotCMS Integration Flow
20+
1. Symfony router matches catch-all route to `CatchAllController::show()`
21+
2. Controller extracts path and optional query parameters (language_id, mode, personaId, publishDate)
22+
3. `DotCMSService` creates page request with parameters and fetches from DotCMS API
23+
4. Page data (layout, containers, contentlets) is passed to Twig templates
24+
5. Twig extension functions render content-type specific templates or fall back to SDK utilities
25+
26+
### Template Architecture
27+
- `templates/page.html.twig`: Main page template that renders layout rows/columns
28+
- `templates/dotcms/container.twig`: Container template with contentlet rendering
29+
- `templates/dotcms/content-types/`: Content-type specific templates (banner.twig, product.twig, etc.)
30+
- `templates/dotcms/header.twig`: Navigation rendering using DotCMS navigation API
31+
32+
## Development Commands
33+
34+
### Start Development Server
35+
```bash
36+
symfony server:start
37+
```
38+
39+
### Testing
40+
```bash
41+
# Run all tests
42+
vendor/bin/phpunit
43+
44+
# Or using Symfony's PHPUnit bridge
45+
php bin/phpunit
46+
```
47+
48+
### Dependency Management
49+
```bash
50+
# Install dependencies
51+
composer install
52+
53+
# For local SDK development
54+
COMPOSER=composer.dev.json composer install
55+
```
56+
57+
### Cache and Assets
58+
```bash
59+
# Clear cache
60+
php bin/console cache:clear
61+
62+
# Install assets
63+
php bin/console assets:install
64+
65+
# Build frontend assets with Webpack Encore
66+
npm run dev
67+
68+
# Build for production
69+
npm run build
70+
71+
# Watch for changes during development
72+
npm run watch
73+
74+
# Start development server with asset watching
75+
npm run dev-server
76+
```
77+
78+
## Configuration
79+
80+
### Environment Variables
81+
- `DOTCMS_HOST`: DotCMS instance URL (default: https://demo.dotcms.com)
82+
- `DOTCMS_API_KEY`: API key for DotCMS authentication
83+
84+
### Service Configuration
85+
DotCMS client is configured in `config/services.yaml`:
86+
- `dotcms.client`: Main DotCMSClient service
87+
- `dotcms.config`: Configuration with host, API key, and client options
88+
- Client timeout: 30 seconds, SSL verification enabled
89+
- Debug logging enabled for development
90+
91+
## Key Files and Their Purpose
92+
93+
### Controllers
94+
- `src/Controller/CatchAllController.php`: Handles all page requests, fetches from DotCMS, maps exceptions
95+
96+
### Services
97+
- `src/Service/DotCMSService.php`: Wraps DotCMS client, provides page and navigation methods with parameter support
98+
99+
### Twig Extensions
100+
- `src/Twig/DotCMSExtension.php`: Template functions for content rendering, HTML attributes, grid classes
101+
102+
### Templates
103+
- `templates/page.html.twig`: Main page template with layout rendering
104+
- `templates/dotcms/container.twig`: Container and contentlet rendering with DotCMS attributes
105+
- `templates/dotcms/content-types/`: Content-type specific templates
106+
- `templates/base.html.twig`: Base template with UVE script integration
107+
108+
### Frontend Assets
109+
- `assets/app.js`: Main JavaScript entry point
110+
- `assets/controllers/dotcms_edit_controller.js`: Stimulus controller for UVE edit functionality
111+
- `webpack.config.js`: Webpack Encore configuration for asset compilation
112+
- `package.json`: Node.js dependencies including @dotcms/uve and @dotcms/types
113+
114+
## Working with Content Types
115+
116+
To add support for new content types:
117+
1. Create template in `templates/dotcms/content-types/{content-type}.twig`
118+
2. Template receives `content` variable (Contentlet object) and `dotcms_host` variable
119+
3. The `generateHtmlBasedOnProperty` function automatically finds and renders the template
120+
4. Falls back to SDK's `simpleContentHtml` if no template exists
121+
122+
## UVE (Universal Visual Editor) Integration
123+
124+
The application includes DotCMS UVE integration for content editing:
125+
126+
### Key Components
127+
- **UVE Script**: Loaded in `templates/base.html.twig` from DotCMS host
128+
- **Edit Controller**: `assets/controllers/dotcms_edit_controller.js` handles edit functionality
129+
- **Dependencies**: Uses `@dotcms/uve` and `@dotcms/types` packages
130+
- **Mode Detection**: Edit buttons only appear when in UVE edit mode
131+
132+
### Stimulus Controller Features
133+
- **Auto-hide**: Edit buttons are hidden when not in edit mode
134+
- **Content Editing**: Calls `editContentlet()` function from UVE library
135+
- **State Management**: Uses `getUVEState()` to detect current mode
136+
137+
### Setup Requirements
138+
1. UVE script must be loaded from DotCMS host
139+
2. Content must have proper data attributes for UVE identification
140+
3. Edit controllers must be attached to editable content elements
141+
142+
## Error Handling
143+
144+
The application maps DotCMS SDK exceptions to Symfony HTTP exceptions:
145+
- `HttpException` codes 400, 401, 404, 500, 503 map to corresponding Symfony exceptions
146+
- `ResponseException` maps to `ServiceUnavailableHttpException`
147+
- All unmapped exceptions default to `ServiceUnavailableHttpException`
148+
149+
## Development Notes
150+
151+
- Uses Symfony 7.2 with PHP 8.2+ requirement
152+
- Includes Doctrine ORM, Twig, Stimulus, and other standard Symfony components
153+
- PHPUnit configured for testing with Symfony bridge
154+
- Webpack Encore handles frontend asset compilation and optimization
155+
- Stimulus controllers provide JavaScript functionality
156+
- UVE integration enables content editing capabilities
157+
- Development uses local PHP SDK when `composer.dev.json` is specified

‎examples/dotcms-symfony/README.md‎

Lines changed: 77 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -22,28 +22,37 @@ This integration allows you to:
2222

2323
```
2424
dotcms-symfony/
25-
├── assets/ # Frontend assets
26-
│ └── styles/ # CSS files
25+
├── assets/ # Frontend assets (managed by Webpack Encore)
26+
│ ├── app.js # Main JavaScript entry point
27+
│ ├── styles/ # CSS files
28+
│ └── controllers/ # Stimulus controllers
29+
│ └── dotcms_edit_controller.js # DotCMS UVE edit controller
2730
├── config/ # Symfony configuration
31+
│ ├── packages/
32+
│ │ └── webpack_encore.yaml # Webpack Encore configuration
2833
│ ├── routes.yaml # Route definitions including catch-all route
2934
│ └── services.yaml # Service definitions including DotCMS client
35+
├── public/
36+
│ └── build/ # Compiled assets (generated by Webpack Encore)
3037
├── src/
3138
│ ├── Controller/
3239
│ │ └── CatchAllController.php # Handles all DotCMS page requests
3340
│ ├── Service/
3441
│ │ └── DotCMSService.php # Wrapper for DotCMS PHP SDK
3542
│ └── Twig/
3643
│ └── DotCMSExtension.php # Twig extensions for DotCMS rendering
37-
└── templates/
38-
├── base.html.twig # Base template
39-
├── page.html.twig # Main page template
40-
└── dotcms/ # DotCMS-specific templates
41-
├── container.twig # Container template
42-
├── header.twig # Header template
43-
└── content-types/ # Content type templates
44-
├── banner.twig
45-
├── product.twig
46-
└── activity.twig
44+
├── templates/
45+
│ ├── base.html.twig # Base template
46+
│ ├── page.html.twig # Main page template
47+
│ └── dotcms/ # DotCMS-specific templates
48+
│ ├── container.twig # Container template
49+
│ ├── header.twig # Header template
50+
│ └── content-types/ # Content type templates
51+
│ ├── banner.twig
52+
│ ├── product.twig
53+
│ └── activity.twig
54+
├── package.json # Node.js dependencies and build scripts
55+
└── webpack.config.js # Webpack Encore configuration
4756
```
4857

4958
## Using SDK Utilities
@@ -96,19 +105,39 @@ symfony new my-dotcms-project
96105
cd my-dotcms-project
97106
```
98107

99-
2. Install the DotCMS PHP SDK:
108+
2. Install the DotCMS PHP SDK and required dependencies:
100109

101110
```bash
102111
composer require dotcms/php-sdk
112+
composer require symfony/webpack-encore-bundle
103113
```
104114

105-
3. Configure your DotCMS connection in `.env`:
115+
3. Install Node.js dependencies:
116+
117+
```bash
118+
npm install
119+
```
120+
121+
4. Configure your DotCMS connection in `.env`:
106122

107123
```
108124
DOTCMS_HOST=https://demo.dotcms.com
109125
DOTCMS_API_KEY=your-api-key-here
110126
```
111127

128+
5. Build frontend assets:
129+
130+
```bash
131+
# For development
132+
npm run dev
133+
134+
# For production
135+
npm run build
136+
137+
# For development with file watching
138+
npm run watch
139+
```
140+
112141
### Using Local SDK Development Setup
113142

114143
If you want to test the Symfony example with a local version of the PHP SDK (for development or testing new changes), you can use the `composer.dev.json` configuration:
@@ -519,7 +548,40 @@ To add support for a new content type:
519548

520549
### Styling
521550

522-
The project includes a basic grid system in `assets/styles/app.css` and uses [Pico.css](https://picocss.com/) for base styling. You can customize these styles or replace them with your preferred CSS framework.
551+
The project uses [Pico.css](https://picocss.com/) for base styling and includes a basic grid system. Assets are managed by Webpack Encore, allowing you to:
552+
553+
- Add CSS/SCSS files to the `assets/styles/` directory
554+
- Import styles in your JavaScript files
555+
- Use CSS frameworks like Bootstrap, Tailwind, etc.
556+
- Leverage Webpack's asset optimization features
557+
558+
To add new styles:
559+
560+
1. Create CSS/SCSS files in `assets/styles/`
561+
2. Import them in `assets/app.js`
562+
3. Run `npm run dev` to compile
563+
564+
### Frontend Architecture
565+
566+
The project uses Stimulus for JavaScript functionality:
567+
568+
- **Stimulus Controllers**: Located in `assets/controllers/`
569+
- **DotCMS UVE Integration**: The `dotcms_edit_controller.js` provides content editing capabilities
570+
- **Build Process**: Webpack Encore handles asset compilation and optimization
571+
572+
### UVE (Universal Visual Editor) Integration
573+
574+
The project includes DotCMS UVE integration for content editing:
575+
576+
- **Edit Mode**: Content editors can edit contentlets directly in the frontend
577+
- **Stimulus Controller**: `dotcms_edit_controller.js` handles the edit functionality
578+
- **Dependencies**: Uses `@dotcms/uve` and `@dotcms/types` packages
579+
- **Automatic Detection**: Edit buttons only appear when in UVE edit mode
580+
581+
The UVE integration allows content editors to:
582+
- Edit contentlets directly on the page
583+
- See changes in real-time
584+
- Use DotCMS's visual editing interface
523585

524586
## Resources
525587

‎examples/dotcms-symfony/assets/bootstrap.js‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,10 @@
1-
import { startStimulusApp } from '@symfony/stimulus-bundle';
1+
import { startStimulusApp } from '@symfony/stimulus-bridge';
22

3-
const app = startStimulusApp();
3+
// Registers Stimulus controllers from controllers.json and in the controllers/ directory
4+
export const app = startStimulusApp(require.context(
5+
'@symfony/stimulus-bridge/lazy-controller-loader!./controllers',
6+
true,
7+
/\.[jt]sx?$/
8+
));
49
// register any custom, 3rd party controllers here
510
// app.register('some_controller_name', SomeImportedController);

‎examples/dotcms-symfony/assets/controllers/csrf_protection_controller.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
const nameCheck = /^[-_a-zA-Z0-9]{4,22}$/;
2-
const tokenCheck = /^[-_\/+a-zA-Z0-9]{24,}$/;
2+
const tokenCheck = /^[-_/+a-zA-Z0-9]{24,}$/;
33

44
// Generate and double-submit a CSRF token in a form field and a cookie, as defined by Symfony's SameOriginCsrfTokenManager
55
document.addEventListener('submit', function (event) {

‎examples/dotcms-symfony/assets/controllers/dotcms_edit_controller.js‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
import { Controller } from '@hotwired/stimulus';
2+
import { getUVEState, editContentlet } from '@dotcms/uve';
3+
import { UVE_MODE } from "@dotcms/types";
4+
5+
6+
export default class extends Controller {
7+
static values = {
8+
contentlet: Object
9+
}
10+
11+
connect() {
12+
const isEditing = getUVEState()?.mode === UVE_MODE.EDIT;
13+
14+
if (!isEditing) {
15+
this.element.style.display = 'none';
16+
}
17+
}
18+
19+
edit() {
20+
editContentlet(this.contentletValue);
21+
}
22+
}

‎examples/dotcms-symfony/assets/vendor/@hotwired/stimulus/stimulus.index.js‎

Lines changed: 7 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎examples/dotcms-symfony/assets/vendor/@hotwired/turbo/turbo.index.js‎

Lines changed: 30 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎examples/dotcms-symfony/assets/vendor/installed.php‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
<?php return array (
2+
'@hotwired/stimulus' =>
3+
array (
4+
'version' => '3.2.2',
5+
'dependencies' =>
6+
array (
7+
),
8+
'extraFiles' =>
9+
array (
10+
),
11+
),
12+
'@hotwired/turbo' =>
13+
array (
14+
'version' => '7.3.0',
15+
'dependencies' =>
16+
array (
17+
),
18+
'extraFiles' =>
19+
array (
20+
),
21+
),
22+
);

0 commit comments

Comments
 (0)