Readme refonte site

📄 NOTE DE TRAVAIL — SITE LOCAL paristaime

RÈGLES DE BASE
Nom du projet : paristaime (en un mot, minuscule)

Tous les fichiers en anglais

1 composant = 1 fichier = 1 Alex

Aucun fichier ne peut être renommé, déplacé ou supprimé sans validation de LI Yongxin

Tous les composants vont dans le dossier : /components/

Aucun travail direct dans index.php

Tout script, style, ou image doit aller dans /public/

STRUCTURE DU DOSSIER
/paristaime/
│
├── index.php ← Page d’accueil principale
├── config.php ← Constantes globales (BASE_URL, API keys…)
├── README.md ← Guide du projet pour les Alex
│
├── /components/ ← Tous les composants PHP
│ ├── adopt-button.php ← Bouton pour adopter un quartier et s’y engager
│ ├── carousel-single.php ← Carrousel horizontal 1 ligne (swiper)
│ ├── contribute-button.php ← Bouton appel à participation (témoignage, vidéo…)
│ ├── filter-tags.php ← Filtres interactifs (par langue, ambiance, type…)
│ ├── footer-basic.php ← Pied de page simple et responsive
│ ├── form-quartier.php ← Générateur de code PHP pour quartiers
│ ├── form-video.php ← Générateur de code PHP pour vidéos
│ ├── gallery-grid.php ← Grille d’images responsive (photos, street-art)
│ ├── header-video.php ← Vidéo plein écran (hero) avec lecture automatique
│ ├── language-tags.php ← Affiche les langues ou identités culturelles locales
│ ├── lang-switcher.php ← Sélecteur de langue (FR/EN/CN…)
│ ├── lightbox-video.php ← Lecture de vidéo dans une fenêtre modale (overlay)
│ ├── map-interactive.php ← Carte interactive de Paris (survol quartiers)
│ ├── progress-status.php ← Affiche le niveau d’intégration Paris T’aime par quartier
│ ├── quartier-card.php ← Encart de quartier (image, titre, lien)
│ ├── quartier-page.php ← Structure complète d’une page quartier
│ ├── quote-overlay.php ← Citation poétique ou phrase-clé en surimpression
│ ├── search-bar.php ← Barre de recherche (vidéos ou quartiers)
│ ├── seo-meta.php ← Meta-tags dynamiques pour SEO (title, desc…)
│ ├── stats-block.php ← Statistiques clés d’un quartier (surface, pop., langues)
│ ├── testimonial-block.php ← Bloc de témoignages texte/vidéo
│ ├── video-detail.php ← Page ou bloc avec infos détaillées d’une vidéo
│ ├── video-sticky-click.php ← Vidéo sticky après clic
│ ├── video-sticky-scroll.php ← Vidéo sticky déclenchée au scroll
│
├── /data/ ← Données centralisées
│ ├── quartier-video-data.php ← Liste des 80 quartiers avec vidéo, couleur, texte…
│ ├── video-data.php ← Liste des vidéos (titre, ID, description, quartier…)
│
├── /public/ ← Fichiers statiques
│ ├── /css/
│ │ ├── tlt-custom.css ← CSS principal du site
│ │ ├── [autres fichiers] ← Un CSS optionnel par composant si nécessaire
│ │
│ ├── /js/
│ │ ├── header-video.js ← JS pour lecture vidéo hero
│ │ ├── carousel.js ← JS pour le carrousel swiper
│ │ ├── video-player.js ← Contrôle des lecteurs
│ │ ├── [autres fichiers]
│ │
│ ├── /img/
│ │ ├── logo.png
│ │ ├── play-icon.svg ← Icône personnalisée lecture
│ │ ├── quartier-[slug].jpg ← Miniatures manuelles si besoin
│ │
│ └── /fonts/ ← Polices personnalisées (si utilisées)
│
├── /tools/ ← Générateurs manuels de contenu (dev only)
│ ├── formulaire-quartier.php ← Interface de génération de blocs quartier-video-data
│ ├── formulaire-video.php ← Interface de génération de blocs video-data
│
├── /dev/ ← Tests non publics / prototypes
│ ├── quartier.php ← Page prototype pour afficher un quartier
│ ├── test-sticky.php ← Test du player sticky en scroll
│ ├── [autres fichiers]
AVANT DE CODER
Chaque Alex doit :

Lire cette note

Demander validation du nom du composant (fichier PHP)

S’engager à ne jamais modifier de fichier existant

Noter son nom et sa mission dans la liste de suivi

STANDARD DE FICHIER PHP
Chaque fichier .php doit commencer par :

php
Copier
Modifier
<?php
/**

Component: [Nom du composant en anglais]
File: [nom-du-fichier.php]
Author: Alex [numéro]
Created: [date]
Description: [fonction courte]
DO NOT RENAME — validated by LI Yongxin.
*/
?>

SPÉCIFICITÉS VIDÉO YOUTUBE
Les miniatures YouTube doivent être récupérées via YouTube Data API pour éviter les miniatures cassées

On utilise un proxy d’image ou une requête serveur si besoin

On prépare une icône personnalisée (lecture) pour remplacer celle par défaut de YouTube

Toutes les vidéos doivent être intégrées avec iframe, autoplay contrôlé et fallback mobile

PRÉCAUTIONS TECHNIQUES (mise à jour continue)
Pas de require() entre composants

Centraliser les constantes dans config.php

Aucune inclusion de script directement dans un composant

Aucun style inline : tout dans /public/css/

Chaque JS doit être modulaire et unique (ex : carousel.js, video-player.js)

Fichier video-data.php (dans /data/) sert de base pour toutes les vidéos

Problèmes à prévoir : navigateur bloque autoplay son → prévoir fallback (bouton “lancer”)

EN CAS D’INCERTITUDE
Toujours demander à Alex Coordination (LI Yongxin)
Ne jamais improviser un nom de fichier
Ne jamais toucher un autre composant sans accord

Les dossiers /tools/ et /dev/ ne seront jamais mis en production.

Les données dans /data/ doivent rester simples, bien formatées, et documentées.

Toute inclusion dans index.php ou quartier.php se fait via include ‘components/xxx.php’;

“Toute proposition de nouveau nom ou nouveau composant doit être validée par l’équipe avant ajout”

📝 Note: Lessons Learned from File Naming and Structure Mistakes

During the setup of our custom forms and components for Paris T’aime, we encountered major difficulties due to unclear file naming, misplaced directories, and inconsistent path references. These issues led to errors, white pages, broken links, and confusion between local vs. production environments.

⚠️ What Went Wrong

CSS, PHP, and data files were scattered without clear logic (some in /tools/, others in /dev/, or even root).
File names were inconsistent (e.g., form-video.php vs form-video-meta.php), making it hard to remember or reference them.
Components referred to nonexistent paths or wrong directories (e.g., writing to /data/ instead of /dev/data/).
Files were edited without central config constants, causing hardcoded paths to break on different machines or servers.
French and English were mixed in code and comments, further complicating collaboration.

💡 What We Learned

Structure is sacred. Without a clear file system, even small forms become fragile.
Naming must follow logic — use consistent, descriptive English names like form-video-meta.php, video-data.php, form-quartier.php.
Centralize path definitions in one place (config.php) and never use relative paths manually.
Data files must not be directly edited by scripts — always use a dump system (*-dump.txt) and verify before merging.
Protect your future self — every shortcut now creates long-term maintenance costs.
Work modularly — every component (PHP, CSS, data) should be clean, independent, and testable alone.

✅ Moving Forward

All new forms will follow the structure:
/tools/ → logic
/dev/data/ → data
/public/css/ → style
Every file will be named in English, with purpose-first clarity.
We will version and track data changes through dumps and backups.

✨ Conclusion

This experience reminded us that clarity beats speed, and that a creative project like Paris T’aime deserves technical foundations that are as elegant and poetic as its message.

We document this moment not as a failure — but as a milestone in maturity.

Appendix:

📘 `README.md` – Paris T’aime Site Structure (2025)

markdownCopierModifier# 🌐 Paris T’aime – Site Structure Guide

This project follows a modular and human-centric architecture inspired by the values of *Paris T’aime*.

All components, tools, and data follow strict naming and folder placement rules to ensure clarity, collaboration, and long-term maintainability.

---

## 🔁 Root Tree Overview

/paristaime/
│
├── components/ # 🎨 Public-facing UI components (reusable)
│ ├── form-video.php
│ └── header-video.php
│
├── tools/ # 🔧 Admin tools for block generation or testing
│ ├── form-video-meta.php
│ ├── form-quartier.php
│
├── data/ # 📦 Final PHP data blocks (editable but versioned)
│ ├── video-data.php
│ ├── quartier-video-data.php
│
├── dev/ # 🧪 Temporary test files and staging scripts
│ ├── quartier.php
│ ├── test-thumbnails.php
│
├── public/ # 🖌️ Assets: styles, images, JS
│ └── css/
│ ├── tlt-custom.css # Global site design
│ ├── form-video.css # Video form-specific layout
│
├── config.php # 📁 Central path config (defines BASE_URL, ROOT_PATH, etc.)
└── index.php # 🔍 Default page (can be replaced by router)

yamlCopierModifier
---

## 📁 Folder Roles & Philosophy

### `components/`
> Modular, reusable parts of the site — visual, semantic, and styled.

- 🟢 Public use
- 💡 Uses data from `/data/`
- ✅ Example: forms, cards, headers, swipers

---

### `tools/`
> Internal use only. Meant for data generation, testing, injection.

- 🔒 Not intended for public visitors
- ✍️ Admin interface for creating PHP array blocks
- ✅ Example: `form-video-meta.php` writes to `video-dump.txt`

---

### `data/`
> All final project data in PHP array format.

- 📦 Canonical source
- 🛑 Never placed in `/dev/`
- 🔁 Read by both `/components/` and `/tools/`

---

### `dev/`
> Testing environment. Temporary pages, scripts, prototypes.

- 🧪 Do not deploy to production
- 🔄 Can be cleaned regularly
- 🧭 Use for A/B tests, debug views, etc.

---

### `public/`
> All frontend static assets.

- 🎨 CSS, JS, images
- 📌 Always referenced using `BASE_URL`

---

## ✅ Rules to Follow

1. 🔐 **NEVER place final data in `/dev/data/`** — always use `/data/`
2. 📁 **Use English file names** only — no accents or underscores
3. 🔄 **One function = one file** — clear component identity
4. 📚 **All tools must be optional** — core site works without them
5. 🌐 **All paths must use `config.php` constants** (`BASE_URL`, `ROOT_PATH`)
6. 📘 Document each component if it's reused

---

## 📎 Contact

Project by LI Yongxin, Founder of *Paris T’aime*  
In collaboration with the 12 Alex of the AI Constellation


Last updated: 2025-05-23

📂 Full Project Structure Map – Paris T’aime
Generated on 2025-05-23

============================================================
📁 /paristaime/

├── components/ # 🎨 Public-facing UI components (reusable)
│ ├── adopt-button.php ← Button to adopt a quartier
│ ├── carousel-single.php ← Carousel displaying single row of videos
│ ├── contribute-button.php ← CTA button for contributing content
│ ├── filter-tags.php ← UI filter for tags
│ ├── footer-basic.php ← Footer displayed across all pages
│ ├── form-quartier.php ← User-facing form for quartier (used in public)
│ ├── form-video.php ← Public form for adding new video metadata
│ ├── gallery-grid.php ← Photo gallery block
│ ├── header-video.php ← Video hero banner for quartier
│ ├── lang-switcher.php ← Language switcher interface
│ ├── language-tags.php ← Display tags for languages
│ ├── lightbox-video.php ← Lightbox video popup display
│ ├── map-interactive.php ← Interactive map of Paris quartiers
│ ├── progress-status.php ← Project progress visual indicator
│ ├── quartier-card.php ← Card UI block for displaying quartier
│ ├── quartier-page.php ← Full quartier detail page
│ ├── quote-overlay.php ← Overlay quote section for testimonials
│ ├── search-bar.php ← Search bar interface
│ ├── seo-meta.php ← Meta info for SEO
│ ├── stats-block.php ← Statistics visualization block
│ ├── testimonial-block.php ← Visitor/local testimonial component
│ ├── video-detail.php ← Detail view for single video
│ ├── video-sticky-click.php ← Sticky video triggered on click
│ └── video-sticky-scroll.php ← Sticky video triggered on scroll

├── tools/ # 🛠️ Admin tools for internal content/data creation
│ ├── form-video-meta.php ← Admin-only: generates block for video-data.php
│ ├── form-quartier.php ← Admin-only: generates block for quartier-video-data.php
│ ├── preview-blocks.php ← Optional test for rendering PHP array blocks
│ ├── test-thumbnails.php ← Tests YouTube ID and retrieves thumbnail
│ └── test-header-video.php ← Standalone test for header-video layout

├── data/ # 📦 Final structured PHP arrays (version-controlled)
│ ├── video-data.php ← Final block of video entries (used on frontend)
│ └── quartier-video-data.php ← Final quartier entries (used in quartier display)

├── dev/ # 🧪 Temporary tests, staging, experiments
│ ├── quartier.php ← Quartier display test using header-video
│ ├── test-scroll-fullscreen.php ← Prototype sticky fullscreen video on scroll
│ └── test-thumbnails.php ← Same as tools/test-thumbnails.php (temp duplicate)

├── public/css/ # 🎨 Component-specific CSS files
│ ├── adopt-button.css
│ ├── carousel-single.css
│ ├── contribute-button.css
│ ├── filter-tags.css
│ ├── footer-basic.css
│ ├── form-quartier.css
│ ├── form-video.css
│ ├── gallery-grid.css
│ ├── header-video.css
│ ├── lang-switcher.css
│ ├── language-tags.css
│ ├── lightbox-video.css
│ ├── map-interactive.css
│ ├── progress-status.css
│ ├── quartier-card.css
│ ├── quartier-page.css
│ ├── quote-overlay.css
│ ├── search-bar.css
│ ├── seo-meta.css
│ ├── stats-block.css
│ ├── testimonial-block.css
│ ├── video-detail.css
│ ├── video-sticky-click.css
│ └── video-sticky-scroll.css

├── public/js/ # 📜 Component-specific JS files
│ ├── adopt-button.js
│ ├── carousel-single.js
│ ├── contribute-button.js
│ ├── filter-tags.js
│ ├── footer-basic.js
│ ├── form-quartier.js
│ ├── form-video.js
│ ├── gallery-grid.js
│ ├── header-video.js
│ ├── lang-switcher.js
│ ├── language-tags.js
│ ├── lightbox-video.js
│ ├── map-interactive.js
│ ├── progress-status.js
│ ├── quartier-card.js
│ ├── quartier-page.js
│ ├── quote-overlay.js
│ ├── search-bar.js
│ ├── seo-meta.js
│ ├── stats-block.js
│ ├── testimonial-block.js
│ ├── video-detail.js
│ ├── video-sticky-click.js
│ └── video-sticky-scroll.js

├── config.php # 🔧 Global constants (paths, BASE_URL, etc.)
├── index.php # 🏠 Homepage or launcher
├── README.md # 📘 Technical readme
├── README-PARISTAIME # ✨ Human/cinematic project manifest

============================================================
✅ RULE: Only tools/ can modify data/ files.
✅ RULE: Only components/ are shown to the public.
✅ RULE: Each component can have its own CSS + JS in /public/
✅ RULE: No duplication of components/tools by name (e.g. form-video)

🧩 Example: `components/form-video.php`

phpCopierModifier<?php require_once __DIR__ . '/../config.php'; ?>
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Add a New Video</title>
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="stylesheet" href="<?php echo BASE_URL; ?>/public/css/tlt-custom.css">
  <link rel="stylesheet" href="<?php echo BASE_URL; ?>/public/css/form-video.css">
</head>
<body>

<?php include __DIR__ . '/form-video-html.php'; ?>

<script src="<?php echo BASE_URL; ?>/public/js/form-video.js"></script>
</body>
</html>

🧠 Global JS Example (shared)

File: /public/js/sticky-player.js

Used in:

video-sticky-click.php
video-sticky-scroll.php

htmlCopierModifier<script src="<?php echo BASE_URL; ?>/public/js/sticky-player.js"></script>

✅ Summary Rules

File Type	Folder	Example
Component HTML	`/components/`	`form-video.php`
Component CSS	`/public/css/`	`form-video.css`
Component JS	`/public/js/`	`form-video.js`
Shared CSS/JS	`/public/css/` + `/js/`	`tlt-custom.css`, `sticky-player.js`

Let’s generate a complete starter kit for the form-video component, with:

✅ PHP file (form-video.php)
🎨 CSS file (form-video.css)
⚙️ JS file (form-video.js)
📂 Proper folder placement according to your architecture

✅ 1. `components/form-video.php`

phpCopierModifier<?php require_once __DIR__ . '/../config.php'; ?>
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Add a New Video</title>
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="stylesheet" href="<?php echo BASE_URL; ?>/public/css/tlt-custom.css">
  <link rel="stylesheet" href="<?php echo BASE_URL; ?>/public/css/form-video.css">
</head>
<body>

<div class="form-video-wrapper">
  <h2>Add a New Video</h2>
  <form class="form-video" method="post" action="save-video.php">
    <label>Title<input type="text" name="title" required></label>
    <label>Slug<input type="text" name="slug"></label>
    <label>Year<input type="number" name="year" value="2025"></label>
    <label>YouTube ID<input type="text" name="video_id" required></label>
    <label>Intro<textarea name="intro"></textarea></label>
    <label>Status
      <select name="status">
        <option value="ready">Ready</option>
        <option value="draft">Draft</option>
      </select>
    </label>
    <button type="submit">Save Video</button>
  </form>
</div>

<script src="<?php echo BASE_URL; ?>/public/js/form-video.js"></script>
</body>
</html>

🎨 2. `public/css/form-video.css`

cssCopierModifier.form-video-wrapper {
  max-width: 700px;
  margin: 2rem auto;
  padding: 2rem;
  background: #fff;
  border-radius: 12px;
  box-shadow: 0 0 10px rgba(0,0,0,0.1);
}

.form-video label {
  display: block;
  margin-bottom: 1rem;
  font-weight: 600;
}

.form-video input,
.form-video select,
.form-video textarea {
  width: 100%;
  padding: 0.6rem;
  margin-top: 0.3rem;
  border: 1px solid #ccc;
  border-radius: 6px;
  font-size: 1rem;
}

.form-video button {
  margin-top: 1rem;
  padding: 0.75rem 1.5rem;
  background: #001944;
  color: #fff;
  border: none;
  border-radius: 6px;
  cursor: pointer;
}

@media (max-width: 600px) {
  .form-video-wrapper {
    padding: 1rem;
  }
}

⚙️ 3. `public/js/form-video.js`

jsCopierModifierdocument.addEventListener('DOMContentLoaded', function () {
  console.log("✅ form-video.js loaded");
});

📂 Folder Placement (Recap)

cssCopierModifier/paristaime
├── /components
│   └── form-video.php
├── /public
│   ├── /css
│   │   └── form-video.css
│   └── /js
│       └── form-video.js

📁 FILE: files-map-components.txt
📍 LOCATION: /paristaime/docs/files-map-components.txt
📅 VERSION: 2025-05-23
🧭 PURPOSE: Prevent naming conflicts, ensure consistent placement, and clarify CSS/JS associations for each PHP component.
──────────────────────────────────────────────

🎬 COMPONENT: form-video.php
📄 PATH: /paristaime/components/form-video.php
🎨 CSS: /public/css/form-video.css
⚙️ JS: /public/js/form-video.js

🎬 COMPONENT: form-quartier.php
📄 PATH: /paristaime/tools/form-quartier.php
🎨 CSS: /public/css/form-quartier.css
⚙️ JS: /public/js/form-quartier.js

🎬 COMPONENT: video-detail.php
📄 PATH: /paristaime/components/video-detail.php
🎨 CSS: /public/css/video-detail.css
⚙️ JS: /public/js/video-detail.js

🎬 COMPONENT: header-video.php
📄 PATH: /paristaime/components/header-video.php
🎨 CSS: /public/css/header-video.css
⚙️ JS: /public/js/header-video.js

🎬 COMPONENT: carousel.php
📄 PATH: /paristaime/components/carousel.php
🎨 CSS: /public/css/carousel.css
⚙️ JS: /public/js/carousel.js

🎬 COMPONENT: video-sticky-click.php
📄 PATH: /paristaime/components/video-sticky-click.php
🎨 CSS: /public/css/video-sticky.css
⚙️ JS: /public/js/sticky-player.js

🎬 COMPONENT: video-sticky-scroll.php
📄 PATH: /paristaime/components/video-sticky-scroll.php
🎨 CSS: /public/css/video-sticky.css
⚙️ JS: /public/js/sticky-player.js

🎬 COMPONENT: quartier.php (dynamic quartier page)
📄 PATH: /paristaime/dev/quartier.php
📄 DATA: /paristaime/dev/data/quartier-video-data.php
🎨 CSS: /public/css/quartier.css
⚙️ JS: /public/js/quartier.js

🎬 COMPONENT: video-form.php (DEPRECATED: replaced by form-video.php)
🛑 DO NOT USE: Was replaced due to naming conflict

──────────────────────────────────────────────

📦 SHARED CSS FILES
✅ /public/css/tlt-custom.css — global styles, fonts, colors, layout base
✅ /public/css/tlt-grid.css — optional shared layout grid system
✅ /public/css/tlt-buttons.css — shared UI button styles (if split later)

📦 SHARED JS FILES
✅ /public/js/tlt-global.js — global JS helpers, like scroll effects, modals
✅ /public/js/sticky-player.js — sticky player used in multiple components
✅ /public/js/swiper-init.js — if Swiper is used in carousels or sliders

──────────────────────────────────────────────

📝 NAMING CONVENTIONS

PHP: form-x.php, video-x.php, header-x.php, etc.
CSS: form-x.css, video-x.css, …
JS: form-x.js, video-x.js, …
Shared files start with: tlt-*.css, tlt-*.js

──────────────────────────────────────────────

🔐 FUTURE ADVICE

Always check this file before naming a new component.
All new PHP files should live in /components/ unless used for tools or admin.
Do not mix tools/ and components/ logic.
All styles should live in /public/css/, never inline or in PHP files.
JS files must be in /public/js/, never embedded.

──────────────────────────────────────────────
✅ Maintained by: Paris T’aime Development Team

📝 Note: Lessons Learned from File Naming and Structure Mistakes

⚠️ What Went Wrong

💡 What We Learned

✅ Moving Forward

✨ Conclusion

Appendix:

📘 README.md – Paris T’aime Site Structure (2025)

🧩 Example: components/form-video.php

🧠 Global JS Example (shared)

✅ Summary Rules

✅ 1. components/form-video.php

🎨 2. public/css/form-video.css

⚙️ 3. public/js/form-video.js

📂 Folder Placement (Recap)

test

data

You may also like

📘 `README.md` – Paris T’aime Site Structure (2025)

🧩 Example: `components/form-video.php`

✅ 1. `components/form-video.php`

🎨 2. `public/css/form-video.css`

⚙️ 3. `public/js/form-video.js`