Skip to content

Commit 842bc49

Browse files
reem-atalahreem-atalah
committed
Update the documentation for the midterm evaluation
1 parent df93cb3 commit 842bc49

File tree

1 file changed

+198
-1
lines changed

1 file changed

+198
-1
lines changed

‎README.md‎

Lines changed: 198 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,199 @@
11
# Content Migration Between CMSs Using CCM & MDE
2-
Google Summer of Code project by Reem Atalah
2+
3+
**Google Summer of Code 2025 Project by Reem Atalah**
4+
5+
## 📋 Overview
6+
7+
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.
8+
9+
## 🚀 Features
10+
11+
- **Multi-CMS Support**: Migrate content between WordPress, Joomla, and more.
12+
- **Standardized Format**: Uses CCM schema for consistent content representation.
13+
- **Metadata Preservation**: Maintains content metadata during migration.
14+
- **User-Friendly Interface**: Intuitive Joomla administrator interface.
15+
- **Comprehensive Testing**: Full test coverage with Cypress (E2E) and PHPUnit (Unit).
16+
- **Simple Migration Feedback**: Displays a success message upon completion or a detailed failure message if migration fails.
17+
18+
## 📁 Project Structure
19+
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+
```
41+
42+
## 🛠️ Prerequisites
43+
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+
```
194+
195+
## 🚧 Future Work
196+
197+
- **User and Media Migration**: Implement full support for migrating users/authors and media files between CMSs.
198+
- **Custom Field Mapping**: Enable advanced mapping for custom fields and metadata unique to each CMS.
199+
- **API Discovery**: Automate detection and configuration of available APIs for supported CMSs to simplify setup and integration.

0 commit comments

Comments
 (0)