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_FieldType' ) ) :
10 /**
11 * The base class for the users to create their custom field types.
12 *
13 * When a framework user implements a custom field type into his/her work, this class may be extended to create a field definition class.
14 *
15 * <h3>Steps to Include a Custom Field Type</h3>
16 * <ol>
17 * <li>
18 * Define a custom field type with a class extending the <em>AdminPageFramework_FieldType</em> class.
19 * <ol>
20 * <li>Set the field type slug such as autocomplete with the <em>$aFieldTypeSlugs</em> property.</li>
21 * <li>Set the default field array definition keys with the <em>$aDefaultKeys</em> property.</li>
22 * <li>Write additional code in the <em>setUp()</em> method that will be performed when the field type definition is parsed.</li>
23 * <li>Add scripts and styles with <em>getEnqueuingScripts()</em>, <em>getEnqueuingStyles()</em>, <em>getScripts()</em>, <em>getStyles()</em> etc.</li>
24 * <li>Compose the output HTML structure with the passed <em>$aField</em> field definition array in the <em>getField()</em> method.</li>
25 * </ol>
26 * </li>
27 * <li>
28 * Include the definition file and instantiate the class in the script(plugin,theme etc.).
29 * <code>
30 * new MyCustomFieldTypeClass( 'MY_CLASS_NAME' ); // pass the PHP class name that extends the framework's class to the first parameter.
31 * </code>
32 * </li>
33 * <li>
34 * Define fields with the custom field type with the <em>addSettingFields()</em> method in the framework extending class.
35 * <code>
36 * $this->addSettingFields(
37 * array(
38 * 'field_id' => 'my_field_id',
39 * 'section_id' => 'my_section_id',
40 * 'type' => 'my_custom_field_type_slug', // <-- here put the field type slug
41 * '...' => '...'
42 * )
43 * );
44 * </code>
45 * </li>
46 * </ol>
47 *
48 * @abstract
49 * @package AdminPageFramework
50 * @subpackage FieldType
51 * @since 2.1.5
52 * @since 3.0.0 Changed the name from AdminPageFramework_CustomFieldType to AdminPageFramework_FieldType.
53 * @remark The user will extend this class to define their custom field types.
54 */
55 abstract class AdminPageFramework_FieldType extends AdminPageFramework_FieldType_Base {
56
57 /*
58 * Convert internal method names for the users to use to be easy to read.
59 */
60 /**#@+
61 * @internal
62 */
63 public function _replyToFieldLoader() { $this->setUp(); } // do stuff that should be done when the field type is loaded for the first time.
64 public function _replyToGetScripts() { return $this->getScripts(); } // should return the script
65 public function _replyToGetInputIEStyles() { return $this->getIEStyles(); } // should return the style for IE
66 public function _replyToGetStyles() { return $this->getStyles(); } // should return the style
67 public function _replyToGetField( $aField ) { return $this->getField( $aField ); } // should return the field output
68 /**#@-*/
69 /**
70 * @internal
71 */
72 protected function _replyToGetEnqueuingScripts() { return $this->getEnqueuingScripts(); } // should return an array holding the urls of enqueuing items
73 /**
74 * @internal
75 */
76 protected function _replyToGetEnqueuingStyles() { return $this->getEnqueuingStyles(); } // should return an array holding the urls of enqueuing items
77
78 /*
79 * Required Properties
80 */
81 /**
82 * Defines the field type slugs used for this field type.
83 *
84 * The slug is used for the type key in a field definition array.
85 *
86 * <code>
87 * $this->addSettingFields(
88 * array(
89 * 'section_id' => '...',
90 * 'type' => 'my_filed_type_slug', // <--- THIS PART
91 * 'field_id' => '...',
92 * 'title' => '...',
93 * )
94 * );
95 * </code>
96 */
97 public $aFieldTypeSlugs = array();
98
99 /**
100 * Defines the default key-values of this field type.
101 *
102 * The users will set the values to the defined keys and if not set, the value set in this property array will take effect. The merged array of the user's field definition array and this property array will be passed to the first parameter of the <em>getField()</em> method.
103 *
104 * <code>
105 * $this->addSettingFields(
106 * array(
107 * 'section_id' => '...',
108 * 'type' => '...',
109 * 'field_id' => '...',
110 * 'my_custom_key' => '...', // <-- THIS PART
111 * )
112 * );
113 * </code>
114 *
115 * <h4>Example</h4>
116 * <code>
117 * $aDefaultKeys = array(
118 * 'my_custom_key' => 'my default value',
119 * 'attributes' => array(
120 * 'size' => 30,
121 * 'maxlength' => 400,
122 * ),
123 * );
124 * </code>
125 * @remark $_aDefaultKeys holds shared default key-values defined in the base class.
126 */
127 protected $aDefaultKeys = array();
128
129 /*
130 * Available Methods for Users - these methods should be overridden in extended classes.
131 */
132 /**#@+
133 * @since 3.0.0
134 * @remark The user will override this method in their class definition.
135 */
136 /**
137 * Loads the field type necessary components.
138 *
139 * This method is triggered when a field definition array that calls this field type is parsed.
140 */
141 protected function setUp() {}
142 protected function getScripts() { return ''; }
143 protected function getIEStyles() { return ''; }
144 protected function getStyles() { return ''; }
145 protected function getField( $aField ) { return ''; }
146
147 /**
148 * Returns an array holding the urls of enqueuing scripts.
149 *
150 * The returning array should consist of all numeric keys. Each element can be either a string( the url or the path of the source file) or an array of custom argument.
151 *
152 * <h4>Custom Argument Array</h4>
153 * <ul>
154 * <li><strong>src</strong> - ( required, string ) The url or path of the target source file</li>
155 * <li><strong>handle_id</strong> - ( optional, string ) The handle ID of the script.</li>
156 * <li><strong>dependencies</strong> - ( optional, array ) The dependency array. For more information, see <a href="http://codex.wordpress.org/Function_Reference/wp_enqueue_script">codex</a>.</li>
157 * <li><strong>version</strong> - ( optional, string ) The stylesheet version number.</li>
158 * <li><strong>translation</strong> - ( optional, array ) The translation array. The handle ID will be used for the object name.</li>
159 * <li><strong>in_footer</strong> - ( optional, boolean ) Whether to enqueue the script before < / head > or before < / body > Default: <code>false</code>.</li>
160 * </ul>
161 *
162 * <h4>Examples</h4>
163 * <code>
164 * protected function getEnqueuingScripts() {
165 * return array(
166 * array( // if you need to set a dependency, pass as a custom argument array.
167 * 'src' => dirname( __FILE__ ) . '/asset/my_script.js', // path or url
168 * 'dependencies' => array( 'jquery' )
169 * ),
170 * dirname( __FILE__ ) . '/asset/my_another.js', // a string value of the target path or url will work as well.
171 * );
172 * }
173 * </code>
174 */
175 protected function getEnqueuingScripts() { return array(); } // should return an array holding the urls of enqueuing items
176
177 /**
178 * Returns an array holding the urls of enqueuing styles.
179 *
180 * The returning array should consist of all numeric keys. Each element can be either a string( the url or the path of the source file) or an array of custom argument.
181 *
182 * <h4>Custom Argument Array</h4>
183 * <ul>
184 * <li><strong>src</strong> - ( required, string ) The url or path of the target source file</li>
185 * <li><strong>handle_id</strong> - ( optional, string ) The handle ID of the stylesheet.</li>
186 * <li><strong>dependencies</strong> - ( optional, array ) The dependency array. For more information, see <a href="http://codex.wordpress.org/Function_Reference/wp_enqueue_style">codex</a>.</li>
187 * <li><strong>version</strong> - ( optional, string ) The stylesheet version number.</li>
188 * <li><strong>media</strong> - ( optional, string ) the description of the field which is inserted into the after the input field tag.</li>
189 * </ul>
190 *
191 * <h4>Examples</h4>
192 * <code>
193 * protected function getEnqueuingStyles() {
194 * return array(
195 * dirname( __FILE__ ) . '/asset/my_style.css',
196 * array(
197 * 'src' => dirname( __FILE__ ) . '/asset/my_style2.css',
198 * 'handle_id' => 'my_style2',
199 * ),
200 * );
201 * }
202 * </code>
203 */
204 protected function getEnqueuingStyles() { return array(); } // should return an array holding the urls of enqueuing items
205 /**#@-*/
206
207 }
208 endif;