chore: complete upload doc with customization

source/uploading_files.rst

@@ -27,3 +27,61 @@ where:
     and using the :term:`upload token` received for link the new object to
     the file uploaded
 (D) The API responds with  :http:statuscode:`201` as shown in :http:post:`/objects`
+
+Limiting which mime types are allowed
+-------------------------------------
+
+If you want to limit the mime types of files uploadable you can edit the frontend configuration
+in ``app/config/frontend.cfg.php`` defining for every object type an array of regexp used to validate the mime type.
+If no one is defined the rules that you can find in ``bedita-app/config/bedita.ini.php`` will be applied.
+
+An example of configuration could be:
+
+.. code-block:: php
+
+    $config['validate_resource']['mime']['Image'] = array('/image\/png/', '/image\/gif/');
+    $config['validate_resource']['mime']['Video'] = array('/video\/\.*/');
+
+To allow ``image/png`` and ``image/gif`` mime types for ``Image`` object
+and all ``video/*`` mime types for ``Video`` object.
+
+Creating a custom object type supporting upload
+-----------------------------------------------
+
+If you want to use ``/files`` endpoint for your custom object types, your model must follow some conventions:
+
+* it can **extends** ``BeditaSimpleStreamModel`` or ``BeditaStreamModel``
+  as done by core multimedia ``object_type`` (image, video, audio, b_e_file, application).
+
+  In this case the upload will follow the classic BEdita flow putting the file uploaded in the path defined in configuration
+  as ``$config['mediaRoot']`` and reachable from ``$config['mediaUrl']`` url unless you follow the below convention.
+
+* if you need to handle the upload in a way different from BEdita the object model must **implements** two methods:
+
+ .. php:method:: apiUpload(File $source, array $options)
+
+      Used for execute the upload action given the source file. It deals with moving the uploaded file
+      in a target destination returning the target url.
+
+      :param File $source: The instance of CakePHP `File <http://api.cakephp.org/1.3/class-File.html>`_ referred to the
+                           file uploaded
+      :param array $options: An array of options containing:
+    
+                             * ``fileName``: the safe file name obtained from source original file name
+                             * ``hashFile``: the md5 hash of the source file
+                             * ``user``: the user data identified by :term:`access token`
+      :returns: Either false on failure, or the target url where the the file is reachable.
+
+ .. php:method:: apiUploadTransformData(array $uploadData)
+
+      Used for finalize the upload action adding additional fields to object data to save.
+
+      :param array $uploadData: An array of data containing information about file previously uploaded:
+
+                             * ``uri``: the url of file uploaded (that one returned from ``apiUpload()``)
+                             * ``name``: the safe file name
+                             * ``mime_type``: the file mime-type
+                             * ``file_size``:  the file size
+                             * ``original_name``:  the original file name uploaded
+                             * ``hash_file``: the md5 hash of file
+      :returns: array of additional fields to add to object data passed in creation according to ``Model`` table used.