Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

[Templating] Create documentation for Templating component #1151

Merged
merged 3 commits into from

4 participants

@GromNaN

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))
+ inheritence and object-oriented helper functions.
+
+Installation
+------------
+
+You can install the component in many different ways:
+
+* Use the official Git repository (https://github.com/symfony/Templating);
+* Install it via PEAR ( `pear.symfony.com/Templating`);
+* Install it via Composer (`symfony/templating` on Packagist).
+
+Usage
+-----
+
+The :class:`Symfony\\Component\\Templating\\PhpEngine` class is the entry point
+of the component. It needs a `TemplateNameParser` to convert a template name
@stof
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))
+
+The template inheritence is designed to share layouts with many templates.
+
+.. code-block::php
+
+ <!-- views/layout.php -->
+ <html>
+ <head>
+ <title><?php $view['slots']->output('title', 'Default title') ?></title>
+ </head>
+ <body>
+ <?php $view['slots']->output('_content') ?>
+ </body>
+ </html>
+
+The :method:`Symfony\Templating\PhpEngine::extend` method is called in the
@stof
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
@cordoval cordoval commented on the diff
components/templating.rst
@@ -0,0 +1,97 @@
+.. index::
+ single: Templating
+
+The Templating Component
+=====================

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))
+.. index::
+ single: Templating
+
+The Templating Component
+=====================
+
+ The Templating Component is a PHP template engine providing template
+ inheritence and object-oriented helper functions.
+
+Installation
+------------
+
+You can install the component in many different ways:
+
+* Use the official Git repository (https://github.com/symfony/Templating);
+* Install it via PEAR ( `pear.symfony.com/Templating`);

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 @@
+.. index::
+ single: Templating
+
+The Templating Component
+=====================
+
+ The Templating Component is a PHP template engine providing template
+ inheritence and object-oriented helper functions.

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!

@GromNaN
GromNaN added a note

Do you have any suggestion ?

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
@GromNaN

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

@ghost Unknown commented on the diff
components/templating.rst
((30 lines not shown))
+convert a template name to a template reference and template loader
+(:class:`Symfony\\Component\\templating\\Loader\\LoaderInterface`) to find the
+template associated to a reference.
+
+ use Symfony\Component\Templating\PhpEngine;
+ use Symfony\Component\Templating\TemplateNameParser;
+ use Symfony\Component\Templating\Loader\FilesystemLoader;
+
+ $loader = new FilesystemLoader(__DIR__ . '/views/%name%');
+
+ $view = new PhpEngine(new TemplateNameParser(), $loader);
+
+ echo $view->render('hello.php', array('firstname' => 'Fabien'));
+
+The :method:`Symfony\\Component\\Templating\\PhpEngine::render` method executes
+the file `views/hello.php` and returns the output text.
@ghost
ghost 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
@weaverryan weaverryan merged commit f5e52f8 into from
@weaverryan
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
Commits on Mar 14, 2012
  1. @GromNaN
  2. @GromNaN

    typo

    GromNaN authored
  3. @GromNaN

    Use introduction from README

    GromNaN authored
This page is out of date. Refresh to see the latest.
Showing with 103 additions and 0 deletions.
  1. +1 −0  components/map.rst.inc
  2. +102 −0 components/templating.rst
View
1  components/map.rst.inc
@@ -8,4 +8,5 @@
* :doc:`/components/locale`
* :doc:`/components/process`
* :doc:`/components/routing`
+* :doc:`/components/templating`
* :doc:`/components/yaml`
View
102 components/templating.rst
@@ -0,0 +1,102 @@
+.. index::
+ single: Templating
+
+The Templating Component
+========================

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
+
+ 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.
+
+Installation
+------------
+
+You can install the component in many different ways:
+
+* Use the official Git repository (https://github.com/symfony/Templating);
+* Install it via PEAR (`pear.symfony.com/Templating`);
+* Install it via Composer (`symfony/templating` on Packagist).
+
+Usage
+-----
+
+The :class:`Symfony\\Component\\Templating\\PhpEngine` class is the entry point
+of the component. It needs a template name parser
+(:class:`Symfony\\Component\\templating\\TemplateNameParserInterface`) to
+convert a template name to a template reference and template loader
+(:class:`Symfony\\Component\\templating\\Loader\\LoaderInterface`) to find the
+template associated to a reference.
+
+ use Symfony\Component\Templating\PhpEngine;
+ use Symfony\Component\Templating\TemplateNameParser;
+ use Symfony\Component\Templating\Loader\FilesystemLoader;
+
+ $loader = new FilesystemLoader(__DIR__ . '/views/%name%');
+
+ $view = new PhpEngine(new TemplateNameParser(), $loader);
+
+ echo $view->render('hello.php', array('firstname' => 'Fabien'));
+
+The :method:`Symfony\\Component\\Templating\\PhpEngine::render` method executes
+the file `views/hello.php` and returns the output text.
@ghost
ghost 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
+
+.. code-block::php
+
+ <!-- views/hello.php -->
+ Hello, <?php echo $firstname ?>!
+
+
+Template inheritence with slots
+-------------------------------
+
+The template inheritence is designed to share layouts with many templates.
+
+.. code-block::php
+
+ <!-- views/layout.php -->
+ <html>
+ <head>
+ <title><?php $view['slots']->output('title', 'Default title') ?></title>
+ </head>
+ <body>
+ <?php $view['slots']->output('_content') ?>
+ </body>
+ </html>
+
+The :method:`Symfony\\Templating\\PhpEngine::extend` method is called in the
+sub-template to set its parent template.
+
+.. code-block::php
+
+ <!-- views/page.php -->
+ <?php $view->extend('layout.php') ?>
+
+ <?php $view['slots']->set('title', $page->title) ?>
+
+ <h1>
+ <?php echo $page->title ?>
+ </h1>
+ <p>
+ <?php echo $page->body ?>
+ </p>
+
+To use template inheritence, the :class:`Symfony\\Templating\\Helper\\SlotsHelper`
+helper must be registered.
+
+ use Symfony\Templating\Helper\SlotsHelper;
+
+ $view->set(new SlotsHelper());
+
+ // Retrieve $page object
+
+ echo $view->render('page.php', array('page' => $page));
+
+.. note::
+
+ Multiple levels of inheritence are possible: a layout can extend an other
+ layout.
+
Something went wrong with that request. Please try again.