documentation/manual/en/module_specs/Zend_Validate-Messages.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.validate.messages">
   4     <title>Validation Messages</title>
   5
   6     <para>
   7         Each validator which is based on <classname>Zend_Validate</classname> provides
   8         one or multiple messages in the case of a failed validation. You can use
   9         this information to set your own messages, or to translate existing messages which a
  10         validator could return to something different.
  11     </para>
  12
  13     <para>
  14         These validation messages are constants which can be found at top of each validator class.
  15         Let's look into <classname>Zend_Validate_GreaterThan</classname> for an descriptive example:
  16     </para>
  17
  18     <programlisting language="php"><![CDATA[
  19 protected $_messageTemplates = array(
  20     self::NOT_GREATER => "'%value%' is not greater than '%min%'",
  21 );
  22 ]]></programlisting>
  23
  24     <para>
  25         As you can see the constant <constant>self::NOT_GREATER</constant> refers to the failure and
  26         is used as key, and the message itself is used as value of the message array.
  27     </para>
  28
  29     <para>
  30         You can retrieve all message templates from a validator by using the
  31         <methodname>getMessageTemplates()</methodname> method. It returns you the above array which
  32         contains all messages a validator could return in the case of a failed validation.
  33     </para>
  34
  35     <programlisting language="php"><![CDATA[
  36 $validator = new Zend_Validate_GreaterThan();
  37 $messages  = $validator->getMessageTemplates();
  38 ]]></programlisting>
  39
  40     <para>
  41         Using the <methodname>setMessage()</methodname> method you can set another message to be
  42         returned in case of the specified failure.
  43     </para>
  44
  45     <programlisting language="php"><![CDATA[
  46 $validator = new Zend_Validate_GreaterThan();
  47 $validator->setMessage('Please enter a lower value', Zend_Validate_GreaterThan::NOT_GREATER);
  48 ]]></programlisting>
  49
  50     <para>
  51         The second parameter defines the failure which will be overridden. When you omit this
  52         parameter, then the given message will be set for all possible failures of this validator.
  53     </para>
  54
  55     <sect2 id="zend.validate.messages.pretranslated">
  56         <title>Using pre-translated validation messages</title>
  57
  58         <para>
  59             Zend Framework is shipped with more than 45 different validators with more than 200
  60             failure messages. It can be a tedious task to translate all of these messages. But for
  61             your convenience Zend Framework comes with already pre-translated validation messages.
  62             You can find them within the path <filename>/resources/languages</filename> in your
  63             Zend Framework installation.
  64         </para>
  65
  66         <note>
  67             <title>Used path</title>
  68
  69             <para>
  70                 The resource files are outside of the library path because all of your translations
  71                 should also be outside of this path.
  72             </para>
  73         </note>
  74
  75         <para>
  76             So to translate all validation messages to German for example, all you have to do is to
  77             attach a translator to <classname>Zend_Validate</classname> using these resource files.
  78         </para>
  79
  80         <programlisting language="php"><![CDATA[
  81 $translator = new Zend_Translate(
  82     array(
  83         'adapter' => 'array',
  84         'content' => '/resources/languages',
  85         'locale'  => $language,
  86         'scan' => Zend_Translate::LOCALE_DIRECTORY
  87     )
  88 );
  89 Zend_Validate_Abstract::setDefaultTranslator($translator);
  90 ]]></programlisting>
  91
  92         <note>
  93             <title>Used translation adapter</title>
  94
  95             <para>
  96                 As translation adapter Zend Framework chose the array adapter. It is simple to
  97                 edit and created very fast.
  98             </para>
  99         </note>
 100
 101         <note>
 102             <title>Supported languages</title>
 103
 104             <para>
 105                 This feature is very young, so the amount of supported languages may not be
 106                 complete. New languages will be added with each release. Additionally feel free to
 107                 use the existing resource files to make your own translations.
 108             </para>
 109
 110             <para>
 111                 You could also use these resource files to rewrite existing translations. So you
 112                 are not in need to create these files manually yourself.
 113             </para>
 114         </note>
 115     </sect2>
 116
 117     <sect2 id="zend.validate.messages.limitation">
 118         <title>Limit the size of a validation message</title>
 119
 120         <para>
 121             Sometimes it is necessary to limit the maximum size a validation message can have.
 122             For example when your view allows a maximum size of 100 chars to be rendered on one
 123             line. To simplify the usage, <classname>Zend_Validate</classname> is able to
 124             automatically limit the maximum returned size of a validation message.
 125         </para>
 126
 127         <para>
 128             To get the actual set size use
 129             <methodname>Zend_Validate::getMessageLength()</methodname>. If it is -1, then the
 130             returned message will not be truncated. This is default behaviour.
 131         </para>
 132
 133         <para>
 134             To limit the returned message size use
 135             <methodname>Zend_Validate::setMessageLength()</methodname>. Set it to any integer size
 136             you need. When the returned message exceeds the set size, then the message
 137             will be truncated and the string '<emphasis>...</emphasis>' will be added instead of
 138             the rest of the message.
 139         </para>
 140
 141         <programlisting language="php"><![CDATA[
 142 Zend_Validate::setMessageLength(100);
 143 ]]></programlisting>
 144
 145         <note>
 146             <title>Where is this parameter used?</title>
 147
 148             <para>
 149                 The set message length is used for all validators, even for self defined ones,
 150                 as long as they extend <classname>Zend_Validate_Abstract</classname>.
 151             </para>
 152         </note>
 153     </sect2>
 154 </sect1>
 155 <!--
 156 vim:se ts=4 sw=4 et:
 157 -->