Rustelo/examples/plugin-example-theme/README.md

Example Analytics Theme Plugin

A complete, production-ready example plugin for the Rustelo website framework demonstrating Level 5 (Compile-Time) plugin architecture.

🎯 Purpose

This plugin serves as a reference implementation showing how to:

1. Create a plugin crate with proper structure and dependencies
2. Implement ResourceContributor trait for providing themes and translations
3. Embed configuration using include_str!() macros
4. Write comprehensive tests for plugin functionality
5. Document thoroughly with examples and usage instructions
6. Follow best practices for Rust plugin development

📦 What This Plugin Provides

Themes

• analytics-dashboard - A professional theme optimized for analytics dashboards
  • High-contrast color scheme for readability
  • Professional color palette (blues, teals, ambers)
  • Comprehensive spacing and typography rules
  • Responsive breakpoints and animation definitions

Translations

• English (en) - Complete English UI strings

  • Dashboard labels and metrics
  • Chart titles and legends
  • Action button labels
  • Status messages and tooltips

• Spanish (es) - Complete Spanish translations

  • Full parity with English strings
  • Localized terminology for analytics

🚀 Quick Start

1. Add to Your Project

In your main Rustelo project's Cargo.toml:

[dependencies]
plugin-example-theme = { path = "./crates/plugin-example-theme" }

2. Register the Plugin

In your server-side resources initialization (src/resources.rs):

use plugin_example_theme::ExampleThemeContributor;

pub fn initialize() -> Result<(), Box<dyn std::error::Error>> {
    // Register your own resources
    rustelo_core_lib::register_contributor(&WebsiteResourceContributor)?;

    // Register the example plugin
    rustelo_core_lib::register_contributor(&ExampleThemeContributor)?;

    // Load all resources from configuration
    rustelo_core_lib::load_resources_from_config()?;

    Ok(())
}

3. Use the Plugin's Theme

In your application's CSS/styling configuration, reference the analytics-dashboard theme:

/* Your CSS can now use the theme variables */
:root {
  --color-primary: #2563EB;
  --color-secondary: #14B8A6;
  --color-accent: #F59E0B;
  /* ... etc ... */
}

📁 Project Structure

plugin-example-theme/
├── Cargo.toml                           # Plugin manifest
├── README.md                            # This file
├── src/
│   ├── lib.rs                          # Public API and initialization
│   └── resources.rs                    # ResourceContributor implementation
├── config/
│   ├── themes/
│   │   └── analytics-dashboard.toml   # Theme configuration
│   └── i18n/
│       ├── en.ftl                     # English translations
│       └── es.ftl                     # Spanish translations
└── examples/
    └── integration_test.rs             # Integration test example

🧪 Testing

Run All Tests

cd crates/plugin-example-theme
cargo test

Expected Output

running 10 tests

test resources::test_contributor_is_clone_and_copy ... ok
test resources::test_contributor_name ... ok
test resources::test_fluent_files_are_not_empty ... ok
test resources::test_fluent_files_are_provided ... ok
test resources::test_menus_and_footers_are_empty ... ok
test resources::test_theme_content_is_not_empty ... ok
test resources::test_theme_is_provided ... ok
test resources::test_theme_is_valid_toml ... ok
test tests::test_plugin_can_be_initialized ... ok
test tests::test_plugin_exports_public_api ... ok

test result: ok. 10 passed; 0 failed; 0 ignored

Test Coverage

The plugin includes tests for:

• ✅ Contributor name and identity
• ✅ Theme availability and content
• ✅ TOML syntax validation
• ✅ Translation files (fluent) availability
• ✅ Empty menus/footers (correctly not provided)
• ✅ Copy/Clone trait implementation
• ✅ Plugin initialization
• ✅ Public API exports

🎨 Theme Details

Color Palette

Purpose	Color	Hex
Primary	Blue	#2563EB
Secondary	Teal	#14B8A6
Accent	Amber	#F59E0B
Success	Green	#10B981
Warning	Amber	#FBBF24
Error	Red	#EF4444
Info	Blue	#3B82F6

Typography

• Heading Font: Inter, system-ui, sans-serif
• Body Font: Inter, system-ui, sans-serif
• Monospace Font: JetBrains Mono, Monaco, monospace
• Scale Factor: 1.125 (12.5% increase per step)

Responsive Breakpoints

• Mobile: 320px
• Tablet: 768px
• Desktop: 1024px
• Wide: 1280px
• Ultra-wide: 1536px

Spacing System

• Base unit: 8px
• Step multiplier: 1.5x
• Increments: 8px, 12px, 18px, 27px, ...

📝 Implementation Details

How It Works

1. Compile Time: During cargo build, this plugin is compiled into your application
2. Static Embedding: Theme and i18n files are embedded via include_str!() macros
3. Initialization: When the application starts, the plugin is registered via initialize()
4. Resource Loading: The framework loads the embedded resources into memory
5. Runtime: The framework makes resources available to components via registries

Why This Design?

• ✅ No Conditional Compilation: Framework doesn't know about plugins
• ✅ Self-Contained: Plugin is a complete, standalone crate
• ✅ Type Safe: Rust compiler validates all resource references
• ✅ Performance: Zero runtime overhead (fully inlined at compile time)
• ✅ Maintainable: Clean separation between plugin and framework
• ✅ Scalable: Add unlimited plugins without increasing complexity

🔧 Customizing This Plugin

Modify the Theme

1. Edit config/themes/analytics-dashboard.toml
2. Change colors, fonts, spacing, or animations
3. Rebuild: cargo build

Add Translations

1. Edit or create files in config/i18n/
2. Use ISO 639-1 language codes (e.g., fr.ftl for French)
3. Update src/resources.rs to include new files
4. Rebuild: cargo build

Extend with More Resources

To add menus or footers:

fn menus(&self) -> HashMap<String, String> {
    let mut menus = HashMap::new();

    let menu_content = include_str!("../config/menus/my-menu.toml");
    menus.insert("my-menu".to_string(), menu_content.to_string());

    menus
}

📚 Learning Resources

For Plugin Developers

• PHASE3-PLUGIN-DEVELOPMENT-GUIDE.md - Comprehensive guide to plugin development
• PHASE1-COMPLETE.md - Architecture foundation documentation
• PHASE2-IMPLEMENTATION-SUMMARY.md - Build-time code generation details

For Framework Users

• RUST_CODE_STYLE.md - Rust coding standards for Rustelo
• Framework API Docs - ResourceContributor trait documentation

🎓 Architecture Level

This plugin implements Level 5 (Compile-Time Plugins) of the Rustelo plugin architecture:

Level 5: Compile-Time Plugins
├─ Trait-based registration
├─ Static code generation at build time
├─ No conditional compilation
├─ Plugin crate is self-contained
└─ Registration at application startup

Future Evolution to Level 8: The same trait interfaces can support runtime plugin loading without breaking changes.

✅ Quality Checklist

• ✅ Implements ResourceContributor trait
• ✅ Has comprehensive documentation with examples
• ✅ Includes 10+ unit tests (100% trait method coverage)
• ✅ Configuration files are valid TOML/FTL
• ✅ No hardcoded paths (uses include_str!())
• ✅ No unsafe code
• ✅ No unwrap() or expect() in production code
• ✅ Cargo.toml has clear version and dependencies
• ✅ README explains purpose and usage
• ✅ Examples show typical integration
• ✅ Error handling is robust
• ✅ Performance optimized (no unnecessary allocations)

🤝 Contributing

To extend this example plugin:

1. Create a feature branch: git checkout -b feature/your-feature
2. Make changes following RUST_CODE_STYLE.md
3. Add tests for new functionality
4. Ensure all tests pass: cargo test --all
5. Submit pull request with clear description

📄 License

This example plugin is provided as part of the Rustelo framework and follows the same license terms.

🆘 Troubleshooting

Plugin doesn't load

Check:

1. Is the plugin added to Cargo.toml?
2. Is initialize() called in your resources module?
3. Are there any compilation errors?

Translations not showing

Check:

1. Are language codes correct (en, es, etc)?
2. Are FTL files valid Fluent syntax?
3. Is the framework loading translations?

Theme colors not applying

Check:

1. Is the theme registered: analytics-dashboard in registry?
2. Are CSS variables using correct names?
3. Are there conflicting theme registrations?

📞 Support

For questions or issues with this plugin:

1. Check PHASE3-PLUGIN-DEVELOPMENT-GUIDE.md for comprehensive documentation
2. Review the source code comments in src/
3. Run tests to verify functionality
4. Check framework documentation for trait specifications

---

Created: 2024-11-02 Status: Production Ready Version: 0.1.0 Compatibility: Rustelo Level 5+