Modula Plugin Template System

Developer Documentation

Welcome to the Modula developer platform guide. This documentation explains how third-party developers can build components, widgets, cards, layouts, and tabs for the Modula system safely and modularly, integrating with our Smarty-based templating engine.

Folder Structure

Developers create plugins placed under the /plugins/ directory. Each plugin follows this folder layout:

/plugins/
  /yourplugin/
    plugin.json
    /components/
      your_component.tpl
    /widgets/
      your_widget.tpl
    /cards/
      your_card.tpl
    /layouts/
      your_layout.tpl
    /tabs/
      your_tab.tpl

All template files (.tpl) should reside inside their respective subfolders.

Smarty Resource Registration and Resolution

Modula automatically scans the /plugins/ folder and core folders to locate template files for the following resource types:

• component:
• widget:
• cards:
• layouts:
• tabs:

When Smarty loads a template like {include file="component:badge_verified.tpl"}, the system searches:

1. Core folder (e.g., /COMPONENTS/)
2. Each plugin’s corresponding subfolder (e.g., /plugins/yourplugin/components/)

Smarty Resource Class Example

Here’s a simplified PHP example showing how the component resource loader searches multiple paths:

<?php
class Smarty_Resource_Component extends \Smarty\Resource\CustomPlugin {
  protected function fetch($name, &$source, &$mtime) {
    $paths = [];

    // Core components folder
    $paths[] = ABSPATH . 'COMPONENTS/' . $name;

    // Search plugins
    $pluginDir = ABSPATH . 'plugins/';
    foreach (glob($pluginDir . '*', GLOB_ONLYDIR) as $plugin) {
      $paths[] = $plugin . '/components/' . $name;
    }

    // Find first existing template
    foreach ($paths as $path) {
      $real = realpath($path);
      if ($real && file_exists($real)) {
        $source = file_get_contents($real);
        $mtime = filemtime($real);
        return;
      }
    }

    // Not found fallback
    $source = "<!-- Component '{$name}' not found -->";
    $mtime = time();
  }
}

Repeat similarly for widget, cards, layouts, and tabs, adjusting the subfolder name accordingly.

Using Templates in Smarty

Developers can include their templates inside other templates or pages using the resource syntax:

{include file="component:badge_verified.tpl" label="Verified" type="blue" icon="check"}
{include file="widget:social_feed.tpl" source="modula" limit=5}
{include file="cards:team_card.tpl" user_id=123 show_email=true}
{include file="layouts:main_layout.tpl" page_title="Dashboard" show_sidebar=true}
{include file="tabs:profile_tabs.tpl" active_tab="info" user_id=123 editable=true}

All parameters passed (e.g., label, type) become Smarty variables accessible inside the template file.

Example: Accessing Passed Variables

Inside badge_verified.tpl, you can use the variables like this:

<span class="badge badge-{$type|default:'default'}" title="{$tooltip|default:''}">
  {if $icon}<i class="icon icon-{$icon}"></i>{/if}
  {$label|default:'Badge'}
</span>

Plugin Manifest (Optional)

Developers can add a plugin.json manifest file to describe their plugin:

{
  "name": "Cool Plugin",
  "author": "DevX",
  "version": "1.0.0",
  "resources": {
    "components": ["badge_verified.tpl"],
    "widgets": ["social_feed.tpl"],
    "cards": ["team_card.tpl"]
  }
}

This manifest can be used by Modula to display info or verify plugin contents in the marketplace.

Security and Best Practices

Testing Your Plugin

1. Upload your plugin folder to /plugins/.
2. Access a page or template that includes your resources, e.g.:

{include file="component:badge_verified.tpl" label="Trusted"}

1. Confirm your templates render as expected.

Summary

• Create plugins under /plugins/yourplugin/ with subfolders for resource types.
• Use the resource prefix syntax in Smarty to include templates.
• Pass variables via {include} to customize output.
• Modula automatically scans core and plugin folders to resolve templates.
• Follow security best practices to ensure safe, modular plugins.

For questions or help building your plugin, contact the Modula team.