README

Enterprise-grade DITA XML authoring and publishing framework for Drupal 10/11.

DESCRIPTION

The DITA CCMS module provides comprehensive DITA (Darwin Information Typing Architecture) content management capabilities for Drupal, enabling technical documentation teams to author, manage, and publish structured content using industry-standard DITA XML format.

This module leverages existing Drupal contrib modules (ECK, Feeds, Workflows) rather than reinventing functionality, following the Drupal principle of "There's a module for that!"

REQUIREMENTS

Drupal 10.3 or 11
PHP 8.1+
Required modules:
- Entity Construction Kit (ECK) ^2.0
- Content Moderation
- Workflows
- Feeds ^3.0
- REST
- Serialization
- Views
- Views Data Export
- Field Group

INSTALLATION

Using Composer (Recommended)

composer require drupal/dita_ccms
drush en dita_ccms -y

Manual Installation

Download and extract to modules/custom/
Enable the module:
```
drush en dita_ccms -y
```
Configure at /admin/config/content/dita-ccms

CONFIGURATION

Initial Setup

Configure DITA Topic Types
- Navigate to /admin/structure/dita-topic-types
- Default types: Topic, Task, Concept, Reference
- Add custom topic types as needed
Set Up Workflows
- Navigate to /admin/config/workflow/workflows/manage/dita_editorial
- Configure states: Draft, Review, Published, Archived
- Assign permissions to roles
Configure Import/Export
- Navigate to /admin/config/content/dita-ccms/import-export
- Set default export formats
- Configure DITA-OT integration (if available)
API Configuration
- Enable REST endpoints at /admin/config/services/rest
- Configure authentication methods
- Set rate limiting (recommended)

FEATURES

Content Management

DITA Topic Management: Create and manage DITA topics using ECK entities
DITA Map Support: Organize topics into maps for structured documentation
Topic Types: Support for standard DITA topic types (concept, task, reference, topic)
Metadata Management: Comprehensive metadata fields (audience, keywords, status)

Import/Export

XML Import: Import existing DITA XML content via Feeds module
Multiple Export Formats: Export to DITA XML, HTML, PDF, EPUB, Markdown
Batch Processing: Queue-based processing for large documentation sets
DITA-OT Integration: Optional integration with DITA Open Toolkit

Workflow & Publishing

Editorial Workflow: Content moderation with configurable states
Publishing Queue: Asynchronous publishing with progress tracking
Version Control: Track content changes and revisions
Access Control: Granular permissions for viewing, editing, and publishing

API & Integration

RESTful API: Full CRUD operations via REST endpoints
GraphQL Support: Query DITA content via GraphQL
Event System: Extensible event-driven architecture
AI Integration: Optional AI-powered content generation (submodule)

USAGE

Creating DITA Topics

Navigate to /admin/content/dita-topics
Click "Add DITA Topic"
Select topic type (concept, task, reference, or generic topic)
Fill in required fields:
- Title
- DITA ID (unique identifier)
- Body content (DITA XML or rich text)
- Metadata (audience, keywords, etc.)
Save as draft or submit for review

Importing DITA Content

Navigate to /admin/content/dita-ccms/import
Upload DITA XML file or ZIP archive
Map DITA elements to Drupal fields
Run import (processed via queue for large files)

Exporting DITA Content

Via UI:

Navigate to topic or map
Click "Export" action
Select format (DITA, HTML, PDF, etc.)
Download generated file

Via API:

# Export single topic
GET /api/dita/topic/{id}/export?format=html

# Export entire map
GET /api/dita/map/{id}/export?format=pdf&include_topics=true

Publishing Workflow

Author creates/edits topic (Draft state)
Submit for review
Reviewer approves/requests changes
Approved content moves to Published state
Published content available for export/API access

API DOCUMENTATION

REST Endpoints

Topics

GET /api/dita/topics - List all topics
GET /api/dita/topics/{id} - Get specific topic
POST /api/dita/topics - Create new topic
PATCH /api/dita/topics/{id} - Update topic
DELETE /api/dita/topics/{id} - Delete topic

Maps

GET /api/dita/maps - List all maps
GET /api/dita/maps/{id} - Get specific map
POST /api/dita/maps - Create new map
PATCH /api/dita/maps/{id} - Update map
DELETE /api/dita/maps/{id} - Delete map

Export

GET /api/dita/export/topic/{id} - Export single topic
GET /api/dita/export/map/{id} - Export map with topics

GraphQL Queries

# Get all topics
query {
  ditaTopics(limit: 10, offset: 0) {
    items {
      id
      title
      ditaId
      topicType
      status
    }
    total
  }
}

# Get specific topic
query {
  ditaTopic(id: "123") {
    id
    title
    body
    metadata {
      audience
      keywords
    }
  }
}

HOOKS

The module provides several hooks for extending functionality:

/**
 * Alter DITA topic before save.
 */
function hook_dita_topic_presave(\Drupal\dita_ccms\Entity\DitaTopic $topic) {
  // Custom logic
}

/**
 * Alter export data before processing.
 */
function hook_dita_export_alter(array &$data, string $format) {
  // Custom export modifications
}

/**
 * React to DITA import completion.
 */
function hook_dita_import_complete(array $imported_items) {
  // Post-import processing
}

THEMING

Template Files

dita-topic.html.twig - Single topic display
dita-topic-list.html.twig - Topic listing
dita-export-preview.html.twig - Export preview

Theme Suggestions

dita-topic--{topic-type}.html.twig
dita-topic--{view-mode}.html.twig
dita-topic--{topic-type}--{view-mode}.html.twig

TESTING

Running Tests

# Unit tests
phpunit web/modules/custom/dita_ccms/tests/src/Unit

# Kernel tests
phpunit web/modules/custom/dita_ccms/tests/src/Kernel

# Functional tests
phpunit web/modules/custom/dita_ccms/tests/src/Functional

# All tests
phpunit web/modules/custom/dita_ccms/tests

Test Coverage

Unit tests: Service classes, helpers, utilities
Kernel tests: Entity operations, API endpoints
Functional tests: User workflows, import/export

TROUBLESHOOTING

Common Issues

Import fails with large files
- Increase PHP memory limit
- Enable queue processing via cron
- Split large documentation sets
Export timeout
- Use queue-based export for large maps
- Increase PHP execution time
- Enable background processing
Permission denied errors
- Check file system permissions
- Verify user roles and permissions
- Check REST endpoint configuration

PERFORMANCE OPTIMIZATION

Caching

Enable render caching for topic displays
Use CDN for exported static files
Configure Redis/Memcached for queue processing

Database

Add indexes for frequently queried fields
Use database query optimization
Enable query caching

Queue Processing

Configure cron for regular queue processing
Use Drush for batch operations
Monitor queue performance

SECURITY CONSIDERATIONS

Validate all XML input to prevent XXE attacks
Sanitize HTML output from DITA transformations
Use proper access controls for sensitive documentation
Enable HTTPS for API endpoints
Implement rate limiting for API access
Regular security updates for dependencies

CONTRIBUTING

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup

# Clone repository
git clone https://github.com/your-org/dita_ccms.git

# Install dependencies
composer install

# Run coding standards
vendor/bin/phpcs --standard=Drupal,DrupalPractice web/modules/custom/dita_ccms

# Fix coding standards
vendor/bin/phpcbf --standard=Drupal,DrupalPractice web/modules/custom/dita_ccms

MAINTAINERS

Your Name - your.email@example.com
Project URL: https://www.drupal.org/project/dita_ccms
Issue Queue: https://www.drupal.org/project/issues/dita_ccms

LICENSE

This project is licensed under the GNU General Public License v2.0 or later.

CREDITS

This module leverages the following excellent Drupal contrib modules:

Entity Construction Kit (ECK) - For flexible entity management
Feeds - For robust import capabilities
Workflows - For editorial workflow management
Views Data Export - For data export functionality

Special thanks to the Drupal community and all contributors.

bluefly / dita_ccms

Maintainers

Details