Caution: This documentation is for eZ Publish legacy, from version 3.x to 6.x.
For 5.x documentation covering Platform see eZ Documentation Center, for difference between legacy and Platform see 5.x Architecture overview.

Table of contents

Custom output renderers

Supported resource

Service "/content/node/<node_id>" has enabled possibility to output XHTML code generated by an output renderer. In order to include an XHTML string which is a both content and layout representation for a given node you need to add the "OutputFormat=xhtml" parameter into your query string e.g "/content/node/2?OutputFormat=xhtml". As part of the JSON result, an XHTML string will be returned and made available via the renderedOutput key.

Example JSON response with renderedOutput

{"metadata":{"objectName":"Home","classIdentifier":"frontpage","datePublished":1193906012,"dateModified":1193914227,"objectRemoteId":"8a9c9c761004866fb458d89910f52bee","objectId":65,"nodeId":2,"nodeRemoteId":"f3e90596361e31d496d4026eb624c983","fullUrl":"http:\/\/www.example.com"},"links":{"name":"http:\/\/www.example.com\/api\/ezp\/content\/node\/2\/field\/name?OutputFormat=xhtml","billboard":"http:\/\/www.example.com\/api\/ezp\/content\/node\/2\/field\/billboard?OutputFormat=xhtml","left_column":"http:\/\/www.example.com\/api\/ezp\/content\/node\/2\/field\/left_column?OutputFormat=xhtml","center_column":"http:\/\/www.example.com\/api\/ezp\/content\/node\/2\/field\/center_column?OutputFormat=xhtml","right_column":"http:\/\/www.example.com\/api\/ezp\/content\/node\/2\/field\/right_column?OutputFormat=xhtml","bottom_column":"http:\/\/www.example.com\/api\/ezp\/content\/node\/2\/field\/bottom_column?OutputFormat=xhtml","tags":"http:\/\/www.example.com\/api\/ezp\/content\/node\/2\/field\/tags?OutputFormat=xhtml","*":"http:\/\/www.example.com\/api\/ezp\/content\/node\/2\/fields?OutputFormat=xhtml"},"renderedOutput":"<html>\n&nbsp;&nbsp;&nbsp;  <head>\n <title>Test<\/title>\n&nbsp;&nbsp;&nbsp;  <\/head>\n&nbsp;&nbsp;&nbsp; \n  <body><\/body>\n<\/html>","requestedResponseGroups":["Metadata"]}
 

Notice the XHTML code in response output and renderedOutput key.

Custom renderers

The default REST layer comes with an "ezpContentXHTMLRenderer" class which is a default XHTML renderer for the "/content/node/<node_id>" service. However, you can implement your own output renderer. In order to do that you need follow these steps:
1.    Create an empty folder called “ezxcustomrenderer” under the “ <eZ Publish>/extension” location.
2.    Next you need to register your custom output renderer in the rest.ini.append.php. In order to do so inside “ezxcustomrenderer” folder create a “settings” folder with the “rest.ini.append.php” file with following content:

<?php /*
 
    [OutputSettings]
    RendererClass[ezxcr]=ezpContentCustomRenderer
 
    */ ?>

    Where the "RendererClass" key is a type of format or renderer name and value is a PHP class name which implements "ezpRestContentRendererInterface".
3.    Once you have registered your custom renderer class, you need to create a new PHP class which has to implement the "ezpRestContentRendererInterface". Create an empty “classes” folder under the “ezxcustomrenderer” extension. Next, under “classes” folder create “custom_renderer.php” file with the following code:

<?php
 
    class ezpContentCustomRenderer extends ezpRestContentRendererInterface
    {
       /**
        * Creates an instance of a ezpContentCustomRenderer for given content
        *
        * @param ezpContent $content
        */
       public function __construct( ezpContent $content, ezpRestMvcController $controller )
       {
           $this->content = $content;
           $this->controller = $controller;
       }
 
       /**
        * Returns string with rendered content
        *
        * @return string
        */
       public function render()
       {
           return 'Custom Renderer String'; // Return string with your representation of $this->content
     }
    }
 
    ?>

   
4.    Enable the “ezxcustomrenderer” by adding the following to the “ActiveExtensions” list in the “settings/override/site.ini.append.php”.

[ExtensionSettings]
[…]
ActiveExtensions[]=oauth
ActiveExtensions[]=rest
ActiveExtensions[]=ezprestapiprovider
ActiveExtensions[]=ezxcustomrenderer

   
5.    Update the autoload array with a following command from the eZ Publish root folder:

php bin/php/ezpgenerateautoloads.php -e -p

  
6.    If you have followed all steps carefully then you should be ready to test your new output renderer provider by calling "www.example.com/api/ezp/v1/content/node/2?OutputFormat=ezxcr". A simple JSON response should look like:

{"metadata":{"objectName":"Home","classIdentifier":"frontpage","datePublished":1193906012,"dateModified":1193914227,"objectRemoteId":"8a9c9c761004866fb458d89910f52bee","objectId":65,"nodeId":2,"nodeRemoteId":"f3e90596361e31d496d4026eb624c983","fullUrl":"http:\/\/www.example.com"},"links":{"name":"http:\/\/www.example.com\/api\/ezp\/content\/node\/2\/field\/name?OutputFormat=ezxcr","billboard":"http:\/\/www.example.com\/api\/ezp\/content\/node\/2\/field\/billboard?OutputFormat=ezxcr","left_column":"http:\/\/www.example.com\/api\/ezp\/content\/node\/2\/field\/left_column?OutputFormat=ezxcr","center_column":"http:\/\/www.example.com\/api\/ezp\/content\/node\/2\/field\/center_column?OutputFormat=ezxcr","right_column":"http:\/\/www.example.com\/api\/ezp\/content\/node\/2\/field\/right_column?OutputFormat=ezxcr","bottom_column":"http:\/\/www.example.com\/api\/ezp\/content\/node\/2\/field\/bottom_column?OutputFormat=ezxcr","tags":"http:\/\/www.example.com\/api\/ezp\/content\/node\/2\/field\/tags?OutputFormat=ezxcr","*":"http:\/\/www.example.com\/api\/ezp\/content\/node\/2\/fields?OutputFormat=ezxcr"},"renderedOutput":"Custom  Renderer String","requestedResponseGroups":["Metadata"]}

Custom templates (built-in XHTML renderer)

The "ezpContentXHTMLRenderer" class which is a default renderer for the XHTML output for the "/content/node/<node_id>" service allows you to select main template (pagelayout type) used for the XHTML rendering. By default the main template is called "rest_pagelayout.tpl" and configured in "rest.ini.append.php" in section "[ezpRestContentController_viewContent_OutputSettings].Template"

Pagelayout

Pagelayout is a main template used for rendering XHTML output for /content/node/<node_id> service. Because system is expecting rest_pagelayout.tpl template to be present, you need to place it under the design folder used by REST layer e.g design/<design_name>/templates. Consider following example for the rest_pagelayout.tpl:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>REST Demo</title>
</head>
 
<body>
{$module_result.content}
</body>
</html>

Node templates

Output for node content and it's related templates is generated for view called “rest”. Consider following example for article template:

<h1>
    {$node.name|wash()}
</h1>
 
<div class="intro">
    {attribute_view_gui attribute=$node.data_map.intro}
</div>
 
<div class="body">
    {attribute_view_gui attribute=$node.data_map.body}
</div>

Override rules

Since the "node/view/rest" view is used for rendering node content, custom override rules needs to define the "Source" parameter accordingly. The following example demonstrates the template override rule for the article class for REST output:

[rest_article]
Source=node/view/rest.tpl
MatchFile=rest/article.tpl
Subdir=templates
Match[class_identifier]=article

Based on the template override information the eZ Publish template engine will search for "article.tpl" in the "design/<design_name>/override/templates/rest/" folder and use it for the article class instance objects.

Geir Arne Waaler (11/03/2011 12:33 pm)

Xiongjie Chen (31/03/2011 1:01 pm)

Comments

There are no comments.