Skip to content

Theme Development

Overview

XOOPS themes control the visual presentation of your site. This guide covers creating custom themes, template customization, and responsive design integration.

Theme Structure

themes/mytheme/
├── theme.html                  # Main template wrapper
├── theme_blockleft.html        # Left block template
├── theme_blockright.html       # Right block template
├── theme_blockcenter_c.html    # Center-center block
├── theme_blockcenter_l.html    # Center-left block
├── theme_blockcenter_r.html    # Center-right block
├── language/                   # Theme translations
│   └── english/
│       └── main.php
├── css/                        # Stylesheets
│   ├── style.css              # Main stylesheet
│   └── admin.css              # Admin customizations
├── js/                         # JavaScript files
├── images/                     # Theme images
│   └── icons/
├── modules/                    # Module template overrides
│   └── publisher/
│       └── publisher_item.tpl
└── theme.ini                   # Theme configuration

Theme Configuration

theme.ini

[General]
name = "My Theme"
version = "1.0.0"
author = "Your Name"
license = "GPL"
description = "A modern responsive theme for XOOPS"

[Screenshots]
screenshot = "screenshot.png"

[Settings]
default_layout = "2-col-right"
responsive = true

[Dependencies]
xoops_version = ">=2.5.11"

Main Template (theme.html)

<!DOCTYPE html>
<html lang="<{$xoops_langcode}>">
<head>
    <meta charset="<{$xoops_charset}>">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title><{$xoops_sitename}> - <{$xoops_pagetitle}></title>
    <meta name="description" content="<{$xoops_meta_description}>">
    <meta name="keywords" content="<{$xoops_meta_keywords}>">

    <{$xoops_module_header}>

    <link rel="stylesheet" href="<{$xoops_url}>/themes/<{$xoops_theme}>/css/style.css">
</head>
<body class="<{$xoops_dirname}>">

    <header class="site-header">
        <div class="container">
            <a href="<{$xoops_url}>" class="logo">
                <{$xoops_sitename}>
            </a>
            <nav class="main-nav">
                <{$xoops_mainmenu}>
            </nav>
        </div>
    </header>

    <div class="page-wrapper">
        <{if $xoops_showlblock}>
        <aside class="sidebar-left">
            <{foreach item=block from=$xoops_lblocks}>
                <{include file="theme:theme_blockleft.html"}>
            <{/foreach}>
        </aside>
        <{/if}>

        <main class="content-main">
            <{$xoops_contents}>
        </main>

        <{if $xoops_showrblock}>
        <aside class="sidebar-right">
            <{foreach item=block from=$xoops_rblocks}>
                <{include file="theme:theme_blockright.html"}>
            <{/foreach}>
        </aside>
        <{/if}>
    </div>

    <footer class="site-footer">
        <p><{$xoops_footer}></p>
    </footer>

    <{$xoops_module_footer}>
</body>
</html>

Block Templates

theme_blockleft.html

<section class="block block-left" id="block-<{$block.id}>">
    <{if $block.title}>
    <h3 class="block-title"><{$block.title}></h3>
    <{/if}>
    <div class="block-content">
        <{$block.content}>
    </div>
</section>

Template Variables

Global Variables

Variable Description
$xoops_sitename Site name
$xoops_url Site URL
$xoops_theme Current theme name
$xoops_charset Character encoding
$xoops_langcode Language code
$xoops_pagetitle Page title
$xoops_dirname Current module directory
$xoops_contents Main page content

User Variables

Variable Description
$xoops_isuser User logged in (bool)
$xoops_isadmin User is admin (bool)
$xoops_userid User ID
$xoops_uname Username

Block Variables

Variable Description
$block.id Block ID
$block.title Block title
$block.content Block HTML content
$block.weight Block weight/order

Module Template Overrides

Place modified module templates in your theme:

themes/mytheme/modules/publisher/publisher_item.tpl

Template lookup order: 1. themes/mytheme/modules/modulename/ 2. modules/modulename/templates/

Responsive Design

CSS Grid Layout

/* css/style.css */
.page-wrapper {
    display: grid;
    grid-template-columns: 250px 1fr;
    gap: 20px;
    max-width: 1200px;
    margin: 0 auto;
    padding: 20px;
}

/* With right sidebar */
.has-right-sidebar .page-wrapper {
    grid-template-columns: 1fr 250px;
}

/* Both sidebars */
.has-both-sidebars .page-wrapper {
    grid-template-columns: 200px 1fr 200px;
}

/* Mobile */
@media (max-width: 768px) {
    .page-wrapper {
        grid-template-columns: 1fr;
    }

    .sidebar-left,
    .sidebar-right {
        order: 2;
    }
}

Mobile Navigation

<nav class="main-nav">
    <button class="nav-toggle" aria-label="Toggle navigation">
        <span></span>
        <span></span>
        <span></span>
    </button>
    <ul class="nav-menu">
        <{$xoops_mainmenu}>
    </ul>
</nav>

@media (max-width: 768px) {
    .nav-menu {
        display: none;
        position: absolute;
        width: 100%;
    }

    .nav-menu.active {
        display: block;
    }
}

Best Practices

  1. Mobile-First - Design for mobile, enhance for desktop
  2. Semantic HTML - Use proper HTML5 elements
  3. Performance - Minimize CSS/JS, optimize images
  4. Accessibility - Include ARIA labels, keyboard navigation
  5. Browser Support - Test across browsers
  6. Module Compatibility - Test with common modules