Initial

example/README.md

@@ -0,0 +1,166 @@
+# Django Translatable Fields - Examples
+
+This directory contains comprehensive examples demonstrating all features of django-translatable-fields.
+
+## Files Overview
+
+- **`models.py`** - Example models showcasing all translatable field types
+- **`admin.py`** - Admin configurations for the example models
+- **`usage_examples.py`** - Practical usage examples and demonstrations
+
+## Example Models
+
+### 1. Product Model
+Demonstrates basic translatable fields:
+- `CharField` - Product name
+- `TextField` - Product description  
+- `SlugField` - SEO-friendly URL slug
+- `EmailField` - Support contact email
+- `URLField` - Product website URL
+
+### 2. Category Model
+Shows category organization with translations:
+- `CharField` - Category name
+- `TextField` - Category description
+- `SlugField` - URL-friendly category slug
+- `CharField` - SEO meta description
+
+### 3. BlogPost Model
+Comprehensive example with all field types:
+- `CharField` - Blog post title and meta description
+- `TextField` - Main blog post content
+- `SlugField` - URL slug for the post
+- `EmailField` - Author contact email
+- `URLField` - External reference URL
+
+### 4. Company Model
+Business-focused model with contact information:
+- `CharField` - Company name
+- `TextField` - Company description and address
+- `SlugField` - Company URL slug
+- `EmailField` - Main contact email
+- `URLField` - Company website
+
+## Running the Examples
+
+### 1. Django Shell Usage
+
+```python
+# Start Django shell
+python manage.py shell
+
+# Import and run examples
+from example.usage_examples import run_all_examples
+run_all_examples()
+```
+
+### 2. Individual Example Functions
+
+```python
+from example.usage_examples import (
+    create_sample_data,
+    demonstrate_language_switching,
+    demonstrate_direct_access,
+    demonstrate_translation_methods,
+    demonstrate_all_field_types
+)
+
+# Create sample data
+product, blog_post, company = create_sample_data()
+
+# Try different demonstrations
+demonstrate_language_switching()
+demonstrate_direct_access()
+demonstrate_translation_methods()
+demonstrate_all_field_types()
+```
+
+## Usage Patterns Demonstrated
+
+### 1. Language-Aware Access
+```python
+from django.utils.translation import activate
+
+# Fields automatically return values based on current language
+activate('en')
+print(product.name)  # "Awesome Widget"
+
+activate('de') 
+print(product.name)  # "Fantastisches Widget"
+```
+
+### 2. Direct Language Access
+```python
+# Access specific language directly
+print(product.name_en)  # "Awesome Widget"
+print(product.name_de)  # "Fantastisches Widget"
+print(product.name_fr)  # "Widget Fantastique"
+```
+
+### 3. Translation Management
+```python
+# Get all translations for a field
+translations = product.get_all_translations('name')
+# {'en': 'Awesome Widget', 'de': 'Fantastisches Widget', 'fr': 'Widget Fantastique'}
+
+# Get specific translation
+german_name = product.get_translation('name', 'de')
+
+# Set translation programmatically
+product.set_translation('name', 'es', 'Widget Fantástico')
+product.save()
+```
+
+### 4. All Field Types in Action
+The examples demonstrate proper usage of:
+- **CharField** - Text fields with max_length
+- **TextField** - Longer text content
+- **SlugField** - URL-friendly identifiers
+- **EmailField** - Email addresses with validation
+- **URLField** - Web URLs with validation
+
+## Admin Interface Features
+
+The admin examples show:
+- Clean interface with translate buttons
+- Modal overlays for translation management
+- WYSIWYG editor for TextField content
+- Proper field validation per language
+- Drag and resize functionality for modals
+
+## Field Validation
+
+Each field type includes proper validation:
+- **EmailField** - Valid email format per language
+- **URLField** - Valid URL format per language  
+- **SlugField** - Slug format validation per language
+- **CharField/TextField** - Length and content validation
+
+## Integration with Django Features
+
+Examples demonstrate compatibility with:
+- Django admin interface
+- Model forms and validation
+- Django's internationalization system
+- Search functionality
+- List filters and display options
+- Prepopulated fields (for slugs)
+
+## Best Practices Shown
+
+1. **Model Design** - Proper use of translatable vs non-translatable fields
+2. **Admin Configuration** - Clean, user-friendly admin interfaces
+3. **Data Access** - Efficient translation retrieval and management
+4. **Validation** - Proper field validation across languages
+5. **SEO Optimization** - Language-specific slugs and meta descriptions
+
+## Testing Your Implementation
+
+Use these examples to:
+1. Verify all field types work correctly
+2. Test language switching functionality
+3. Validate admin interface behavior
+4. Check translation storage and retrieval
+5. Ensure proper field validation
+
+The examples provide a solid foundation for implementing translatable fields in your own Django applications.