Merge pull request #57 from BitBagCommerce/OP-401

OP-401 - functionalities.md updated with developer information

doc/functionalities.md

@@ -17,3 +17,92 @@ When the order is placed, user can now go to the 'Export shipping data' section
 <div align="center">
     <img src="./images/shipping_export.png"/>
 </div>
+
+## Development
+The plugin in itself does not carry functionalities on an `out-of-the-box` basis, but provides an excellent framework for developers to write them.
+
+The skeleton for creating such functionalities can be found under the tab: `USAGE` in the `README.md` file.
+
+> Using the attached skeleton, at least 2 services are needed for the plugin to work:
+- one - handling the form responsible for creating the `shipping gateway`;
+- the other - responsible for handling the `export of the shipment`.
+
+### Shipping Gateway configuration form
+```yaml
+services:
+    app.form.type.frank_martin_shipping_gateway:
+        class: App\Form\Type\FrankMartinShippingGatewayType
+        tags:
+            - { name: bitbag.shipping_gateway_configuration_type, type: "frank_martin_shipping_gateway", label: "Transporter Gateway" }
+```
+
+`label: "Transporter Gateway"` - this label will appear in the create menu when adding a new `shipping gateway`.
+`type: "frank_martin_shipping_gateway"` - this is the name of the `shipping gateway`.
+
+```php
+    // App\EventListener\FrankMartinShippingExportEventListener.php
+    //..
+    /** @var ShippingExportInterface $shippingExport */
+    $shippingExport = $event->getSubject();
+    Assert::isInstanceOf($shippingExport, ShippingExportInterface::class);
+
+    $shippingGateway = $shippingExport->getShippingGateway();
+    Assert::notNull($shippingGateway);
+    // ----------------------------------------------
+    $nameOfTheShippingGateway = $shippingGateway->getCode();
+    // ----------------------------------------------
+```
+
+### Exporting Shipment handling
+```yaml
+services:
+    app.event_listener.frank_martin_shipping_export:
+        class: App\EventListener\FrankMartinShippingExportEventListener
+        arguments:
+            - '@request_stack'
+            - '@filesystem'
+            - '@bitbag.manager.shipping_export'
+            - '%bitbag.shipping_labels_path%'
+        tags:
+            - { name: kernel.event_listener, event: 'bitbag.shipping_export.export_shipment', method: exportShipment }
+```
+
+Method responsible for handling the export of the shipment:
+
+`public function exportShipment(ResourceControllerEvent $event): void`
+
+#### Retrieving a parameter from a form
+
+Example with `IBAN` parameter:
+```php
+// App\Form\Type\FrankMartinShippingGatewayType.php
+//..
+    ->add('iban', TextType::class, [
+        'label' => 'IBAN',
+        'constraints' => [
+            new NotBlank([
+                'message' => 'IBAN number cannot be blank.',
+                'groups' => 'bitbag',
+            ]),
+        ],
+    ])
+//..
+```
+
+Retrieving the `IBAN` parameter from the form when handling `shipment exports`:
+```php
+// App\EventListener\FrankMartinShippingExportEventListener.php
+//..
+    /** @var ShippingExportInterface $shippingExport */
+    $shippingExport = $event->getSubject();
+    Assert::isInstanceOf($shippingExport, ShippingExportInterface::class);
+
+    $shippingGateway = $shippingExport->getShippingGateway();
+    Assert::notNull($shippingGateway);
+
+    $parameterIBANFromTheForm = $shippingGateway->getConfigValue('iban');
+// ..
+```
+
+
+