LamaPress

Appearance

Data Flow ​

This guide explains how data flows from ACF fields through templates to components in LamaPress.

Table of Contents ​

Overview ​

LamaPress uses an automatic data flow system that:

  1. Scans templates for section usage
  2. Extracts ACF field definitions from component acf.php files
  3. Registers field groups with WordPress/ACF
  4. Retrieves field values during template rendering
  5. Passes data to components via props or variables

Data Flow Architecture ​

Template File → llSection() → Section ACF → Field Registration → Field Retrieval → Component Rendering

Flow Steps:

  1. Template calls llSection(name, key)
  2. System scans template for section calls
  3. System loads section's acf.php file
  4. System generates ACF field group with unique keys
  5. WordPress/ACF registers field group
  6. Template renders and calls llField(name, key)
  7. ACF returns field value
  8. Component receives data and renders

Registration Phase ​

Template Scanning ​

On every request, llSections() is called, which:

  1. Scans template files in components/templates/
  2. Extracts llSection() calls using regex
  3. Identifies section names and keys

Example Template:

php
llSection('hero_basic', 'homepage_hero');
llSection('rich_content', 'homepage_content');

Extracted Data:

  • Section: hero_basic, Key: homepage_hero
  • Section: rich_content, Key: homepage_content

Section Field Extraction ​

For each section found:

  1. Loads acf.php from section directory
  2. Extracts field definitions ($groupFields)
  3. Gets section metadata ($name, $title, $key)

Example acf.php:

php
<?php
$key = 'hero_basic_key';
$name = 'hero_basic';
$title = 'Hero Basic';

$groupFields = [
    [
        'key' => 'title',
        'label' => 'Title',
        'name' => 'title',
        'type' => 'text',
    ],
];

ACF Field Group Generation ​

System generates ACF field groups:

  1. Creates accordion tabs for each section
  2. Prefixes field keys with section key
  3. Registers field group with WordPress

Generated Structure:

php
[
    'key' => 'template_home',
    'title' => 'Fixed content sections',
    'fields' => [
        [
            'key' => 'homepage_hero',
            'label' => '1 Hero Basic',
            'type' => 'accordion',
        ],
        [
            'key' => 'homepage_hero_title',
            'label' => 'Title',
            'name' => 'homepage_hero_title',
            'type' => 'text',
        ],
        // ... more fields
    ],
    'location' => [
        [
            [
                'param' => 'page_template',
                'operator' => '==',
                'value' => 'components/templates/home.php',
            ],
        ],
    ],
]

Rendering Phase ​

Template Execution ​

When WordPress renders a page:

  1. Selects template based on page type
  2. Executes template file (components/templates/*.php)
  3. Calls llStartTemplate() to begin output buffering

Section Loading ​

Template calls llSection(name, key):

php
llSection('hero_basic', 'homepage_hero');

What happens:

  1. System locates components/sections/hero_basic/index.php
  2. Includes the template file
  3. Section template receives $key and $section variables

Field Retrieval ​

Section template retrieves fields using llField():

php
<?php
$title = llField('title', $key, $section);
$content = llField('content', $key, $section);
?>

Field Resolution:

  • If $section provided: Returns $section['title']
  • If only $key provided: Calls get_field($key . '_title')
  • Returns null if field doesn't exist

Component Rendering ​

Sections can load blocks and parts:

php
<?php
llBlock('rich_content', [
    'content' => $content,
    'classes' => 'custom-class',
]);
?>

Data Flow:

  1. Block receives props via extract($props)
  2. Block template accesses variables directly
  3. Block can load parts with data

Data Flow Examples ​

Simple Section ​

Template:

php
llSection('hero_basic', 'homepage_hero');

Section ACF:

php
$groupFields = [
    ['key' => 'title', 'name' => 'title', 'type' => 'text'],
];

Section Template:

php
<?php
$title = llField('title', $key, $section);
?>
<h1><?= esc_html($title) ?></h1>

Result:

  • Field registered as homepage_hero_title
  • Value retrieved via get_field('homepage_hero_title')
  • Rendered in template

Flexible Content ​

Template:

php
llSection('flexible', 'homepage_flexible');

System:

  1. Scans all sections (or specified list)
  2. Creates flexible content layouts
  3. Each layout uses section's fields

Result:

  • CMS shows flexible content field
  • User can add sections dynamically
  • Each section uses its own field definitions

Nested Components ​

Section Template:

php
<?php
$items = llField('items', $key, $section);
foreach ($items as $item) {
    llBlock('card', [
        'title' => $item['title'],
        'content' => $item['content'],
    ]);
}
?>

Data Flow:

  1. Section retrieves repeater field
  2. Loops through items
  3. Passes item data to block
  4. Block renders with data

Best Practices ​

1. Unique Keys ​

Always use unique, descriptive keys:

php
// Good
llSection('hero_basic', 'homepage_hero');
llSection('hero_basic', 'about_hero');

// Bad (conflicts)
llSection('hero_basic', 'hero');
llSection('hero_basic', 'hero');

2. Field Naming ​

Use consistent field names:

php
// Good
$title = llField('title', $key, $section);
$subtitle = llField('subtitle', $key, $section);

// Avoid
$heading = llField('heading', $key, $section);
$subheading = llField('subheading', $key, $section);

3. Data Validation ​

Always check for field existence:

php
<?php
$title = llField('title', $key, $section);
if ($title) {
    echo '<h1>' . esc_html($title) . '</h1>';
}
?>

Next Steps:

Released under the MIT License.

Copyright © 2024 LamaPress