Symbol

What are Symbols?

Symbols are reusable PHP components in FanCoolo that you create in the WordPress admin and inject into your blocks using React-like syntax.

Key Characteristics

• Taxonomy-based: Created as Funculo Items with taxonomy term “symbols”
• React-like syntax: Used in blocks as <Button />, <Card />, etc.
• Server-side rendering: Processed to PHP at render time
• Attribute-driven: Accept attributes to create variations (Primary, Outline, Ghost, etc.)
• Reusable: One symbol can be used across multiple blocks
• Centralized: Changes to a symbol automatically update all blocks using it

Benefits

• DRY Code – Write once, use everywhere
• Consistent Design – Enforce design system patterns
• Easy Updates – Change symbol once, updates all blocks
• Variations – Use attributes to create multiple variants (Primary/Outline/Ghost buttons)
• Clean Block Code – Blocks stay simple and readable

How Symbols Work

1. Create Symbol in WordPress Admin (Funculo Items → Add New → Type: Symbols)
2. Write PHP Code for the symbol component and add title “button or Button”
3. Save & Generate – FanCoolo generates fancoolo-blocks/symbols/button.php
4. Use in Blocks – Add <Button /> in block PHP code
5. Render Time – SymbolProcessor converts <Button /> to the symbol’s PHP output

Naming Convention

Symbol Post Title	Generated File	Usage in Block
Button	button.php	<Button />
card	card.php	<Card />
Product Card	product-card.php	<ProductCard />
Social icon	social-icon.php	<SocialIcon />

Rule: PascalCase in blocks → kebab-case files

Defining Attributes

By default a symbol just outputs static markup. To make it configurable — so the same symbol can render a Primary, Outline, or Ghost button — you define attributes.

Symbols use the same Attributes Manager as blocks. Open a symbol and switch to the Attributes tab:

1. Click “+ Add attribute”
2. Choose the Type (Text, Number, Toggle, Select, etc.)
3. Enter the Attribute name in camelCase (e.g. text, type, size)
4. For Select or Radio, click “+ Add Option” to add the available choices
5. Save the symbol

The attributes you define are stored with the symbol and become the fields users see when they drop the symbol into a block.

Available Types

The same set as block attributes: Text, Textarea, Number, Range, Date, Image, File, Link, Color, Select, Toggle, Checkbox, Radio, Relationship, Post Types, Taxonomies.

Reading Attributes in PHP

Inside the symbol’s PHP, read each value from the $symbol_attrs array — always with a fallback default:

<?php
$text = $symbol_attrs['text'] ?? 'Button text';
$type = $symbol_attrs['type'] ?? 'primary';
?>

The key matches the attribute name you entered in the Attributes tab.

Every attribute is also available as its own variable, named after the attribute in snake_case, so $label holds $symbol_attrs['label'] and $button_url holds $symbol_attrs['buttonUrl']. If the block passes no value, the variable holds the attribute's default. Your own $symbol_attrs['…'] ?? '…' lines keep working.

Type $sym in the symbol's Content editor to pick an attribute and insert the code for it.

Passing Values from a Block

When you use a symbol inside a block — <Button text="Click me" /> — the block editor shows a Symbol Attributes panel in the sidebar. Each symbol instance appears as an accordion listing the attributes you defined, rendered as the matching field (text input, number, toggle, select buttons).

You can either:

• Type a static value — written straight into the tag, e.g. <Button text="Click me" />.
• Bind a block attribute — click the dropdown next to a field and pick one of the block’s own attributes. FanCoolo inserts it as $attributes['…'] (shown with a PHP badge), so the symbol value is driven by the block’s data at render time.
• Pick a WordPress value — choose WordPress values… in the same dropdown. See below.

Changes made in the panel update the symbol tag in the editor live.

WordPress Values

Pass common WordPress values to a symbol without writing PHP.

1. In the Symbol Attributes panel, open the dropdown next to an attribute.
2. Choose WordPress values….
3. Search or pick a value, for example Post title.

The field then shows WP: Post title, and the tag in your template gets a $wp['…'] token:

<Button
    label="$wp['post_title']"
    url="$wp['post_permalink']"
/>

Inside a Query Loop each post gets its own value. When there is no value, for example no term on the page or a logged-out visitor for the user name, the symbol uses its own default.

Group	Values
Post	Post title, Post permalink, Post excerpt, Post date, Post author, Post author URL, Featured image URL, Post ID, Post categories, Post tags
Archive	Archive title, Archive description
Term	Term name, Term link
Site	Site name, Site tagline, Site URL
User	User display name
Date	Current year

Symbol Styles (SCSS)

Each symbol has an SCSS tab next to Content and Attributes. Styles written there are added to every block that uses the symbol, also when the symbol sits inside another symbol. You don't select or import anything.

.fc-button {
    padding: var(--wp--preset--spacing--20) var(--wp--preset--spacing--40);
    background: var(--wp--preset--color--primary);
}

• Global SCSS partials load first, so their variables and mixins work here.
• The block's own SCSS loads after the symbol's, so a block can override how a symbol looks.
• Style the symbol's own class, not the block's class, because the symbol is used in many blocks.
• When you save a symbol, FanCoolo updates the stylesheet of every block that uses it.

Reference Warnings

FanCoolo marks symbol references that no longer match, so you see them before a visitor does. In the Content editor a squiggle appears under the problem, and the message shows when you hover it. The Symbol Attributes panel shows the same problems in amber on the affected tag:

• Symbol not found: no symbol has that tag name. Check the spelling or create the symbol.
• Not defined on this symbol: the tag passes an attribute the symbol does not define. Click × to remove it from the tag, or add the attribute to the symbol.
• Block attribute deleted: the value reads $attributes['x'], but that block attribute no longer exists.
• Unknown WordPress value: the $wp['…'] key is not a known WordPress value.

Inside a symbol, $attributes['x'] always gets a warning, because symbols have no block attributes. Use the symbol's own attributes instead. Warnings never block a save, and FanCoolo does not change your templates for you. See Content for the full list of messages.

Examples – Button

Static

For the excersise perpose we will call (Add title) symbol “Button”

<button>Button text<button>

Add it in block content as <Button />

Simple

<?php

$text = $symbol_attrs['text'] ?? 'Button text';

?>

<button><?php echo esc_html($text); ?></button>

In block content example

`<Button text="Click me" />`

Multiple overwrites

<?php

$text = $symbol_attrs['text'] ?? 'Button text';
$type = $symbol_attrs['type'] ?? 'primary';
$size = $symbol_attrs['size'] ?? 'medium';
$url = $symbol_attrs['url'] ?? '';

// Build CSS class
$class = 'btn btn-' . $type . ' btn-' . $size;

?>

<?php if (!empty($url)): ?>
    <a href="<?php echo esc_url($url); ?>" class="<?php echo esc_attr($class); ?>">
        <?php echo esc_html($text); ?>
    </a>
<?php else: ?>
    <button class="<?php echo esc_attr($class); ?>">
        <?php echo esc_html($text); ?>
    </button>
<?php endif; ?>

In block content examples

<!-- Primary Button (default) -->
<Button text="Submit" />

<!-- Outline Button -->
<Button text="Cancel" type="outline" />

<!-- Ghost Button -->
<Button text="Learn More" type="ghost" />

<!-- Large Primary Button -->
<Button text="Get Started" type="primary" size="large" />

<!-- Link Button -->
<Button text="Read More" type="primary" url="/about" />

Using true

<?php

$text = $symbol_attrs['text'] ?? 'Button text';
$disabled = $symbol_attrs['disabled'] ?? false;

?>

<button <?php echo ($disabled ? 'disabled' : ''); ?>>
        <?php echo esc_html($text); ?>
</button>

<!-- Disabled Button -->
<Button text="Unavailable" disabled="true" />

Examples – Card Symbol with Variations

Create Symbol: “Card”

Symbol PHP:

<?php
$title = $symbol_attrs['title'] ?? '';
$description = $symbol_attrs['description'] ?? '';
$variant = $symbol_attrs['variant'] ?? 'default';
$image = $symbol_attrs['image'] ?? '';

$class = 'card card-' . $variant;
?>

<div class="<?php echo esc_attr($class); ?>">
    <?php if (!empty($image)): ?>
        <img src="<?php echo esc_url($image); ?>" alt="<?php echo esc_attr($title); ?>" class="card-image" />
    <?php endif; ?>

    <div class="card-content">
        <?php if (!empty($title)): ?>
            <h3 class="card-title"><?php echo esc_html($title); ?></h3>
        <?php endif; ?>

        <?php if (!empty($description)): ?>
            <p class="card-description"><?php echo esc_html($description); ?></p>
        <?php endif; ?>
    </div>
</div>

<div class="cards-grid">
    <Card
        title="Feature One"
        description="This is a default card"
        variant="default"
    />

    <Card
        title="Feature Two"
        description="This is an outlined card"
        variant="outline"
    />

    <Card
        title="Feature Three"
        description="This is an elevated card with shadow"
        variant="elevated"
        image="https://example.com/image.jpg"
    />
</div>