Admin Page Framework Documentation
  • Package
  • Class
  • Tree

Packages

  • AdminPageFramework
    • FieldType
    • MetaBox
    • Page
    • PostType
    • TaxonomyField

Classes

  • AdminPageFramework
  • AdminPageFramework_Menu
  • AdminPageFramework_Page
  • AdminPageFramework_Setting
  1 <?php
  2 /**
  3  * Admin Page Framework
  4  * 
  5  * http://en.michaeluno.jp/admin-page-framework/
  6  * Copyright (c) 2013-2014 Michael Uno; Licensed MIT
  7  * 
  8  */
  9 if ( ! class_exists( 'AdminPageFramework_Setting' ) ) :
 10 /**
 11  * Provides public methods to add form elements with WordPress Settings API. 
 12  *
 13  * @abstract
 14  * @since       2.0.0
 15  * @extends     AdminPageFramework_Setting_Base
 16  * @package     AdminPageFramework
 17  * @subpackage  Page
 18  * @var         array       $aFieldErrors                       stores the settings field errors.
 19  */
 20 abstract class AdminPageFramework_Setting extends AdminPageFramework_Setting_Base {
 21                                     
 22     /**
 23     * Sets the given message to be displayed in the next page load. 
 24     * 
 25     * This is used to inform users about the submitted input data, such as "Updated successfully." or "Problem occurred." etc. and normally used in validation callback methods.
 26     * 
 27     * <h4>Example</h4>
 28     * <code>if ( ! $bVerified ) {
 29     *       $this->setFieldErrors( $aErrors );      
 30     *       $this->setSettingNotice( 'There was an error in your input.' );
 31     *       return $aOldPageOptions;
 32     *   }</code>
 33     *
 34     * @since            2.0.0
 35     * @since            2.1.2           Added a check to prevent duplicate items.
 36     * @since            2.1.5           Added the $bOverride parameter.
 37     * @since            3.0.0           Changed the scope to public from protected.
 38     * @access           public
 39     * @param            string          the text message to be displayed.
 40     * @param            string          ( optional ) the type of the message, either "error" or "updated"  is used.
 41     * @param            string          ( optional ) the ID of the message. This is used in the ID attribute of the message HTML element.
 42     * @param            integer         ( optional ) false: do not override when there is a message of the same id. true: override the previous one.
 43     * @return           void
 44     */      
 45     public function setSettingNotice( $sMsg, $sType='error', $sID=null, $bOverride=true ) {
 46         
 47         // Check if the same message has been added already.
 48         $aWPSettingsErrors = isset( $GLOBALS['wp_settings_errors'] ) ? ( array ) $GLOBALS['wp_settings_errors'] : array();
 49         $sID = isset( $sID ) ? $sID : $this->oProp->sOptionKey;     // the id attribute for the message div element.
 50 
 51         foreach( $aWPSettingsErrors as $iIndex => $aSettingsError ) {
 52             
 53             if ( $aSettingsError['setting'] != $this->oProp->sOptionKey ) continue;
 54                         
 55             // If the same message is added, no need to add another.
 56             if ( $aSettingsError['message'] == $sMsg ) return;
 57                 
 58             // Prevent duplicated ids.
 59             if ( $aSettingsError['code'] === $sID ) {
 60                 if ( ! $bOverride ) 
 61                     return;
 62                 else    // remove the item with the same id  
 63                     unset( $aWPSettingsErrors[ $iIndex ] );
 64             }
 65                             
 66         }
 67 
 68         add_settings_error( 
 69             $this->oProp->sOptionKey, // the script specific ID so the other settings error won't be displayed with the settings_errors() function.
 70             $sID, 
 71             $sMsg,  // error or updated
 72             $sType
 73         );
 74                     
 75     }
 76 
 77     /**
 78      * Adds the given form section items into the property. 
 79      * 
 80      * The passed section array must consist of the following keys.
 81      * 
 82      * <h4>Example</h4>
 83      * <code>$this->addSettingSections(
 84      *      array(
 85      *          'section_id'    => 'text_fields',
 86      *          'page_slug' => 'first_page',
 87      *          'tab_slug'  => 'textfields',
 88      *          'title' => 'Text Fields',
 89      *          'description'   => 'These are text type fields.',
 90      *          'order' => 10,
 91      *      ),  
 92      *      array(
 93      *          'section_id'    => 'selectors',
 94      *          'page_slug' => 'first_page',
 95      *          'tab_slug'  => 'selectors',
 96      *          'title' => 'Selectors and Checkboxes',
 97      *          'description'   => 'These are selector type options such as dropdown lists, radio buttons, and checkboxes',
 98      *      )</code>
 99      *
100      * @since           2.0.0
101      * @since           3.0.0           Changed the scope to public from protected.
102      * @access          public
103      * @remark          Accepts variadic parameters; the number of accepted parameters are not limited to three.
104      * @remark          The actual registration will be performed in the <em>_replyToRegisterSettings()</em> method with the <em>admin_menu</em> hook.
105      * @remark          The target section tab slug and the target tab slug will be reset once the method returns.
106      * @param           array|string            the section array or the target page slug. If the target page slug is set, the next section array can omit the page slug key.
107      * <strong>Section Array</strong>
108      * <ul>
109      * <li><strong>section_id</strong> - ( required, string ) the section ID. Avoid using non-alphabetic characters except underscore and numbers.</li>
110      * <li><strong>page_slug</strong> - ( optional, string ) the page slug that the section belongs to. If the target page slug is set, it can be omitted.</li>
111      * <li><strong>tab_slug</strong> - ( optional, string ) the tab slug that the section belongs to. The tab here refers to in-page tabs.</li>
112      * <li><strong>section_tab_slug</strong> - ( optional, string ) [3.0.0+] the section tab slug that the section are grouped into. The tab here refers to section tabs.</li>
113      * <li><strong>title</strong> - ( optional, string ) the title of the section.</li>
114      * <li><strong>capability</strong> - ( optional, string ) the <a href="http://codex.wordpress.org/Roles_and_Capabilities">access level</a> of the section. If the page visitor does not have sufficient capability, the section will be invisible to them.</li>
115      * <li><strong>if</strong> - ( optional, boolean ) if the passed value is false, the section will not be registered.</li>
116      * <li><strong>order</strong> - ( optional, integer ) the order number of the section. The higher the number is, the lower the position it gets.</li>
117      * <li><strong>help</strong> - ( optional, string ) the help description added to the contextual help tab.</li>
118      * <li><strong>help_aside</strong> - ( optional, string ) the additional help description for the side bar of the contextual help tab.</li>
119      * <li><strong>repeatable</strong> - ( optional, boolean|array ) [3.0.0+] Indicates whether or not the section is repeatable. To set a minimum/maximum number of sections, pass an array with the key, <em>min</em>, and <em>max</em>. e.g. <em>array( 'min' => 3, 'max' => 10 )</em></li>
120      * </ul>
121      * @param           array                   ( optional ) another section array.
122      * @param           array                   ( optional ) add more section array to the next parameters as many as necessary.
123      * @return          void
124      */     
125     public function addSettingSections( $aSection1, $aSection2=null, $_and_more=null ) {
126         
127         foreach( func_get_args() as $asSection ) $this->addSettingSection( $asSection );
128         
129         // reset the stored target tab slug and the target section tab slug
130         $this->_sTargetTabSlug = null;
131         $this->_sTargetSectionTabSlug = null;
132         
133     }
134     
135     /**
136      * A singular form of the adSettingSections() method which takes only a single parameter.
137      * 
138      * This is useful when adding section arrays in loops.
139      * 
140      * @since           2.1.2
141      * @since           3.0.0           Changed the scope to public from protected.
142      * @access          public
143      * @remark          The actual registration will be performed in the <em>_replyToRegisterSettings()</em> method with the <em>admin_menu</em> hook.
144      * @param           array|string            the section array. If a string is passed, it is considered as a target page slug that will be used as a page slug element from the next call so that the element can be ommited.
145      * @return          void
146      */
147     public function addSettingSection( $asSection ) {
148                 
149         if ( ! is_array( $asSection ) ) {
150             $this->_sTargetPageSlug = is_string( $asSection ) ? $asSection : $this->_sTargetPageSlug;
151             return;
152         } 
153         
154         $aSection = $asSection;
155         $this->_sTargetPageSlug = isset( $aSection['page_slug'] ) ? $aSection['page_slug'] : $this->_sTargetPageSlug;
156         $this->_sTargetTabSlug = isset( $aSection['tab_slug'] ) ? $aSection['tab_slug'] : $this->_sTargetTabSlug;
157         $this->_sTargetSectionTabSlug = isset( $aSection['section_tab_slug'] ) ? $aSection['section_tab_slug'] : $this->_sTargetSectionTabSlug;
158         $aSection = $this->oUtil->uniteArrays( 
159             $aSection, 
160             array( 
161                 'page_slug' => $this->_sTargetPageSlug ? $this->_sTargetPageSlug : null,        // checking the value allows the user to reset the internal target manually
162                 'tab_slug' => $this->_sTargetTabSlug ? $this->_sTargetTabSlug : null,
163                 'section_tab_slug' => $this->_sTargetSectionTabSlug ? $this->_sTargetSectionTabSlug : null,
164             )
165         );  // avoid undefined index warnings.
166         
167         $aSection['page_slug'] = $aSection['page_slug'] ? $this->oUtil->sanitizeSlug( $aSection['page_slug'] ) : ( $this->oProp->sDefaultPageSlug ? $this->oProp->sDefaultPageSlug : null );
168         $aSection['tab_slug'] = $this->oUtil->sanitizeSlug( $aSection['tab_slug'] );
169         $aSection['section_tab_slug'] = $this->oUtil->sanitizeSlug( $aSection['section_tab_slug'] );
170         
171         if ( ! $aSection['page_slug'] ) return; // The page slug is necessary.
172         $this->oForm->addSection( $aSection );
173         
174     }
175     
176     /**
177     * Removes the given section(s) by section ID.
178     * 
179     * This accesses the property storing the added section arrays and removes the specified ones.
180     * 
181     * <h4>Example</h4>
182     * <code>$this->removeSettingSections( 'text_fields', 'selectors', 'another_section', 'yet_another_section' );
183     * </code>
184     * 
185     * @since            2.0.0
186     * @since            3.0.0           Changed the scope to public from protected.
187     * @access           public
188     * @remark           Accepts variadic parameters; the number of accepted parameters are not limited to three.
189     * @remark           The actual registration will be performed in the <em>_replyToRegisterSettings()</em> method with the <em>admin_menu</em> hook.
190     * @param            string          the section ID to remove.
191     * @param            string          ( optional ) another section ID to remove.
192     * @param            string          ( optional ) add more section IDs to the next parameters as many as necessary.
193     * @return           void
194     */  
195     public function removeSettingSections( $sSectionID1=null, $sSectionID2=null, $_and_more=null ) {    
196         
197         foreach( func_get_args() as $_sSectionID ) 
198             $this->oForm->removeSection( $_sSectionID );
199         
200     }
201     
202     /**
203     * Adds the given field array items into the field array property by the given field definition array(s).
204     * 
205     * The field definition array requires specific keys. Refer to the parameter section of this method.
206     *   
207     * <h4>Example</h4>
208     * <code>$this->addSettingFields(
209     *       array(
210     *           'field_id'  =>  'text',
211     *           'section_id'    =>  'text_fields',
212     *           'title' =>  __( 'Text', 'admin-page-framework-demo' ),
213     *           'description'   =>  __( 'Type something here.', 'admin-page-framework-demo' ),
214     *           'type'  =>  'text',
215     *           'order' =>  1,
216     *           'default'   =>  123456,
217     *           'size'  =>  40,
218     *       ),  
219     *       array(
220     *           'field_id'  =>  'text_multiple',
221     *           'section_id'    =>  'text_fields',
222     *           'title' =>  'Multiple Text Fields',
223     *           'description'   =>  'These are multiple text fields.',
224     *           'type'  =>  'text',
225     *           'order' =>  2,
226     *           'default'   =>  'Hello World',
227     *           'label' =>  'First Item',
228     *           'attributes'    =>  array(
229     *               'size'  =>  30
230     *           ),
231     *           array(
232     *               'label' =>  'Second Item',
233     *               'default'   =>  'Foo bar',
234     *               'attributes'    =>  array(
235     *                   'size'  =>  60,
236     *               ),
237     *           ),
238     *           array(
239     *               'label' =>  'Third Item',
240     *               'default'   =>  'Yes, we can.',
241     *               'attributes'    =>  array(
242     *                   'size'  =>  90,
243     *               ),
244     *           ),
245     *       )
246     *   );</code> 
247     * 
248     * @since            2.0.0
249     * @since            3.0.0           Changed the scope to public from protected.
250     * @access           public
251     * @remark           Accepts variadic parameters; the number of accepted parameters are not limited to three.
252     * @remark           The actual registration will be performed in the <em>_replyToRegisterSettings()</em> method with the <em>admin_menu</em> hook.
253     * @param            array           the field definition array.
254     * <h4>Built-in Field Types</h4>
255     * <ul>
256     *   <li><strong>text</strong> - a normal field to enter text input.</li>
257     *   <li><strong>text</strong> - a masked text input field.</li>
258     *   <li><strong>textarea</strong> - a text input field with multiple lines. It supports rich text editor.</li>
259     *   <li><strong>radio</strong> - a set of radio buttons that lets the user pick an option.</li>
260     *   <li><strong>checkbox</strong> - a check box that lets the user enable/disable an item.</li>
261     *   <li><strong>select</strong> - a drop-down list that lest the user pick one or more item(s) from a list.</li>
262     *   <li><strong>hidden</strong> - a hidden field that will be useful to insert invisible values.</li>
263     *   <li><strong>file</strong> - a file uploader that lets the user upload files.</li>
264     *   <li><strong>image</strong> - a custom text field with the image uploader script that lets the user set the image URL.</li>
265     *   <li><strong>media</strong> - a custom text field with the media uploader script that lets the user set the file URL.</li>
266     *   <li><strong>color</strong> - a custom text field with the color picker script.</li>
267     *   <li><strong>submit</strong> - a submit button that lets the user send the form.</li>
268     *   <li><strong>export</strong> - a custom submit field that lets the user export the stored data.</li>
269     *   <li><strong>import</strong> - a custom combination field of the file and the submit fields that let the user import data.</li>
270     *   <li><strong>posttype</strong> - a check-list of post types enabled on the site.</li>
271     *   <li><strong>taxonomy</strong> - a set of check-lists of taxonomies enabled on the site in a tabbed box.</li>
272     *   <li><strong>size</strong> - a combination field of the text and the select fields that let the user set sizes with a selectable unit.</li>
273     *   <li><strong>section_title</strong> - [3.0.0+] a text field type that will be placed in the section title so that it lets the user set the section title. Note that only one field with this field type is allowed per a section.</li>
274     * </ul> 
275     * <h4>Field Definition Array</h4>
276     * <ul>
277     *   <li><strong>field_id</strong> - ( required, string ) the field ID. Avoid using non-alphabetic characters except underscore and numbers.</li>
278     *   <li><strong>type</strong> - ( required, string ) the type of the field. The supported types are listed below.</li>
279     *   <li><strong>section_id</strong> - ( optional, string ) the section ID that the field belongs to. If not set, the internal <em>_default</em> section ID will be assigned.</li>
280     *   <li><strong>title</strong> - ( optional, string ) the title of the section.</li>
281     *   <li><strong>description</strong> - ( optional, string ) the description of the field which is inserted into the after the input field tag.</li>
282     *   <li><strong>tip</strong> - ( optional, string ) the tip for the field which is displayed when the mouse is hovered over the field title.</li>
283     *   <li><strong>capability</strong> - ( optional, string ) the http://codex.wordpress.org/Roles_and_Capabilities">access level of the section. If the page visitor does not have sufficient capability, the section will be invisible to them.</li>
284     *   <li><strong>error_message</strong> - ( optional, string ) the error message to display above the input field.</li>
285     *   <li><strong>before_field</strong> - ( optional, string ) the HTML string to insert before the input field output.</li>
286     *   <li><strong>after_field</strong> - ( optional, string ) the HTML string to insert after the input field output.</li>
287     *   <li><strong>if</strong> - ( optional, boolean ) if the passed value is false, the section will not be registered.</li>
288     *   <li><strong>order</strong> - ( optional, integer ) the order number of the section. The higher the number is, the lower the position it gets.</li>
289     *   <li><strong>label</strong> - ( optional, string ) the text label(s) associated with and displayed along with the input field. Some input types can ignore this key.</li>
290     *   <li><strong>default</strong> - ( optional, string|array ) the default value(s) assigned to the input tag's value attribute.</li>
291     *   <li><strong>value</strong> - ( optional, string|array ) the value(s) assigned to the input tag's <em>value</em> attribute to override the default and the stored value.</li>
292     *   <li><strong>delimiter</strong> - ( optional, string ) the HTML string that delimits multiple elements. This is available if the <var>label</var> key is passed as array. It will be enclosed in inline-block elements so the passed HTML string should not contain block elements.</li>
293     *   <li><strong>before_input</strong> - ( optional, string ) the HTML string inserted right before the input tag. It will be enclosed in the <code>label</code> tag so the passed HTML string should not contain block elements.</li>
294     *   <li><strong>after_input</strong> - ( optional, string ) the HTML string inserted right after the input tag. It will be enclosed in the <code>label</code> tag so the passed HTML string should not contain block elements.</li>
295     *   <li><strong>label_min_width</strong> - ( optional, string ) the inline style property of the <em>min-width</em> of the label tag for the field in pixel without the unit. Default: <code>120</code>.</li>
296     *   <li><strong>help</strong> - ( optional, string ) the help description added to the contextual help tab.</li>
297     *   <li><strong>help_aside</strong> - ( optional, string ) the additional help description for the side bar of the contextual help tab.</li>
298     *   <li><strong>repeatable</strong> - [3.0.0+] ( optional, array|boolean ) whether the fields should be repeatable. If it yields true, the plus and the minus buttons appear next to each field that lets the user add/remove the fields. Optionally an setting array can be passed.
299     *       <h5>Repeatable Fields Setting Array</h5>
300     *       <ul>
301     *           <li><strong>max</strong> - the allowed maximum number of fields to be repeated.</li>
302     *           <li><strong>min</string> - the allowed minimum number of fields to be repeated.</li>
303     *       </ul>
304     *   </li>
305     *   <li><strong>sortable</strong> - [3.0.0+] ( optional, boolean ) whether the fields should be sortable. If it yields true, the fields will be enclosed in a draggable box.
306     *   <li><strong>attributes</strong> - [3.0.0+] ( optional, array ) holds key-value pairs representing the attribute and its property. Note that some field types have specific keys in the first dimensions. e.g.<em>array( 'class' => 'my_custom_class_selector', 'style' => 'background-color:#777', 'size' => 20, )</em></li>
307     *   <li><strong>show_title_column</strong> - [3.0.0+] ( optional, boolean ) If true, the field title column will be omitted from the output.</li>
308     *   <li><strong>hidden</strong> - [3.0.0+] ( optional, boolean ) If true, the entire field row output will be invisible with the inline style attribute of <em>style="display:none"</em>.</li>
309     * </ul>
310     * 
311     * <h4>Field Type Specific Keys</h4>
312     * <p>Each field type uses specific array keys.</p>
313     * <ul>
314     *   <li><strong>text</strong> - a text input field which allows the user to type text.</li>
315     *   <li><strong>password</strong> - a password input field which allows the user to type text.</li>
316     *   <li><strong>number, range</strong> - HTML5 input field types. Some browsers do not support these.</li>
317     *   <li><strong>textarea</strong> - a textarea input field. The following array keys are supported.
318     *       <ul>
319     *           <li><strong>rich</strong> - [2.1.2+]( optional, array ) to make it a rich text editor pass a non-empty value. It accept a setting array of the <code>_WP_Editors</code> class defined in the core.
320     * For more information, see the argument section of <a href="http://codex.wordpress.org/Function_Reference/wp_editor" target="_blank">this page</a>.
321     *           </li>
322     *       </ul>
323     *   </li>
324     *   <li><strong>radio</strong> - a radio button input field.</li>
325     *   <li><strong>checkbox</strong> - a check box input field.</li>
326     *   <li><strong>select</strong> - a drop-down input field.
327     *       <ul>
328     *           <li><strong>is_multiple</strong> - ( optional, boolean ) if this is set to true, the <em>multiple</em> attribute will be inserted into the field input tag, which enables the multiple selections for the user.</li>
329     *       </ul>
330     *   </li>
331     *   <li><strong>size</strong> - a size input field. This is a combination of number and select fields.
332     *       <ul>
333     *           <li>
334     *               <strong>units</strong> - ( optional, array ) defines the units to show. e.g. <em>array( 'px' => 'px', '%' => '%', 'em' => 'em'  )</em> 
335     *               Default: <em>array( 'px' => 'px', '%' => '%', 'em' => 'em', 'ex' => 'ex', 'in' => 'in', 'cm' => 'cm', 'mm' => 'mm', 'pt' => 'pt', 'pc' => 'pc' )</em>
336     *           </li>
337     *           <li><strong>is_multiple</strong> - ( optional, boolean ) if this is set to true, the <em>multiple</em> attribute will be inserted into the field input tag, which enables the multiple selections for the user.</li>
338     *           <li><strong>attributes</strong> - [3.0.0+] ( optional, array ) The attributes array of this field type has four initial keys: size, unit, optgroup, and option and they have a regular attribute array in each.</li>
339     *       </ul>
340     *   </li>
341     *   <li><strong>hidden</strong> - a hidden input field.</li>
342     *   <li><strong>file</strong> - a file upload input field.</li>
343     *   <li><strong>submit</strong> - a submit button input field.
344     *       <ul>
345     *           <li><strong>href</strong> - ( optional, string ) the url(s) linked to the submit button.</li>
346     *           <li><strong>redirect_url</strong> - ( optional, string ) the url(s) redirected to after submitting the input form.</li>
347     *           <li><strong>reset</strong> - [2.1.2+] ( optional, boolean ) the option key to delete. Set 1 for the entire option.</li>
348     *       </ul>
349     *   </li>
350     *   <li><strong>import</strong> - an import input field. This is a custom file and submit field.
351     *       <ul>
352     *           <li><strong>option_key</strong> - ( optional, string ) the option table key to save the importing data.</li>
353     *           <li><strong>format</strong> - ( optional, string ) the import format. json, or array is supported. Default: array</li>
354     *           <li><strong>is_merge</strong> - ( optional, boolean ) [2.0.5+] determines whether the imported data should be merged with the existing options.</li>
355     *       </ul>
356     *   </li>
357     *   <li><strong>export</strong> - an export input field. This is a custom submit field.
358     *       <ul>
359     *           <li><strong>file_name</strong> - ( optional, string ) the file name to download.</li>
360     *           <li><strong>format</strong> - ( optional, string ) the format type. array, json, or text is supported. Default: array.</li>
361     *           <li><strong>data</strong> - ( optional, string|array|object ) the data to export.</li>
362     *       </ul>
363     *   </li>
364     *   <li><strong>image</strong> - an image input field. This is a custom text field with an attached JavaScript script.
365     *       <ul>
366     *           <li><strong>show_preview</strong> - ( optional, boolean ) if this is set to false, the image preview will be disabled.</li>
367     *           <li><strong>attributes_to_store</strong> - [2.1.3+] ( optional, array ) the array of the attribute names of the image to save. If this is set, the field will be an array with the specified attributes. The supported attributes are, 'title', 'alt', 'width', 'height', 'caption', 'id', 'align', and 'link'. Note that for external URLs, ID will not be captured. e.g. <em>'attributes_to_store' => array( 'id', 'caption', 'description' )</em></li>
368     *           <li><strong>allow_external_source</strong> - [2.1.3+] ( optional, boolean ) whether external URL can be set via the uploader.</li>
369     *           <li><strong>attributes</strong> - [3.0.0+] ( optional, array ) The attributes array of this field type has three keys: input, button, and preview and they have a regular attribute array in each.</li>
370     *       </ul>
371     *   </li>
372     *   <li><strong>media</strong> - [2.1.3+] a media input field. This is a custom text field with an attached JavaScript script.
373     *       <ul>
374     *           <li><strong>attributes_to_store</strong> - [2.1.3+] ( optional, array ) the array of the attribute names of the image to save. If this is set, the field will be an array with the specified attributes. The supported attributes are, 'id', 'caption', and 'description'. Note that for external URLs, ID will not be captured. e.g. <em>'attributes_to_store' => array( 'id', 'caption', 'description' )</em></li>
375     *           <li><strong>allow_external_source</strong> - [2.1.3+] ( optional, boolean ) whether external URL can be set via the uploader.</li>
376     *       </ul>
377     *   </li>
378     *   <li><strong>color</strong> - a color picker input field. This is a custom text field with a JavaScript script.</li>
379     *   <li><strong>taxonomy</strong> - a taxonomy check list. This is a set of check boxes listing a specified taxonomy. This does not accept to create multiple fields by passing an array of labels.
380     *       <ul>
381     *           <li><strong>taxonomy_slugs</strong> - ( optional, array ) the taxonomy slug to list.</li>
382     *           <li><strong>max_width</strong> - ( optional, string ) the inline style property value of <em>max-width</em> of this element. Include the unit such as px, %. Default: 100%</li>
383     *           <li><strong>height</strong> - ( optional, string ) the inline style property value of <em>height</em> of this element. Include the unit such as px, %. Default: 250px</li>
384     *       </ul>
385     *   </li>
386     *   <li><strong>posttype</strong> - a post-type check list. This is a set of check boxes listing post type slugs.
387     *       <ul>
388     *           <li><strong>slugs_to_remove</strong> - ( optional, array ) the post type slugs not to be listed. e.g.<em>array( 'revision', 'attachment', 'nav_menu_item' )</em></li>
389     *       </ul>
390     *   </li>
391     * </ul> 
392     * @param            array           ( optional ) another field array.
393     * @param            array           ( optional ) add more field arrays to the next parameters as many as necessary.
394     * @return           void
395     */      
396     public function addSettingFields( $aField1, $aField2=null, $_and_more=null ) {  
397         foreach( func_get_args() as $aField ) $this->addSettingField( $aField );
398     }
399     /**
400     * Adds the given field array items into the field array property.
401     * 
402     * Identical to the addSettingFields() method except that this method does not accept enumerated parameters. 
403     * 
404     * @since            2.1.2
405     * @since            3.0.0           Changed the scope to public from protected.
406     * @access           public
407     * @param            array|string    the field array or the target section ID. If the target section ID is set, the section_id key can be omitted from the next passing field array.
408     * @return           void
409     */  
410     public function addSettingField( $asField ) {
411         $this->oForm->addField( $asField ); 
412     }   
413     
414     /**
415     * Removes the given field(s) by field ID.
416     * 
417     * This accesses the property storing the added field arrays and removes the specified ones.
418     * 
419     * <h4>Example</h4>
420     * <code>$this->removeSettingFields( 'fieldID_A', 'fieldID_B', 'fieldID_C', 'fieldID_D' );
421     * </code>
422     * 
423     * @since            2.0.0
424     * @since            3.0.0           Changed the scope to public from protected.
425     * @access           public
426     * @remark           Accepts variadic parameters; the number of accepted parameters are not limited to three.
427     * @remark           The actual registration will be performed in the <em>_replyToRegisterSettings()</em> method with the <em>admin_menu</em> hook.
428     * @param            string          the field ID to remove.
429     * @param            string          ( optional ) another field ID to remove.
430     * @param            string          ( optional ) add more field IDs to the next parameters as many as necessary.
431     * @return           void
432     */  
433     public function removeSettingFields( $sFieldID1, $sFieldID2=null, $_and_more ) {
434                 
435         foreach( func_get_args() as $_sFieldID ) $this->oForm->removeField( $_sFieldID );
436 
437     }   
438             
439     /**
440      * Sets the field error array. 
441      * 
442      * This is normally used in validation callback methods when the submitted user's input data have an issue.
443      * This method saves the given array in a temporary area( transient ) of the options database table.
444      * 
445      * <h4>Example</h4>
446      * <code>
447      *  public function validation_APF_Demo_verify_text_field_submit( $aNewInput, $aOldOptions ) {
448      *
449      *      // 1. Set a flag.
450      *      $bVerified = true;
451      *      
452      *      // 2. Prepare an error array. 
453      *      $aErrors = array();
454      *
455      *      // 3. Check if the submitted value meets your criteria.
456      *      if ( ! is_numeric( $aNewInput['verify_text_field'] ) ) {
457      *          $aErrors['verify_text_field'] = __( 'The value must be numeric:', 'admin-page-framework-demo' ) 
458      *              . $aNewInput['verify_text_field'];
459      *          $bVerified = false;
460      *      }
461      *  
462      *      // 4. An invalid value is found.
463      *      if ( ! $bVerified ) {
464      *          // 4-1. Set the error array for the input fields.
465      *          $this->setFieldErrors( $aErrors );      
466      *          $this->setSettingNotice( 'There was an error in your input.' );
467      *          return $aOldOptions;
468      *      }
469      *                  
470      *      return $aNewInput;      
471      *
472      *  }
473      * </code>
474      * 
475      * @since           2.0.0
476      * @since           3.0.0           Changed the scope to public from protected.
477      * @remark          the user may use this method.
478      * @remark          the transient name is a MD5 hash of the extended class name + _ + page slug ( the passed ID )
479      * @param           array           the field error array. The structure should follow the one contained in the submitted $_POST array.
480      * @param           string          this should be the page slug of the page that has the dealing form field.
481      * @param           integer         the transient's lifetime. 300 seconds means 5 minutes.
482      */ 
483     public function setFieldErrors( $aErrors, $sID=null, $nSavingDuration=300 ) {
484         
485         $sID = isset( $sID ) ? $sID : ( isset( $_POST['page_slug'] ) ? $_POST['page_slug'] : ( isset( $_GET['page'] ) ? $_GET['page'] : $this->oProp->sClassName ) );   
486         set_transient( md5( $this->oProp->sClassName . '_' . $sID ), $aErrors, $nSavingDuration );  // store it for 5 minutes ( 60 seconds * 5 )
487     
488     }
489 
490     /**
491      * Retrieves the specified field value stored in the options by field ID.
492      *  
493      * @since           2.1.2
494      * @since           3.0.0           Changed the scope to public from protected. Dropped the sections. Made it return a default value even if it's not saved in the database.
495      * @access          public
496      * @param           string          The field ID.
497      * @return          array|string|null       If the field ID is not set in the saved option array, it will return null. Otherwise, the set value. 
498      * If the user has not submitted the form, the framework will try to return the default value set in the field definition array.
499      */
500     public function getFieldValue( $sFieldID, $sSectionID='' ) {
501         
502         $_aOptions = $this->oUtil->uniteArrays( $this->oProp->aOptions, $this->oProp->getDefaultOptions( $this->oForm->aFields ) );
503         
504         /* If it's saved, return it */
505         if ( ! $sSectionID ) {
506             if ( array_key_exists( $sFieldID, $_aOptions ) )
507                 return $_aOptions[ $sFieldID ];
508                 
509             // loop through section elements
510             foreach( $_aOptions as $aOptions ) {
511                 if ( array_key_exists( $sFieldID, $aOptions ) )
512                     return $aOptions[ $sFieldID ];
513             }
514                 
515         }
516         if ( $sSectionID )
517             if ( array_key_exists( $sSectionID, $_aOptions ) && array_key_exists( $sFieldID, $_aOptions[ $sSectionID ] ) )
518                 return $_aOptions[ $sSectionID ][ $sFieldID ];
519     
520         return null;
521                     
522     }
523             
524 }
525 endif;
Admin Page Framework Documentation API documentation generated by ApiGen 2.8.0