├── README.md ├── widget-sample.php └── wph-widget-class.php /README.md: -------------------------------------------------------------------------------- 1 | # WordPress Widgets Helper Class 2 | 3 | **This repository is deprecated; No further Issues or Pull Requests will be considered or approved.** 4 | 5 | Alternative fork by @Mte90: https://github.com/WPBP/Widgets-Helper 6 | 7 | ## Summary 8 | 9 | A class that extends the built-in WP_Widget class to provide an easier/faster way to create Widgets for WordPress. 10 | 11 | ### Features 12 | 13 | Automatic fields creation 14 | Validation methods 15 | Filter methods 16 | Before/After form output methods 17 | Custom form fields creation 18 | 19 | Check the inline comments and Widget sample for more information. 20 | 21 | ### Roadmap / Wishlist 22 | 23 | More Custom fields 24 | [Widget Logic](http://wordpress.org/extend/plugins/widget-logic/ "Widget Logic") alike functionality 25 | 26 | ### Version 27 | 28 | 1.6 29 | 30 | ### License 31 | 32 | GPLv2 33 | 34 | ### Credits 35 | 36 | by @sksmatt 37 | www.mattvarone.com 38 | 39 | Contributors: 40 | 41 | Joachim Kudish ( @jkudish ) 42 | Joaquin http://bit.ly/p18bOk 43 | markyoungdev http://bit.ly/GK6PwU 44 | -------------------------------------------------------------------------------- /widget-sample.php: -------------------------------------------------------------------------------- 1 | __( 'My Recent Posts', 'mv-my-recente-posts' ), 33 | // Widget Backend Description 34 | 'description' => __( 'My Recent Posts Widget Description', 'mv-my-recente-posts' ), 35 | ); 36 | 37 | // Configure the widget fields 38 | // Example for: Title ( text ) and Amount of posts to show ( select box ) 39 | 40 | // fields array 41 | $args['fields'] = array( 42 | 43 | // Title field 44 | array( 45 | // field name/label 46 | 'name' => __( 'Title', 'mv-my-recente-posts' ), 47 | // field description 48 | 'desc' => __( 'Enter the widget title.', 'mv-my-recente-posts' ), 49 | // field id 50 | 'id' => 'title', 51 | // field type ( text, checkbox, textarea, select, select-group ) 52 | 'type'=>'text', 53 | // class, rows, cols 54 | 'class' => 'widefat', 55 | // default value 56 | 'std' => __( 'Recent Posts', 'mv-my-recente-posts' ), 57 | 58 | /* 59 | Set the field validation type/s 60 | /////////////////////////////// 61 | 62 | 'alpha_dash' 63 | Returns FALSE if the value contains anything other than alpha-numeric characters, underscores or dashes. 64 | 65 | 'alpha' 66 | Returns FALSE if the value contains anything other than alphabetical characters. 67 | 68 | 'alpha_numeric' 69 | Returns FALSE if the value contains anything other than alpha-numeric characters. 70 | 71 | 'numeric' 72 | Returns FALSE if the value contains anything other than numeric characters. 73 | 74 | 'boolean' 75 | Returns FALSE if the value contains anything other than a boolean value ( true or false ). 76 | 77 | ---------- 78 | 79 | You can define custom validation methods. Make sure to return a boolean ( TRUE/FALSE ). 80 | Example: 81 | 82 | 'validate' => 'my_custom_validation', 83 | 84 | Will call for: $this->my_custom_validation( $value_to_validate ); 85 | 86 | */ 87 | 88 | 'validate' => 'alpha_dash', 89 | 90 | /* 91 | 92 | Filter data before entering the DB 93 | ////////////////////////////////// 94 | 95 | strip_tags ( default ) 96 | wp_strip_all_tags 97 | esc_attr 98 | esc_url 99 | esc_textarea 100 | 101 | */ 102 | 103 | 'filter' => 'strip_tags|esc_attr' 104 | ), 105 | 106 | // Amount Field 107 | array( 108 | 'name' => __( 'Amount' ), 109 | 'desc' => __( 'Select how many posts to show.', 'mv-my-recente-posts' ), 110 | 'id' => 'amount', 111 | 'type'=>'select', 112 | // selectbox fields 113 | 'fields' => array( 114 | array( 115 | // option name 116 | 'name' => __( '1 Post', 'mv-my-recente-posts' ), 117 | // option value 118 | 'value' => '1' 119 | ), 120 | array( 121 | 'name' => __( '2 Posts', 'mv-my-recente-posts' ), 122 | 'value' => '2' 123 | ), 124 | array( 125 | 'name' => __( '3 Posts', 'mv-my-recente-posts' ), 126 | 'value' => '3' 127 | ) 128 | 129 | // add more options 130 | ), 131 | 'validate' => 'my_custom_validation', 132 | 'filter' => 'strip_tags|esc_attr', 133 | ), 134 | 135 | // Output type checkbox 136 | array( 137 | 'name' => __( 'Output as list', 'mv-my-recente-posts' ), 138 | 'desc' => __( 'Wraps posts with the
Hey There!
'; 179 | 180 | echo $out; 181 | } 182 | 183 | } // class 184 | 185 | // Register widget 186 | if ( ! function_exists( 'mv_my_register_widget' ) ) 187 | { 188 | function mv_my_register_widget() 189 | { 190 | register_widget( 'MV_My_Recent_Posts_Widget' ); 191 | } 192 | 193 | add_action( 'widgets_init', 'mv_my_register_widget', 1 ); 194 | } 195 | } -------------------------------------------------------------------------------- /wph-widget-class.php: -------------------------------------------------------------------------------- 1 | '', 37 | 'description' => '', 38 | 'fields' => array(), 39 | 'options' => array(), 40 | ); 41 | 42 | // parse and merge args with defaults 43 | $args = wp_parse_args( $args, $defaults ); 44 | 45 | // extract each arg to its own variable 46 | extract( $args, EXTR_SKIP ); 47 | 48 | // set the widget vars 49 | $this->slug = sanitize_title( $label ); 50 | $this->fields = $fields; 51 | 52 | // check options 53 | $this->options = array( 'classname' => $this->slug, 'description' => $description ); 54 | if ( ! empty( $options ) ) $this->options = array_merge( $this->options, $options ); 55 | 56 | // call WP_Widget to create the widget 57 | parent::__construct( $this->slug, $label, $this->options ); 58 | 59 | } 60 | 61 | 62 | /** 63 | * Form 64 | * 65 | * Creates the settings form. 66 | * 67 | * @access private 68 | * @param array 69 | * @return void 70 | * @since 1.0 71 | */ 72 | 73 | function form( $instance ) { 74 | $this->instance = $instance; 75 | $form = $this->create_fields(); 76 | 77 | echo $form; 78 | } 79 | 80 | 81 | /** 82 | * Update Fields 83 | * 84 | * @access private 85 | * @param array 86 | * @param array 87 | * @return array 88 | * @since 1.0 89 | */ 90 | 91 | function update( $new_instance, $old_instance ) { 92 | $instance = $old_instance; 93 | 94 | $this->before_update_fields(); 95 | 96 | foreach ( $this->fields as $key ) { 97 | $slug = $key['id']; 98 | 99 | if ( isset( $key['validate'] ) ) { 100 | if ( false === $this->validate( $key['validate'], $new_instance[$slug] ) ) 101 | return $instance; 102 | } 103 | 104 | if ( isset( $key['filter'] ) ) 105 | $instance[$slug] = $this->filter( $key['filter'], $new_instance[$slug] ); 106 | else 107 | $instance[$slug] = strip_tags( $new_instance[$slug] ); 108 | } 109 | 110 | return $this->after_validate_fields( $instance ); 111 | } 112 | 113 | 114 | /** 115 | * Before Validate Fields 116 | * 117 | * Allows to hook code on the update. 118 | * 119 | * @access public 120 | * @param string 121 | * @return string 122 | * @since 1.6 123 | */ 124 | 125 | function before_update_fields() { 126 | return; 127 | } 128 | 129 | 130 | /** 131 | * After Validate Fields 132 | * 133 | * Allows to modify the output after validating the fields. 134 | * 135 | * @access public 136 | * @param string 137 | * @return string 138 | * @since 1.6 139 | */ 140 | 141 | function after_validate_fields( $instance = "" ) { 142 | return $instance; 143 | } 144 | 145 | 146 | /** 147 | * Validate 148 | * 149 | * @access private 150 | * @param string 151 | * @param string 152 | * @return boolean 153 | * @since 1.0 154 | */ 155 | 156 | function validate( $rules, $value ) { 157 | $rules = explode( '|', $rules ); 158 | 159 | if ( empty( $rules ) || count( $rules ) < 1 ) 160 | return true; 161 | 162 | foreach ( $rules as $rule ) { 163 | if ( false === $this->do_validation( $rule, $value ) ) 164 | return false; 165 | } 166 | 167 | return true; 168 | } 169 | 170 | 171 | /** 172 | * Filter 173 | * 174 | * @access private 175 | * @param string 176 | * @param string 177 | * @return void 178 | * @since 1.0 179 | */ 180 | 181 | function filter( $filters, $value ) { 182 | $filters = explode( '|', $filters ); 183 | 184 | if ( empty( $filters ) || count( $filters ) < 1 ) 185 | return $value; 186 | 187 | foreach ( $filters as $filter ) 188 | $value = $this->do_filter( $filter, $value ); 189 | 190 | return $value; 191 | } 192 | 193 | 194 | /** 195 | * Do Validation Rule 196 | * 197 | * @access private 198 | * @param string 199 | * @param string 200 | * @return boolean 201 | * @since 1.0 202 | */ 203 | 204 | function do_validation( $rule, $value = "" ) 205 | { 206 | switch ( $rule ) { 207 | 208 | case 'alpha': 209 | return ctype_alpha( $value ); 210 | break; 211 | 212 | case 'alpha_numeric': 213 | return ctype_alnum( $value ); 214 | break; 215 | 216 | case 'alpha_dash': 217 | return preg_match( '/^[a-z0-9-_]+$/', $value ); 218 | break; 219 | 220 | case 'numeric': 221 | return ctype_digit( $value ); 222 | break; 223 | 224 | case 'integer': 225 | return ( bool ) preg_match( '/^[\-+]?[0-9]+$/', $value ); 226 | break; 227 | 228 | case 'boolean': 229 | return is_bool( $value ); 230 | break; 231 | 232 | case 'email': 233 | return is_email( $value ); 234 | break; 235 | 236 | case 'decimal': 237 | return ( bool ) preg_match( '/^[\-+]?[0-9]+\.[0-9]+$/', $value ); 238 | break; 239 | 240 | case 'natural': 241 | return ( bool ) preg_match( '/^[0-9]+$/', $value ); 242 | return; 243 | 244 | case 'natural_not_zero': 245 | if ( ! preg_match( '/^[0-9]+$/', $value ) ) return false; 246 | if ( $value == 0 ) return false; 247 | return true; 248 | return; 249 | 250 | default: 251 | if ( method_exists( $this, $rule ) ) 252 | return $this->$rule( $value ); 253 | else 254 | return false; 255 | break; 256 | 257 | } 258 | } 259 | 260 | 261 | /** 262 | * Do Filter 263 | * 264 | * @access private 265 | * @param string 266 | * @param string 267 | * @return boolean 268 | * @since 1.0 269 | */ 270 | 271 | function do_filter( $filter, $value = "" ) 272 | { 273 | switch ( $filter ) 274 | { 275 | case 'strip_tags': 276 | return strip_tags( $value ); 277 | break; 278 | 279 | case 'wp_strip_all_tags': 280 | return wp_strip_all_tags( $value ); 281 | break; 282 | 283 | case 'esc_attr': 284 | return esc_attr( $value ); 285 | break; 286 | 287 | case 'esc_url': 288 | return esc_url( $value ); 289 | break; 290 | 291 | case 'esc_textarea': 292 | return esc_textarea( $value ); 293 | break; 294 | 295 | default: 296 | if ( method_exists( $this, $filter ) ) 297 | return $this->$filter( $value ); 298 | else 299 | return $value; 300 | break; 301 | } 302 | } 303 | 304 | 305 | /** 306 | * Create Fields 307 | * 308 | * Creates each field defined. 309 | * 310 | * @access private 311 | * @param string 312 | * @return string 313 | * @since 1.0 314 | */ 315 | 316 | function create_fields( $out = "" ) { 317 | 318 | $out = $this->before_create_fields( $out ); 319 | 320 | if ( ! empty( $this->fields ) ) { 321 | foreach ( $this->fields as $key ) 322 | $out .= $this->create_field( $key ); 323 | } 324 | 325 | $out = $this->after_create_fields( $out ); 326 | 327 | return $out; 328 | } 329 | 330 | 331 | /** 332 | * Before Create Fields 333 | * 334 | * Allows to modify code before creating the fields. 335 | * 336 | * @access public 337 | * @param string 338 | * @return string 339 | * @since 1.0 340 | */ 341 | 342 | function before_create_fields( $out = "" ) { 343 | return $out; 344 | } 345 | 346 | 347 | /** 348 | * After Create Fields 349 | * 350 | * Allows to modify code after creating the fields. 351 | * 352 | * @access public 353 | * @param string 354 | * @return string 355 | * @since 1.0 356 | */ 357 | 358 | function after_create_fields( $out = "" ) { 359 | return $out; 360 | } 361 | 362 | 363 | /** 364 | * Create Fields 365 | * 366 | * @access private 367 | * @param string 368 | * @param string 369 | * @return string 370 | * @since 1.0 371 | */ 372 | 373 | function create_field( $key, $out = "" ) { 374 | 375 | /* Set Defaults */ 376 | $key['std'] = isset( $key['std'] ) ? $key['std'] : ""; 377 | 378 | $slug = $key['id']; 379 | 380 | if ( isset( $this->instance[$slug] ) ) 381 | $key['value'] = empty( $this->instance[$slug] ) ? '' : strip_tags( $this->instance[$slug] ); 382 | else 383 | unset( $key['value'] ); 384 | 385 | /* Set field id and name */ 386 | $key['_id'] = $this->get_field_id( $slug ); 387 | $key['_name'] = $this->get_field_name( $slug ); 388 | 389 | /* Set field type */ 390 | if ( ! isset( $key['type'] ) ) $key['type'] = 'text'; 391 | 392 | /* Prefix method */ 393 | $field_method = 'create_field_' . str_replace( '-', '_', $key['type'] ); 394 | 395 | /* Check forClass */ 396 | $p = ( isset( $key['class-p'] ) ) ? '
' : '
'; 397 | 398 | /* Run method */ 399 | if ( method_exists( $this, $field_method ) ) 400 | return $p.$this->$field_method( $key ).'
'; 401 | 402 | } 403 | 404 | 405 | /** 406 | * Field Text 407 | * 408 | * @access private 409 | * @param array 410 | * @param string 411 | * @return string 412 | * @since 1.5 413 | */ 414 | 415 | function create_field_text( $key, $out = "" ) 416 | { 417 | $out .= $this->create_field_label( $key['name'], $key['_id'] ) . '