Extends Zend_Form_Element_File to provide support to keep/remove/replace existing files and to enhance for use with content records. More...

Inheritance diagram for Content_Form_Element_File:

Public Member Functions
	getActionFieldName ()
	Get the name of the action field (which indicates the disposition of the existing file).
	getActionFieldValue ()
	Get the action for the existing file (e.g.
	getContentRecord ()
	Get the associated content record (if set).
	getDefaultDisplayDecorators ()
	Get the default display decorators to use when rendering content elements of this type.
	getExistingFileInfo ()
	Get any available information about an existing file.
	getFileContent ()
	Get the contents of the uploaded file on the server.
	getFileTempName ()
	Get the temporary name of the uploaded file on the server.
	getFormData ()
	Get the form data from which the existing file action will be read.
	getValidators ()
	Retrieve all validators; proxy to adapter.
	hasExistingFile ()
	Determine if this field has an existing file set.
	isRemoved ()
	Determine if the existing file has been marked for removal.
	isReplaced ()
	Determine if the existing file has been marked for replacement.
	isValid ($value, $context=null)
	Validate upload Overridden to handle content edit's "keep existing file" option.
	populateFromRecord (P4Cms_Record $record)
	Populate the file element from the given record.
	populateRecord (P4Cms_Record $record)
	Set the file value on the given record.
	setContentRecord ($content)
	Set the associated content record for this element.
	setExistingFileInfo ($info, $value=null)
	Set information about an existing file.
	setFormData ($data)
	Set the form data from which the existing file action will be read.
Public Attributes
const	ACTION_KEEP = 'keep'
const	ACTION_REMOVE = 'remove'
const	ACTION_REPLACE = 'replace'
Protected Attributes
	$_contentRecord = null
	$_existingFileInfo = null
	$_formData = null

Detailed Description

Extends Zend_Form_Element_File to provide support to keep/remove/replace existing files and to enhance for use with content records.

Adds options to display a icon for an existing file. Adds method to get the uploaded file contents.

Copyright:: 2011-2012 Perforce Software. All rights reserved

License:: Please see LICENSE.txt in top-level folder of this distribution.

Version:: 2012.2/486814

Member Function Documentation

Content_Form_Element_File::getActionFieldName ( )

Get the name of the action field (which indicates the disposition of the existing file).

Derived from this file element's name.

Returns:: string the name of the 'action' field associated with this file input.

    {
        return $this->getName() . "-existing-file-action";
    }

Content_Form_Element_File::getActionFieldValue ( )

Get the action for the existing file (e.g.

keep, remove, replace). Defaults to 'keep'.

Returns:: string the value of the existing file action field.

    {
        $data   = $this->getFormData();
        $action = $this->getActionFieldName();
        return array_key_exists($action, $data) ? $data[$action] : self::ACTION_KEEP;
    }

Content_Form_Element_File::getContentRecord ( )

Get the associated content record (if set).

Returns:: null|P4Cms_Content the associated content record or null if none set.

Implements P4Cms_Content_EnhancedElementInterface.

    {
        return $this->_contentRecord;
    }

Content_Form_Element_File::getDefaultDisplayDecorators ( )

Get the default display decorators to use when rendering content elements of this type.

Returns:: array decorators configuration array suitable for passing to element setDecorators().

Implements P4Cms_Content_EnhancedElementInterface.

Reimplemented in Content_Form_Element_ImageFile.

    {
        return array(
            array(
                'decorator' => 'DisplayFileLink',
                'options'   => array(
                    'placement' => Content_Form_Decorator_DisplayFileLink::REPLACE
                )
            )
        );
    }

Content_Form_Element_File::getExistingFileInfo ( )

Get any available information about an existing file.

Returns:: array information about an existing file false if no existing file is set.

    {
        if ($this->hasExistingFile()) {
            return $this->_existingFileInfo;
        }

        return false;
    }

Content_Form_Element_File::getFileContent ( )

Get the contents of the uploaded file on the server.

    {
        return file_get_contents($this->getFileTempName());
    }

Content_Form_Element_File::getFileTempName ( )

Get the temporary name of the uploaded file on the server.

    {
        if (!$this->isUploaded()) {
            throw new Content_Exception("Cannot get file temp name if file not uploaded.");
        }

        $fileInfo = $this->getFileInfo();
        return $fileInfo[$this->getName()]['tmp_name'];
    }

Content_Form_Element_File::getFormData ( )

Get the form data from which the existing file action will be read.

Reads from $_POST directly unless data has been explicitly set via setFormData().

Returns:: array the form data to pull file action from.

    {
        return isset($this->_formData) ? $this->_formData : $_POST;
    }

Content_Form_Element_File::getValidators ( )

Retrieve all validators; proxy to adapter.

Returns:: array

    {
        $adapter    = $this->getTransferAdapter();
        $validators = $adapter->getValidators($this->getName());
        if (!$validators) {
            $validators = $adapter->getValidators();
        }

        return $validators;
    }

Content_Form_Element_File::hasExistingFile ( )

Determine if this field has an existing file set.

Set existing file info to indicate there is an existing file.

Returns:: bool true if there is an existing file; false otherwise.

    {
        if (is_array($this->_existingFileInfo)
            || array_key_exists($this->getActionFieldName(), $this->getFormData())
        ) {
            return true;
        } else {
            return false;
        }
    }

Content_Form_Element_File::isRemoved ( )

Determine if the existing file has been marked for removal.

Returns:: bool true if the file is marked for removal; false otherwise.

    {
        return ($this->getActionFieldValue() === self::ACTION_REMOVE);
    }

Content_Form_Element_File::isReplaced ( )

Determine if the existing file has been marked for replacement.

Returns:: bool true if the file is marked for replacement; false otherwise.

    {
        return ($this->getActionFieldValue() === self::ACTION_REPLACE);
    }

Content_Form_Element_File::isValid	(	$	value,
		$	context = `null`
	)

Validate upload Overridden to handle content edit's "keep existing file" option.

Parameters:

string	$value	File, can be optional, give null to validate all files
mixed	$context	optional context

Returns:: bool

    {
        if ($this->_validated) {
            return true;
        }

        $isRequired = $this->isRequired();

        if ($isRequired
            && $this->hasExistingFile()
            && $this->getActionFieldValue() == self::ACTION_KEEP
        ) {
            $this->setRequired(false);
        }

        $result = parent::isValid($value, $context);

        $this->setRequired($isRequired);

        return $result;
    }

Content_Form_Element_File::populateFromRecord ( P4Cms_Record $ record )

Populate the file element from the given record.

If there is an existing file, set file info on the form.

Parameters:

P4Cms_Record $record the record to populate from

Returns:: P4Cms_Record_EnhancedElementInterface provides fluent interface

Implements P4Cms_Record_EnhancedElementInterface.

    {
        $field = $this->getName();
        
        // nothing to do if record doesn't have a field with this name.
        if (!$record->hasField($field)) {
            return $this;
        }
        
        $metadata = $record->getFieldMetadata($field);
        if (is_array($metadata) && !empty($metadata)) {
            $this->setExistingFileInfo($metadata);
        }
        
        return $this;
    }

Content_Form_Element_File::populateRecord ( P4Cms_Record $ record )

Set the file value on the given record.

File elements require special handling. Three cases:

File is flagged for removal, clear the record value and metadata.
New file is uploaded, set the record value and metadata.
Existing file is 'kept', do nothing.

Parameters:

P4Cms_Record $record the record to populate

Returns:: P4Cms_Record_EnhancedElementInterface provides fluent interface

Implements P4Cms_Record_EnhancedElementInterface.

Reimplemented in Content_Form_Element_ImageFile.

    {
        $field = $this->getName();
        
        // if file is flagged for removal, clear it.
        if ($this->isRemoved()) {
            $record->setValue($field, null);
            $record->setFieldMetadata($field, null);
        }

        // if a new file has been uploaded, store it.
        if ($this->isUploaded() && ($this->isReplaced() || !$this->hasExistingFile())) {
            // grab the name of the temp file, so we can get its filesize
            $tempFilename = $this->getFileTempName();
            
            $record->setValue($field, $this->getFileContent());
            $record->setFieldMetadata(
                $field,
                array(
                    'mimeType' => $this->getMimeType(),
                    'filename' => basename($this->getFileName()),
                    'fileSize' => filesize($tempFilename)
                )
            );
        }
        
        return $this;
    }

Content_Form_Element_File::setContentRecord ( $ content )

Set the associated content record for this element.

Parameters:

P4Cms_Content $content the associated content record for this element.

Implements P4Cms_Content_EnhancedElementInterface.

    {
        $this->_contentRecord = $content;
    }

Content_Form_Element_File::setExistingFileInfo	(	$	info,
		$	value = `null`
	)

Set information about an existing file.

Info can be set by passing an array of key/value pairs, or by passing a string (key) as the first argument and a value for the second argument to set a specific property.

If there is an existing file, but nothing is known about it, pass an empty array. Setting to false or null will indicate there is no existing file (the default case).

File info may contain any key/value pairs. The following keys are used to inform how the file element is rendered:

filename
mimeType
iconUri

Parameters:

array \| string	$info	information about an existing file if a string is given, sets the named key in the file info array.
string	$value	optional - value to set when called with a string (key) for the first param.

Returns:: P4Cms_Form_Element_ImageFile provides fluent interface.

    {
        if (is_string($info)) {
            $key        = $info;
            $info       = $this->_existingFileInfo ?: array();
            $info[$key] = $value;
        }
        
        $this->_existingFileInfo = $info;

        return $this;
    }

Content_Form_Element_File::setFormData ( $ data )

Set the form data from which the existing file action will be read.

Normally it is unnecessary to set this as the element will read from $_POST by default.

Parameters:

array $data the form data to pull the file action from.

Returns:: P4Cms_Form_Element_ImageFile provides fluent interface.

    {
        $this->_formData = $data;
    }

Member Data Documentation

Content_Form_Element_File::$_contentRecord = null [protected]

Content_Form_Element_File::$_existingFileInfo = null [protected]

Content_Form_Element_File::$_formData = null [protected]

const Content_Form_Element_File::ACTION_KEEP = 'keep'

const Content_Form_Element_File::ACTION_REMOVE = 'remove'

const Content_Form_Element_File::ACTION_REPLACE = 'replace'

The documentation for this class was generated from the following file:

application/content/forms/elements/File.php

Content_Form_Element_File Class Reference

Public Member Functions

Public Attributes

Protected Attributes

Detailed Description

Member Function Documentation

Member Data Documentation