Field.class.php

<?php

abstract class spunQ_Field implements spunQ_IField {

    public static function normalizeTemplateCssParameter($class) {
        if ($class === NULL) {
            $class = '';
        } elseif (is_array($class)) {
            $description = spunQ_Type::getDescription($class);
            if ($description !== 'array<string>') {
                throw new spunQ_HtmlException('spunQ.html.form.field.UnrecognizedCssDeclaration', $description);
            }
            $class = implode(' ', $class);
        } elseif (!is_string($class)) {
            throw new spunQ_HtmlException('spunQ.html.form.field.UnrecognizedCssDeclaration', spunQ_Type::getDescription($class));
        }
        if (!preg_match('/^[a-z0-9 _-]*$/i', $class)) {
            throw new spunQ_HtmlException('spunQ.html.form.field.InvalidCssDeclaration', $class);
        }
        return $class;
    }

    protected $name;

    protected $container;

    protected $useSubmittedValue = true;

    protected $converters = array();

    protected $validators = array();

    protected $validationMessages = NULL;

    protected $submittedValue = NULL;

    protected $submittedRawValue = NULL;

    public function __construct(spunQ_IFieldContainer $container, $name) {
        $this->name = $name;
        # the $container will call setContainer() on this field,
        # which will set $this->container, so there is no need
        # to set it manually here.
        $container->addField($this);
        return NULL;
    }

    public function setUseSubmittedValue($useSubmittedValue = true) {
        $this->useSubmittedValue = $useSubmittedValue;
        return $this;
    }

    public function getForm() {
        if ($this->container instanceof spunQ_Form) {
            return $this->container;
        }
        return $this->container->getForm();
    }

    public function __clone() {
        $this->container = NULL;
        return NULL;
    }

    public function getContainer() {
        return $this->container;
    }

    public function setContainer(spunQ_IFieldContainer $container) {
        if ($this->container !== NULL) {
            $this->container->removeField($this);
        }
        $this->container = $container;
        return $this;
    }

    public function getName() {
        return $this->name;
    }

    public function getTypePath() {
        return $this->container->getTypeString() . '.' . $this->getTypePathPart();
    }

    public function getTypePathPart() {
        return $this->getName();
    }

    public function addConverter(spunQ_IFieldValueConverter $converter) {
        $this->converters[] = $converter;
        return $this;
    }

    public function addValidator(spunQ_IFieldValidator $validator) {
        $this->validators[] = $validator;
        return $this;
    }

    public function getConverters() {
        return $this->converters;
    }

    public function getValidators() {
        return $this->validators;
    }

    public function getHtmlId($postfix = '') {
        return $this->container->getFieldHtmlId($this, $postfix);
    }

    public function getHtmlName() {
        return $this->container->getFieldHtmlName($this);
    }

    public function getUseSubmittedValue() {
        return $this->useSubmittedValue;
    }

    public function show($value = NULL, $template = NULL, $templateParameters = array(), $htmlIdPostFix = '') {
        if ($template === NULL) {
            $template = $this->getDefaultTemplate();
        }
        $templateParameters['value'] = $this->getDisplayValue($value);
        $templateParameters['field'] = $this;
        $templateParameters['htmlIdPostFix'] = $htmlIdPostFix;
        template($template, $templateParameters);
        return $this;
    }

    public function showValidatorsJs() {
        $formTypeName = $this->getForm()->getTypeString();
        $typePath = $this->getTypePath();
        foreach ($this->validators as $i => $validator) {
            if (!$validator->showJsValidationString($typePath, $typePath . '.')) {
                echo "spunQ.form.registerValidator('$typePath', spunQ.form.validator.AjaxValidator('$formTypeName', '$typePath', $i));\n";
            }
        }
        return $this;
    }

    public function submittedValueValid() {
        if (!$this->container->wasSubmitted()) {
            throw new spunQ_HtmlException('spunQ.html.form.field.NotSubmitted');
        }
        return count($this->getValidationMessages()) === 0;
    }

    public function getSubmittedRawValue() {
        # calling $container->wasSubmitted() will guarantee that
        # _processSubmission() is invoked.
        if (!$this->container->wasSubmitted()) {
            throw new spunQ_HtmlException('spunQ.html.form.field.NotSubmitted');
        }
        return $this->submittedRawValue;
    }

    public function getSubmittedValue() {
        # calling $container->wasSubmitted() will guarantee that
        # _processSubmission() is invoked.
        if (!$this->container->wasSubmitted()) {
            throw new spunQ_HtmlException('spunQ.html.form.field.NotSubmitted');
        }
        return $this->submittedValue;
    }

    public function getValue() {
        return $this->getSubmittedValue();
    }

    public function getDisplayValue($originalValue) {
        if ($this->getUseSubmittedValue() && $this->container->wasSubmitted()) {
            return $this->spunQToRaw($this->getSubmittedValue());
        }
        return $this->spunQToRaw($originalValue);
    }

    public function getValidationMessages() {
        if ($this->validationMessages === NULL) {
            # the next call will ensure that _processSubmission() is invoked if
            # there is a submitted value for this field, which in turn will set
            # $this->validationMessages.
            if ($this->container->wasSubmitted()) {
                # no submitted value for this field, set validationmessages
                # manually
                if ($this->validationMessages === NULL) {
                    $this->validationMessages = array();
                }
            } else {
                $this->validationMessages = array();
            }
        }
        return $this->validationMessages;
    }

    public function getFieldByPath($path) {
        throw new spunQ_HtmlException('spunQ.html.form.FieldDoesNotExist', $this->getTypePath(), implode('.', $path));
    }

    public function _processSubmission(&$rawValue) {
        # Just store relevant values and pass execution to rawToSpunQ().
        $this->submittedRawValue = $rawValue;
        $this->validationMessages = array();
        $result = $this->rawToSpunQ($rawValue);
        $this->submittedValue = $rawValue;
        return $result;
    }

    protected function spunQToRaw($value) {
        foreach ($this->converters as $converter) {
            $value = $converter->convertSpunQToRaw($value);
        }
        return $value;
    }

    protected function rawToSpunQ(&$value) {
        foreach (array_reverse($this->converters) as $converter) {
            $this->validationMessages = $converter->convertRawToSpunQ($this->getTypePath() . '.', $value);
            if (!empty($this->validationMessages)) {
                vdebug($this->getForm()->getName() . ' not submitted (validation message(s) for field "' . $this->getTypePath() . '": "' . implode('", "', $this->validationMessages) . '")');
                return false;
            }
        }
        foreach ($this->validators as $validator) {
            $message = $validator->validate($this->getTypePath() . '.', $value);
            if ($message !== NULL) {
                $this->validationMessages[] = $message;
            }
        }
        if (!empty($this->validationMessages)) {
            vdebug($this->getForm()->getName() . ' submitted, but validation for field "' . $this->getTypePath() . '" failed: "' . implode('", "', $this->validationMessages) . '")');
        }
        return true;
    }

    protected function getDefaultTemplate() {
        return 'spunQ.form.field.text';
    }

}

---