Skip to content

Commit 7666d71

Browse files
fmontesfmontes
committed
feat(docs): Update CLAUDE.md and README.md with UVE integration details and frontend asset management
1 parent 70ca786 commit 7666d71

2 files changed

Lines changed: 120 additions & 18 deletions

File tree

‎examples/dotcms-symfony/CLAUDE.md‎

Lines changed: 43 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,8 @@ This is a Symfony 7.2 application that demonstrates integration with DotCMS usin
1313
- **Service layer**: `DotCMSService` wraps the DotCMS PHP SDK client for consistent API access
1414
- **Twig extensions**: `DotCMSExtension` provides template functions for rendering DotCMS content
1515
- **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
1618

1719
### DotCMS Integration Flow
1820
1. Symfony router matches catch-all route to `CatchAllController::show()`
@@ -60,8 +62,17 @@ php bin/console cache:clear
6062
# Install assets
6163
php bin/console assets:install
6264

63-
# Update importmap
64-
php bin/console importmap:install
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
6576
```
6677

6778
## Configuration
@@ -92,6 +103,13 @@ DotCMS client is configured in `config/services.yaml`:
92103
- `templates/page.html.twig`: Main page template with layout rendering
93104
- `templates/dotcms/container.twig`: Container and contentlet rendering with DotCMS attributes
94105
- `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
95113

96114
## Working with Content Types
97115

@@ -101,6 +119,26 @@ To add support for new content types:
101119
3. The `generateHtmlBasedOnProperty` function automatically finds and renders the template
102120
4. Falls back to SDK's `simpleContentHtml` if no template exists
103121

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+
104142
## Error Handling
105143

106144
The application maps DotCMS SDK exceptions to Symfony HTTP exceptions:
@@ -113,5 +151,7 @@ The application maps DotCMS SDK exceptions to Symfony HTTP exceptions:
113151
- Uses Symfony 7.2 with PHP 8.2+ requirement
114152
- Includes Doctrine ORM, Twig, Stimulus, and other standard Symfony components
115153
- PHPUnit configured for testing with Symfony bridge
116-
- Asset mapper handles frontend assets (CSS, JS)
154+
- Webpack Encore handles frontend asset compilation and optimization
155+
- Stimulus controllers provide JavaScript functionality
156+
- UVE integration enables content editing capabilities
117157
- 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

0 commit comments

Comments
 (0)