Skip to content
This repository

[Templating] Create documentation for Templating component #1151

Merged
merged 3 commits into from over 2 years ago

5 participants

Jérôme Tamarelle Luis Cordova Ryan Weaver Christophe Coevoet Drak
Jérôme Tamarelle

This component can be very useful standalone and I found it has a very poor documentation.

This page needs 2 others chapiters about Escaping and the AssetHelper.

components/templating.rst
((8 lines not shown))
  8 + inheritence and object-oriented helper functions.
  9 +
  10 +Installation
  11 +------------
  12 +
  13 +You can install the component in many different ways:
  14 +
  15 +* Use the official Git repository (https://github.com/symfony/Templating);
  16 +* Install it via PEAR ( `pear.symfony.com/Templating`);
  17 +* Install it via Composer (`symfony/templating` on Packagist).
  18 +
  19 +Usage
  20 +-----
  21 +
  22 +The :class:`Symfony\\Component\\Templating\\PhpEngine` class is the entry point
  23 +of the component. It needs a `TemplateNameParser` to convert a template name
1
Christophe Coevoet
stof added a note

this should also be a link to the api doc (probably using the interface instead of the class)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
components/templating.rst
((48 lines not shown))
  48 +
  49 +The template inheritence is designed to share layouts with many templates.
  50 +
  51 +.. code-block::php
  52 +
  53 + <!-- views/layout.php -->
  54 + <html>
  55 + <head>
  56 + <title><?php $view['slots']->output('title', 'Default title') ?></title>
  57 + </head>
  58 + <body>
  59 + <?php $view['slots']->output('_content') ?>
  60 + </body>
  61 + </html>
  62 +
  63 +The :method:`Symfony\Templating\PhpEngine::extend` method is called in the
1
Christophe Coevoet
stof added a note

you need to double the \ to escape them otherwise the link to the api doc will not work

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Luis Cordova cordoval commented on the diff
components/templating.rst
... ... @@ -0,0 +1,97 @@
  1 +.. index::
  2 + single: Templating
  3 +
  4 +The Templating Component
  5 +=====================
1
Luis Cordova
cordoval added a note

Please complete the === at the same level of heading so it can render properly

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
components/templating.rst
((1 lines not shown))
  1 +.. index::
  2 + single: Templating
  3 +
  4 +The Templating Component
  5 +=====================
  6 +
  7 + The Templating Component is a PHP template engine providing template
  8 + inheritence and object-oriented helper functions.
  9 +
  10 +Installation
  11 +------------
  12 +
  13 +You can install the component in many different ways:
  14 +
  15 +* Use the official Git repository (https://github.com/symfony/Templating);
  16 +* Install it via PEAR ( `pear.symfony.com/Templating`);
1
Luis Cordova
cordoval added a note

remove extra space after opening parenthesis

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
components/templating.rst
... ... @@ -0,0 +1,97 @@
  1 +.. index::
  2 + single: Templating
  3 +
  4 +The Templating Component
  5 +=====================
  6 +
  7 + The Templating Component is a PHP template engine providing template
  8 + inheritence and object-oriented helper functions.
3
Luis Cordova
cordoval added a note

Please add another paragraph as how different this is from twig and in which cases is this more convenient, or if this is a default case. A clear complete discussion on this can be most helpful. Thanks!

Jérôme Tamarelle
GromNaN added a note

Do you have any suggestion ?

Luis Cordova
cordoval added a note

To start it is not true that it is just a PHP template engine. There are interfaces there, this is just an implementation. The idea is
the infrastructure and then the concrete implementation but it does not limit itself to the concrete implementation.

Templating provides all the tools needed to build any kind of template system.

It provides an infrastructure to load template files and optionally monitor them for changes. It also provides a concrete template engine implementation using PHP with additional tools for escaping and separating templates into blocks and layouts.

I think the use cases are interesting as they could be very specialized, very minimalist or something...

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Jérôme Tamarelle

@cordoval I've updated the PR to put the introduction written by Fabien in the README file.

Luis Cordova

+1

Drak drak commented on the diff
components/templating.rst
((30 lines not shown))
  30 +convert a template name to a template reference and template loader
  31 +(:class:`Symfony\\Component\\templating\\Loader\\LoaderInterface`) to find the
  32 +template associated to a reference.
  33 +
  34 + use Symfony\Component\Templating\PhpEngine;
  35 + use Symfony\Component\Templating\TemplateNameParser;
  36 + use Symfony\Component\Templating\Loader\FilesystemLoader;
  37 +
  38 + $loader = new FilesystemLoader(__DIR__ . '/views/%name%');
  39 +
  40 + $view = new PhpEngine(new TemplateNameParser(), $loader);
  41 +
  42 + echo $view->render('hello.php', array('firstname' => 'Fabien'));
  43 +
  44 +The :method:`Symfony\\Component\\Templating\\PhpEngine::render` method executes
  45 +the file `views/hello.php` and returns the output text.
1
Drak
drak added a note

You know you can just end the sentence with a double colon

the file `views/hello.php` and returns the output text::

Then you can drop the .. code-block::php directives.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Ryan Weaver weaverryan merged commit f5e52f8 into from
Ryan Weaver
Collaborator

Hey Jérôme!

I think this is an excellent start - I've merged this in with changes at sha: 0485b29.

I did also add a placeholder for the two sections you mentioned. At some point, I think we'll need to add more information about the EngineInterface, helpers, globals, caching, etc. I've added those to #955.

Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
This page is out of date. Refresh to see the latest.

Showing 2 changed files with 103 additions and 0 deletions. Show diff stats Hide diff stats

  1. +1 0  components/map.rst.inc
  2. +102 0 components/templating.rst
1  components/map.rst.inc
@@ -8,4 +8,5 @@
8 8 * :doc:`/components/locale`
9 9 * :doc:`/components/process`
10 10 * :doc:`/components/routing`
  11 +* :doc:`/components/templating`
11 12 * :doc:`/components/yaml`
102 components/templating.rst
Source Rendered
... ... @@ -0,0 +1,102 @@
  1 +.. index::
  2 + single: Templating
  3 +
  4 +The Templating Component
  5 +========================
  6 +
  7 + Templating provides all the tools needed to build any kind of template
  8 + system.
  9 +
  10 + It provides an infrastructure to load template files and optionally monitor
  11 + them for changes. It also provides a concrete template engine implementation
  12 + using PHP with additional tools for escaping and separating templates into
  13 + blocks and layouts.
  14 +
  15 +Installation
  16 +------------
  17 +
  18 +You can install the component in many different ways:
  19 +
  20 +* Use the official Git repository (https://github.com/symfony/Templating);
  21 +* Install it via PEAR (`pear.symfony.com/Templating`);
  22 +* Install it via Composer (`symfony/templating` on Packagist).
  23 +
  24 +Usage
  25 +-----
  26 +
  27 +The :class:`Symfony\\Component\\Templating\\PhpEngine` class is the entry point
  28 +of the component. It needs a template name parser
  29 +(:class:`Symfony\\Component\\templating\\TemplateNameParserInterface`) to
  30 +convert a template name to a template reference and template loader
  31 +(:class:`Symfony\\Component\\templating\\Loader\\LoaderInterface`) to find the
  32 +template associated to a reference.
  33 +
  34 + use Symfony\Component\Templating\PhpEngine;
  35 + use Symfony\Component\Templating\TemplateNameParser;
  36 + use Symfony\Component\Templating\Loader\FilesystemLoader;
  37 +
  38 + $loader = new FilesystemLoader(__DIR__ . '/views/%name%');
  39 +
  40 + $view = new PhpEngine(new TemplateNameParser(), $loader);
  41 +
  42 + echo $view->render('hello.php', array('firstname' => 'Fabien'));
  43 +
  44 +The :method:`Symfony\\Component\\Templating\\PhpEngine::render` method executes
  45 +the file `views/hello.php` and returns the output text.
  46 +
  47 +.. code-block::php
  48 +
  49 + <!-- views/hello.php -->
  50 + Hello, <?php echo $firstname ?>!
  51 +
  52 +
  53 +Template inheritence with slots
  54 +-------------------------------
  55 +
  56 +The template inheritence is designed to share layouts with many templates.
  57 +
  58 +.. code-block::php
  59 +
  60 + <!-- views/layout.php -->
  61 + <html>
  62 + <head>
  63 + <title><?php $view['slots']->output('title', 'Default title') ?></title>
  64 + </head>
  65 + <body>
  66 + <?php $view['slots']->output('_content') ?>
  67 + </body>
  68 + </html>
  69 +
  70 +The :method:`Symfony\\Templating\\PhpEngine::extend` method is called in the
  71 +sub-template to set its parent template.
  72 +
  73 +.. code-block::php
  74 +
  75 + <!-- views/page.php -->
  76 + <?php $view->extend('layout.php') ?>
  77 +
  78 + <?php $view['slots']->set('title', $page->title) ?>
  79 +
  80 + <h1>
  81 + <?php echo $page->title ?>
  82 + </h1>
  83 + <p>
  84 + <?php echo $page->body ?>
  85 + </p>
  86 +
  87 +To use template inheritence, the :class:`Symfony\\Templating\\Helper\\SlotsHelper`
  88 +helper must be registered.
  89 +
  90 + use Symfony\Templating\Helper\SlotsHelper;
  91 +
  92 + $view->set(new SlotsHelper());
  93 +
  94 + // Retrieve $page object
  95 +
  96 + echo $view->render('page.php', array('page' => $page));
  97 +
  98 +.. note::
  99 +
  100 + Multiple levels of inheritence are possible: a layout can extend an other
  101 + layout.
  102 +

Tip: You can add notes to lines in a file. Hover to the left of a line to make a note

Something went wrong with that request. Please try again.