├── 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
  • tag.', 'mv-my-recente-posts' ), 139 | 'id' => 'list', 140 | 'type'=>'checkbox', 141 | // checked by default: 142 | 'std' => 1, // 0 or 1 143 | 'filter' => 'strip_tags|esc_attr', 144 | ), 145 | 146 | // add more fields 147 | 148 | ); // fields array 149 | 150 | // create widget 151 | $this->create_widget( $args ); 152 | } 153 | 154 | // Custom validation for this widget 155 | 156 | function my_custom_validation( $value ) 157 | { 158 | if ( strlen( $value ) > 1 ) 159 | return false; 160 | else 161 | return true; 162 | } 163 | 164 | // Output function 165 | 166 | function widget( $args, $instance ) 167 | { 168 | 169 | // And here do whatever you want 170 | 171 | $out = $args['before_title']; 172 | $out .= $instance['title']; 173 | $out .= $args['after_title']; 174 | 175 | // here you would get the most recent posts based on the selected amount: $instance['amount'] 176 | // Then return those posts on the $out variable ready for the output 177 | 178 | $out .= '

    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 for

    Class */ 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'] ) . '
    '; 418 | 419 | $out .= ''; 435 | 436 | return $out; 437 | } 438 | 439 | 440 | /** 441 | * Field Textarea 442 | * 443 | * @access private 444 | * @param array 445 | * @param string 446 | * @return string 447 | * @since 1.5 448 | */ 449 | 450 | function create_field_textarea( $key, $out = "" ) 451 | { 452 | $out .= $this->create_field_label( $key['name'], $key['_id'] ) . '
    '; 453 | 454 | $out .= ''; 470 | 471 | if ( isset( $key['desc'] ) ) 472 | $out .= '
    '.esc_html( $key['desc'] ).''; 473 | 474 | return $out; 475 | } 476 | 477 | 478 | /** 479 | * Field Checkbox 480 | * 481 | * @access private 482 | * @param array 483 | * @param string 484 | * @return string 485 | * @since 1.5 486 | */ 487 | 488 | function create_field_checkbox( $key, $out = "" ) 489 | { 490 | $out .= $this->create_field_label( $key['name'], $key['_id'] ); 491 | 492 | $out .= ' '; 506 | 507 | return $out; 508 | } 509 | 510 | 511 | /** 512 | * Field Select 513 | * 514 | * @access private 515 | * @param array 516 | * @param string 517 | * @return string 518 | * @since 1.5 519 | */ 520 | 521 | function create_field_select( $key, $out = "" ) 522 | { 523 | $out .= $this->create_field_label( $key['name'], $key['_id'] ) . '
    '; 524 | 525 | $out .= ' '; 547 | 548 | if ( isset( $key['desc'] ) ) 549 | $out .= '
    '.esc_html( $key['desc'] ).''; 550 | 551 | return $out; 552 | } 553 | 554 | 555 | /** 556 | * Field Select with Options Group 557 | * 558 | * @access private 559 | * @param array 560 | * @param string 561 | * @return string 562 | * @since 1.5 563 | */ 564 | 565 | function create_field_select_group( $key, $out = "" ) 566 | { 567 | 568 | $out .= $this->create_field_label( $key['name'], $key['_id'] ) . '
    '; 569 | 570 | $out .= ''; 599 | 600 | if ( isset( $key['desc'] ) ) 601 | $out .= '
    '.esc_html( $key['desc'] ).''; 602 | 603 | return $out; 604 | } 605 | 606 | 607 | /** 608 | * Field Number 609 | * 610 | * @access private 611 | * @param array 612 | * @param string 613 | * @return string 614 | * @since 1.5 615 | */ 616 | 617 | function create_field_number( $key, $out = "" ) 618 | { 619 | $out .= $this->create_field_label( $key['name'], $key['_id'] ) . '
    '; 620 | 621 | $out .= ''; 637 | 638 | return $out; 639 | } 640 | 641 | 642 | /** 643 | * Field Label 644 | * 645 | * @access private 646 | * @param string 647 | * @param string 648 | * @return string 649 | * @since 1.5 650 | */ 651 | 652 | function create_field_label( $name = "", $id = "" ) { 653 | return ''; 654 | } 655 | 656 | } // class 657 | } --------------------------------------------------------------------------------