Chill-project/chill-bundles
6
0
Fork 0
mirror of https://gitlab.com/Chill-Projet/chill-bundles.git synced 2025-11-24 20:58:31 +00:00
Code Issues Actions Projects Releases Wiki Activity

Fix formatting issues

Browse Source
This commit is contained in:
Julie Lenaerts
2025-11-24 11:49:54 +01:00
parent 82cb83c561
commit 449c5ba4f2
22 changed files with 197 additions and 1312 deletions
Download Patch File Download Diff File Expand all files Collapse all files

109
docs/source/bundles/custom-fields.md
View File

@@ -1,11 +1,3 @@
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU
Free Documentation License".
## Custom fields bundle
This bundle provides the ability to add custom fields to existing entities.
@@ -14,14 +6,10 @@ Those custom fields contains extra data and will be stored in the DB, along with
In the database, custom fields are stored in json format.
The full specification discussed [here. ](https://redmine.champs-libres.coop/issues/239)
[JSON Type on postgresql documentation ](http://www.postgresql.org/docs/9.3/static/datatype-json.html)
The documentation of json type, which is used to store data in the database.
The full specification discussed [here](https://redmine.champs-libres.coop/issues/239)
:depth: 4
:local:
[JSON Type on postgresql documentation](http://www.postgresql.org/docs/9.3/static/datatype-json.html)
The documentation of json type, which is used to store data in the database.
### Custom Fields concepts
@@ -33,12 +21,12 @@ Automatically, those fields are added at the person form. They are also printed
##### Custom fields and custom fields group
Custom fields are associated to a custom fields group. When a user want to add custom fields on an entity, he must first create a custom fields group and associate this field with an entity. Then he may add add custom fields to this groups.
Custom fields are associated to a custom fields group. When a user want to add custom fields on an entity, he must first create a custom fields group and associate this field with an entity. Then he may add add custom fields to this groups.
Some entities needs a **default** custom fields group. For instance, the default custom fields group will be printed on the main form for person, and will be appended on the main person view. Some bundle does not use this feature (i.e. the `report` bundle).
In the future of the `person bundle`, other custom fields group will be added in forms accessible from the menu, allowing users to completely customize and separate their entities.
### Allow custom fields on an entity
As a developer, you must allow your users to add custom fields on your entities.
@@ -48,31 +36,33 @@ As a developer, you must allow your users to add custom fields on your entities.
##### Create a json field on your entity
Declare a json field in your database :
```bash
Chill\CustomFieldsBundle\Entity\BlopEntity:
type: entity
# ...
fields:
cFData:
type: json_array
```
Create the field accordingly in the class logic :
```bash
namespace Chill\CustomFieldsBundle\Entity;
/**
* BlopEntity
*/
class BlopEntity
{
/**
* @var array
*/
private $cFData;
/**
* You must set a setter in order to save automatically custom
* You must set a setter in order to save automatically custom
* fields from forms, using Form Component
*
* @param array $cFData
@@ -83,9 +73,9 @@ Create the field accordingly in the class logic :
$this->cFData = $cFData;
return $this;
}
/**
* You also must create a getter in order to let Form
* You also must create a getter in order to let Form
* component populate form fields
*
* @return array
@@ -94,7 +84,8 @@ Create the field accordingly in the class logic :
{
return $this->cFData;
}
```
##### Declare your customizable entity in configuration
This step is necessary to allow user to create custom fields group associated with this entity.
@@ -112,22 +103,25 @@ This method is discouraged but explained first as it helps to undersand the reco
Add those file under `chill_custom_fields` section :
```yaml
chill_custom_fields:
customizables_entities:
- { class: Chill\YourBundleBundle\Entity\BlopEntity, name: blop_entity }
```
* The `name` allow you to define a string which is translatable. This string will appears when chill's admin will add/retrieve new customFieldsGroup.
* The class, which is a full FQDN class path
Automatically, in DependencyInjection/Extension class (recommended)
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
This is the recommended way for declaring customizable classes.
This is the recommended way for declaring customizable classes.
You can prepend configuration of `custom fields bundle` from the class `YourBundle\DependencyInjection\YourBundleExtension`. **Note** that you also have to implements `Symfony\Component\DependencyInjection\Extension\PrependExtensionInterface` on this class to make the `prepend` function being taken into account.
Example here :
Example here :
```php
class ChillYourBundleExtension extends Extension implements PrependExtensionInterface
{
/**
@@ -141,16 +135,17 @@ Example here :
}
$container->prependExtensionConfig('chill_custom_fields',
array('customizables_entities' =>
array('customizables_entities' =>
array(
array(
'class' => 'Chill\YourBundleBundle\Entity\BlopEntity',
'class' => 'Chill\YourBundleBundle\Entity\BlopEntity',
'name' => 'blop_entity',)
)
)
);
}
}
```
* The `name` allow you to define a string which is translatable. This string will appears when chill's admin will add/retrieve new customFieldsGroup.
* The class, which is a full FQDN class path
@@ -162,19 +157,22 @@ Example here :
You may add options to the groups associated with an entity.
In `config.yml` the declaration should be :
In `config.yml` the declaration should be :
```yaml
chill_custom_fields:
customizables_entities:
-
-
class: Chill\YourBundleBundle\Entity\BlopEntity
name: BlopEntity
options:
# this will create a "myFieldKey" field as text, with a maxlength attribute to 150 (see http://symfony.com/doc/master/reference/forms/types/text.html)
myFieldKey: {form_type: text, form_options: {attr: [maxlength: 150]}}
myFieldKey: {form_type: text, form_options: {attr: [maxlength: 150]}}
```
In the `PrependExtensionInterface::prepend` function, the options key will be added in the configuration definition :
In the `PrependExtensionInterface::prepend` function, the options key will be added in the configuration definition :
```php
class ChillYourBundleExtension extends Extension implements PrependExtensionInterface
{
/**
@@ -188,10 +186,10 @@ In the `PrependExtensionInterface::prepend` function, the options key will be ad
}
$container->prependExtensionConfig('chill_custom_fields',
array('customizables_entities' =>
array('customizables_entities' =>
array(
array(
'class' => 'Chill\YourBundleBundle\Entity\BlopEntity',
'class' => 'Chill\YourBundleBundle\Entity\BlopEntity',
'name' => 'BlopEntity',
'options' => array(
'myFieldKey' => [ 'form_type' => 'text', 'form_options' => [ 'attr' => [ 'maxlength' => 150 ] ]
@@ -201,9 +199,11 @@ In the `PrependExtensionInterface::prepend` function, the options key will be ad
);
}
}
**Example :** the entity `Report` from **ReportBundle** has to pick some custom fields belonging to a group to print them in *summaries* the timeline page. The definition will use the special type `custom_fields_group_linked_custom_field` which will add a select input with all fields associated with the current custom fields group :
```
**Example :** the entity `Report` from **ReportBundle** has to pick some custom fields belonging to a group to print them in *summaries* the timeline page. The definition will use the special type `custom_fields_group_linked_custom_field` which will add a select input with all fields associated with the current custom fields group :
```php
class ChillReportExtension extends Extension implements PrependExtensionInterface
{
/**
@@ -218,15 +218,15 @@ In the `PrependExtensionInterface::prepend` function, the options key will be ad
}
$container->prependExtensionConfig('chill_custom_fields',
array('customizables_entities' =>
array('customizables_entities' =>
array(
array(
'class' => 'Chill\ReportBundle\Entity\Report',
'class' => 'Chill\ReportBundle\Entity\Report',
'name' => 'ReportEntity',
'options' => array(
'summary_fields' => array(
'form_type' => 'custom_fields_group_linked_custom_fields',
'form_options' =>
'form_options' =>
[
'multiple' => true,
'expanded' => false
@@ -238,12 +238,13 @@ In the `PrependExtensionInterface::prepend` function, the options key will be ad
);
}
}
```
Note that `custom_fields_group_linked_custom_fields` does not create any input on `CustomFieldsGroup` creation : there aren't any fields associated with the custom fields just after the group creation... You have to add custom fields and associate them with the newly created group to see them appears.
### Rendering custom fields and custom fields group in a template
Each custom field can be `active` or not. Only `active` custom fields has to be dislayed.
Each custom field can be `active` or not. Only `active` custom fields has to be dislayed.
For rendering custom fields, two function are available :
@@ -271,12 +272,14 @@ Examples
The signature is :
* array **$fields** the array raw, as stored in the db
* CustomField **$customField** a customField instance
* CustomField **$customField** a customField instance
* string **$documentType** the type of document. Default to `html`.
Examples:
```bash
{{ chill_custom_field_widget(entity.customFields, customField) }}
```
##### chill_custom_field_is_empty
@@ -298,14 +301,17 @@ The signature is :
* array **$fields** the array raw, as stored in the db
* CustomFieldsGroup **$customFieldsGroup** the custom field group to render
```bash
{{ chill_custom_fields_group_widget(entity.cFData, entity.customFieldsGroup) }}
```
### Custom Fields's form
You should simply use the 'custom_field' type in a template, with the group you would like to render in the `group` option's type.
Example :
Example :
```php
namespace Chill\ReportBundle\Form;
use Symfony\Component\Form\AbstractType;
@@ -324,14 +330,14 @@ Example :
$builder
->add('user')
->add('date', 'date',
->add('date', 'date',
array('required' => true, 'widget' => 'single_text', 'format' => 'dd-MM-yyyy'))
#add the custom fields :
->add('cFData', 'custom_field',
->add('cFData', 'custom_field',
array('attr' => array('class' => 'cf-fields'), 'group' => $options['cFGroup']))
;
}
/**
* @param OptionsResolverInterface $resolver
*/
@@ -360,22 +366,25 @@ Example :
return 'chill_reportbundle_report';
}
}
```
### Available configuration
Those options are available in the configuration, under the `chill_custom_field` key.
Example :
```yaml
chill_custom_field:
show_empty_values_in_views: false
```
show_empty_values_in_views *boolean*:
Allow to hide / show empty values in views. The aim of this configuration parameter is to hide (or show) empty values when :term:`custom fields group` are rendered.
Default value : `true`
### Glossary
custom fields group
A group of custom fields
A group of custom fields