New Page Template Workflow

This is the recommended process for building a new custom page template in Balinot.

Use case example: a new “About us” page.

1. Decide the page type first

Reusable page template:

• Use this when the structure may be reused on other pages.
• Recommended names:
  • templates/page-about.php
  • templates/partials/about/

One-off page:

• Use this when the structure is tied to one real page and one content set.
• Recommended names:
  • page file can still be a normal template or a slug-based file.
  • partial folder can be templates/partials/about-10445/.

Rule:

• Prefer the reusable version first.
• Use the numeric page-specific folder only when the page is truly custom and not expected to become a pattern.

2. Create the template file

Recommended file:

• templates/page-about.php

Minimal skeleton:

<?php
/*
Template Name: About
*/
 
defined('ABSPATH') || exit;
 
get_header();
 
$sections = ['hero', 'story', 'values', 'team'];
?>
 
<div class="w-full max-w-full">
    <main class="w-full overflow-hidden">
        <?php do_action('balinot_before_main_content'); ?>
 
        <?php foreach ($sections as $slug) : ?>
            <?php get_template_part("templates/partials/about/`{$slug}`"); ?>
        <?php endforeach; ?>
 
        <?php get_template_part('templates/partials/general/faqs'); ?>
        <?php get_template_part('templates/partials/general/reviews'); ?>
 
        <?php do_action('balinot_after_main_content'); ?>
    </main>
</div>
 
<?php get_footer(); ?>

The template should orchestrate sections, not own all the markup.

3. Create the page partial folder

Recommended folder:

• templates/partials/about/

Recommended section files:

• hero.php
• story.php
• values.php
• team.php
• gallery.php
• timeline.php

Each file should own one section.

Typical pattern inside a partial:

<?php
defined('ABSPATH') || exit;
 
$post_id = get_queried_object_id();
$story_section = get_field('story_section', $post_id) ?: [];
 
$title = $story_section['title'] ?? '';
$text = $story_section['text'] ?? '';
?>
 
<section class="...">
    <h2><?= esc_html($title); ?></h2>
    <div><?= wp_kses_post($text); ?></div>
</section>

Rule:

• Let the section partial read the section field group it owns.

4. Decide if a block should become a general partial

Create a file in templates/partials/general/ when the block is shared by multiple page templates.

Good candidates:

• shared CTA band
• shared FAQ router
• shared reviews router
• shared help block
• shared trust bar

Examples already in the theme:

• templates/partials/general/faqs.php
• templates/partials/general/reviews.php
• templates/partials/general/help.php

Rule:

• If at least two page templates should use the same section with the same logic, prefer a general partial.

5. Decide if a block should become a component

Create a file in templates/components/ when the block is mostly presentational and can receive prepared args.

Good candidates:

• stat-card.php
• quote-card.php
• team-card.php
• media-block.php
• feature-list.php

Component rule:

• Components should receive data.
• Components should not be the main owner of page-specific ACF lookups.

Good example of the pattern already used:

• templates/partials/general/reviews.php prepares data and selects a component in templates/components/reviews-*.php.
• templates/partials/general/faqs.php prepares data and selects a component in templates/components/faqs-*.php.

6. Add dedicated CSS or JS only if the page needs it

If the page needs its own frontend assets:

1. Create assets/css/about.css and optionally assets/js/about.js.
2. Add an about rule in modules/00-enqueue.php.
3. Match it by slug or by template path.

Example rule:

'about' => [
    'style' => true,
    'script' => true,
    'page_slugs' => ['quienes-somos'],
    'templates' => ['templates/page-about.php'],
],

7. Naming conventions to keep the repo coherent

Recommended:

• Template file: page-about.php
• Page partial folder: partials/about/
• General shared section: partials/general/cta-band.php
• Router family: components/reviews-1.php, components/reviews-2.php
• Generic presentational block: components/team-card.php

Avoid:

• Putting all page markup directly in page-about.php.
• Putting page-specific ACF logic into components.
• Creating a general partial for something that only one page will ever use.

8. Quick decision matrix

Use templates/page-*.php when:

• you need a full page layout entry point.

Use templates/partials/{page}/ when:

• the section belongs to one page template family.

Use templates/partials/general/ when:

• the section logic is shared by multiple pages.

Use templates/components/ when:

• the file is mostly presentational and should render args prepared elsewhere.