ferrero-naming-tool/README.md

Ferrero Communication Assets - Naming Convention Tool

A web-based tool for creating and decoding Ferrero communication asset filenames according to the official naming convention.

Features

• Filename Builder: Interactive form to generate properly formatted filenames
• Filename Decoder: Parse existing filenames to see their components
• Help Documentation: Comprehensive guide with examples and best practices
• OMG Job Number: Required field for tracking (numbers only, max 10 digits)
• Data Management: Python scripts to parse Excel data and update the tool
• Ferrero Branding: Styled with Montserrat font to match Ferrero's visual identity
• Responsive Layout: Optimized for landscape/desktop viewing

Naming Convention Structure

[OMG_JOB_NUMBER]_[BRAND_CODE]_[COUNTRY_CODE]_[LANGUAGE_CODE]_[SUBJECT_TITLE]_[ASSET_TYPE]_[SPOT_VERSION]*_[SECONDS]S_[ASPECT_RATIO]

Example: 12345_RAF_IT_it_ME MOMENT_OLV_6S_1x1

• OMG Job Number: Numbers only, max 10 digits (e.g., 12345)
• Brand Code: 2-5 characters (e.g., RAF = Raffaello)
• Country Code: 2 characters, ISO 3166-1 (e.g., IT = Italy, DE = Germany, GB = United Kingdom, US = United States)
• Language Code: 2-3 characters, ISO 639-1/639-2 (e.g., en = English, it = Italian, de = German)
• Subject Title: Max 15 characters, uppercase
• Asset Type: 3 characters (e.g., OLV = Online Video)
• Spot Version: Optional 3 characters + "MST" for master files
• Seconds: Duration (e.g., 6S)
• Aspect Ratio: 3-4 characters (e.g., 1x1, 16x9)

Data Library

The tool includes comprehensive data with ISO standard codes:

• 105 Brands: All Ferrero brands (Nutella, Kinder, Ferrero Rocher, etc.)
• 38 Countries: ISO 3166-1 country codes (IT, DE, GB, US, etc.)
• 25 Languages: ISO 639-1 language codes (en, it, de, es, fr, etc.)
• 39 Asset Types: Complete range from OLV to Brand Books
• 6 Aspect Ratios: Common video and image formats

Installation

Prerequisites

• PHP 8.x or higher
• Python 3.x (only needed for updating data from Excel)
• MAMP Pro or similar PHP server

Setup

For MAMP Pro Users (Recommended):

1. Point MAMP Pro document root to: /path/to/Ferrero-naming-convention/public
2. Start MAMP server
3. Access the tool via your MAMP domain

For Development/Testing:

The project includes a Python virtual environment in ferrero-venv/ for data management scripts.

Usage

Running the Tool

Simply access the tool through your web server (MAMP Pro or other PHP server). All functionality is self-contained in the PHP application.

Example URL: http://ferrero-naming.test (or your MAMP domain)

Tool Interface

The application has three tabs:

1. Filename Builder - Create new filenames with validation
2. Filename Decoder - Parse and break down existing filenames
3. Help - Complete documentation with examples

Project Structure

Ferrero-naming-convention/
├── ferrero-venv/           # Python virtual environment (for data updates)
├── backend/
│   ├── api.php             # PHP API endpoints
│   ├── excel_parser.py     # Python script to parse Excel data
│   ├── data.json           # Naming convention data (105 brands, 38 countries, 25 languages, 39 asset types)
│   └── requirements.txt    # Python dependencies
├── public/
│   ├── index.php           # Main application page
│   ├── api.php             # PHP backend logic
│   ├── css/
│   │   └── style.css       # Ferrero-branded styles (Montserrat font)
│   └── js/
│       └── app.js          # Frontend application logic
├── Filenaming.xlsx         # Source data (official specification)
├── .gitignore              # Git ignore rules
└── README.md               # This file

PHP API Endpoints

GET api.php?action=data

Get all naming convention data (brands, countries, asset types, etc.)

GET api.php?action=brands

Get all brand codes

POST api.php?action=brands

Add a new brand code

{
  "code": "RAF",
  "name": "Raffaello"
}

GET api.php?action=countries

Get all country codes (ISO 3166-1)

GET api.php?action=languages

Get all language codes (ISO 639-1/639-2)

GET api.php?action=asset-types

Get all asset types

POST api.php?action=build

Build a filename from components

{
  "omg_job_number": "12345",
  "brand_code": "RAF",
  "country_code": "IT",
  "language_code": "it",
  "subject_title": "ME MOMENT",
  "asset_type": "OLV",
  "spot_version": "",
  "seconds": "6",
  "aspect_ratio": "1x1",
  "has_master": false
}

Response:

{
  "filename": "12345_RAF_IT_it_ME MOMENT_OLV_6S_1x1"
}

POST api.php?action=decode

Decode a filename into components

{
  "filename": "12345_RAF_IT_it_ME MOMENT_OLV_6S_1x1"
}

Response:

{
  "omg_job_number": "12345",
  "brand_code": "RAF",
  "brand_name": "RAFFAELLO",
  "country_code": "IT",
  "country_name": "Italy",
  "language_code": "it",
  "language_name": "Italian",
  "subject_title": "ME MOMENT",
  "asset_type": "OLV",
  "asset_type_name": "On Line Video",
  "spot_version": "",
  "has_master": false,
  "seconds": "6",
  "aspect_ratio": "1x1"
}

Managing Data

Updating from Excel

When the official Filenaming.xlsx file is updated, regenerate the data:

# Activate Python virtual environment
source ferrero-venv/bin/activate

# Run the Excel parser
python3 backend/excel_parser.py

This will:

• Parse the "List of Values" sheet
• Extract all brands, countries, asset types, aspect ratios
• Generate updated backend/data.json

Manual Data Edits

You can also edit backend/data.json directly. The file structure:

{
  "brands": { "CODE": "Brand Name" },
  "countries": { "CODE": "Country Name" },
  "languages": { "code": "Language Name" },
  "asset_types": { "CODE": "Asset Type Name" },
  "aspect_ratios": ["1x1", "16x9", ...],
  "spot_versions": ["Master", ...],
  "examples": [...]
}

Note: Country codes use ISO 3166-1 (uppercase), language codes use ISO 639-1 (lowercase).

Browser Compatibility

• Chrome/Edge (latest)
• Firefox (latest)
• Safari (latest)

Design

• Font: Montserrat (Google Fonts)
• Color Scheme: Ferrero brand colors (browns, golds, creams)
• Layout: Responsive landscape-optimized design
• Framework: Pure PHP/JavaScript (no dependencies)

Troubleshooting

Data Not Loading

Ensure backend/data.json exists. If not, run:

source ferrero-venv/bin/activate
python3 backend/excel_parser.py

PHP Errors

Check PHP error logs in MAMP Pro or your server configuration.

Styling Issues

Clear browser cache or do a hard refresh (Cmd+Shift+R on Mac, Ctrl+Shift+R on Windows).

License

© Ferrero. All rights reserved.

Support

For issues or questions, contact your IT administrator.