feature #153 Allow to configure the titles and labels of the pages an…

…d UI elements (javiereguiluz)

This PR was squashed before being merged into the master branch (closes #153).

Discussion
----------

Allow to configure the titles and labels of the pages and UI elements

This PR adds support for some of the basic customizations that aren't still available in EasyAdmin. Read the new documentation to see how it works.

I have 3 questions regarding this PR:

  * How can we add support to include variables as part of the `title`/`label`? What if the title wants to display the `id` or the `title` of the associated entity?
  * The `trans` filter is applied to all titles. Is this enough to provide full translation support? (this question is specially directed to @ogizanagi who raised this question in another issue).
  * The label to create new entities is customized via the `label` option of the `new` action. I don't like the `label` name because it's too generic and it can be confused with `title`. I thought about `button_label` in `new` action or `new_button_label` in `list` action. Thoughts or comments?

Commits
-------

e14a708 Allow to configure the titles and labels of the pages and UI elements

DependencyInjection/EasyAdminExtension.php

@@ -117,13 +117,11 @@ private function processEntitiesConfiguration(array $entitiesConfiguration)
             // copy the original entity configuration to not lose any of its options
             $config = $entityConfiguration;
 
-            // if the common 'form' config is defined, and 'new' or 'edit' config are
-            // undefined, just copy the 'form' config into them to simplify the rest of the code
-            if (isset($config['form']['fields']) && !isset($config['edit']['fields'])) {
-                $config['edit']['fields'] = $config['form']['fields'];
-            }
-            if (isset($config['form']['fields']) && !isset($config['new']['fields'])) {
-                $config['new']['fields'] = $config['form']['fields'];
+            // if the common 'form' config is defined, use its options to complete
+            // the configuration for the 'new' and 'edit' actions
+            if (isset($config['form'])) {
+                $config['new'] = isset($config['new']) ? array_replace($config['form'], $config['new']) : $config['form'];
+                $config['edit'] = isset($config['edit']) ? array_replace($config['form'], $config['edit']) : $config['form'];
             }
 
             // configuration for the actions related to the entity ('list', 'edit', etc.)

Resources/doc/4-customizing-list-action.md

@@ -45,6 +45,75 @@ easy_admin:
 Refer to the [EasyAdmin Configuration Reference](10-configuration-reference.md)
 chapter to check out all the available configuration formats.
 
+Customize the Title of the Page
+-------------------------------
+
+By default, the title of the listing page just displays the name of the entity.
+Define the `title` option to set a custom page title:
+
+```yaml
+# app/config/config.yml
+easy_admin:
+    entities:
+        Customer:
+            class: AppBundle\Entity\Customer
+            list:
+                title: "Most recent customers"
+        # ...
+```
+
+The `title` option can include the following variable:
+
+  * `%entity_name%`, resolves to the class name of the current entity (e.g.
+    `Customer`, `Product`, `User`, etc.)
+
+Beware that, in Symfony applications, YAML values enclosed with `%` and `%`
+have a special meaning. Use two consecutive `%` characters to avoid any issue:
+
+```yaml
+easy_admin:
+    entities:
+        Customer:
+            class: AppBundle\Entity\Customer
+            list:
+                title: '%%entity_name%% listing'
+        # ...
+```
+
+Customize the Label of the Button to Create new Items
+-----------------------------------------------------
+
+Listing page includes a button in the top right part of the page to create new
+items of the same entity. By default, this button displays a generic label that
+includes the name of the entity. Define the `action_label` option of the `new`
+action to change this value:
+
+```yaml
+# app/config/config.yml
+easy_admin:
+    entities:
+        Customer:
+            class: AppBundle\Entity\Customer
+            new:  # <-- define it in the 'new' action, not in the 'list' action
+                action_label: "Add Customer"
+        # ...
+```
+
+Similarly to the page title, this label can also include the `%entity_name%`
+variable to display the class name of the current entity:
+
+```yaml
+# app/config/config.yml
+easy_admin:
+    entities:
+        Customer:
+            class: AppBundle\Entity\Customer
+            new:
+                # use double %% to escape special YAML characters
+                action_label: "Add %%entity_name%%"
+        # ...
+```
+
 Customize the Number of Item Rows Displayed
 -------------------------------------------
 

Resources/doc/5-customizing-show-action.md

@@ -18,6 +18,45 @@ easy_admin:
     # ...
 ```
 
+Customize the Title of the Page
+-------------------------------
+
+By default, the title of the `show` page displays the name of the entity and
+the value of the primary key field. Define the `title` option to set a custom
+page title:
+
+```yaml
+# app/config/config.yml
+easy_admin:
+    entities:
+        Customer:
+            class: AppBundle\Entity\Customer
+            show:
+                title: 'Customer details'
+        # ...
+```
+
+The `title` option can include any of the following two variables:
+
+  * `%entity_name%`, resolves to the class name of the current entity (e.g.
+    `Customer`, `Product`, `User`, etc.)
+  * `%entity_id%`, resolves to the value of the primary key of the entity being
+    displayed. Even if the option is called `entity_id`, it also works for
+    primary keys with names different from `id`.
+
+Beware that, in Symfony applications, YAML values enclosed with `%` and `%`
+have a special meaning. Use two consecutive `%` characters to avoid any issue:
+
+```yaml
+easy_admin:
+    entities:
+        Customer:
+            class: AppBundle\Entity\Customer
+            show:
+                title: 'Customer %%entity_id%% details'
+        # ...
+```
+
 Customize the Order of the Fields
 ---------------------------------
 

Resources/doc/6-customizing-new-edit-actions.md

@@ -1,22 +1,117 @@
 Chapter 6. Customizing the New and Edit Actions
 ===============================================
 
+The `new` action is displayed when creating a new item of the given entity,
+whereas the `edit` action is displayed when editing any entity instance. Both
+actions are pretty similar, so most of the times you apply them the same
+customization.
+
+Instead of duplicating the configuration for both actions, you can define a new
+*virtual* `form` action with the common configuration:
+
+```yaml
+easy_admin:
+    entities:
+        Customer:
+            class: AppBundle\Entity\Customer
+            form:  # <-- 'form' is applied to both 'new' and 'edit' actions
+                fields:
+                    - 'id'
+                    - { property: 'email', type: 'email', label: 'Contact' }
+                    # ...
+    # ...
+```
+
+Any option defined in the `form` action will be copied into the `new` and
+`edit` actions. However, any option defined in the `edit` and `new` action
+overrides the corresponding `form` option. In other words, always use the
+`form` action to define the common configuration, and then define in the `new`
+and `edit` actions just the specific options you want to override:
+
+```yaml
+easy_admin:
+    entities:
+        Customer:
+            class: AppBundle\Entity\Customer
+            form:
+                fields: ['id', 'name', 'email']
+                title:  'Add customer'
+            new:
+                fields: ['name', 'email']
+            edit:
+                title:  'Edit customer'
+    # ...
+```
+
+The above configuration is equivalent to the following:
+
+```yaml
+easy_admin:
+    entities:
+        Customer:
+            class: AppBundle\Entity\Customer
+            new:
+                fields: ['name', 'email']
+                title:  'Add customer'
+            edit:
+                fields: ['id', 'name', 'email']
+                title:  'Edit customer'
+    # ...
+```
+
+Customize the Title of the Page
+-------------------------------
+
+By default, the title of the `edit`/`new` pages displays a very generic title.
+Define the `title` option to set a custom page title:
+
+```yaml
+# app/config/config.yml
+easy_admin:
+    entities:
+        Customer:
+            class: AppBundle\Entity\Customer
+            form:
+                title: 'Modify customer information'
+        # ...
+```
+
+The `title` option can include any of the following two variables:
+
+  * `%entity_name%`, resolves to the class name of the current entity (e.g.
+    `Customer`, `Product`, `User`, etc.)
+  * `%entity_id%`, resolves to the value of the primary key of the entity being
+    edited. Obviously, this variable is not available for the title of the
+    `new` action. Even if the option is called `entity_id`, it also works for
+    primary keys with names different from `id`.
+
+Beware that, in Symfony applications, YAML values enclosed with `%` and `%`
+have a special meaning. Use two consecutive `%` characters to avoid any issue:
+
+```yaml
+easy_admin:
+    entities:
+        Customer:
+            class: AppBundle\Entity\Customer
+            form:
+                title: 'Modify customer %%entity_id%% information'
+        # ...
+```
+
 Customize which Fields are Displayed
 ------------------------------------
 
 By default, the forms used to create and edit entities display all their
 properties. Customize any of these forms for any of your entities using the
-`new` and `edit` options:
+`fields` option:
 
 ```yaml
 easy_admin:
     entities:
         Customer:
             class: AppBundle\Entity\Customer
-            edit:
+            form:
                 fields: ['firstName', 'secondName', 'phone', 'email']
-            new:
-                fields: ['firstName', 'secondName', 'phone', 'email', 'creditLimit']
     # ...
 ```
 
@@ -32,16 +127,14 @@ Customize the Order of the Fields Displayed
 By default, forms show their fields in the same order as they were defined in
 the associated entities. You could customize the fields order just by
 reordering the entity properties, but it's more convenient to just define the
-order using the `fields` option of the `new` and `edit` options:
+order using the `fields` option:
 
 ```yaml
 easy_admin:
     entities:
         Customer:
             class: AppBundle\Entity\Customer
-            edit:
-                fields: ['firstName', 'secondName', 'phone', 'email']
-            new:
+            form:
                 fields: ['firstName', 'secondName', 'phone', 'email']
     # ...
 ```
@@ -61,7 +154,7 @@ easy_admin:
     entities:
         Customer:
             class: AppBundle\Entity\Customer
-            edit:
+            form:
                 fields:
                     - 'id'
                     - { property: 'email', type: 'email', label: 'Contact' }
@@ -86,31 +179,6 @@ These are the options that you can define for form fields:
     For example, to display a big input field, use the Bootstrap 3 class called
     `input-lg`.
 
-Apply the Same Customization to the New and Edit Forms
-------------------------------------------------------
-
-Even if you can define different options for the fields used in the `new` and
-`edit` action, most of the times they will be exactly the same. If that's your
-case, define the options in the special `form` action instead of duplicating
-the `new` and `edit` configuration:
-
-```yaml
-easy_admin:
-    entities:
-        Customer:
-            class: AppBundle\Entity\Customer
-            form:  # <-- 'form' is applied to both 'new' and 'edit' actions
-                fields:
-                    - 'id'
-                    - { property: 'email', type: 'email', label: 'Contact' }
-                    # ...
-    # ...
-```
-
-If `new` or `edit` options are defined, they will always be used, regardless
-of the `form` option. In other words, `form` and `new`/`edit` are mutually
-exclusive options.
-
 Add Custom Doctrine Types to Forms
 ----------------------------------