Merge pull request #27 from LIN3S/docs/customizations

Docs/customizations

Author: gorkalaucirica

docs/custom_action.md

@@ -1,3 +1,92 @@
 # Creating a custom action
 
-> TODO
+An action is any change that can be performed over a single entity. A creation, an edition, a state change... all of 
+them are considered actions. Due to project requirements a variety of actions may be applied therefore, sometimes is not
+enough to use common CRUD actions. Even though, we provide built in new, edit and delete actions available under 
+`LIN3S\AdminBundle\Action\Type` namespace and work well with Symfony Forms.
+
+To create an action: 
+1. Extend `LIN3S\AdminBundle\Action\ActionType` interface. This `ActionType` will receive  a set of parameters and is 
+expected to return a `Symfony\Component\HttpFoundation\Response` Common responses are a rendered twig template or a 
+`RedirectResponse`.
+1. Add the class to Dependency Container with `lin3s_admin.action` tag name and the desired alias.
+1. Define the action in `admin.yml` in the entity where is going to be used. Example:
+```yaml
+my_entity:
+    class: AdminBundle\Entity\MyEntity
+    name:
+        singular: admin.my_entity.name.singular
+        plural: admin.my_entity.name.plural
+    actions:
+        my_action:
+            type: my_custom_action_alias
+            options:
+                name: MyAction
+                catchable_exceptions: AdminBundle\Entity\MyEntity\Exception\MyCustomException: admin.exception.my_entity.error_message
+    ...
+```
+
+## The parameters
+* entity: The entity affected by this action. 
+* config: The entity configuration.
+* request: The HTTP request
+* options: An array with the declared options.
+
+## Action scope
+Once defined an action for an entity can be attached to global scope of the list or locally to each row of content.
+
+### Global
+Adding an action in global scope creates a top button in list view with the name defined and iterates over all the 
+entity rows calling axecute method per each.
+
+Example: 
+```yaml
+taxon_header:
+    class: AdminBundle\Entity\MyEntity
+    name:
+        ...
+    actions:
+        my_action:
+            type: my_action
+            options:
+                name: MyAction
+    list:
+        fields:
+            ...
+        filters:
+            ...
+        global_actions: ["new", "my_action"]
+```
+
+### Row
+Adding an action as row level creates a button in the action list column per row to launch itself affecting only to the
+row entity where the link button has been triggered.
+
+Example: 
+```yaml
+taxon_header:
+    class: AdminBundle\Entity\TaxonHeader\TaxonHeader
+    name:
+        ...
+    actions:
+        my_action:
+            type: aitor_action
+            options:
+                name: MiAccion
+    list:
+        fields:
+            my_fancy_entity_field:
+                name: admin.my_entity.list.fields.my_fancy_entity_field
+                type: string
+                options:
+                    field: my_fancy_entity_field
+            actions:
+                name: lin3s_admin.list.table.actions
+                type: actions
+                options:
+                    actions: ['edit', 'my_action']
+        filters:
+            ...
+        global_actions: ...
+```
+

docs/custom_list_field.md

@@ -1 +1,29 @@
 # Creating a custom list field
+
+In case you want to write your own list field column rendered you need to implement
+`LIN3S\AdminBundle\ListFields\ListFieldType`. The `render()` method is expected to return an already escaped
+string, can be HTML but be careful as it will be printed in the list without been escaped.
+
+ListFieldTypes are usually generic and need to be associated with an entity in the configuration.
+
+1. Create a new class implementing `LIN3S\AdminBundle\ListFields\ListFieldType`
+1. Add the class to Dependency Container with `lin3s_admin.list_field_type` tag name and the desired alias.
+1. Reference the created service with the alias in the property `type` of list > field > field_name of your `admin.yml`
+
+## Header function
+
+You can handle the header representation of the column within this function, these are the parameters available:
+* options: Array with the name of the field.
+* configuration: The configuration.
+
+## Render function
+
+You can handle the header representation of the row within this function, these are the parameters available:
+* entity: The entity to represent in the row.
+* options: Array with the options declared in admin.yml
+* configuration: The configuration.
+
+## Translation
+
+Translating header or rendered row content is possible adding the argument `"@translator.default"` to receive an 
+instance of  translator ready to use.

docs/custom_list_filter.md

@@ -1 +1,33 @@
 # Creating a custom list filter
+
+A list filter is an implementation that defines how an a filter input has to be rendered. This works together with the
+`AdminRepository` that receives the submitted form that was built using list filter types.
+
+Using filters, you can implement customized search based on any field of your entities, although those already 
+provided `text` and `date` may be enough for most project, perhaps you will need to customize or create more complex 
+filters for your project specific business logic. 
+
+1. Create a new class implementing `LIN3S\AdminBundle\Configuration\Type\ListFilterType`
+1. Add the class to Dependency Container with `lin3s_admin.list_filter_type` tag name and the desired alias.
+1. Reference the created service with the alias in the property `type` of list > filters > field_name of your `admin.yml`
+
+## Render function
+
+You can handle the header representation of the row within this function, these are the parameters available:
+* filter: A `ListFilter` entity of the filter.
+* currentValue: The value to be filtered.
+* options: An array of options.
+
+Text filter example:
+
+```php
+    $attributes = $currentValue !== null ? ' value="' . $currentValue . '"' : '';
+    
+    foreach ($options['attrs'] as $attrName => $attr) {
+        $attributes .= ' ' . $attrName . '="' . $attr . '"';
+    }
+    
+    return sprintf('<input %s type="text" data-filter-field="%s">', $attributes, $filter->field());
+```
+
+

docs/index.md

@@ -19,6 +19,8 @@ Common responses are a rendered twig template or a `RedirectResponse`.
 
 ActionTypes are usually generic and need to be associated with an entity in the configuration.
 
+[More details](custom_action.md)
+
 ###ListFieldType
 
 A list field type is an implementation that defines how a list table column will be rendered. This bundle implements
@@ -31,11 +33,15 @@ string, can be HTML but be careful as it will be printed in the list without bee
 
 ListFieldTypes are usually generic and need to be associated with an entity in the configuration.
 
+[More details](custom_list_field.md)
+
 ###ListFilters
 
 A list filter is an implementation that defines how an a filter input has to be rendered. This works together with the
 `AdminRepository` that receives the submitted form that was built using list filter types.
 
+[More details](custom_list_filter.md)
+
 ### Configuration reference
 
 [Configuration reference docs](configuration_reference.md)