Complex Component Structure

When to Create a Component Folder

• Rule: A component MUST be placed in its own folder when:

  • It has multiple sub-components/partials
  • It requires its own JavaScript (in <script> tag)
  • It has multiple variants or states

Folder Structure

• Rule: Complex components MUST follow this structure:

component-name/
├── core.latte              # REQUIRED: Entry point with {block core} and optional {block script}
└── [sub-component].latte   # Optional: Sub-components

Example (Newsletter form component):

newsletter-form/
├── core.latte           # Main entry point with blocks
├── form.latte           # Form fields sub-component
└── success.latte        # Success message sub-component

Example (Navigation module):

navigation/
├── core.latte           # Main navigation wrapper with blocks
├── desktop-menu.latte   # Desktop version
├── mobile-menu.latte    # Mobile hamburger menu
└── dropdown.latte       # Dropdown submenu

Block Structure in core.latte

• Rule: The core.latte file MUST contain a {block core} for HTML content. If JavaScript is needed, it MUST be in a separate {block script}.

• Reason: This allows explicit inclusion of each block separately using {include core from ...} and {include script from ...}.

Example (core.latte):

{**
 * Newsletter Form Component
 * @param string $formAction - Form submission URL
 * @param string $buttonText - Submit button text
 * @param bool $showNameField - Whether to show name field
 *}
{default $formAction = '/newsletter/subscribe'}
{default $buttonText = 'Subscribe'}
{default $showNameField = false}

{block core}
<div class="newsletter-form" id="newsletter-{$uniqueId ?? 'default'}">
	{include 'form.latte',
		action => $formAction,
		buttonText => $buttonText,
		showName => $showNameField
	}
	
	{include 'success.latte'}
</div>
{/block}

{block script}
<script>
(function() {
	const form = document.getElementById('newsletter-{$uniqueId ?? 'default'}');
	// Component JavaScript logic...
})();
</script>
{/block}

Using Complex Components

• Rule: When including a complex component, use {include core from ...} for HTML and {include script from ...} for JavaScript.

Example (In page template):

<!-- Include HTML content -->
{include core from 'partials/components/newsletter-form/core.latte',
	buttonText => 'Get updates',
	showNameField => true
}

<!-- Later, typically at the end of the page -->
{include script from 'partials/components/newsletter-form/core.latte',
	buttonText => 'Get updates',
	showNameField => true
}

Example (Incorrect):

<!-- DO NOT include the whole file directly -->
{include 'partials/components/newsletter-form/core.latte'}

<!-- DO NOT include sub-components directly from outside -->
{include 'partials/components/newsletter-form/form.latte'}

Summary:

• Complex components MUST have their own folder with kebab-case naming.
• core.latte MUST contain {block core} and optionally {block script}.
• Include using {include core from ...} and {include script from ...}.
• Sub-components are only included from within core.latte.