Skip to content

Commit

Permalink
minor #783 Added a new tutorial about formatting dates and numbers (j…
Browse files Browse the repository at this point in the history 
…aviereguiluz)

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

Discussion
----------

Added a new tutorial about formatting dates and numbers

We decided to create brief and focused tutorials about important backend features to make it easier to find that information. This PR extracts some contents of the original documentation into a new tutorial and adds some new contents.

Commits
-------

7920a23 Added a new tutorial about formatting dates and numbers
  • Loading branch information
@javiereguiluz
javiereguiluz committed Jan 10, 2016
2 parents 470b774 + 7920a23 commit 3b47e18
Show file tree
Hide file tree
Showing 3 changed files with 140 additions and 84 deletions.
1 change: 1 addition & 0 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,7 @@ Documentation
* [Customizing Backend Actions](https://github.com/javiereguiluz/EasyAdminBundle/blob/master/Resources/doc/tutorials/customizing-backend-actions.md)
* [Customizing AdminController](https://github.com/javiereguiluz/EasyAdminBundle/blob/master/Resources/doc/tutorials/customizing-admin-controller.md)
* [Advanced Design Customization](https://github.com/javiereguiluz/EasyAdminBundle/blob/master/Resources/doc/tutorials/advanced-design-customization.md)
* [How to Format Dates and Numbers](https://github.com/javiereguiluz/EasyAdminBundle/blob/master/Resources/doc/tutorials/format-date-number.md)
* [How to Translate the Backend](https://github.com/javiereguiluz/EasyAdminBundle/blob/master/Resources/doc/tutorials/i18n.md)
* [How to Define Custom Actions](https://github.com/javiereguiluz/EasyAdminBundle/blob/master/Resources/doc/tutorials/custom-actions.md)
* [How to Use a WYSIWYG Editor](https://github.com/javiereguiluz/EasyAdminBundle/blob/master/Resources/doc/tutorials/wysiwyg-editor.md)
Expand Down
85 changes: 1 addition & 84 deletions Resources/doc/getting-started/4-views-and-actions.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -269,7 +269,7 @@ These are the options that you can define for each field:
* `css_class` (optional): the CSS class applied to the form field widget
container element in the `edit`, `new` and `show` views. For example, when
using the default Bootstrap based form theme, this value is applied to the
`<div>` element which wraps the label, the widget and the error messages of
`<div>` element which wraps the label, the widget and the error messages of
the field.
* `template` (optional): the name of the custom template used to render the
contents of the field in the `list` and `show` views. This option is fully
Expand Down Expand Up @@ -313,89 +313,6 @@ to learn about all the available options, their usage and allowed values.
> customizations, as explained in the
> [Advanced Design Customization] [advanced-design-customization] tutorial.
### Customize Date Format

By default, these are the formats applied to date properties (read the
[date configuration options](http://php.net/manual/en/function.date.php) page
in the PHP manual in case you don't know the meaning of these formats):

* `date`: `Y-m-d`
* `time`: `H:i:s`
* `datetime`: `F j, Y H:i`

These default formats can be overridden in two ways: globally for all entities
and locally for each entity property. Define the global `formats` option to set
the new formats for all entities (define any or all the `date`, `time` and
`datetime` options):

```yaml
easy_admin:
formats:
date: 'd/m/Y'
time: 'H:i'
datetime: 'd/m/Y H:i:s'
entities:
# ...
```

The value of the `format` option is passed to the `format()` method of the
`DateTime` class, so you can use any of the
[date configuration options](http://php.net/manual/en/function.date.php)
defined by PHP.

The same `format` option can be applied to any date-based property. This local
option always overrides the global formats:

```yaml
easy_admin:
entities:
Customer:
class: AppBundle\Entity\Customer
list:
fields:
- { property: 'dateOfBirth', format: 'j/n/Y' }
# ...
# ...
```

### Customize Number Format

Number related properties (`bigint`, `integer`, `smallint`, `decimal`, `float`)
are displayed using the appropriate formatting according to the locale of your
Symfony application. Use the `format` option to explicitly set the format
applied to numeric properties.

The global `formats` option applies the same formatting for all numeric values:

```yaml
easy_admin:
formats:
# ...
number: '%.2f'
entities:
# ...
```

In this case, the value of the `format` option is passed to the `sprintf()`
function, so you can use any of the
[PHP format specifiers](http://php.net/manual/en/function.sprintf.php).

The same `format` option can be applied to any numeric property. This local
configuration always overrides the global format:

```yaml
easy_admin:
entities:
Product:
class: AppBundle\Entity\Product
list:
fields:
- { property: 'serialNumber', format: '%010s' }
- { property: 'margin', format: '%01.2f' }
# ...
# ...
```

### Customize Boolean Properties

By default, when an entity is editable its boolean properties are displayed in
Expand Down
138 changes: 138 additions & 0 deletions Resources/doc/tutorials/format-date-number.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,138 @@
How to Format Dates and Numbers
===============================

Customizing Date and Time Properties
------------------------------------

### Display-Based Views (`list` and `show`)

By default, these are the formats applied to date and time properties (read the
[date configuration options](http://php.net/manual/en/function.date.php) in the
PHP manual in case you don't understand the meaning of these formats):

* `date`: `Y-m-d`
* `time`: `H:i:s`
* `datetime`: `F j, Y H:i`

These default formats can be overridden in two ways: globally for all entities
and locally for each entity property. The global `formats` option sets the
formats for all entities and properties (define any or all the `date`, `time`
and `datetime` options):

```yaml
easy_admin:
formats:
date: 'd/m/Y'
time: 'H:i'
datetime: 'd/m/Y H:i:s'
entities:
# ...
```

The values of the `date`, `time` and `datetime` options are passed to the
`format()` method of the `DateTime` class, so you can use any of the
[date configuration options](http://php.net/manual/en/function.date.php) defined
by PHP.

Date/time based properties can also define their formatting using the `format`
option. This local option always overrides the global format:

```yaml
easy_admin:
entities:
Customer:
class: AppBundle\Entity\Customer
list:
fields:
- { property: 'dateOfBirth', format: 'j/n/Y' }
# ...
# ...
```

### Form-Based Views (`edit` and `new`)

These views rely on the Symfony Form component to display the form fields used
to set the value for the date/time properties. Use the options defined in the
[DateTimeType](http://symfony.com/doc/current/reference/forms/types/datetime.html),
[DateType](http://symfony.com/doc/current/reference/forms/types/date.html) and
[TimeType](http://symfony.com/doc/current/reference/forms/types/time.html) types
to change their appearance and behavior.

For example, to display your dates as a single `<input>` text element, define
the `date_widget` form field option (commonly used together with `date_format`):

```yaml
easy_admin:
entities:
Product:
edit:
fields:
- { property: 'saleStartsAt', type_options: { date_widget: 'single_text' } }
# ...
```

Customizing Numeric Properties
------------------------------

### Display-Based Views (`list` and `show`)

Numeric properties (`bigint`, `integer`, `smallint`, `decimal`, `float`) are
formatted by default according to the locale of your Symfony application. Use
the `format` option to explicitly set the format applied to numbers.

The global `formats` option applies the same formatting for all entities and
properties:

```yaml
easy_admin:
formats:
# ...
number: '%.2f'
entities:
# ...
```

In this case, the value of the `number` option is passed to the `sprintf()`
function, so you can use any of the
[PHP format specifiers](http://php.net/manual/en/function.sprintf.php).

Numeric properties can also define their formatting using the `format`
option. This local option always overrides the global format:

```yaml
easy_admin:
entities:
Product:
class: AppBundle\Entity\Product
list:
fields:
- { property: 'serialNumber', format: '%010s' }
- { property: 'margin', format: '%01.2f' }
# ...
# ...
```

### Form-Based Views (`edit` and `new`)

These views rely on the Symfony Form component to display the form fields used
to set the value for numeric properties. Use the options defined in the
[NumberType](http://symfony.com/doc/current/reference/forms/types/number.html),
[IntegerType](http://symfony.com/doc/current/reference/forms/types/integer.html),
[MoneyType](http://symfony.com/doc/current/reference/forms/types/money.html) and
[PercentType](http://symfony.com/doc/current/reference/forms/types/percent.html)
types to change their appearance and behavior.

For example, to display a numeric property which stores some price, you can
define the `currency` option of the `MoneyType` form type:

```yaml
easy_admin:
entities:
Product:
edit:
fields:
- { property: 'price', type: 'Symfony\Component\Form\Extension\Core\Type\MoneyType', type_options: { currency: 'EUR' } }
# In Symfony 2.x you can use
# - { property: 'price', type: 'money', type_options: { currency: 'EUR' } }
# ...
```

0 comments on commit 3b47e18

Please sign in to comment.