Skip to content

Latest commit

 

History

History
309 lines (233 loc) · 7.57 KB

README.md

File metadata and controls

309 lines (233 loc) · 7.57 KB

Aikeedo Theme Starter

A modern theme development starter kit for Aikeedo, using Vite.js for asset building and Twig for templating. This project compiles into a PHP Composer package that integrates with Aikeedo's theming system.

Tech Stack

  • Frontend:
    • Alpine.js for JavaScript interactivity
    • Tailwind CSS for styling
    • Tabler Icons for iconography
  • Backend:
    • Twig templates for PHP templating
    • Gettext for translations
    • PHP Composer package structure

Project Structure

theme-starter/
├── src/                    # Frontend source
│   ├── js/               # JavaScript files
│   │   ├── components/  # Custom elements
│   │   └── index.js    # Main JS entry
│   └── css/             # CSS files
│       ├── base.css    # Base styles
│       └── index.css   # Main CSS entry
│
├── static/                # PHP package structure
│   ├── composer.json     # Package definition
│   ├── templates/       # Twig template files
│   ├── sections/       # Reusable template sections
│   ├── snippets/      # Template partials
│   ├── layouts/       # Base layouts
│   ├── locale/        # Translation files (.po)
│   └── src/          # PHP source files
│
└── scripts/              # Build and utility scripts
    ├── pack.mjs        # Theme packaging
    ├── release.mjs    # Release creation
    └── locale-extract.mjs # Translation extraction

Prerequisites

  • Node.js 18+ and npm (for asset building)
  • Composer (for package installation in Aikeedo)
  • Running Aikeedo installation
  • Basic knowledge of:
    • Alpine.js and Tailwind CSS
    • Twig templating
    • PHP Composer packages

Detailed Setup Instructions

  1. Clone the Repository

    git clone https://github.com/heyaikeedo/themes-starter.git my-theme
    cd my-theme
  2. Configure Your Theme Package

    Edit /static/composer.json with your theme details:

    {
      "name": "your-vendor/your-theme-name",
      "description": "Your theme description",
      "version": "1.0.0",
      "type": "aikeedo-theme",
      "homepage": "https://your-site.com",
      "license": "AIKEEDO",
      "authors": [
        {
          "name": "Your Name",
          "email": "your.email@example.com",
          "homepage": "https://your-site.com",
          "role": "Developer"
        }
      ],
      "support": {
        "email": "support@your-site.com",
        "docs": "https://docs.your-site.com/"
      },
      "require": {
        "heyaikeedo/composer": "^1.0.0"
      },
      "extra": {
        "entry-class": "YourVendor\\ThemeName\\Theme",
        "title": "Your Theme Title",
        "description": "Your theme description",
        "logo": "https://your-site.com/logo.png",
        "icon": "https://your-site.com/icon.png",
        "status": "active"
      },
      "autoload": {
        "psr-4": {
          "YourVendor\\ThemeName\\": "src/"
        }
      }
    }

    Important:

    • Replace YourVendor\\ThemeName with your actual namespace
    • The namespace in autoload.psr-4 must match your entry-class namespace
    • The src/ directory should contain your PHP classes
  3. Set Up Environment

    a. Create your local environment file:

    cp .env .env.local

    b. Configure .env.local with your paths:

    # Windows path example:
    BUILD_DIR=C:/xampp/htdocs/aikeedo/public/content/plugins/your-vendor/your-theme-name
    
    # Linux/Mac path example:
    BUILD_DIR=/var/www/aikeedo/public/content/plugins/your-vendor/your-theme-name
    
    # Aikeedo server URL (required for development)
    AIKEEDO_SERVER=http://localhost:8000

    Critical: The final path segments (your-vendor/your-theme-name) MUST match your composer.json package name!

  4. Install Dependencies

    a. Install npm packages:

    npm install

    b. Verify installation:

    # Should list alpinejs and other dependencies
    npm list
  5. Start Development Server

    npm run dev

    This will:

    • Start Vite dev server on port 5174
    • Watch for file changes
    • Copy static files to BUILD_DIR
    • Extract translations automatically
  6. Register Theme with Aikeedo

    In your Aikeedo installation directory:

    # Add your theme as a requirement
    composer require your-vendor/your-theme-name
    
  7. Configure Aikeedo

    Add or update these settings in your Aikeedo's .env file:

    # Required for development
    THEME_ASSETS_SERVER=http://localhost:5174/
    
    # Set environment to development
    ENVIRONMENT=dev
    
    # Enable debug mode for development
    DEBUG=1
    
    # Disable caching for development
    CACHE=0
  8. Verify Installation

    # Your theme should be here
    ls /path/to/aikeedo/public/content/plugins/your-vendor/your-theme-name
  9. Activate Your Theme

    a. Log into Aikeedo admin panel b. Navigate to: Themes c. Find your theme in the list d. Click "Publish" to activate

  10. Verify Development Setup

    Check these points:

    • Vite dev server running (http://localhost:5174)
    • Static files copied to BUILD_DIR
    • Theme visible in Aikeedo admin
    • CSS/JS changes reflect immediately
    • Twig template changes trigger reload
    • Translations being extracted

Common Setup Issues

Assets Not Loading

If theme assets aren't loading:

  • Verify THEME_ASSETS_SERVER in Aikeedo's .env
  • Ensure Vite server is running
  • Check proxy settings in vite.config.mjs

Template Changes Not Reflecting

  1. Clear Aikeedo's cache
  2. Check BUILD_DIR path is correct

Development Features

Hot Module Replacement

  • Instant CSS updates via Tailwind
  • Alpine.js component reloading
  • Full page reload for Twig changes
  • Automatic static file copying

Internationalization

  • Automatic string extraction to PO files
  • Multiple language support
  • Translation file watching
  • Uses PHP's Gettext

Custom Elements

<!-- Dark/Light Mode Switcher -->
<mode-switcher>
  <button class="text-2xl">
    <i class="ti ti-moon-stars dark:hidden"></i>
    <i class="hidden ti ti-sun-filled dark:block"></i>
  </button>
</mode-switcher>

<!-- Avatar Component -->
<x-avatar title="User Name" src="/path/to/avatar.jpg" length="2"></x-avatar>

Twig Templates

{% extends "@theme/layouts/theme.twig" %}

{% block template %}
  <div class="container">
    {% include "@theme/sections/header.twig" %}
    {{ content }}
  </div>
{% endblock %}

Available Commands

Command Purpose
npm run dev Start Vite development server
npm run build Build production assets
npm run serve Preview production build
npm run locale Extract translatable strings
npm run pack Create installable theme package
npm run release Create distribution package

Troubleshooting

Common Issues

  1. Assets Not Loading

    • Verify Vite server is running (port 5174)
    • Check AIKEEDO_SERVER setting
    • Verify proxy settings in vite.config.mjs
  2. Template Changes Not Reflecting

    • Check BUILD_DIR permissions
    • Verify Twig file locations
    • Clear Aikeedo's cache
  3. Build Problems

    • Verify all paths in .env.local
    • Check write permissions
    • Review Vite build output

Need Help?