Theme Development Workflow

# Theme Development Workflow This guide provides a step-by-step workflow for developing themes in FearlessCMS, from initial setup to final deployment. ## Prerequisites Before starting theme development, ensure you have: - A working FearlessCMS installation - Basic knowledge of HTML, CSS, and JavaScript - A code editor (VS Code, Sublime Text, etc.) - Basic understanding of responsive design principles ## Development Environment Setup ### 1. Create Theme Directory ```bash # Navigate to your FearlessCMS themes directory cd themes/ # Create your theme directory mkdir my-theme cd my-theme # Create required subdirectories mkdir templates mkdir assets mkdir assets/images mkdir assets/js ``` ### 2. Initialize Theme Files Create the basic theme structure: ```bash # Create theme configuration touch theme.json touch config.json touch README.md # Create template files touch templates/home.html touch templates/page.html touch templates/blog.html touch templates/404.html # Create assets touch assets/style.css # Placeholder for thumbnail (add actual image later) # thumbnail.png or screenshot.png will go here touch assets/theme.js ``` ## Step-by-Step Development Process ### Step 1: Define Theme Configuration Start by creating your `theme.json`: ```json { "name": "My Awesome Theme", "description": "A modern, responsive theme for blogs and websites", "version": "1.0.0", "author": "Your Name", "license": "MIT", "templates": { "home": "home.html", "page": "page.html", "blog": "blog.html", "404": "404.html" } } ``` ### Step 2: Create Basic Templates Start with a simple `templates/page.html`: ```html {{title}} - {{siteName}}

``` ### Step 3: Add Basic Styling Create `assets/style.css`: ```css /* Reset and base styles */ * { margin: 0; padding: 0; box-sizing: border-box; } body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; line-height: 1.6; color: #333; } /* Layout */ header, main, footer { padding: 2rem; } /* Typography */ h1 { font-size: 2.5rem; margin-bottom: 1rem; } /* Responsive */ @media (max-width: 768px) { h1 { font-size: 2rem; } } ``` ### Step 4: Test Your Theme 1. **Activate the theme** in the admin panel 2. **Create a test page** with some content 3. **View the page** in your browser 4. **Check for errors** in browser console ### Step 5: Iterate and Improve Based on your testing, improve the theme: 1. **Fix layout issues** 2. **Improve typography** 3. **Add responsive design** 4. **Enhance visual appeal** ### Step 6: Add Theme Options Create `config.json` for customizable options: ```json { "options": { "logo": { "type": "image", "label": "Logo Image", "description": "Upload your site logo" }, "primaryColor": { "type": "color", "label": "Primary Color", "default": "#007bff" }, "showSidebar": { "type": "checkbox", "label": "Show Sidebar", "default": true } } } ``` ### Step 7: Implement Advanced Features Add more sophisticated features: 1. **Navigation menus** 2. **Blog functionality** 3. **Search capability** 4. **Social media integration** 5. **Custom JavaScript** ## Development Best Practices ### 1. Start Simple Begin with a basic, functional theme and add features gradually: ```html {{title}}

``` ### 2. Use Modular Templates As your theme grows, break it into reusable components using the modular template system: ```html {{module=head.html}} {{module=header.html}}

{{module=footer.html}} ``` **Benefits of modular templates:** - **Maintainability**: Common elements in single files - **Reusability**: Use modules across multiple templates - **Consistency**: Changes update everywhere automatically - **Organization**: Cleaner, more organized code structure **Common modules to create:** - `head.html` - HTML head section - `header.html` - Site header with navigation - `footer.html` - Site footer - `navigation.html` - Navigation menus - `sidebar.html` - Sidebar content - `hero-banner.html` - Hero banner sections For detailed information, see the [Modular Templates Guide](modular-templates). ### 3. Use Semantic HTML Always use proper HTML5 semantic elements: ```html

``` ### 4. Mobile-First Design Start with mobile styles and add desktop enhancements: ```css /* Mobile first */ .container { padding: 1rem; } /* Tablet and up */ @media (min-width: 768px) { .container { padding: 2rem; max-width: 1200px; margin: 0 auto; } } /* Desktop */ @media (min-width: 1024px) { .container { padding: 3rem; } } ``` ### 5. Use CSS Custom Properties Make your theme easily customizable: ```css :root { --primary-color: #007bff; --secondary-color: #6c757d; --text-color: #333; --bg-color: #fff; --border-color: #e9ecef; } .button { background-color: var(--primary-color); color: white; padding: 0.5rem 1rem; border: none; border-radius: 4px; } .card { background-color: var(--bg-color); border: 1px solid var(--border-color); border-radius: 8px; padding: 1rem; } ``` ### 6. Progressive Enhancement Add JavaScript features progressively: ```html ``` ## Testing Your Theme ### 1. Content Testing Test with different types of content: - **Short pages** (just a title and paragraph) - **Long pages** (lots of content) - **Pages with images** - **Pages with lists and tables** - **Blog posts with different formats** ### 2. Browser Testing Test in multiple browsers: - Chrome/Chromium - Firefox - Safari - Edge ### 3. Device Testing Test on different devices: - **Mobile phones** (portrait and landscape) - **Tablets** (portrait and landscape) - **Desktop computers** (different screen sizes) ### 4. Performance Testing Check theme performance: - **Page load speed** - **CSS file size** - **JavaScript execution time** - **Image optimization** ## Debugging Tips ### 1. Use Browser Developer Tools - **Inspect elements** to see how CSS is applied - **Check console** for JavaScript errors - **Use network tab** to see if files are loading - **Test responsive design** with device simulation ### 2. Add Debug Output Temporarily add debug information to your templates: ```html

    Debug Info:

    Title: {{title}}

    URL: {{url}}

    Theme: {{theme}}

    Children: {{#if children}}Yes{{else}}No{{/if}}

``` ### 3. Check File Permissions Ensure your theme files have proper permissions: ```bash chmod 644 assets/style.css chmod 644 templates/*.html chmod 644 theme.json chmod 644 config.json ``` ## Version Control ### 1. Initialize Git Repository ```bash cd themes/my-theme git init ``` ### 2. Create .gitignore ```bash # .gitignore .DS_Store *.log node_modules/ # Add any build tool directories if you use them # .sass-cache/ # dist/ # build/ ``` ### 3. Make Initial Commit ```bash git add . git commit -m "Initial theme commit" ``` ## Creating Theme Thumbnails Before deploying your theme, create a thumbnail image for the admin panel preview: ### 1. Prepare Your Theme for Screenshot ```bash # Ensure theme is active and properly styled # Add sample content to showcase the theme # Test at desktop resolution (1200px+ width) ``` ### 2. Capture the Thumbnail 1. **Open your theme** in a browser at desktop resolution 2. **Navigate to homepage** or most representative page 3. **Take a screenshot** of the full viewport 4. **Crop to 1200x675px** (16:9 aspect ratio) 5. **Optimize the image** to keep under 500KB 6. **Save as `thumbnail.png`** in your theme root directory ### 3. Thumbnail Best Practices ```bash # Good thumbnail characteristics: # - Shows homepage or main layout # - High resolution and clear quality # - Realistic sample content (not Lorem Ipsum) # - Proper lighting and contrast # - Highlights theme's unique features ``` ### 4. Test Thumbnail Display 1. **Refresh admin panel** to see the thumbnail 2. **Check grid layout** - ensure it displays properly 3. **Test modal view** - click to view larger version 4. **Verify fallback** - temporarily rename file to test placeholder ### 5. Thumbnail File Requirements - **Filename**: `thumbnail.png`, `thumbnail.jpg`, `screenshot.png`, or `screenshot.jpg` - **Dimensions**: 1200x675px (recommended) - **Format**: PNG (preferred), JPG, JPEG, GIF, or WebP - **Size**: Under 500KB for optimal performance - **Location**: Theme root directory (same level as config.json) ## Deployment ### 1. Package Your Theme Create a clean distribution: ```bash # Verify thumbnail is present ls -la thumbnail.png # or thumbnail.jpg, screenshot.png, etc. # Remove development files rm -rf .git rm -rf node_modules # Remove any build tool directories # rm -rf .sass-cache # rm -rf dist # rm -rf build # Create zip file (include thumbnail) zip -r my-theme-v1.0.0.zip . -x "*.git*" "node_modules/*" ``` ### 2. Install in FearlessCMS 1. **Upload** the theme to your FearlessCMS installation 2. **Extract** to the `themes/` directory 3. **Verify thumbnail** appears in admin themes section 4. **Activate** the theme in admin panel 5. **Configure** theme options 6. **Test** thoroughly ## Maintenance ### 1. Keep Dependencies Updated Regularly update any external dependencies: - CSS frameworks - JavaScript libraries - Font files ### 2. Monitor Performance Track theme performance over time: - Page load speeds - User feedback - Browser compatibility issues ### 3. Version Management Use semantic versioning for your theme: - **Major version** (1.0.0 → 2.0.0): Breaking changes - **Minor version** (1.0.0 → 1.1.0): New features - **Patch version** (1.0.0 → 1.0.1): Bug fixes ## Example: Complete Development Session Here's an example of a complete development session: ```bash # 1. Create theme structure mkdir -p themes/my-blog-theme/{templates,assets/{css,js,images}} # 2. Create basic files cd themes/my-blog-theme touch theme.json config.json README.md touch templates/{home,page,blog,404}.html touch assets/css/style.css assets/js/theme.js # 3. Edit theme.json cat > theme.json << 'EOF' { "name": "My Blog Theme", "description": "A clean blog theme", "version": "1.0.0", "author": "Your Name", "license": "MIT", "templates": { "home": "home.html", "page": "page.html", "blog": "blog.html", "404": "404.html" } } EOF # 4. Create basic template cat > templates/page.html << 'EOF' {{title}} - {{siteName}}

EOF # 5. Add basic CSS cat > assets/css/style.css << 'EOF' * { margin: 0; padding: 0; box-sizing: border-box; } body { font-family: sans-serif; line-height: 1.6; padding: 2rem; } EOF # 6. Test the theme # - Activate in admin panel # - Create test content # - View in browser # - Debug any issues # 7. Iterate and improve # - Add more styling # - Implement responsive design # - Add theme options # - Test thoroughly ``` This workflow ensures you create a robust, maintainable theme that works well across different devices and content types.