File Organization - Zalbi Theme

This guide provides a comprehensive breakdown of every file and directory in Zalbi Theme, including their purpose, key functions, and relationships.

Complete Directory Tree

zalbi-theme/
├── inc/                          # Core functionality modules
│   ├── custom-header.php         # Custom header implementation
│   ├── customizer.php            # WordPress Customizer settings
│   ├── jetpack.php               # Jetpack compatibility
│   ├── template-functions.php    # Helper functions
│   └── template-tags.php         # Custom template tags
│
├── template-parts/               # Reusable template components
│   ├── content.php               # Default post content
│   ├── content-page.php          # Page content layout
│   ├── content-search.php        # Search result formatting
│   └── content-none.php          # No results message
│
├── js/                           # JavaScript files
│   ├── navigation.js             # Mobile menu & keyboard nav
│   ├── navigation copy 1.js      # Legacy/backup file
│   └── customizer.js             # Live preview for Customizer
│
├── img/                          # Theme images
│   └── logo.webp                 # Zalbi logo (994KB)
│
├── languages/                    # Translation files
│   ├── zalbi.pot                 # Translation template
│   └── readme.txt                # Translation instructions
│
├── _zalbi/                       # Legacy backup directory
│   └── [mirror of theme files]   # Previous version backup
│
├── Template Files (Root)
├── front-page.php                # Homepage template
├── single-hinchable.php          # Single inflatable template
├── single-evento.php             # Single event template
├── single.php                    # Single post template
├── page-catalogo.php             # Catalog page template
├── page-eventos.php              # Events page template
├── page.php                      # Generic page template
├── archive.php                   # Archive template
├── search.php                    # Search results template
├── 404.php                       # Error page template
├── index.php                     # Fallback template
│
├── Core Files (Root)
├── header.php                    # Site header
├── header_copia.php              # Header backup/variant
├── footer.php                    # Site footer
├── sidebar.php                   # Sidebar widget area
├── comments.php                  # Comments section
├── functions.php                 # Theme configuration (236 lines)
│
├── Styles (Root)
├── style.css                     # Main stylesheet (42KB)
├── style-rtl.css                 # RTL language support (16KB)
│
├── Configuration Files
├── composer.json                 # PHP dependencies
├── package.json                  # Node.js dependencies
├── phpcs.xml.dist                # PHP CodeSniffer config
├── screenshot.png                # Theme screenshot
├── readme.txt                    # WordPress.org readme
├── README.md                     # Development readme
└── LICENSE                       # GPL v2 license

Root-Level Template Files

Front Page & Homepage

front-page.php

Purpose: Custom homepage layout for ZalbiPriority: Takes precedence over home.php and index.php for the front pageFeatures:

Custom hero section
Featured content areas
Business-specific homepage layout

When Used: Automatically loaded when set as the front page in Settings → Reading

Custom Post Type Templates

single-hinchable.php

Purpose: Display individual inflatable rental itemsCustom Fields (ACF):

medidas - Dimensions/measurements
capacidad - Capacity (number of people)
etiqueta_color - Color-coded category tag

Features:

Bilingual content (Spanish/Euskera)
Custom breadcrumb navigation
Category-based color coding:
- Orange: Sports / Kirola
- Pink: Inflatable / Puzgarria
- Blue: Aquatic / Uretakoa
- Green: Event / Ekitaldia
- Purple: Game / Jokoa

Translation Arrays:

// Euskera color translations
$nombres_visuales = array(
    'tag-orange' => 'Kirola',
    'tag-pink'   => 'Puzgarria',
    'tag-blue'   => 'Uretakoa',
    'tag-green'  => 'Ekitaldia',
    'tag-purple' => 'Jokoa'
);

Location: single-hinchable.php:1

single-evento.php

Purpose: Display individual event pagesFeatures:

Event-specific layout
Custom styling for event content
Integration with evento custom post type

Post Type: evento (registered in functions.php:171)URL Structure: /eventos/event-name/

Page Templates

page-catalogo.php

Purpose: Display filterable catalog of inflatablesTemplate Name: “Plantilla Catalogo”Key Features:

Category filtering interface
Custom taxonomy query (tipo_hinchable)
Bilingual UI elements
Custom category ordering

Category Order:

Hinchables/Puzgarriak (Inflatables)
Acuáticos/Uretakoak (Aquatic items)
Deportivos/Kirol atrakzioak (Sports attractions)
Juegos/Jokoak (Games)

Implementation:

$orden_personalizado = array(
    'hinchable', 'hinchables', 'puzgarria', 'puzgarriak',
    'acuatico', 'acuaticos', 'uretakoa', 'uretakoak',
    'atracciones-deportivas', 'deportivos', 'kirola',
    'juegos', 'juego', 'jokoak', 'jokoa'
);

Location: page-catalogo.php:1

page-eventos.php

Purpose: Display events archive/listingFeatures:

Events grid or list layout
Event filtering capabilities
Integration with evento post type

Assignment: Applied to pages via template selection or slug matching

page.php

Purpose: Default template for standard pagesFeatures:

Clean page layout
Loads template-parts/content-page.php
Supports comments if enabled

Usage: Fallback for any page without a specific template

Blog & Content Templates

single.php

Purpose: Display single blog postsFeatures:

Post metadata (date, author, categories)
Featured image display
Comments section
Post navigation

Usage: Standard WordPress blog posts

archive.php

Purpose: Display category, tag, and date archivesFeatures:

Archive title and description
Post loop with template-parts/content.php
Pagination

Usage: All archive pages (categories, tags, dates, authors)

search.php

Purpose: Display search resultsFeatures:

Search query display
Results count
Loads template-parts/content-search.php
“No results” handling with template-parts/content-none.php

Usage: Activated when users submit search queries

404.php

Purpose: Error page for not found contentFeatures:

User-friendly error message
Search widget
Suggested content
Custom styling

Usage: Automatically displayed for missing pages/posts

index.php

Purpose: Ultimate fallback templateFeatures:

Generic content loop
Works for any content type
Simple, reliable layout

Usage: Loaded when no more specific template existsImportance: Required by WordPress - theme won’t activate without it

Partial Templates

header.php

Purpose: Site header sectionContains:

<head> section with wp_head()
Site logo/branding
Primary navigation menu
Mobile menu toggle

Called By: get_header() in all templatesLocation: header.php:1

header_copia.php

Purpose: Backup or alternative headerStatus: Legacy file - likely an older version or variantRecommendation: Review and remove if not in use

footer.php

Purpose: Site footer sectionContains:

Footer widget areas
Legal menu (registered as menu-legal)
Copyright information
WhatsApp floating button (if configured)
wp_footer() hook

Called By: get_footer() in all templatesSpecial Feature: WhatsApp button integration with Customizer settingsLocation: footer.php:1

sidebar.php

Purpose: Sidebar widget areaContains:

Dynamic sidebar (sidebar-1)
Widget display logic

Called By: get_sidebar() in applicable templatesWidget Area: Registered in functions.php:103

comments.php

Purpose: Comments section templateFeatures:

Comment list display
Comment form
Password-protected post handling
No comments state

Called By: comments_template() in single posts/pages

Core Configuration Files

Theme Functions

functions.php (236 lines)

Purpose: Main theme configuration and setupKey Functions:

Theme Setup (Lines 18-90)

function zalbi_setup()

Loads text domain: zalbi
Registers navigation menus:
- menu-1 (Primary)
- menu-legal (Legal Footer)
Adds theme supports:
- title-tag
- post-thumbnails
- html5
- custom-background
- custom-logo

function zalbi_widgets_init()

Registers sidebar: sidebar-1

Scripts & Styles (Lines 121-135)

function zalbi_scripts()

Enqueues:
- style.css (theme styles)
- navigation.js (mobile menu)
- Font Awesome 6.4.0
- Google Fonts (Nunito, Open Sans)

Custom Post Type: Hinchable (Lines 138-150)

function zalbi_register_hinchables()

Post type: hinchable
Slug: catalogo
Supports: title, editor, thumbnail, excerpt
Icon: dashicons-smiley

Custom Taxonomy (Lines 153-168)

function zalbi_register_taxonomies()

Taxonomy: tipo_hinchable
Applied to: hinchable
Hierarchical: yes
Slug: tipo

Custom Post Type: Evento (Lines 171-183)

function zalbi_register_eventos()

Post type: evento
Slug: eventos
Supports: title, editor, thumbnail, excerpt
Icon: dashicons-calendar-alt

WhatsApp Customizer (Lines 186-208)

function zalbi_customize_whatsapp($wp_customize)

Setting: zalbi_whatsapp_number
Section: “Botón WhatsApp”
Field type: text
Description: Phone number with country code

Include Files (Lines 213-235)

inc/custom-header.php
inc/template-tags.php
inc/template-functions.php
inc/customizer.php
inc/jetpack.php (conditional)

Location: functions.php:1

Include Directory (`inc/`)

inc/template-tags.php (4,770 bytes)

Purpose: Custom template tags for displaying post metadataFunctions:

zalbi_posted_on()

Displays post publication date
Shows updated date if different
HTML5 time element
Linked to post permalink

zalbi_posted_by()

Displays post author
Links to author archive
Microformat support (vcard)

zalbi_entry_footer()

Shows categories and tags
Edit post link for logged-in users
Conditional display logic

Usage: Called directly in template filesLocation: inc/template-tags.php:1

inc/template-functions.php (913 bytes)

Purpose: Helper functions that enhance theme functionalityFunctions:

zalbi_body_classes($classes)

Modifies body CSS classes
Adds contextual classes
Enhances styling capabilities

zalbi_pingback_header()

Adds pingback URL to header
Supports WordPress pingback feature

Hooks:

body_class filter
wp_head action

Location: inc/template-functions.php:1

inc/customizer.php (1,718 bytes)

Purpose: WordPress Customizer integrationFeatures:

Live preview support
Custom theme options
Sanitization callbacks
Transport methods

Integration: Works with js/customizer.js for live updatesHook: customize_registerLocation: inc/customizer.php:1

inc/custom-header.php (1,880 bytes)

Purpose: Custom header image implementationFeatures:

Header image support
Header text color customization
Responsive header images
Default header configuration

WordPress Feature: custom-headerLocation: inc/custom-header.php:1

inc/jetpack.php (1,546 bytes)

Purpose: Jetpack plugin compatibilityFeatures:

Infinite scroll support
Social sharing configuration
Content options integration

Loading: Conditional - only if Jetpack is activeCheck: defined( 'JETPACK__VERSION' )Location: inc/jetpack.php:1

Template Parts Directory (`template-parts/`)

template-parts/content.php (1,423 bytes)

Purpose: Default post content display in loopsContains:

Post title
Post metadata (via template tags)
Post excerpt or content
Featured image
Read more link

Used In:

archive.php
index.php
Search results

Called By: get_template_part( 'template-parts/content', get_post_type() )

template-parts/content-page.php (1,206 bytes)

Purpose: Page content layoutContains:

Page title
Page content (the_content())
Comments template call
Edit link

Used In: page.phpCalled By: get_template_part( 'template-parts/content', 'page' )

template-parts/content-search.php (883 bytes)

Purpose: Search result item formattingContains:

Post title linked to permalink
Post excerpt
Post metadata (lighter than default)

Used In: search.phpCalled By: get_template_part( 'template-parts/content', 'search' )

template-parts/content-none.php (1,256 bytes)

Purpose: No results found messageVariations:

Search: “Nothing found” + search form
Archive: “Nothing found” + suggestions
404: Handled in 404.php instead

Used In:

archive.php
search.php

Called By: get_template_part( 'template-parts/content', 'none' )

JavaScript Directory (`js/`)

js/navigation.js (1,850 bytes)

js/customizer.js (1,011 bytes)

Purpose: Live preview in WordPress CustomizerFeatures:

Real-time site title updates
Bloginfo live preview
Background color updates
Text color changes

Context: Only loads in Customizer previewWorks With: inc/customizer.php

js/navigation copy 1.js (2,980 bytes)

Assets Directories

Images (`img/`)

img/logo.webp (994KB)

Purpose: Zalbi theme logoFormat: WebP (modern, optimized)Size: 994KB (large file - consider optimization)Usage: Displayed in header, likely via custom logo featureRecommendation: Optimize or create multiple sizes for responsive display

Translations (`languages/`)

languages/zalbi.pot (4,632 bytes)

Purpose: Translation template (Portable Object Template)Contains:

All translatable strings from theme
Context for translators
String references (file:line)

Usage: Base file for creating translationsText Domain: zalbiLanguages Supported: Spanish (default), Euskera (via Polylang)

languages/readme.txt (322 bytes)

Purpose: Translation instructionsContains:

How to translate the theme
POT file usage
Translation workflow

Stylesheets

style.css (42,100 bytes)

Purpose: Main theme stylesheetHeader Information:

Theme Name: zalbi-theme
Version: 1.0.0
Author: Yeray Garrido
Text Domain: zalbi
Based on: Underscores (_s)

Structure (from Table of Contents):

Generic (Normalize, Box sizing)
Base (Typography, Elements, Links, Forms)
Layouts
Components (Navigation, Posts, Comments, Widgets, Media)
Plugins (Jetpack)
Utilities (Accessibility, Alignments)

Size: 42KB (well-organized, moderate size)RTL Support: Yes (style-rtl.css)

style-rtl.css (16,934 bytes)

Purpose: Right-to-left language supportLanguages: Arabic, Hebrew, Persian, etc.Contents: Mirrored layouts and reversed directional stylesAuto-generated: Via build toolsSize: 16KB

Configuration Files

composer.json

Purpose: PHP dependency managementDependencies: (Check file for specifics)

PHP CodeSniffer
WordPress Coding Standards

Scripts:

lint:wpcs - Code style checking
lint:php - PHP syntax validation
make-pot - Generate translation file

package.json

Purpose: Node.js dependency managementScripts:

compile:css - SASS to CSS compilation
compile:rtl - RTL stylesheet generation
watch - Watch and recompile SASS
lint:scss - SCSS linting
lint:js - JavaScript linting
bundle - Create distribution ZIP

Dev Dependencies: Build tools and linters

phpcs.xml.dist

Purpose: PHP CodeSniffer configurationStandards: WordPress Coding StandardsRules: PHP compatibility, best practicesIgnored: vendor/, node_modules/

Documentation & Meta Files

README.md

Purpose: Development documentationContents:

Installation instructions
Development setup
CLI commands
Underscores framework info
Theme customization guide

Audience: Developers working on the theme

readme.txt

Purpose: WordPress.org theme readmeContents:

Theme description
Installation instructions
Changelog
Credits

Format: WordPress-specific markdownAudience: End users installing the theme

LICENSE (18,046 bytes)

Purpose: Software licenseLicense: GNU General Public License v2 or laterSize: 18KB (full GPL text)Compatibility: WordPress license requirement

screenshot.png (264 bytes)

Purpose: Theme preview screenshotSize: 264 bytes (very small - likely placeholder)Recommendation: Replace with actual theme screenshot (1200x900px recommended)Usage: Displayed in WordPress Appearance → Themes

Legacy Directory (`_zalbi/`)

The _zalbi/ directory contains a complete backup of the theme files from a previous version.

Purpose: Backup/archive of earlier theme iteration Contents: Mirror of all theme files Recommendation:

Keep for version history if needed
Remove from production to reduce file size
Consider using version control (Git) instead

Impact: Doubles theme file count and size

File Count Summary

Template Files

19 PHP template files in root directory

Include Files

5 files in inc/ directory

Template Parts

4 files in template-parts/ directory

JavaScript

3 files in js/ directory

Assets

1 logo + 2 translation files

Configuration

6 config files (composer, package, phpcs, etc.)

File Naming Conventions

Zalbi Theme follows WordPress theme development standards for file naming:

Template Files

Lowercase with hyphens: single-evento.php
Descriptive names: page-catalogo.php
WordPress hierarchy: 404.php, archive.php

Include Files

Descriptive purpose: template-tags.php
Hyphenated words: custom-header.php
Organized in inc/ directory

JavaScript Files

Lowercase, descriptive: navigation.js
Purpose-based naming: customizer.js

Styles

Main file: style.css (required)
Variants: style-rtl.css

Maintenance Recommendations

Remove Duplicates

Delete backup files:

header_copia.php
js/navigation copy 1.js
_zalbi/ directory (if version controlled)

Optimize Assets

Compress and optimize:

img/logo.webp (994KB → consider 100-200KB)
Generate responsive image sizes

Update Screenshot

Replace screenshot.png:

Current: 264 bytes (too small)
Recommended: 1200x900px
Show actual theme design

Version Control

Use Git instead of file copies:

Remove _zalbi/ backup directory
Commit regularly
Tag releases

Theme Overview

High-level architecture and design

Template Hierarchy

How WordPress selects templates

Get Started

Theme Structure

Custom Post Types

Customization

Template Development

​Complete Directory Tree

​Root-Level Template Files

​Front Page & Homepage

​Custom Post Type Templates

​Page Templates

​Blog & Content Templates

​Partial Templates

​Core Configuration Files

​Theme Functions

​Theme Setup (Lines 18-90)

​Widget Registration (Lines 103-116)

​Scripts & Styles (Lines 121-135)

​Custom Post Type: Hinchable (Lines 138-150)

​Custom Taxonomy (Lines 153-168)

​Custom Post Type: Evento (Lines 171-183)

​WhatsApp Customizer (Lines 186-208)

​Include Files (Lines 213-235)

​Include Directory (inc/)

​zalbi_posted_on()

​zalbi_posted_by()

​zalbi_entry_footer()

​zalbi_body_classes($classes)

​zalbi_pingback_header()

​Template Parts Directory (template-parts/)

​JavaScript Directory (js/)

​Assets Directories

​Images (img/)

​Translations (languages/)

​Stylesheets

​Configuration Files

​Documentation & Meta Files

​Legacy Directory (_zalbi/)

​File Count Summary

Template Files

Include Files

Template Parts

JavaScript

Assets

Configuration

​File Naming Conventions

​Template Files

​Include Files

​JavaScript Files

​Styles

​Maintenance Recommendations

Remove Duplicates

Optimize Assets

Update Screenshot

Version Control

​Related Resources

Theme Overview

Template Hierarchy

Build docs developers (and LLMs) love

Complete Directory Tree

Root-Level Template Files

Front Page & Homepage

Custom Post Type Templates

Page Templates

Blog & Content Templates

Partial Templates

Core Configuration Files

Theme Functions

Theme Setup (Lines 18-90)

Widget Registration (Lines 103-116)

Scripts & Styles (Lines 121-135)

Custom Post Type: Hinchable (Lines 138-150)

Custom Taxonomy (Lines 153-168)

Custom Post Type: Evento (Lines 171-183)

WhatsApp Customizer (Lines 186-208)

Include Files (Lines 213-235)

Include Directory (`inc/`)

zalbi_posted_on()

zalbi_posted_by()

zalbi_entry_footer()

zalbi_body_classes($classes)

zalbi_pingback_header()

Template Parts Directory (`template-parts/`)

JavaScript Directory (`js/`)

Assets Directories

Images (`img/`)

Translations (`languages/`)

Stylesheets

Configuration Files

Documentation & Meta Files

Legacy Directory (`_zalbi/`)

File Count Summary

File Naming Conventions

Template Files

Include Files

JavaScript Files

Styles

Maintenance Recommendations

Related Resources