10000 [quick tour] mostly typos by talitakz · Pull Request #6275 · symfony/symfony-docs · GitHub
[go: up one dir, main page]
Skip to content

[quick tour] mostly typos #6275

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 4 commits into from
Closed

[quick tour] mostly typos #6275

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4944be9
mostly typos
talitakz Feb 15, 2016
b90ef42
typo in documentation reference
talitakz Feb 15, 2016
79e02ac
changes according to comments after pull request
talitakz Mar 11, 2016
c7ad331
typo
talitakz Mar 11, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
mostly typos
  • Loading branch information
@talitakz
talitakz committed Feb 15, 2016
commit 4944be90d7e61737a44e20145437b8beaca65892
4 changes: 2 additions & 2 deletions quick_tour/the_architecture.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -257,7 +257,7 @@ Understanding the Cache and Logs
--------------------------------

Symfony applications can contain several configuration files defined in
several formats (YAML, XML, PHP, etc.) Instead of parsing and combining
several formats (YAML, XML, PHP, etc.). Instead of parsing and combining
all those files for each request, Symfony uses its own cache system. In
fact, the application configuration is only parsed for the very first request
and then compiled down to plain PHP code stored in the ``app/cache/``
Expand Down Expand Up @@ -309,4 +3 10000 09,4 @@ need to learn a lot to become a Symfony master. Ready to dig into these
topics now? Look no further - go to the official :doc:`/book/index` and
pick any topic you want.

.. _Composer: https://getcomposer.org
.. _`Composer`: https://getcomposer.org
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is technically not wrong ... but I prefer this syntax too :)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The proposed changed is more common throughout the documentation.

28 changes: 14 additions & 14 deletions quick_tour/the_big_picture.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,12 +29,13 @@ When developing a Symfony application, your responsibility as a developer
is to write the code that maps the user's *request* (e.g. ``http://localhost:8000/``)
to the *resource* associated with it (the ``Homepage`` HTML page).

The code to execute is defined in **actions** and **controllers**. The mapping
between user's requests and that code is defined via the **routing** configuration.
And the contents displayed in the browser are usually rendered using **templates**.
The code to execute is defined in **controllers** also called **actions** which
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The original description of actions/controllers is too short ... but the new is a bit confusing. What about the following?

The code to execute is defined as methods of PHP classes. The methods are
called **actions** and the classes **controllers**, but in practice most
developers use **controllers** to refer to both of them.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this sounds okej. My words were actually based on the paragraf from Controller chapter which goes like this (http://symfony.com/doc/current/book/controller.html#a-simple-controller):

"Note that the controller is the indexAction method, which lives inside a controller class (HelloController). Don't be confused by the naming: a controller class is simply a convenient way to group several controllers/actions together. Typically, the controller class will house several controllers/actions (e.g. updateAction, deleteAction, etc)."

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like your wording @javiereguiluz !

are methods defined in **controller classes** . The mapping between user's requests
and that code is defined via the **routing** configuration. And the contents displayed
in the browser are usually rendered using **templates**.

When you browsed ``http://localhost:8000/app/example`` earlier, Symfony executed
the controller defined in the ``src/AppBundle/Controller/DefaultController.php``
If you'd browsed ``http://localhost:8000/app/example`` for example, Symfony could
executed the controller defined in the ``src/AppBundle/Controller/DefaultController.php``
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. 

When you go to ``http://localhost:8000/app/example``, Symfony will execute the
controller in ``src/AppBundle/Controller/DefaultController.php`` and render the ...

file and rendered the ``app/Resources/views/default/index.html.twig`` template.
In the following sections you'll learn in detail the inner workings of Symfony
controllers, routes and templates.
Expand All @@ -43,7 +44,7 @@ Actions and Controllers
~~~~~~~~~~~~~~~~~~~~~~~

Open the ``src/AppBundle/Controller/DefaultController.php`` file and you'll
see the following code (for now, don't look at the ``@Route`` configuration
see the following code (for now, don't look at the ``@Route()`` configuration
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm -1 on this change, annotations are like classes. We use the () to indicate functions

because that will be explained in the next section)::

namespace AppBundle\Controller;
Expand All @@ -69,7 +70,7 @@ is called ``Default`` and the PHP class is called ``DefaultController``.
The methods defined in a controller are called **actions**, they are usually
associated with one URL of the application and their names are suffixed
with ``Action``. In this example, the ``Default`` controller has only one
action called ``index`` and defined in the ``indexAction`` method.
action called ``index`` and defined in the ``indexAction()`` method.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

so (to make things clear), +1 here :)


Actions are usually very short - around 10-15 lines of code - because they
just call other parts of the application to get or generate the needed
Expand All @@ -85,7 +86,7 @@ Routing
Symfony routes each request to the action that handles it by matching the
requested URL against the paths configured by the application. Open again
the ``src/AppBundle/Controller/DefaultController.php`` file and take a look
at the three lines of code above the ``indexAction`` method::
at the three lines of code above the ``indexAction()`` method::

// src/AppBundle/Controller/DefaultController.php
namespace AppBundle\Controller;
Expand Down Expand Up @@ -138,7 +139,8 @@ The only content of the ``index`` action is this PHP instruction::

The ``$this->render()`` method is a convenient shortcut to render a template.
Symfony provides some useful shortcuts to any controller extending from
the ``Controller`` class.
the base Symfony :class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller`
class.

By default, application templates are stored in the ``app/Resources/views/``
directory. Therefore, the ``default/index.html.twig`` template corresponds
Expand Down Expand Up @@ -194,7 +196,7 @@ environments**.
What is an Environment?
~~~~~~~~~~~~~~~~~~~~~~~

An :term:`Environment` represents a group of configurations that's used
An :term:`environment` represents a group of configurations that's used
to run your application. Symfony defines two environments by default: ``dev``
(suited for when developing the application locally) and ``prod`` (optimized
for when executing the application on production).
Expand Down Expand Up @@ -235,7 +237,7 @@ In this example, the ``config_dev.yml`` configuration file imports the common
with its own options.

For more details on environments, see
":ref:`Environments & Front Controllers <page-creation-environments>`" article.
":ref:`<page-creation-environments>`" section of the book.

Final Thoughts
--------------
Expand All @@ -246,6 +248,4 @@ how Symfony makes it really easy to implement web sites better and faster.
If you are eager to learn more about Symfony, dive into the next section:
":doc:`The View <the_view>`".

.. _Composer: https://getcomposer.org/
.. _executable installer: https://getcomposer.org/download
.. _Twig: http://twig.sensiolabs.org/
.. _`Twig`: http://twig.sensiolabs.org/
9 changes: 5 additions & 4 deletions quick_tour/the_controller.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,9 @@ result of executing any action of any controller is the creation of a
to the user.

So far, all the actions shown in this tutorial used the ``$this->render()``
shortcut to return a rendered response as result. In case you need it, you
can also create a raw ``Response`` object to return any text content::
controller shortcut method to return a rendered response as result. In case
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What about replacing rendered response as result by rendered template as result ?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This too sounds fine. I will make a change.

you need it, you can also create a raw ``Response`` object to return any
text content::

// src/AppBundle/Controller/DefaultController.php
namespace AppBundle\Controller;
Expand Down Expand Up @@ -51,7 +52,7 @@ each value.

Let's create a new action with route variables to show this feature in action.
Open the ``src/AppBundle/Controller/DefaultController.php`` file and add
a new method called ``helloAction`` with the following content::
a new method called ``helloAction()`` with the following content::

// src/AppBundle/Controller/DefaultController.php
namespace AppBundle\Controller;
Expand Down Expand Up @@ -343,4 +344,4 @@ That's all there is to it and I'm not even sure you'll have spent the full
10 minutes. You were briefly introduced to bundles in the first part and
all the features you've learned about so far are part of the core FrameworkBundle.
But thanks to bundles, everything in Symfony can be extended or replaced.
That's the topic of the :doc:`next part of this tutorial <the_architecture>`.
That's the topic of the :doc:`next part of this tutorial <the_architecture>`.
34 changes: 17 additions & 17 deletions quick_tour/the_view.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ about this template engine. This section just gives you a quick overview
of its main concepts.

A Twig template is a text file that can generate any type of content (HTML,
CSS, JavaScript, XML, CSV, LaTeX, etc.) Twig elements are separated from
CSS, JavaScript, XML, CSV, LaTeX, etc.). Twig elements are separated from
the rest of the template contents using any of these delimiters:

``{{ ... }}``
Expand Down Expand Up @@ -50,7 +50,7 @@ Below is a minimal template that illustrates a few basics, using two variables
</body>
</html>

To render a template in Symfony, use the ``render`` method from within a
To render a template in Symfony, use the ``render()`` method from within a
controller. If the template needs variables to generate its contents, pass
them as an array using the second optional argument::

Expand Down Expand Up @@ -160,7 +160,7 @@ Don't forget to check out the official `Twig documentation`_ to learn everything
about filters, functions and tags.

Including other Templates
~~~~~~~~~~~~~~~~~~~~~~~~~
-------------------------
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The original ~~~ is correct in this case because this is a third-level heading (--- is second level).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I propose this change because I don't see why the content under title "Including other Templates" (and "Embedding other Controllers") would be subtitle of the title "Using Tags, Filters and Functions" based on the content. If this decision is based on the fact that include(), render() or controller() are Twig's functions then also other titles like "Creating Links between Pages" and so one should be subtitles of the title "Using Tags, Filters and Functions".

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm fine with this change - I can see both sides


The best way to share a snippet of code between several templates is to
create a new template fragment that can then be included from other templates.
Expand Down Expand Up @@ -190,7 +190,7 @@ using the ``include()`` function:
{% endblock %}

Embedding other Controllers
~~~~~~~~~~~~~~~~~~~~~~~~~~~
---------------------------
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same here.


And what if you want to embed the result of another controller in a template?
That's very useful when working with Ajax, or when the embedded template
Expand All @@ -212,7 +212,6 @@ action of the ``Default`` controller (the ``AppBundle`` part will be explained
later)::

// src/AppBundle/Controller/DefaultController.php

class DefaultController extends Controller
{
public function topArticlesAction()
Expand All @@ -229,31 +228,31 @@ later)::
}

Creating Links between Pages
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
----------------------------

Creating links between pages is a must for web applications. Instead of
hardcoding URLs in templates, the ``path`` function knows how to generate
URLs based on the routing configuration. That way, all your URLs can be
easily updated by just changing the configuration:
hardcoding URLs in templates, the ``path()`` function knows how to generate
relative URLs based on the routing configuration. That way, all your URLs
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"relative" doesn't add anything useful

can be easily updated by just changing the configuration:

.. code-block:: html+twig

<a href="{{ path('homepage') }}">Return to homepage</a>

The ``path`` function takes the route name as the first argument and you
The ``path()`` function takes the route name as the first argument and you
can optionally pass an array of route parameters as the second argument.

.. tip::

The ``url`` function is very similar to the ``path`` function, but generates
The ``url()`` function is very similar to the ``path()`` function, but generates
*absolute* URLs, which is very handy when rendering emails and RSS files:
``<a href="{{ url('homepage') }}">Visit our website</a>``.

Including Assets: Images, JavaScripts and Stylesheets
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-----------------------------------------------------

What would the Internet be without images, JavaScripts and stylesheets?
Symfony provides the ``asset`` function to deal with them easily:
Symfony provides the ``asset()`` function to deal with them easily:

.. code-block:: twig

Expand All @@ -262,10 +261,11 @@ Symfony provides the ``asset`` function to deal with them easily:
<img src="{{ asset('images/logo.png') }}" />

The ``asset()`` function looks for the web assets inside the ``web/`` directory.
If you store them in another directory, read :doc:`this article </cookbook/assetic/asset_management>`
If you store them in another directory, read
:doc:`this article </cookbook/assetic/asset_management>`
to learn how to manage web assets.

Using the ``asset`` function, your application is more portable. The reason
Using the ``asset()`` function, your application is more portable. The reason
is that you can move the application root directory anywhere under your
web root directory without changing anything in your template's code.

Expand All @@ -285,5 +285,5 @@ But I'm getting ahead of myself. First, you need to learn more about the
controller and that's exactly the topic of the :doc:`next part of this tutorial
<the_controller>`. Ready for another 10 minutes with Symfony?

.. _Twig: http://twig.sensiolabs.org/
.. _Twig documentation: http://twig.sensiolabs.org/documentation
.. _`Twig`: http://twig.sensiolabs.org/
.. _`Twig documentation`: http://twig.sensiolabs.org/documentation
0