Contents

Html5FileUpload

This component is part of the "rhubarbphp/module-leaf-html5upload" composer package.

The Html5FileUpload control extends the SimpleFileUpload class to allow use of modern HTML 5 XHR uploading.

If supported the control will present the following elements during upload:

'Cancel Upload' button
Progress bar
Upload speed indication

Standard usage

For simple behaviour using the control is identical to using the SimpleFileUpload control and the same fileUploadedEvent is raised. However you should be aware that the event could be raised either during an XHR request or a normal POST request (if the client doesn't support HTML 5) and so if you are upgrading from SimpleFileUpload it's likely the overall strategy for your page may need to change.

Additional properties and methods

setAllowMultipleUploads(bool): True to enable multiple uploads from a single selection
setIndicators(Html5FileUploadIndicators): Sets an object of type Html5FileUploadIndicators that has the following four boolean flags uploadSpeed, timeRemaining, overallProgress (e.g. 1 of 3), currentFileName. These flags control which elements are present during upload in the indication area.
getIndicators(): Gets the current Html5FileUploadIndicators flag set.

Customising Upload Behaviours

The view bridge of the upload emits events at key integration points allowing for some very individual cases a place to handle these within a parent view bridge.

The client events raised are:

"UploadStarted": Raised when a new file starts uploading. The javascript File object is passed as an argument.
"ProgressReported": Raised when a new upload progress data is available. The javascript File object and a progress structure are passed as arguments.
"UploadCompleted": Raised when a file upload completes. The javascript file object is passed as an argument.
"UploadCancelled": Raised when the user clicks "Cancel Upload"

The other approach is to extend the Leaf, View and ViewBridge to change or wrap the existing behaviours in a new upload control.

Examples

Out-of-the-box upload

SingleUploadExample.php SingleUploadExampleModel.php SingleUploadExampleView.php styles.css

<?php

namespace Rhubarb\Leaf\Controls\Html5Upload\Examples\SingleUpload;

use Rhubarb\Leaf\Leaves\Leaf;
use Rhubarb\Leaf\Leaves\LeafModel;

class SingleUploadExample extends Leaf
{

    /**
     * Returns the name of the standard view used for this leaf.
     *
     * @return string
     */
    protected function getViewClass()
    {
        return SingleUploadExampleView::class;
    }

    /**
     * Should return a class that derives from LeafModel
     *
     * @return LeafModel
     */
    protected function createModel()
    {
        return new SingleUploadExampleModel();
    }
}

<?php

namespace Rhubarb\Leaf\Controls\Html5Upload\Examples\SingleUpload;

use Rhubarb\Leaf\Leaves\LeafModel;

class SingleUploadExampleModel extends LeafModel
{

}

<?php

namespace Rhubarb\Leaf\Controls\Html5Upload\Examples\SingleUpload;

use Rhubarb\Leaf\Controls\Common\FileUpload\UploadedFileDetails;
use Rhubarb\Leaf\Controls\Html5Upload\Html5FileUpload;
use Rhubarb\Leaf\Views\View;

class SingleUploadExampleView extends View
{
    protected function createSubLeaves()
    {
        parent::createSubLeaves();

        $this->registerSubLeaf(
            $upload = new Html5FileUpload("TestUpload")
        );

        $upload->setAllowMultipleUploads(false);
    }

    public function getDeploymentPackage()
    {
        $package = parent::getDeploymentPackage();
        $package->resourcesToDeploy[] =  __DIR__.'/styles.css';

        return $package;
    }

    protected function printViewContent()
    {
        print $this->leaves["TestUpload"];
    }
}

.c-file-upload__label {
    font-weight: bold;
}

.c-file-upload__remaining {
    float: right;
}

.c-file-upload__speed {
    float: right;
}


.c-file-upload__progress {
    background: #e3e3e3;
    display: block;
    position: relative;
    width: 100%;
    height: 10px;
    border-radius: 50px;
    padding: 2px;
    margin: 8px 0;
}


.c-file-upload__progress-bar {
    background: hotpink;
    height: 100%;
    border-radius: 40px;
}


.c-file-upload__button {
    background: #e3e3e3;
    border: none;
    border-radius: 4px;
    padding: 8px 16px;
    cursor: pointer;
}




@media only screen and (max-width: 736px) {
    .c-file-upload__speed {
        display: none;
    }

    .c-file-upload__remaining {
        float: none;
        display: block;
        margin-bottom: 8px;
    }
}

Upload with 'existing file' support

SingleHtml5FileUploadWithPersistenceExample.php SingleHtml5FileUploadWithPersistenceExampleModel.php SingleHtml5FileUploadWithPersistenceExampleView.php

<?php

namespace Rhubarb\Leaf\Controls\Html5Upload\Examples\SingleUploadWithPersistence;

use Rhubarb\Leaf\Controls\Common\FileUpload\Exceptions\FileUploadedException;
use Rhubarb\Leaf\Controls\Common\FileUpload\UploadedFileDetails;
use Rhubarb\Leaf\Leaves\Leaf;

class SingleHtml5FileUploadWithPersistenceExample extends Leaf
{
    /**
    * @var SingleHtml5FileUploadWithPersistenceExampleModel
    */
    protected $model;
    
    protected function getViewClass()
    {
        return SingleHtml5FileUploadWithPersistenceExampleView::class;
    }
    
    protected function createModel()
    {
        $model = new SingleHtml5FileUploadWithPersistenceExampleModel();
        $model->fileUploadedEvent->attachHandler(function(UploadedFileDetails $file){
            if ($this->model->simulateError){
                throw new FileUploadedException("Error simulated", []);
            }
            return $file->originalFilename;
        });

        return $model;
    }
}

<?php

namespace Rhubarb\Leaf\Controls\Html5Upload\Examples\SingleUploadWithPersistence;

use Rhubarb\Crown\Events\Event;
use Rhubarb\Leaf\Leaves\LeafModel;

class SingleHtml5FileUploadWithPersistenceExampleModel extends LeafModel
{
    public $example = "";

    public $simulateError = false;

    public $initialValue = "";

    /**
     * @var Event
     */
    public $fileUploadedEvent;

    public function __construct()
    {
        parent::__construct();

        $this->fileUploadedEvent = new Event();
    }
}

<?php

namespace Rhubarb\Leaf\Controls\Html5Upload\Examples\SingleUploadWithPersistence;

use Rhubarb\Leaf\Controls\Common\Buttons\Button;
use Rhubarb\Leaf\Controls\Common\Checkbox\Checkbox;
use Rhubarb\Leaf\Controls\Common\FileUpload\UploadedFileDetails;
use Rhubarb\Leaf\Controls\Common\Text\TextBox;
use Rhubarb\Leaf\Controls\Html5Upload\SingleHtml5FileUploadWithPersistence;
use Rhubarb\Leaf\Views\View;

class SingleHtml5FileUploadWithPersistenceExampleView extends View
{
    /**
    * @var SingleHtml5FileUploadWithPersistenceExampleModel
    */
    protected $model;

    protected function createSubLeaves()
    {
        parent::createSubLeaves();

        $this->registerSubLeaf(
            $upload = new SingleHtml5FileUploadWithPersistence("example"),
            $initialValue = new TextBox("initialValue"),
            new Checkbox("simulateError"),
            new Button("setValue", "Set", function(){
                $this->model->example = $this->model->initialValue;
            })
        );

        $initialValue->setPlaceholderText("Initial Value");

        $upload->fileUploadedEvent->attachHandler(function(UploadedFileDetails $file){
            return $this->model->fileUploadedEvent->raise($file);
        });
    }

    protected function printViewContent()
    {
        print $this->leaves["example"];
        print $this->leaves["simulateError"]." Simulate error";
        print $this->leaves["initialValue"];
        print $this->leaves["setValue"];
    }
}