Skip to content

Commit 2de57b7

Browse files
reem-atalahreem-atalah
committed
separate user and developer docs
1 parent 8bc944d commit 2de57b7

File tree

3 files changed

+245
-174
lines changed

3 files changed

+245
-174
lines changed

‎README.md‎

Lines changed: 7 additions & 174 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66

77
The Content Creation Management (CCM) component is a Joomla extension that enables seamless content migration between different Content Management Systems (CMS) using a Common Content Model (CCM) and Model-Driven Engineering (MDE) format. This project facilitates migration between WordPress, Joomla and easily extending other CMS platforms.
88

9-
## 🚀 Features
9+
## Features
1010

1111
- **Multi-CMS Support**: Migrate content between WordPress, Joomla, and more.
1212
- **Standardized Format**: Uses CCM schema for consistent content representation.
@@ -15,182 +15,15 @@ The Content Creation Management (CCM) component is a Joomla extension that enabl
1515
- **Comprehensive Testing**: Full test coverage with Cypress (E2E) and PHPUnit (Unit).
1616
- **Simple Migration Feedback**: Displays a success message upon completion or a detailed failure message if migration fails.
1717

18-
## 📁 Project Structure
18+
## � Documentation
1919

20-
```
21-
gsoc25_api/
22-
├── src/administrator/components/com_ccm/ # Main component source
23-
│ ├── src/ # PHP classes
24-
│ │ ├── Controller/ # MVC Controllers
25-
│ │ ├── Model/ # Data models
26-
│ │ ├── View/ # View classes
27-
│ │ ├── Table/ # Database tables
28-
│ │ ├── Schema/ # CMS-CCM mapping
29-
│ │ └── Service/ # Service providers
30-
│ ├── tmpl/ # Template files
31-
│ ├── forms/ # Form definitions
32-
│ ├── language/ # Language files
33-
│ └── sql/ # Database schema
34-
├── tests/ # Test suites
35-
│ ├── System/ # Cypress E2E tests
36-
│ └── Unit/ # PHPUnit unit tests
37-
├── cypress.config.mjs # Cypress configuration
38-
├── phpunit.xml # PHPUnit configuration
39-
└── composer.json # PHP dependencies
40-
```
20+
This project includes comprehensive documentation for different audiences:
4121

42-
## 🛠️ Prerequisites
22+
### For Users
23+
📝 **[User Guide](docs/USER_GUIDE.md)** - Step-by-step instructions for installing and using the CCM component to migrate content between CMSs.
4324

44-
- **Joomla 4.0+** instance
45-
- **PHP 8.1+** with MySQLi extension
46-
- **MySQL/MariaDB** database
47-
- **Node.js 16+** and npm
48-
- **Composer** for PHP dependency management
49-
50-
## 📦 Installation & Setup
51-
52-
### 1. Clone the Repository
53-
54-
```bash
55-
git clone https://github.com/joomla-projects/gsoc25_api.git
56-
cd gsoc25_api
57-
```
58-
59-
### 2. Install Dependencies
60-
61-
**PHP Dependencies:**
62-
```bash
63-
composer install
64-
```
65-
66-
**Node.js Dependencies:**
67-
```bash
68-
npm install
69-
```
70-
71-
### 3. Joomla Installation
72-
73-
74-
1. Open your Joomla app
75-
2. Access the administrator panel
76-
3. Navigate to **System > Install > Extensions**
77-
4. Upload the zip file for the component
78-
79-
### 4. Database Setup
80-
81-
The component will automatically create the required database tables upon installation:
82-
- `#__ccm_cms` - Stores CMS configurations
83-
- Initiallizes the CMSs available for migration
84-
85-
## 🔧 Configuration
86-
87-
### Environment Setup for Testing
88-
89-
Update `cypress.config.mjs` with your environment details:
90-
91-
```javascript
92-
env: {
93-
sitename: 'Your Site Name',
94-
username: 'your-admin-username',
95-
password: 'your-admin-password',
96-
db_host: 'localhost',
97-
db_name: 'your_joomla_db',
98-
db_user: 'db_username',
99-
db_password: 'db_password',
100-
db_prefix: 'your_prefix_',
101-
}
102-
```
103-
104-
## 📝 How to Use the CCM Component
105-
106-
### 1. Editing a CMS
107-
108-
1. In Joomla Admin, go to **Components > CCM**
109-
2. Choose on of the CMSs
110-
3. Update in the CMS details:
111-
- **Name**: Descriptive name for the CMS
112-
- **URL**: Base URL of the source CMS
113-
- **Credentials**: API keys or authentication details
114-
115-
### 2. Configuring Content Mapping
116-
117-
1. Navigate in the component folder into **src > Schema > ${cms}-ccm**
118-
2. Map content types between a CMS and the CCM:
119-
- **Posts/Articles**: Map WordPress "posts" or Joomla "articles" to the CCM "ContentItem" type.
120-
- **Categories**: Align CMS-specific categories/taxonomies to the CCM "categories" property.
121-
- **Users/Authors**: Map user or author fields to the CCM "author" definition. *(future work)*
122-
- **Media**: Link media files (images, attachments) to the CCM "media" references. *(future work)*
123-
- **Custom Fields**: Extend the mapping for any custom fields or metadata your CMS uses. *(future work)*
124-
- **Example Mapping File** (`schema/wordpress-ccm.json`):
125-
```json
126-
{
127-
"ContentItem":
128-
[
129-
{
130-
"type": "posts",
131-
"properties": {
132-
"ID": "id",
133-
"post_title": "title",
134-
"post_content": "content",
135-
"post_status": "status",
136-
"post_date": "created",
137-
}
138-
}
139-
]
140-
}
141-
```
142-
143-
### 3. Running a Migration
144-
145-
1. Navigate to **Components > CCM > Migration**
146-
2. Select source and target CMS
147-
3. Choose content types to migrate:
148-
- Categories
149-
- Media files *(future work)*
150-
- Users *(future work)*
151-
- Articles/Posts
152-
153-
> **Note:** It is important to migrate the referenced items first for example we need to migrate **categories first**, as articles/posts reference categories. Migrating articles before their referenced categories exist may result in missing or incorrect category assignments. Always follow this order: **Categories → Media files → Users → Articles/Posts**.
154-
4. Click **Apply Migration**
155-
5. Monitor progress in real-time
156-
157-
### 4. Migration Process
158-
159-
The migration follows these steps:
160-
161-
1. **Content Extraction**: Retrieves content from source CMS via API
162-
2. **CCM Conversion**: Transforms content to CCM standard format
163-
3. **Target Conversion**: Adapts CCM format to target CMS structure
164-
4. **Import**: Creates content in target CMS
165-
166-
## 🧪 Testing
167-
168-
### Running Unit Tests (PHPUnit)
169-
170-
```bash
171-
# Run all unit tests
172-
./vendor/bin/phpunit
173-
174-
# Run specific test class
175-
./vendor/bin/phpunit tests/Unit/Ccm/Administrator/Model/CmsModelTest.php
176-
```
177-
178-
### Running E2E Tests (Cypress)
179-
180-
**Prerequisites for E2E Tests:**
181-
- Joomla instance running at `http://localhost:8000`
182-
- Admin user configured in cypress.config.mjs
183-
184-
```bash
185-
# Run all E2E tests
186-
npx cypress run
187-
188-
# Open Cypress GUI for interactive testing
189-
npx cypress open
190-
191-
# Run specific test file
192-
npx cypress run --spec "tests/System/integration/administrator/components/com_ccm/Migration.cy.js"
193-
```
25+
### For Developers
26+
🛠️ **[Developer Guide](docs/DEVELOPER_GUIDE.md)** - Technical documentation including project structure, development setup, testing procedures, and architectural details.
19427

19528
## 🚧 Future Work
19629

‎docs/DEVELOPER_GUIDE.md‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
# Developer Guide - Content Migration Between CMSs Using CCM & MDE
2+
3+
## 📋 Overview
4+
5+
This guide provides technical details for developers working on the Content Creation Management (CCM) component. The CCM component enables seamless content migration between different Content Management Systems (CMS) using a Common Content Model (CCM) and Model-Driven Engineering (MDE) format.
6+
7+
## 💻 Environment
8+
9+
This project is developed and tested on **Linux Ubuntu**.
10+
11+
## 📁 Project Structure
12+
13+
```
14+
gsoc25_api/
15+
├── src/administrator/components/com_ccm/ # Main component source
16+
│ ├── src/ # PHP classes
17+
│ │ ├── Controller/ # MVC Controllers
18+
│ │ ├── Model/ # Data models
19+
│ │ ├── View/ # View classes
20+
│ │ ├── Table/ # Database tables
21+
│ │ ├── Schema/ # CMS-CCM mapping
22+
│ │ └── Service/ # Service providers
23+
│ ├── tmpl/ # Template files
24+
│ ├── forms/ # Form definitions
25+
│ ├── language/ # Language files
26+
│ └── sql/ # Database schema
27+
├── tests/ # Test suites
28+
│ ├── System/ # Cypress E2E tests
29+
│ └── Unit/ # PHPUnit unit tests
30+
├── cypress.config.mjs # Cypress configuration
31+
├── phpunit.xml # PHPUnit configuration
32+
└── composer.json # PHP dependencies
33+
```
34+
35+
## 🛠️ Development Prerequisites
36+
37+
- **Joomla 4.0+** instance
38+
- **PHP 8.1+** with MySQLi extension
39+
- **MySQL/MariaDB** database
40+
- **Node.js 16+** and npm
41+
- **Composer** for PHP dependency management
42+
43+
## 📦 Development Setup
44+
45+
### 1. Clone the Repository
46+
47+
```bash
48+
git clone https://github.com/joomla-projects/gsoc25_api.git
49+
cd gsoc25_api
50+
```
51+
52+
### 2. Install Dependencies
53+
54+
**PHP Dependencies:**
55+
```bash
56+
composer install
57+
```
58+
59+
**Node.js Dependencies:**
60+
```bash
61+
npm install
62+
```
63+
64+
## 🔧 Configuration
65+
66+
### Environment Setup for Testing
67+
68+
Update `cypress.config.mjs` with your environment details:
69+
70+
```javascript
71+
env: {
72+
sitename: 'Your Site Name',
73+
username: 'your-admin-username',
74+
password: 'your-admin-password',
75+
db_host: 'localhost',
76+
db_name: 'your_joomla_db',
77+
db_user: 'db_username',
78+
db_password: 'db_password',
79+
db_prefix: 'your_prefix_',
80+
}
81+
```
82+
83+
## 🗺️ Content Mapping Configuration
84+
85+
### Configuring Content Mapping
86+
87+
1. Navigate in the component folder into **src > Schema > ${cms}-ccm**
88+
2. Map content types between a CMS and the CCM:
89+
- **Posts/Articles**: Map WordPress "posts" or Joomla "articles" to the CCM "ContentItem" type.
90+
- **Categories**: Align CMS-specific categories/taxonomies to the CCM "categories" property.
91+
- **Users/Authors**: Map user or author fields to the CCM "author" definition. *(future work)*
92+
- **Media**: Link media files (images, attachments) to the CCM "media" references. *(future work)*
93+
- **Custom Fields**: Extend the mapping for any custom fields or metadata your CMS uses. *(future work)*
94+
95+
### Example Mapping File
96+
97+
**Example Mapping File** (`schema/wordpress-ccm.json`):
98+
```json
99+
{
100+
"ContentItem":
101+
[
102+
{
103+
"type": "posts",
104+
"properties": {
105+
"ID": "id",
106+
"post_title": "title",
107+
"post_content": "content",
108+
"post_status": "status",
109+
"post_date": "created",
110+
}
111+
}
112+
]
113+
}
114+
```
115+
116+
## 🧪 Testing
117+
118+
### Running Unit Tests (PHPUnit)
119+
120+
```bash
121+
# Run all unit tests
122+
./vendor/bin/phpunit
123+
124+
# Run specific test class
125+
./vendor/bin/phpunit tests/Unit/Ccm/Administrator/Model/CmsModelTest.php
126+
```
127+
128+
### Running E2E Tests (Cypress)
129+
130+
**Prerequisites for E2E Tests:**
131+
- Joomla instance running at `http://localhost:8000`
132+
- Admin user configured in cypress.config.mjs
133+
134+
```bash
135+
# Run all E2E tests
136+
npx cypress run
137+
138+
# Open Cypress GUI for interactive testing
139+
npx cypress open
140+
141+
# Run specific test file
142+
npx cypress run --spec "tests/System/integration/administrator/components/com_ccm/Migration.cy.js"
143+
```
144+
145+
## 🧰 Development Notes
146+
147+
### Architecture
148+
149+
The CCM component follows Joomla's MVC (Model-View-Controller) architecture pattern:
150+
151+
- **Controllers**: Handle user requests and coordinate between models and views
152+
- **Models**: Manage data logic and database operations
153+
- **Views**: Present data to users through templates
154+
- **Tables**: Handle database table operations
155+
- **Schema**: Define mapping between different CMS formats and CCM
156+
- **Services**: Provide shared functionality across the component
157+
158+
### Migration Process Flow
159+
160+
1. **Content Extraction**: Retrieves content from source CMS via API
161+
2. **CCM Conversion**: Transforms content to CCM standard format
162+
3. **Target Conversion**: Adapts CCM format to target CMS structure
163+
4. **Import**: Creates content in target CMS
164+
165+
### Testing Strategy
166+
167+
- **Unit Tests**: Test individual classes and methods in isolation
168+
- **E2E Tests**: Test complete user workflows through the browser
169+
- **Comprehensive Coverage**: Both test suites provide full coverage of component functionality

0 commit comments

Comments
 (0)