Troubleshooting Render system - xoopscube/legacy GitHub Wiki

The rendering process within the html/modules/legacy/kernel directory represents an important area for exploring
the dual-system bridge and gaining proficiency in XOOPSCube development.
Understanding this directory is key to comprehending template rendering processes and troubleshooting problems,
especially when templates fail to render or are displayed without their associated theme.

Core Components of the Legacy Render System

The rendering process in XOOPSCube Legacy is primarily managed by these classes within the legacy/kernel directory:

  1. XCube_RenderTarget

    • Purpose: Represents a single rendering target. Think of it as a container for the data and template that will be rendered.
    • Responsibilities:
      • Stores the template name (setTemplateName()).
      • Holds variables to be assigned to the template (setAttribute()).
      • Collects the rendered output (getResult()).
    • Key Methods:
      • setTemplateName(string $name): Sets the name of the template file to be used.
      • setAttribute(string $key, mixed $value): Assigns a variable to the template.
      • getResult(): Returns the rendered output as a string.

  2. XCube_RenderSystem

    • Purpose: The core class responsible for managing the rendering process. It knows how to take a RenderTarget and produce the final output.
    • Responsibilities:
      • Creates RenderTarget objects (createRenderTarget()).
      • Renders a RenderTarget (render()).
      • Manages the template engine (Smarty in this case).
    • Key Methods:
      • createRenderTarget(string $name): Creates a new RenderTarget object.
      • render(XCube_RenderTarget $target): Renders the given RenderTarget and returns the output.

  3. XCube_Delegate

    • Purpose: Delegates are used to extend or modify the rendering process. They allow other modules or components to hook into the rendering flow.
    • Responsibilities:
      • Provide a way to modify the RenderTarget before it's rendered.
      • Allow for custom rendering logic.
    • Key Methods:
      • add(): Adds a delegate function.
      • call(): Calls the delegate functions.

  4. XCube_Root

    • Purpose: The central registry for the entire XOOPSCube system. It holds references to all the core components, including the RenderSystem.
    • Responsibilities:
      • Provides access to the RenderSystem (getRenderSystem()).
      • Manages the request, context, and other core objects.
    • Key Methods:
      • getRenderSystem(string $name): Returns the RenderSystem object with the given name (e.g., 'Legacy_RenderSystem').

  5. XCube_Controller:

    • Purpose: Manages the overall request lifecycle, including rendering.
    • Responsibilities:
      • Handles the request.
      • Dispatches to modules.
      • Triggers the rendering process.
    • Key Methods:
      • execute(): Executes the request.
      • The Rendering Process - Step-by-Step

How the rendering process typically works

  1. Request Arrives: A user makes a request to a XOOPSCube page.
  2. Controller Takes Over: The XCube_Controller takes control of the request.
  3. Module Dispatch: The controller determines which module should handle the request and dispatches to it.
  4. Module Logic: The module's code executes, preparing the data that needs to be displayed.
  5. Create Render Target: The module's code gets the RenderSystem from XCube_Root and creates a RenderTarget object:
$root = XCube_Root::getSingleton();
$renderSystem = $root->getRenderSystem('Legacy_RenderSystem');
$renderTarget = $renderSystem->createRenderTarget('main'); // 'main' is a common name

[!CAUTION] Use code with care.

Set Template

The module's code sets the template name on the RenderTarget:

$renderTarget->setTemplateName('mymodule_mytemplate.html');

Assign Variables

The module's code assigns variables to the RenderTarget:

$renderTarget->setAttribute('myVar', $myValue);
$renderTarget->setAttribute('myArray', $myArray);

Delegates

The controller or module might call delegates to allow other components to modify the RenderTarget before rendering.

Render

The controller calls the render() method on the RenderSystem, passing the RenderTarget:

$renderSystem->render($renderTarget);

[!IMPORTANT] Smarty Takes Over: The RenderSystem uses Smarty to process the template.

Smarty

  • Reads the template file.
  • Replaces template variables with the values from the RenderTarget.
  • Executes any Smarty logic in the template.
  • Output: The render() method returns the rendered output as a string.
  • Display: The controller or module displays the rendered output, often by simply echoing it.
  • Get Result: The module can get the result of the render with:
echo $renderTarget->getResult();

Templates Rendered Alone Without the Theme

[!TIP] Troubleshooting templates rendering without their theme.

This usually happens when:

  1. Direct Template Display: Code directly uses $xoopsTpl (the Smarty object) to display a template without going through the RenderTarget system. This bypasses the theme's layout.
  2. Missing Layout: The RenderTarget is not set up to use the theme's layout. This can happen if:
  • The RenderTarget is not created correctly.
  • The template name is not set correctly.
  • The RenderSystem is not configured to use the theme.
  1. Incorrect Delegate Usage: Delegates might be modifying the RenderTarget in a way that removes the theme's layout.
  2. No header and footer: The header and footer are not included, so the theme is not loaded.

How to Ensure Templates Use the Theme

  1. Always Use RenderTarget: Never directly use $xoopsTpl to display templates. Always use the RenderTarget system.
  2. Correct Template Name: Make sure the template name is set correctly on the RenderTarget.
  3. Use the Main Render Target: When creating a RenderTarget, use the 'main' name:
$renderTarget = $renderSystem->createRenderTarget('main');

Include Header and Footer: Make sure that the header and footer are included in the file that renders the template.

require_once XOOPS_ROOT_PATH . '/header.php';
// ...
require_once XOOPS_ROOT_PATH . '/footer.php';

[!WARNING] Check Delegates! If you're using delegates, make sure they're not inadvertently removing the theme's layout.

[!NOTE] Check the controller: Make sure that the controller is correctly rendering the template.

Summary

The key to understanding the rendering process in XOOPSCube Legacy is to grasp the roles of XCube_RenderTarget, XCube_RenderSystem, XCube_Root, XCube_Delegate, and XCube_Controller. By always using the RenderTarget system and following the correct steps, you can ensure that your templates are rendered correctly within the theme's layout.