# Guide d'Utilisation - EUROMA CMS

## Table des Matieres

1. [Vue d'Ensemble](#vue-densemble)
2. [Architecture du Projet](#architecture-du-projet)
3. [Templates](#templates)
4. [Pages](#pages)
5. [Sections](#sections)
6. [Menus](#menus)
7. [Parametres (Settings)](#parametres-settings)
8. [Langues et Traductions](#langues-et-traductions)
9. [Mots-cles (Keywords)](#mots-cles-keywords)
10. [Configuration URLs](#configuration-urls)
11. [Configuration Django](#configuration-django)
12. [Template Tags Disponibles](#template-tags-disponibles)
13. [Drapeaux de Pays](#drapeaux-de-pays)
14. [Administration](#administration)

---

## Vue d'Ensemble

EUROMA CMS est une application Django modulaire permettant de gerer des pages, sections, menus et parametres de maniere dynamique. Le systeme supporte les traductions multilingues et utilise une architecture basee sur les templates.

### Applications Principales

| Application | Description |
|-------------|-------------|
| `cms` | Gestion des templates, pages, sections, menus, parametres |
| `traduction` | Systeme de traduction multilingue |
| `config` | Configuration globale, icones, pays |
| `apps/core` | Vues principales et mixins |
| `apps/news` | Actualites et evenements |
| `apps/universities` | Gestion des universites |
| `apps/research` | Domaines de recherche |
| `apps/team` | Membres de l'equipe |
| `apps/program` | Programme et bourses |
| `apps/contact` | Formulaire de contact |

---

## Architecture du Projet

```
greentech/
├── cms/                          # Application CMS principale
│   ├── models.py                 # Modeles: Template, Page, Section, Menu...
│   ├── admin.py                  # Configuration admin
│   ├── views.py                  # Vues publiques et HTMX
│   ├── urls.py                   # Routes CMS
│   ├── context_processors.py     # Variables globales
│   ├── templatetags/
│   │   └── cms_tags.py           # Tags: get_menu, get_setting, render_section
│   ├── templates/
│   │   ├── admin/cms/            # Templates admin personnalises
│   │   └── cms/
│   │       └── master/           # Template par defaut
│   │           ├── base.html
│   │           ├── index.html
│   │           ├── sections/
│   │           ├── partials/
│   │           └── components/
│   └── static/cms/               # Fichiers statiques par template
│
├── traduction/                   # Systeme de traduction
│   ├── models.py                 # Language, Dictionnaire
│   ├── registry.py               # Champs traduisibles par modele
│   ├── middleware.py             # Detection de langue
│   └── templatetags/
│       └── traduction_tags.py    # Tags de traduction
│
├── config/                       # Configuration globale
│   ├── models.py                 # Icon, Country, mixins
│   └── templatetags/
│       └── config_tags.py        # country_flag, flag_img
│
├── templates/                    # Templates globaux
│   ├── base.html                 # Template racine
│   └── components/               # Composants reutilisables
│
└── static/                       # Fichiers statiques globaux
```

---

## Templates

### Concept

Un **Template** represente un theme ou une mise en page specifique. Chaque template possede sa propre structure de fichiers.

### Creation d'un Template

1. **Dans l'admin** : CMS → Templates → Ajouter
2. Remplir les champs :
   - **Nom** : Nom affiche (ex: "Theme Principal")
   - **Slug** : Identifiant unique (auto-genere)
   - **Repertoire** : Nom du dossier (ex: `master`, `landing`)
   - **Fichier de base** : Fichier principal (defaut: `index.html`)

### Structure Creee Automatiquement

A la creation, le systeme genere automatiquement :

```
cms/templates/cms/{template_dir}/
├── base.html           # Template de base (extends base.html global)
├── index.html          # Page principale
├── sections/           # Dossier des sections
│   └── section-title.html
└── partials/           # Composants reutilisables

cms/static/cms/{template_dir}/
├── css/
│   └── style.css       # Styles specifiques
└── js/
    └── main.js         # Scripts specifiques
```

### Fichiers Supplementaires (TemplateFile)

Pour creer des variantes de page (autre.html, contact.html) :

1. Dans l'admin du Template, section "Fichiers de template"
2. Ajouter un fichier avec nom et description
3. Le fichier herite automatiquement de `base.html` du template

### Heritage des Templates

```
templates/base.html                    # Base globale
    └── cms/{template}/base.html       # Base du template
        ├── cms/{template}/index.html  # Page principale
        └── cms/{template}/autre.html  # Variante
```

---

## Pages

### Concept

Une **Page** est une entite de contenu qui utilise un Template et contient des Sections ordonnees.

### Creation d'une Page

1. **Dans l'admin** : CMS → Pages → Ajouter
2. Configurer :
   - **Nom** : Nom interne
   - **Slug** : URL de la page (auto-genere)
   - **Template** : Theme a utiliser
   - **Fichier de template** : Variante (optionnel, defaut: index.html)
   - **Titre** : Titre affiche (traduisible)
   - **Description** : Meta description (traduisible)
   - **Mots-cles** : Separes par virgules (cree automatiquement les Keywords)
   - **Active** : Visible sur le site
   - **Page d'accueil** : Une seule possible

### Ajouter des Sections

Dans le formulaire de la Page :
1. Section "Sections de la page"
2. Selectionner une Section existante
3. Definir l'ordre
4. **Bouton "Reordonner les sections"** : Interface drag-drop

### URLs des Pages

```python
# Page d'accueil (is_homepage=True)
/                           # cms:home

# Pages par slug
/page/about.html            # cms:page (slug='about')
/page/contact.html          # cms:page (slug='contact')
```

---

## Sections

### Concept

Une **Section** est un bloc de contenu reutilisable. Chaque section correspond a un fichier HTML dans le dossier `sections/` du template.

### Creation d'une Section

1. **Dans l'admin** : CMS → Sections → Ajouter
2. Configurer :
   - **Nom** : Identifiant (ex: "Hero", "Features")
   - **Template** : Template parent
   - **Fichier** : Nom sans extension (ex: `hero` → `hero.html`)
   - **Titre** : Titre affiche (traduisible)
   - **Description** : Sous-titre (traduisible)
   - **Image** : Image de fond optionnelle

### Fichier de Section

Le fichier est cree automatiquement dans `cms/templates/cms/{template}/sections/{file}.html` :

```django
{% load static %}
{# Section: Hero #}

<section class="py-16">
    <div class="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
        {% include 'cms/master/partials/section-title.html' %}

        {# Contenu de la section #}
        <div>
            <!-- Votre contenu ici -->
        </div>
    </div>
</section>
```

### Variables Disponibles dans une Section

```django
{{ section.title }}         # Titre traduit
{{ section.description }}   # Description traduite
{{ section.image.url }}     # URL de l'image
{{ section.name }}          # Nom interne
{{ section.file }}          # Nom du fichier
```

---

## Menus

### Concept

Un **Menu** est une collection d'elements de navigation. Les **MenuItems** peuvent avoir des sous-elements (dropdowns).

### Creation d'un Menu

1. **Dans l'admin** : CMS → Menus → Ajouter
2. Configurer :
   - **Nom** : Nom affiche (ex: "Menu Principal")
   - **Slug** : Identifiant (ex: `front-menu`, `footer`)
   - **Emplacement** : header, footer, sidebar, topbar
   - **Actif** : Visible

### Types d'URL pour les MenuItems

| Type | Description | Exemple |
|------|-------------|---------|
| **Interne** | URL nommee Django | `core:home`, `news:list` |
| **Externe** | URL complete | `https://example.com` |
| **Page CMS** | Lien vers une Page | Selectionner une page |

### Structure Hierarchique

Les MenuItems peuvent avoir un parent pour creer des sous-menus :

```
Menu Principal (front-menu)
├── Accueil                    → core:home
├── Le Programme              → program:about
│   ├── Presentation          → program:about
│   ├── Comment postuler?     → program:apply
│   └── La Bourse             → program:scholarship
├── Universites               → universities:list
└── Contact                   → contact:contact
```

### Reordonner les Elements

1. Dans la liste des Menus, cliquer sur "Ordonner"
2. Glisser-deposer les elements
3. Sauvegarde automatique

### Utilisation dans les Templates

```django
{% load cms_tags %}

{# Recuperer le menu #}
{% get_menu 'front-menu' as nav %}

{# Afficher les elements #}
{% for item in nav.get_root_items %}
    <a href="{{ item.get_url }}">{{ item.title }}</a>

    {% if item.has_children %}
        {% for child in item.get_children %}
            <a href="{{ child.get_url }}">{{ child.title }}</a>
        {% endfor %}
    {% endif %}
{% endfor %}
```

---

## Parametres (Settings)

### Concept

Les **Settings** sont des valeurs cle-valeur configurables (email, telephone, logo, etc.).

### Types de Parametres (SettingType)

| Type | Usage | Format |
|------|-------|--------|
| Texte | Valeur simple | - |
| Email | Adresse email | `<a href="mailto:{value}">{value}</a>` |
| Telephone | Numero | `<a href="tel:{value}">{value}</a>` |
| URL | Lien externe | `<a href="{value}" target="_blank">{value}</a>` |
| Devise EUR | Montant | `{value} €` |
| Devise USD | Montant | `${value}` |
| Pourcentage | Nombre | `{value}%` |
| Image | Fichier image | - |
| Logo | Image logo | `<img src="{value}" class="logo" />` |
| Favicon | Icone | `<link rel="icon" href="{value}" />` |

### Creation d'un Parametre

1. **Dans l'admin** : CMS → Parametres → Ajouter
2. Configurer :
   - **Type** : Type de formatage
   - **Nom** : Nom affiche
   - **Slug** : Cle d'acces (ex: `site_email`)
   - **Valeur** : Texte OU
   - **Image** : Fichier image

### Utilisation dans les Templates

```django
{% load cms_tags %}

{# Valeur formatee #}
{% get_setting 'site_email' as email %}
{{ email }}  {# Affiche: <a href="mailto:...">...</a> #}

{# Valeur brute #}
{% setting_value 'site_email' as raw_email %}
{{ raw_email }}  {# Affiche: contact@example.com #}

{# Image #}
{% setting_image 'logo' 'logo-class' 'Alt text' %}
```

---

## Langues et Traductions

### Configuration des Langues

1. **Dans l'admin** : Traduction → Langues
2. Ajouter une langue :
   - **Code** : Code ISO (fr, en, de)
   - **Nom** : Francais, English, Deutsch
   - **Nom natif** : Francais, English, Deutsch
   - **Code drapeau** : Code pays pour le drapeau (fr, gb, de)
   - **Par defaut** : Une seule langue par defaut
   - **Ordre** : Ordre d'affichage

### Champs Traduisibles

Les champs traduisibles sont definis dans `traduction/registry.py` :

```python
TRANSLATABLE_FIELDS = {
    'cms.section': ['title', 'description'],
    'cms.page': ['title', 'description'],
    'cms.menuitem': ['title'],
    'cms.setting': ['value'],
    'news.newsarticle': ['title', 'excerpt', 'content'],
    'universities.university': ['name', 'description', 'city'],
    # ...
}
```

### Interface de Traduction

Dans le formulaire d'edition d'un objet traduisible :
1. Onglets de langue en haut du formulaire
2. Saisir la traduction pour chaque langue
3. Sauvegarder

### Selecteur de Langue Frontend

Le selecteur de langue est integre dans le topbar :
- Affiche les drapeaux des langues actives
- Parametre `?lang=xx` pour changer de langue
- La langue est stockee en session

### Utilisation dans les Templates

```django
{% load traduction_tags %}

{# Langue courante #}
{% current_language as lang %}
{{ lang.code }}  {# fr #}

{# Toutes les langues #}
{% get_languages as languages %}
{% for lang in languages %}
    <a href="?lang={{ lang.code }}">{{ lang.name }}</a>
{% endfor %}

{# Traduction d'un champ #}
{{ article.title }}  {# Automatique si prefetch #}
{{ article|translate:'title' }}  {# Manuel #}
```

---

## Mots-cles (Keywords)

### Concept

Les **Keywords** sont des mots-cles polymorphiques pouvant etre associes a n'importe quel objet (Page, Article, etc.).

### Fonctionnement

1. Dans le champ `keywords_text` d'une Page, saisir : `django, python, cms`
2. A la sauvegarde, le systeme :
   - Cree les Keywords s'ils n'existent pas
   - Cree les KeywordAssignments
   - Supprime les anciens non presents

### Utilisation dans les Templates

```django
{% load cms_tags %}

{# Recuperer les mots-cles d'un objet #}
{% get_keywords page as keywords %}
{% for keyword in keywords %}
    <span class="tag">{{ keyword.name }}</span>
{% endfor %}

{# Afficher les mots-cles avec style #}
{% render_keywords page 'tag-list' %}

{# Objets ayant un mot-cle #}
{% get_objects_with_keyword 'django' as django_objects %}
```

---

## Configuration URLs

### URLs Principales

```python
# greentech/urls.py
urlpatterns = [
    path('admin/', admin.site.urls),
    path('cms/', include('cms.urls')),           # CMS
    path('', include('apps.core.urls')),         # Core (home)
    path('news/', include('apps.news.urls')),    # Actualites
    path('universities/', include('apps.universities.urls')),
    path('research/', include('apps.research.urls')),
    path('team/', include('apps.team.urls')),
    path('program/', include('apps.program.urls')),
    path('contact/', include('apps.contact.urls')),
]
```

### URLs CMS

```python
# cms/urls.py
urlpatterns = [
    # Pages publiques
    path('', views.home_view, name='home'),
    path('page/<slug:slug>.html', views.page_view, name='page'),

    # Admin reordonnancement
    path('admin/page/<int:page_id>/reorder/', ...),
    path('admin/menu/<int:menu_id>/reorder/', ...),

    # Endpoints HTMX
    path('admin/page/<int:page_id>/reorder-sections/', ...),
    path('admin/menu/<int:menu_id>/reorder-items/', ...),
]
```

---

## Configuration Django

### Settings Essentiels

```python
# greentech/settings.py

INSTALLED_APPS = [
    # Django
    'django.contrib.admin',
    'django.contrib.auth',
    ...

    # Third-party
    'django_htmx',

    # Project
    'cms',
    'traduction',
    'config',
    'image_factory',
    'history',
    'apps.core',
    'apps.news',
    'apps.universities',
    'apps.research',
    'apps.team',
    'apps.program',
    'apps.contact',
]

MIDDLEWARE = [
    ...
    'django_htmx.middleware.HtmxMiddleware',
    'traduction.middleware.LanguageMiddleware',
]

TEMPLATES = [
    {
        'OPTIONS': {
            'context_processors': [
                ...
                'config.context_processors.site_config',
                'cms.context_processors.cms_context',
                'traduction.context_processors.language_context',
            ],
        },
    },
]
```

### Variables de Contexte Globales

Les context processors ajoutent automatiquement :

```python
# Disponibles dans tous les templates
{{ site_config }}           # Configuration du site
{{ current_language }}      # Objet Language courant
{{ current_language_code }} # Code langue (fr, en, de)
{{ header_menu }}           # Menu header (si configure)
{{ footer_menu }}           # Menu footer (si configure)
```

---

## Template Tags Disponibles

### CMS Tags (`{% load cms_tags %}`)

```django
{# Settings #}
{% get_setting 'slug' as var %}
{% setting_value 'slug' as var %}
{% setting_image 'slug' 'class' 'alt' %}
{% setting_formatted 'slug' pattern='<b>{value}</b>' %}

{# Menus #}
{% get_menu 'slug' as menu %}
{% render_menu menu 'nav-class' 'item-class' 'link-class' %}
{% menu_item_class item 'active' 'has-dropdown' %}
{% is_active_menu_item item as is_active %}

{# Pages & Sections #}
{% get_page 'slug' as page %}
{% get_homepage as home %}
{% render_section section 'extra-class' %}
{% include_section section %}

{# Keywords #}
{% get_keywords object as keywords %}
{% render_keywords object 'class' %}
{% get_objects_with_keyword 'name' as objects %}

{# Formatage #}
{% format_phone '+33123456789' %}
{% format_email 'contact@example.com' %}
{% format_url 'https://example.com' 'Texte' %}
{% format_currency '1500' currency='EUR' %}
{% format_address 'Adresse multi-lignes' %}
{% format_social 'twitter' 'username' %}
```

### Traduction Tags (`{% load traduction_tags %}`)

```django
{# Langue #}
{% current_language as lang %}
{% current_language_code as code %}
{% get_languages as languages %}
{% get_default_language as default %}

{# Traductions #}
{{ object|translate:'field' }}
{{ object|translate_lang:'field:en' }}
{% get_translation object 'field' as value %}
{% trans object 'field' %}

{# Selecteur #}
{% language_selector %}
```

### Config Tags (`{% load config_tags %}`)

```django
{# Drapeaux #}
{{ 'fr'|country_flag }}
{{ 'de'|country_flag:'w40' }}
{% flag_img 'jp' 'w80' 'w-8 h-6 rounded' %}
{% flag_url 'us' as url %}
```

---

## Drapeaux de Pays

### Utilisation

Le filtre `country_flag` genere une image de drapeau via flagcdn.com :

```django
{% load config_tags %}

{{ 'fr'|country_flag }}
{# <img src="https://flagcdn.com/w20/fr.png" alt="France" class="w-4 h-3 inline-block" /> #}

{{ 'gb'|country_flag:'w40' }}
{# Taille 40px #}
```

### Tailles Disponibles

`w20`, `w40`, `w80`, `w160`, `w320`, `w640`, `w1280`, `w2560`

### Codes Speciaux

- `gb` : Royaume-Uni (pas `uk` ou `en`)
- `eu` : Union europeenne
- `un` : Nations Unies

---

## Administration

### Acces Admin

URL : `/admin/`

### Sections CMS

| Section | Description |
|---------|-------------|
| Templates | Gestion des themes |
| Pages | Pages du site |
| Sections | Blocs de contenu |
| Menus | Navigation |
| Parametres | Valeurs cle-valeur |
| Mots-cles | Tags polymorphiques |

### Fonctionnalites Admin

- **Reordonnancement** : Drag-drop pour sections et menus
- **Traductions** : Onglets de langue dans les formulaires
- **Autocomplete** : Champs relationnels avec recherche
- **Prepopulated** : Slugs generes automatiquement
- **Inline** : Edition des relations directement

### Raccourcis

- **Bouton "Ordonner"** : Dans la liste des Pages et Menus
- **Bouton "Reordonner les sections"** : Dans le formulaire Page
- **Indicateurs** : Fichiers existants (✓) ou manquants (✗)

---

## Commandes Utiles

```bash
# Migrations
python manage.py makemigrations
python manage.py migrate

# Fixtures
python manage.py loaddata setting_types  # Types de parametres
python manage.py loaddata icons          # Icones
python manage.py loaddata countries      # Pays

# Traductions
python manage.py generate_translations   # Generer dictionnaire JS

# Collectstatic
python manage.py collectstatic

# Serveur de developpement
python manage.py runserver
```

---

## Bonnes Pratiques

### Templates

1. Toujours heriter de `base.html` du template
2. Utiliser les blocs definis (`page_title`, `page_content`, etc.)
3. Placer les composants reutilisables dans `partials/`

### Sections

1. Une section = un fichier HTML
2. Utiliser `section.title` et `section.description` pour les titres
3. Garder les sections modulaires et reutilisables

### Menus

1. Utiliser des slugs descriptifs (`front-menu`, `footer-links`)
2. Limiter la profondeur a 2 niveaux
3. Utiliser les icones pour ameliorer l'UX

### Traductions

1. Toujours definir la langue par defaut en premier
2. Utiliser les codes pays corrects pour les drapeaux
3. Prefetcher les traductions dans les vues pour les performances

---

## Support

Pour toute question ou probleme :
- Consulter ce guide
- Verifier les logs Django
- Contacter l'equipe de developpement