Repository navigation
Expand file tree
/
Copy pathgeneral-template.php
More file actions
5677 lines (5150 loc) · 180 KB
/
Copy pathgeneral-template.php
File metadata and controls
5677 lines (5150 loc) · 180 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?php
/**
* General template tags that can go anywhere in a template.
*
* @package WordPress
* @subpackage Template
*/
/**
* Loads header template.
*
* Includes the header template for a theme or if a name is specified then a
* specialized header will be included.
*
* For the parameter, if the file is called "header-special.php" then specify
* "special".
*
* @since 1.5.0
* @since 5.5.0 A return value was added.
* @since 5.5.0 The `$args` parameter was added.
*
* @param string|null $name The name of the specialized header. Default null.
* @param array $args Optional. Additional arguments passed to the header template.
* Default empty array.
* @return void|false Void on success, false if the template does not exist.
*/
function get_header( $name = null, $args = array() ) {
/**
* Fires before the header template file is loaded.
*
* @since 2.1.0
* @since 2.8.0 The `$name` parameter was added.
* @since 5.5.0 The `$args` parameter was added.
*
* @param string|null $name Name of the specific header file to use. Null for the default header.
* @param array $args Additional arguments passed to the header template.
*/
do_action( 'get_header', $name, $args );
$templates = array();
$name = (string) $name;
if ( '' !== $name ) {
$templates[] = "header-{$name}.php";
}
$templates[] = 'header.php';
if ( ! locate_template( $templates, true, true, $args ) ) {
return false;
}
}
/**
* Loads footer template.
*
* Includes the footer template for a theme or if a name is specified then a
* specialized footer will be included.
*
* For the parameter, if the file is called "footer-special.php" then specify
* "special".
*
* @since 1.5.0
* @since 5.5.0 A return value was added.
* @since 5.5.0 The `$args` parameter was added.
*
* @param string|null $name The name of the specialized footer. Default null.
* @param array $args Optional. Additional arguments passed to the footer template.
* Default empty array.
* @return void|false Void on success, false if the template does not exist.
*/
function get_footer( $name = null, $args = array() ) {
/**
* Fires before the footer template file is loaded.
*
* @since 2.1.0
* @since 2.8.0 The `$name` parameter was added.
* @since 5.5.0 The `$args` parameter was added.
*
* @param string|null $name Name of the specific footer file to use. Null for the default footer.
* @param array $args Additional arguments passed to the footer template.
*/
do_action( 'get_footer', $name, $args );
$templates = array();
$name = (string) $name;
if ( '' !== $name ) {
$templates[] = "footer-{$name}.php";
}
$templates[] = 'footer.php';
if ( ! locate_template( $templates, true, true, $args ) ) {
return false;
}
}
/**
* Loads sidebar template.
*
* Includes the sidebar template for a theme or if a name is specified then a
* specialized sidebar will be included.
*
* For the parameter, if the file is called "sidebar-special.php" then specify
* "special".
*
* @since 1.5.0
* @since 5.5.0 A return value was added.
* @since 5.5.0 The `$args` parameter was added.
*
* @param string|null $name The name of the specialized sidebar. Default null.
* @param array $args Optional. Additional arguments passed to the sidebar template.
* Default empty array.
* @return void|false Void on success, false if the template does not exist.
*/
function get_sidebar( $name = null, $args = array() ) {
/**
* Fires before the sidebar template file is loaded.
*
* @since 2.2.0
* @since 2.8.0 The `$name` parameter was added.
* @since 5.5.0 The `$args` parameter was added.
*
* @param string|null $name Name of the specific sidebar file to use. Null for the default sidebar.
* @param array $args Additional arguments passed to the sidebar template.
*/
do_action( 'get_sidebar', $name, $args );
$templates = array();
$name = (string) $name;
if ( '' !== $name ) {
$templates[] = "sidebar-{$name}.php";
}
$templates[] = 'sidebar.php';
if ( ! locate_template( $templates, true, true, $args ) ) {
return false;
}
}
/**
* Loads a template part into a template.
*
* Provides a simple mechanism for child themes to overload reusable sections of code
* in the theme.
*
* Includes the named template part for a theme or if a name is specified then a
* specialized part will be included. If the theme contains no {slug}.php file
* then no template will be included.
*
* The template is included using require, not require_once, so you may include the
* same template part multiple times.
*
* For the $name parameter, if the file is called "{slug}-special.php" then specify
* "special".
*
* @since 3.0.0
* @since 5.5.0 A return value was added.
* @since 5.5.0 The `$args` parameter was added.
*
* @param string $slug The slug name for the generic template.
* @param string|null $name Optional. The name of the specialized template. Default null.
* @param array $args Optional. Additional arguments passed to the template.
* Default empty array.
* @return void|false Void on success, false if the template does not exist.
*/
function get_template_part( $slug, $name = null, $args = array() ) {
/**
* Fires before the specified template part file is loaded.
*
* The dynamic portion of the hook name, `$slug`, refers to the slug name
* for the generic template part.
*
* @since 3.0.0
* @since 5.5.0 The `$args` parameter was added.
*
* @param string $slug The slug name for the generic template.
* @param string|null $name The name of the specialized template
* or null if there is none.
* @param array $args Additional arguments passed to the template.
*/
do_action( "get_template_part_{$slug}", $slug, $name, $args );
$templates = array();
$name = (string) $name;
if ( '' !== $name ) {
$templates[] = "{$slug}-{$name}.php";
}
$templates[] = "{$slug}.php";
/**
* Fires before an attempt is made to locate and load a template part.
*
* @since 5.2.0
* @since 5.5.0 The `$args` parameter was added.
*
* @param string $slug The slug name for the generic template.
* @param string $name The name of the specialized template
* or an empty string if there is none.
* @param string[] $templates Array of template files to search for, in order.
* @param array $args Additional arguments passed to the template.
*/
do_action( 'get_template_part', $slug, $name, $templates, $args );
if ( ! locate_template( $templates, true, false, $args ) ) {
return false;
}
}
/**
* Displays search form.
*
* Will first attempt to locate the searchform.php file in either the child or
* the parent, then load it. If it doesn't exist, then the default search form
* will be displayed. The default search form is HTML, which will be displayed.
* There is a filter applied to the search form HTML in order to edit or replace
* it. The filter is {@see 'get_search_form'}.
*
* This function is primarily used by themes which want to hardcode the search
* form into the sidebar and also by the search widget in WordPress.
*
* There is also an action that is called whenever the function is run called,
* {@see 'pre_get_search_form'}. This can be useful for outputting JavaScript that the
* search relies on or various formatting that applies to the beginning of the
* search. To give a few examples of what it can be used for.
*
* @since 2.7.0
* @since 5.2.0 The `$args` array parameter was added in place of an `$echo` boolean flag.
*
* @param array $args {
* Optional. Array of display arguments.
*
* @type bool $echo Whether to echo or return the form. Default true.
* @type string $aria_label ARIA label for the search form. Useful to distinguish
* multiple search forms on the same page and improve
* accessibility. Default empty.
* }
* @return void|string Void if 'echo' argument is true, search form HTML if 'echo' is false.
*/
function get_search_form( $args = array() ) {
/**
* Fires before the search form is retrieved, at the start of get_search_form().
*
* @since 2.7.0 as 'get_search_form' action.
* @since 3.6.0
* @since 5.5.0 The `$args` parameter was added.
*
* @link https://core.trac.wordpress.org/ticket/19321
*
* @param array $args The array of arguments for building the search form.
* See get_search_form() for information on accepted arguments.
*/
do_action( 'pre_get_search_form', $args );
$echo = true;
if ( ! is_array( $args ) ) {
/*
* Back compat: to ensure previous uses of get_search_form() continue to
* function as expected, we handle a value for the boolean $echo param removed
* in 5.2.0. Then we deal with the $args array and cast its defaults.
*/
$echo = (bool) $args;
// Set an empty array and allow default arguments to take over.
$args = array();
}
// Defaults are to echo and to output no custom label on the form.
$defaults = array(
'echo' => $echo,
'aria_label' => '',
);
$args = wp_parse_args( $args, $defaults );
/**
* Filters the array of arguments used when generating the search form.
*
* @since 5.2.0
*
* @param array $args The array of arguments for building the search form.
* See get_search_form() for information on accepted arguments.
*/
$args = apply_filters( 'search_form_args', $args );
// Ensure that the filtered arguments contain all required default values.
$args = array_merge( $defaults, $args );
$format = current_theme_supports( 'html5', 'search-form' ) ? 'html5' : 'xhtml';
/**
* Filters the HTML format of the search form.
*
* @since 3.6.0
* @since 5.5.0 The `$args` parameter was added.
*
* @param string $format The type of markup to use in the search form.
* Accepts 'html5', 'xhtml'.
* @param array $args The array of arguments for building the search form.
* See get_search_form() for information on accepted arguments.
*/
$format = apply_filters( 'search_form_format', $format, $args );
$search_form_template = locate_template( 'searchform.php' );
if ( '' !== $search_form_template ) {
ob_start();
require $search_form_template;
$form = ob_get_clean();
} else {
// Build a string containing an aria-label to use for the search form.
if ( $args['aria_label'] ) {
$aria_label = 'aria-label="' . esc_attr( $args['aria_label'] ) . '" ';
} else {
/*
* If there's no custom aria-label, we can set a default here. At the
* moment it's empty as there's uncertainty about what the default should be.
*/
$aria_label = '';
}
if ( 'html5' === $format ) {
$form = '<form role="search" ' . $aria_label . 'method="get" class="search-form" action="' . esc_url( home_url( '/' ) ) . '">
<label>
<span class="screen-reader-text">' .
/* translators: Hidden accessibility text. */
_x( 'Search for:', 'label' ) .
'</span>
<input type="search" class="search-field" placeholder="' . esc_attr_x( 'Search …', 'placeholder' ) . '" value="' . get_search_query() . '" name="s" />
</label>
<input type="submit" class="search-submit" value="' . esc_attr_x( 'Search', 'submit button' ) . '" />
</form>';
} else {
$form = '<form role="search" ' . $aria_label . 'method="get" id="searchform" class="searchform" action="' . esc_url( home_url( '/' ) ) . '">
<div>
<label class="screen-reader-text" for="s">' .
/* translators: Hidden accessibility text. */
_x( 'Search for:', 'label' ) .
'</label>
<input type="text" value="' . get_search_query() . '" name="s" id="s" />
<input type="submit" id="searchsubmit" value="' . esc_attr_x( 'Search', 'submit button' ) . '" />
</div>
</form>';
}
}
/**
* Filters the HTML output of the search form.
*
* @since 2.7.0
* @since 5.5.0 The `$args` parameter was added.
*
* @param string $form The search form HTML output.
* @param array $args The array of arguments for building the search form.
* See get_search_form() for information on accepted arguments.
*/
$result = apply_filters( 'get_search_form', $form, $args );
if ( null === $result ) {
$result = $form;
}
if ( $args['echo'] ) {
echo $result;
} else {
return $result;
}
}
/**
* Retrieves the markup for an accessible tooltip.
*
* Returns a button with an accessible name popover hint.
*
* @since 7.1.0
*
* @param string $content Plain-text tooltip content. An empty value returns an empty string.
* @param array $args {
* Optional. Arguments for building the tooltip.
*
* @type string $id Unique ID for the popover element. Default is a
* generated unique ID.
* @type string $button Existing `button` or `a` markup. Used instead of generated button.
* Default empty string.
* @type string $label Not used for tooltips.
* @type string $close_label Not used for tooltips.
* @type string $icon Dashicons icon class for the toggle button.
* Default 'dashicons-editor-help'. Should match the control's
* visible label.
* @type string $class Additional class(es) for the wrapping element.
* Default empty.
* }
* @return string Tooltip HTML markup, or an empty string when no content is provided.
*/
function wp_get_tooltip( $content, $args = array() ) {
$args['type'] = 'tooltip';
return wp_get_tooltip_helper( $content, $args );
}
/**
* Retrieves the markup for an accessible toggle tip.
*
* Returns a button and an action triggered toggle tip with `$content`.
*
* @since 7.1.0
*
* @param string $content Plain-text tooltip content. An empty value returns an empty string.
* @param array $args {
* Optional. Arguments for building the tooltip.
*
* @type string $id Unique ID for the popover element. Default is a
* generated unique ID.
* @type string $button Existing `button` markup. Used instead of generated button.
* Default empty string.
* @type string $label Accessible label for the toggle button.
* Default 'Help', matching the default icon.
* Ignored for tooltips.
* @type string $close_label Accessible label for the close button. Default 'Close'.
* @type string $icon Dashicons icon class for the toggle button.
* Default 'dashicons-editor-help'. Should match the control's
* visible label.
* @type string $class Additional class(es) for the wrapping element.
* Default empty.
* }
* @return string Toggletip HTML markup, or an empty string when no content is provided.
*/
function wp_get_toggletip( $content, $args = array() ) {
$args['type'] = 'toggletip';
return wp_get_tooltip_helper( $content, $args );
}
/**
* Retrieves the markup for an accessible tooltip or toggletip.
*
* Returns a button and either a hover/focus triggered tooltip popover or an action
* triggered toggle tip. Enqueue the `wp-tooltip` style and script where it is used.
* Tooltips are used to show the accessible name of a control.
* Toggletips are used for longer supporting text explaining context.
*
* @since 7.1.0
*
* @param string $content Plain-text tooltip content. An empty value returns an empty string.
* @param array $args {
* Optional. Arguments for building the tooltip.
*
* @type string $id Unique ID for the popover element. Default is a
* generated unique ID.
* @type string $button Existing `button` or `a` markup. Used instead of generated button.
* Default empty string.
* @type string $label Accessible label for the toggle button.
* Default 'Help', matching the default icon.
* Ignored for tooltips.
* @type string $close_label Accessible label for the close button. Default 'Close'.
* @type string $icon Dashicons icon class for the toggle button.
* Default 'dashicons-editor-help'. Should match the control's
* visible label.
* @type string $class Additional class(es) for the wrapping element.
* Default empty.
* @type string $type Type of tooltip: either `tooltip` or `toggletip`.
* Default 'tooltip'.
* }
* @return string Tooltip HTML markup, or an empty string when no content is provided.
*/
function wp_get_tooltip_helper( $content, $args = array() ) {
$content = trim( (string) $content );
if ( '' === $content ) {
return '';
}
$defaults = array(
'id' => wp_unique_id( 'wp-tooltip-' ),
'button' => '',
'label' => __( 'Help' ),
'close_label' => __( 'Close' ),
'icon' => 'dashicons-editor-help',
'class' => '',
'type' => 'tooltip',
);
$args = wp_parse_args( $args, $defaults );
$classes = ( 'tooltip' === $args['type'] ) ? 'wp-tooltip wp-is-tooltip' : 'wp-tooltip wp-is-toggletip';
if ( '' !== $args['class'] ) {
$classes .= ' ' . $args['class'];
}
$icon = ( $args['icon'] ) ? trim( $args['icon'] ) : $defaults['icon'];
$id = ( $args['id'] ) ? $args['id'] : $defaults['id'];
// Tooltips use the content as the accessible name; toggletips use the label.
$label = ( 'tooltip' === $args['type'] ) ? wp_strip_all_tags( $content, true ) : $args['label'];
/*
* The generated button is a plain skeleton. Every dynamic attribute is
* added through the tag processor below, so caller-supplied markup is
* never scanned or substituted and a percent sign in custom markup,
* such as a percent-encoded URL, is never treated as a conversion
* specification.
*/
$default_button = '<button type="button"><span></span></button>';
$is_default = ! $args['button'];
$button = ( $args['button'] ) ? $args['button'] : $default_button;
// The accepted root element is a `button`, or an `a` for tooltips.
$tag = false;
$processor = new WP_HTML_Tag_Processor( $button );
if ( true === $processor->next_tag( 'button' ) ) {
$tag = 'button';
} else {
$processor = new WP_HTML_Tag_Processor( $button );
if ( 'tooltip' === $args['type'] && true === $processor->next_tag( 'a' ) ) {
$tag = 'a';
}
}
if ( false === $tag ) {
// Button HTML passed was not valid. Reset to default.
$is_default = true;
$button = $default_button;
$processor = new WP_HTML_Tag_Processor( $button );
$processor->next_tag( 'button' );
$tag = 'button';
}
/*
* Attributes that apply to every accepted button are added in one pass.
* Attributes that name the control are only added when the caller's
* markup did not already provide them.
*/
if ( null === $processor->get_attribute( 'aria-label' ) ) {
$processor->set_attribute( 'aria-label', $label );
}
$processor->add_class( 'wp-tooltip__toggle' );
if ( 'button' === $tag && 'tooltip' !== $args['type'] ) {
$processor->set_attribute( 'popovertarget', $id );
$processor->set_attribute( 'aria-haspopup', 'dialog' );
}
// The generated button also carries the dashicon on its inner span.
if ( $is_default && true === $processor->next_tag( 'span' ) ) {
$processor->set_attribute( 'class', 'dashicons ' . $icon );
$processor->set_attribute( 'aria-hidden', 'true' );
}
$button = $processor->get_updated_html();
/*
* The markup only uses phrasing content so it is valid when nested
* in a phrasing context. Sectioning content (e.g. `div`, `dialog`) will
* cause the parser to close an open `p`, creating an empty and breaking
* the layout. See #65660.
*/
if ( 'tooltip' === $args['type'] ) {
$markup = sprintf(
'<span class="%1$s">
%6$s
<span popover="hint" id="%2$s" class="wp-tooltip__bubble" role="tooltip">' .
'<span id="%2$s-text" class="wp-tooltip__text">%5$s</span>' .
'</span>' .
'</span>',
esc_attr( $classes ),
esc_attr( $id ),
esc_attr( $label ),
esc_attr( $icon ),
esc_html( $content ),
$button,
);
} else {
/*
* A `span` with `role="dialog"` is used instead of a `dialog` element to keep the
* markup as phrasing content. The `aria-label`, `tabindex`, and `autofocus`
* attributes reproduce the accessible name and focus handling of the native element.
*/
$markup = sprintf(
'<span class="%1$s">
%7$s
<span popover="auto" id="%2$s" class="wp-tooltip__bubble" role="dialog" aria-label="%3$s" tabindex="-1" autofocus>' .
'<span id="%2$s-text" class="wp-tooltip__text">%5$s</span>' .
'<button type="button" class="wp-tooltip__close" popovertarget="%2$s" popovertargetaction="hide" aria-label="%6$s">' .
'<span class="dashicons dashicons-no-alt" aria-hidden="true"></span>' .
'</button>' .
'</span>' .
'</span>',
esc_attr( $classes ),
esc_attr( $id ),
esc_attr( $label ),
esc_attr( $icon ),
esc_html( $content ),
esc_attr( $args['close_label'] ),
$button,
);
}
return $markup;
}
/**
* Displays the Log In/Out link.
*
* Displays a link, which allows users to navigate to the Log In page to log in
* or log out depending on whether they are currently logged in.
*
* @since 1.5.0
*
* @param string $redirect Optional path to redirect to on login/logout.
* @param bool $display Default to echo and not return the link.
* @return void|string Void if `$display` argument is true, log in/out link if `$display` is false.
*/
function wp_loginout( $redirect = '', $display = true ) {
if ( ! is_user_logged_in() ) {
$link = '<a href="' . esc_url( wp_login_url( $redirect ) ) . '">' . __( 'Log in' ) . '</a>';
} else {
$link = '<a href="' . esc_url( wp_logout_url( $redirect ) ) . '">' . __( 'Log out' ) . '</a>';
}
if ( $display ) {
/**
* Filters the HTML output for the Log In/Log Out link.
*
* @since 1.5.0
*
* @param string $link The HTML link content.
*/
echo apply_filters( 'loginout', $link );
} else {
/** This filter is documented in wp-includes/general-template.php */
return apply_filters( 'loginout', $link );
}
}
/**
* Retrieves the logout URL.
*
* Returns the URL that allows the user to log out of the site.
*
* @since 2.7.0
*
* @param string $redirect Path to redirect to on logout.
* @return string The logout URL. Note: HTML-encoded via esc_html() in wp_nonce_url().
*/
function wp_logout_url( $redirect = '' ) {
$args = array();
if ( ! empty( $redirect ) ) {
$args['redirect_to'] = urlencode( $redirect );
}
$logout_url = add_query_arg( $args, site_url( 'wp-login.php?action=logout', 'login' ) );
$logout_url = wp_nonce_url( $logout_url, 'log-out' );
/**
* Filters the logout URL.
*
* @since 2.8.0
*
* @param string $logout_url The HTML-encoded logout URL.
* @param string $redirect Path to redirect to on logout.
*/
return apply_filters( 'logout_url', $logout_url, $redirect );
}
/**
* Retrieves the login URL.
*
* @since 2.7.0
*
* @param string $redirect Path to redirect to on log in.
* @param bool $force_reauth Whether to force reauthorization, even if a cookie is present.
* Default false.
* @return string The login URL. Not HTML-encoded.
*/
function wp_login_url( $redirect = '', $force_reauth = false ) {
$login_url = site_url( 'wp-login.php', 'login' );
if ( ! empty( $redirect ) ) {
$login_url = add_query_arg( 'redirect_to', urlencode( $redirect ), $login_url );
}
if ( $force_reauth ) {
$login_url = add_query_arg( 'reauth', '1', $login_url );
}
/**
* Filters the login URL.
*
* @since 2.8.0
* @since 4.2.0 The `$force_reauth` parameter was added.
*
* @param string $login_url The login URL. Not HTML-encoded.
* @param string $redirect The path to redirect to on login, if supplied.
* @param bool $force_reauth Whether to force reauthorization, even if a cookie is present.
*/
return apply_filters( 'login_url', $login_url, $redirect, $force_reauth );
}
/**
* Returns the URL that allows the user to register on the site.
*
* @since 3.6.0
*
* @return string User registration URL.
*/
function wp_registration_url() {
/**
* Filters the user registration URL.
*
* @since 3.6.0
*
* @param string $register The user registration URL.
*/
return apply_filters( 'register_url', site_url( 'wp-login.php?action=register', 'login' ) );
}
/**
* Provides a simple login form for use anywhere within WordPress.
*
* The login form HTML is echoed by default. Pass a false value for `$echo` to return it instead.
*
* @since 3.0.0
* @since 6.6.0 Added `required_username` and `required_password` arguments.
*
* @param array $args {
* Optional. Array of options to control the form output. Default empty array.
*
* @type bool $echo Whether to display the login form or return the form HTML code.
* Default true (echo).
* @type string $redirect URL to redirect to. Must be absolute, as in "https://example.com/mypage/".
* Default is to redirect back to the request URI.
* @type string $form_id ID attribute value for the form. Default 'loginform'.
* @type string $label_username Label for the username or email address field. Default 'Username or Email Address'.
* @type string $label_password Label for the password field. Default 'Password'.
* @type string $label_remember Label for the remember field. Default 'Remember Me'.
* @type string $label_log_in Label for the submit button. Default 'Log In'.
* @type string $id_username ID attribute value for the username field. Default 'user_login'.
* @type string $id_password ID attribute value for the password field. Default 'user_pass'.
* @type string $id_remember ID attribute value for the remember field. Default 'rememberme'.
* @type string $id_submit ID attribute value for the submit button. Default 'wp-submit'.
* @type bool $remember Whether to display the "rememberme" checkbox in the form.
* @type string $value_username Default value for the username field. Default empty.
* @type bool $value_remember Whether the "Remember Me" checkbox should be checked by default.
* Default false (unchecked).
* @type bool $required_username Whether the username field has the 'required' attribute.
* Default false.
* @type bool $required_password Whether the password field has the 'required' attribute.
* Default false.
*
* }
* @return void|string Void if 'echo' argument is true, login form HTML if 'echo' is false.
*/
function wp_login_form( $args = array() ) {
$defaults = array(
'echo' => true,
// Default 'redirect' value takes the user back to the request URI.
'redirect' => ( is_ssl() ? 'https://' : 'http://' ) . $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI'],
'form_id' => 'loginform',
'label_username' => __( 'Username or Email Address' ),
'label_password' => __( 'Password' ),
'label_remember' => __( 'Remember Me' ),
'label_log_in' => __( 'Log In' ),
'id_username' => 'user_login',
'id_password' => 'user_pass',
'id_remember' => 'rememberme',
'id_submit' => 'wp-submit',
'remember' => true,
'value_username' => '',
// Set 'value_remember' to true to default the "Remember me" checkbox to checked.
'value_remember' => false,
// Set 'required_username' to true to add the required attribute to username field.
'required_username' => false,
// Set 'required_password' to true to add the required attribute to password field.
'required_password' => false,
);
/**
* Filters the default login form output arguments.
*
* @since 3.0.0
*
* @see wp_login_form()
*
* @param array $defaults An array of default login form arguments.
*/
$args = wp_parse_args( $args, apply_filters( 'login_form_defaults', $defaults ) );
/**
* Filters content to display at the top of the login form.
*
* The filter evaluates just following the opening form tag element.
*
* @since 3.0.0
*
* @param string $content Content to display. Default empty.
* @param array $args Array of login form arguments.
*/
$login_form_top = apply_filters( 'login_form_top', '', $args );
/**
* Filters content to display in the middle of the login form.
*
* The filter evaluates just following the location where the 'login-password'
* field is displayed.
*
* @since 3.0.0
*
* @param string $content Content to display. Default empty.
* @param array $args Array of login form arguments.
*/
$login_form_middle = apply_filters( 'login_form_middle', '', $args );
/**
* Filters content to display at the bottom of the login form.
*
* The filter evaluates just preceding the closing form tag element.
*
* @since 3.0.0
*
* @param string $content Content to display. Default empty.
* @param array $args Array of login form arguments.
*/
$login_form_bottom = apply_filters( 'login_form_bottom', '', $args );
$direction_style = is_rtl() ? ' style="direction: ltr;"' : '';
$form =
sprintf(
'<form name="%1$s" id="%1$s" action="%2$s" method="post">',
esc_attr( $args['form_id'] ),
esc_url( site_url( 'wp-login.php', 'login_post' ) )
) .
$login_form_top .
sprintf(
'<p class="login-username">
<label for="%1$s">%2$s</label>
<input type="text" name="log" id="%1$s" autocomplete="username" class="input" value="%3$s" size="20"%4$s%5$s />
</p>',
esc_attr( $args['id_username'] ),
esc_html( $args['label_username'] ),
esc_attr( $args['value_username'] ),
( $args['required_username'] ? ' required="required"' : '' ),
$direction_style
) .
sprintf(
'<p class="login-password">
<label for="%1$s">%2$s</label>
<input type="password" name="pwd" id="%1$s" autocomplete="current-password" spellcheck="false" class="input" value="" size="20"%3$s%4$s />
</p>',
esc_attr( $args['id_password'] ),
esc_html( $args['label_password'] ),
( $args['required_password'] ? ' required="required"' : '' ),
$direction_style
) .
$login_form_middle .
( $args['remember'] ?
sprintf(
'<p class="login-remember"><label><input name="rememberme" type="checkbox" id="%1$s" value="forever"%2$s /> %3$s</label></p>',
esc_attr( $args['id_remember'] ),
( $args['value_remember'] ? ' checked="checked"' : '' ),
esc_html( $args['label_remember'] )
) : ''
) .
sprintf(
'<p class="login-submit">
<input type="submit" name="wp-submit" id="%1$s" class="button button-primary" value="%2$s" />
<input type="hidden" name="redirect_to" value="%3$s" />
</p>',
esc_attr( $args['id_submit'] ),
esc_attr( $args['label_log_in'] ),
esc_url( $args['redirect'] )
) .
$login_form_bottom .
'</form>';
if ( $args['echo'] ) {
echo $form;
} else {
return $form;
}
}
/**
* Returns the URL that allows the user to reset the lost password.
*
* @since 2.8.0
*
* @param string $redirect Path to redirect to on login.
* @return string Lost password URL.
*/
function wp_lostpassword_url( $redirect = '' ) {
$args = array(
'action' => 'lostpassword',
);
if ( ! empty( $redirect ) ) {
$args['redirect_to'] = urlencode( $redirect );
}
if ( is_multisite() ) {
$blog_details = get_site();
$wp_login_path = $blog_details->path . 'wp-login.php';
} else {
$wp_login_path = 'wp-login.php';
}
$lostpassword_url = add_query_arg( $args, network_site_url( $wp_login_path, 'login' ) );
/**
* Filters the Lost Password URL.
*
* @since 2.8.0
*
* @param string $lostpassword_url The lost password page URL.
* @param string $redirect The path to redirect to on login.
*/
return apply_filters( 'lostpassword_url', $lostpassword_url, $redirect );
}
/**
* Displays the Registration or Admin link.
*
* Display a link which allows the user to navigate to the registration page if
* not logged in and registration is enabled or to the dashboard if logged in.
*
* @since 1.5.0
*
* @param string $before Text to output before the link. Default `<li>`.
* @param string $after Text to output after the link. Default `</li>`.
* @param bool $display Default to echo and not return the link.
* @return void|string Void if `$display` argument is true, registration or admin link
* if `$display` is false.
*/
function wp_register( $before = '<li>', $after = '</li>', $display = true ) {
if ( ! is_user_logged_in() ) {
if ( get_option( 'users_can_register' ) ) {
$link = $before . '<a href="' . esc_url( wp_registration_url() ) . '">' . __( 'Register' ) . '</a>' . $after;
} else {
$link = '';
}
} elseif ( current_user_can( 'read' ) ) {
$link = $before . '<a href="' . admin_url() . '">' . __( 'Site Admin' ) . '</a>' . $after;
} else {
$link = '';
}
/**
* Filters the HTML link to the Registration or Admin page.
*
* Users are sent to the admin page if logged-in, or the registration page
* if enabled and logged-out.
*
* @since 1.5.0
*
* @param string $link The HTML code for the link to the Registration or Admin page.
*/
$link = apply_filters( 'register', $link );
if ( $display ) {
echo $link;
} else {
return $link;
}
}
/**
* Theme container function for the 'wp_meta' action.
*
* The {@see 'wp_meta'} action can have several purposes, depending on how you use it,
* but one purpose might have been to allow for theme switching.
*
* @since 1.5.0
*
* @link https://core.trac.wordpress.org/ticket/1458 Explanation of 'wp_meta' action.
*/
function wp_meta() {
/**
* Fires before displaying echoed content in the sidebar.
*
* @since 1.5.0
*/
do_action( 'wp_meta' );
}
/**
* Displays information about the current site.
*
* @since 0.71
*
* @see get_bloginfo() For possible `$show` values
*
* @param string $show Optional. Site information to display. Default empty.
*/
function bloginfo( $show = '' ) {
echo get_bloginfo( $show, 'display' );
}
/**
* Retrieves information about the current site.