projects / GitHub / WoltLab / woltlab.github.io.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
Deployed 1a4ec0e to 5.4 with MkDocs 1.1.2 and mike 0.5.5
[GitHub/WoltLab/woltlab.github.io.git] / 5.4 / php / api / events / index.html
CommitLineData
45ca63d0
TD		 1
2<!doctype html>
3<html lang="en" class="no-js">
4 <head>
5
6 <meta charset="utf-8">
7 <meta name="viewport" content="width=device-width,initial-scale=1">
8
9
10
11
12 <link rel="shortcut icon" href="../../../assets/default.favicon.ico">
13 <meta name="generator" content="mkdocs-1.1.2, mkdocs-material-7.0.3">
14
15
16
17 <title>Events - WoltLab Suite Documentation</title>
18
19
20
21 <link rel="stylesheet" href="../../../assets/stylesheets/main.1655a90d.min.css">
22
23
24 <link rel="stylesheet" href="../../../assets/stylesheets/palette.7fa14f5b.min.css">
25
26
27
28 <meta name="theme-color" content="#009485">
29
30
31
32
33
34
35
36
37 <link rel="stylesheet" href="../../../stylesheets/extra.css">
38
39
40
41
42
43 </head>
44
45
46
47
48
49
50
51 <body dir="ltr" data-md-color-scheme="" data-md-color-primary="teal" data-md-color-accent="">
52
53
54
55 <input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
56 <input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
57 <label class="md-overlay" for="__drawer"></label>
58 <div data-md-component="skip">
59
60
61 <a href="#events" class="md-skip">
62 Skip to content
63 </a>
64
65 </div>
66 <div data-md-component="announce">
67
68 <aside class="md-announce">
69 <div class="md-announce__inner md-grid md-typeset">
70
71 <a href="https://www.woltlab.com">Back to <strong>woltlab.com</strong></a>
72
73 </div>
74 </aside>
75
76 </div>
77
78
79
80<header class="md-header" data-md-component="header">
81 <nav class="md-header__inner md-grid" aria-label="Header">
82 <a href="../../.." title="WoltLab Suite Documentation" class="md-header__button md-logo" aria-label="WoltLab Suite Documentation">
83
84 <img src="../../../assets/logo.png" alt="logo">
85
86 </a>
87 <label class="md-header__button md-icon" for="__drawer">
88 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3V6m0 5h18v2H3v-2m0 5h18v2H3v-2z"/></svg>
89 </label>
90 <div class="md-header__title" data-md-component="header-title">
91 <div class="md-header__ellipsis">
92 <div class="md-header__topic">
93 <span class="md-ellipsis">
94 WoltLab Suite Documentation
95 </span>
96 </div>
97 <div class="md-header__topic" data-md-component="header-topic">
98 <span class="md-ellipsis">
99
100 Events
101
102 </span>
103 </div>
104 </div>
105 </div>
106 <div class="md-header__options">
107
108 </div>
109
110 <label class="md-header__button md-icon" for="__search">
111 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5z"/></svg>
112 </label>
113
114<div class="md-search" data-md-component="search" role="dialog">
115 <label class="md-search__overlay" for="__search"></label>
116 <div class="md-search__inner" role="search">
117 <form class="md-search__form" name="search">
118 <input type="text" class="md-search__input" name="query" aria-label="Search" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" data-md-state="active" required>
119 <label class="md-search__icon md-icon" for="__search">
120 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5z"/></svg>
121 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11h12z"/></svg>
122 </label>
123 <button type="reset" class="md-search__icon md-icon" aria-label="Clear" tabindex="-1">
124 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 6.41L17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12 19 6.41z"/></svg>
125 </button>
126 </form>
127 <div class="md-search__output">
128 <div class="md-search__scrollwrap" data-md-scrollfix>
129 <div class="md-search-result" data-md-component="search-result">
130 <div class="md-search-result__meta">
131 Initializing search
132 </div>
133 <ol class="md-search-result__list"></ol>
134 </div>
135 </div>
136 </div>
137 </div>
138</div>
139
140
141 </nav>
142</header>
143
144 <div class="md-container" data-md-component="container">
145
146
147
148
149 <main class="md-main" data-md-component="main">
150 <div class="md-main__inner md-grid">
151
152
153
154 <div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" >
155 <div class="md-sidebar__scrollwrap">
156 <div class="md-sidebar__inner">
157
158
159
160
161
162<nav class="md-nav md-nav--primary" aria-label="Navigation" data-md-level="0">
163 <label class="md-nav__title" for="__drawer">
164 <a href="../../.." title="WoltLab Suite Documentation" class="md-nav__button md-logo" aria-label="WoltLab Suite Documentation">
165
166 <img src="../../../assets/logo.png" alt="logo">
167
168 </a>
169 WoltLab Suite Documentation
170 </label>
171
172 <ul class="md-nav__list" data-md-scrollfix>
173
174
175
176
177
178
179
180
181 <li class="md-nav__item">
182 <a href="../../../getting-started/" class="md-nav__link">
183 Getting Started
184 </a>
185 </li>
186
187
188
189
190
191
192
193
194
195
196
197
198
199 <li class="md-nav__item md-nav__item--active md-nav__item--nested">
200
201
202 <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_2" type="checkbox" id="__nav_2" checked>
203
204 <label class="md-nav__link" for="__nav_2">
205 PHP API
206 <span class="md-nav__icon md-icon"></span>
207 </label>
208 <nav class="md-nav" aria-label="PHP API" data-md-level="1">
209 <label class="md-nav__title" for="__nav_2">
210 <span class="md-nav__icon md-icon"></span>
211 PHP API
212 </label>
213 <ul class="md-nav__list" data-md-scrollfix>
214
215
216
217
218
219 <li class="md-nav__item">
220 <a href="../../pages/" class="md-nav__link">
221 Pages
222 </a>
223 </li>
224
225
226
227
228
229
230
231 <li class="md-nav__item">
232 <a href="../../database-objects/" class="md-nav__link">
233 Database Objects
234 </a>
235 </li>
236
237
238
239
240
241
242
243 <li class="md-nav__item">
244 <a href="../../database-access/" class="md-nav__link">
245 Database Access
246 </a>
247 </li>
248
249
250
251
252
253
254
255 <li class="md-nav__item">
256 <a href="../../exceptions/" class="md-nav__link">
257 Exceptions
258 </a>
259 </li>
260
261
262
263
264
265
266
267
268
269
270 <li class="md-nav__item md-nav__item--active md-nav__item--nested">
271
272
273 <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_2_5" type="checkbox" id="__nav_2_5" checked>
274
275 <label class="md-nav__link" for="__nav_2_5">
276 API
277 <span class="md-nav__icon md-icon"></span>
278 </label>
279 <nav class="md-nav" aria-label="API" data-md-level="2">
280 <label class="md-nav__title" for="__nav_2_5">
281 <span class="md-nav__icon md-icon"></span>
282 API
283 </label>
284 <ul class="md-nav__list" data-md-scrollfix>
285
286
287
288
289
290 <li class="md-nav__item">
291 <a href="../caches/" class="md-nav__link">
292 Caches
293 </a>
294 </li>
295
296
297
298
299
300
301
302 <li class="md-nav__item">
303 <a href="../comments/" class="md-nav__link">
304 Comments
305 </a>
306 </li>
307
308
309
310
311
312
313
314 <li class="md-nav__item">
315 <a href="../cronjobs/" class="md-nav__link">
316 Cronjobs
317 </a>
318 </li>
319
320
321
322
323
324
325
326
327
328 <li class="md-nav__item md-nav__item--active">
329
330 <input class="md-nav__toggle md-toggle" data-md-toggle="toc" type="checkbox" id="__toc">
331
332
333
334
335 <label class="md-nav__link md-nav__link--active" for="__toc">
336 Events
337 <span class="md-nav__icon md-icon"></span>
338 </label>
339
340 <a href="./" class="md-nav__link md-nav__link--active">
341 Events
342 </a>
343
344
345<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
346
347
348
349
350
351 <label class="md-nav__title" for="__toc">
352 <span class="md-nav__icon md-icon"></span>
353 Table of contents
354 </label>
355 <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
356
357 <li class="md-nav__item">
358 <a href="#introductory-example" class="md-nav__link">
359 Introductory Example
360 </a>
361
362</li>
363
364 <li class="md-nav__item">
365 <a href="#listening-to-events" class="md-nav__link">
366 Listening to Events
367 </a>
368
369</li>
370
371 <li class="md-nav__item">
372 <a href="#firing-events" class="md-nav__link">
373 Firing Events
374 </a>
375
376 <nav class="md-nav" aria-label="Firing Events">
377 <ul class="md-nav__list">
378
379 <li class="md-nav__item">
380 <a href="#example-using-parameters-argument" class="md-nav__link">
381 Example: Using $parameters argument
382 </a>
383
384</li>
385
386 </ul>
387 </nav>
388
389</li>
390
391 <li class="md-nav__item">
392 <a href="#advanced-example-additional-form-field" class="md-nav__link">
393 Advanced Example: Additional Form Field
394 </a>
395
396</li>
397
398 </ul>
399
400</nav>
401
402 </li>
403
404
405
406
407
408
409
410
411 <li class="md-nav__item md-nav__item--nested">
412
413
414 <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_2_5_5" type="checkbox" id="__nav_2_5_5" >
415
416 <label class="md-nav__link" for="__nav_2_5_5">
417 Form Builder
418 <span class="md-nav__icon md-icon"></span>
419 </label>
420 <nav class="md-nav" aria-label="Form Builder" data-md-level="3">
421 <label class="md-nav__title" for="__nav_2_5_5">
422 <span class="md-nav__icon md-icon"></span>
423 Form Builder
424 </label>
425 <ul class="md-nav__list" data-md-scrollfix>
426
427
428
429
430
431 <li class="md-nav__item">
432 <a href="../form_builder/overview/" class="md-nav__link">
433 Overview
434 </a>
435 </li>
436
437
438
439
440
441
442
443 <li class="md-nav__item">
444 <a href="../form_builder/structure/" class="md-nav__link">
445 Structure
446 </a>
447 </li>
448
449
450
451
452
453
454
455 <li class="md-nav__item">
456 <a href="../form_builder/form_fields/" class="md-nav__link">
457 Fields
458 </a>
459 </li>
460
461
462
463
464
465
466
467 <li class="md-nav__item">
468 <a href="../form_builder/validation_data/" class="md-nav__link">
469 Validation and Data
470 </a>
471 </li>
472
473
474
475
476
477
478
479 <li class="md-nav__item">
480 <a href="../form_builder/dependencies/" class="md-nav__link">
481 Dependencies
482 </a>
483 </li>
484
485
486
487 </ul>
488 </nav>
489 </li>
490
491
492
493
494
495
496
497 <li class="md-nav__item">
498 <a href="../package_installation_plugins/" class="md-nav__link">
499 Package Installation Plugins
500 </a>
501 </li>
502
503
504
505
506
507
508
509 <li class="md-nav__item">
510 <a href="../user_activity_points/" class="md-nav__link">
511 User Activity Points
512 </a>
513 </li>
514
515
516
517
518
519
520
521 <li class="md-nav__item">
522 <a href="../user_notifications/" class="md-nav__link">
523 User Notifications
524 </a>
525 </li>
526
527
528
529
530
531
532
533 <li class="md-nav__item">
534 <a href="../sitemaps/" class="md-nav__link">
535 Sitemaps
536 </a>
537 </li>
538
539
540
541 </ul>
542 </nav>
543 </li>
544
545
546
547
548
549
550
551 <li class="md-nav__item">
552 <a href="../../code-style/" class="md-nav__link">
553 Code Style
554 </a>
555 </li>
556
557
558
559
560
561
562
563 <li class="md-nav__item">
564 <a href="../../apps/" class="md-nav__link">
565 Apps
566 </a>
567 </li>
568
569
570
571
572
573
574
575 <li class="md-nav__item">
576 <a href="../../gdpr/" class="md-nav__link">
577 GDPR
578 </a>
579 </li>
580
581
582
583 </ul>
584 </nav>
585 </li>
586
587
588
589
590
591
592
593
594
595
596
597 <li class="md-nav__item md-nav__item--nested">
598
599
600 <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_3" type="checkbox" id="__nav_3" >
601
602 <label class="md-nav__link" for="__nav_3">
603 Languages, Templates & CSS
604 <span class="md-nav__icon md-icon"></span>
605 </label>
606 <nav class="md-nav" aria-label="Languages, Templates & CSS" data-md-level="1">
607 <label class="md-nav__title" for="__nav_3">
608 <span class="md-nav__icon md-icon"></span>
609 Languages, Templates & CSS
610 </label>
611 <ul class="md-nav__list" data-md-scrollfix>
612
613
614
615
616
617 <li class="md-nav__item">
618 <a href="../../../view/languages/" class="md-nav__link">
619 Languages
620 </a>
621 </li>
622
623
624
625
626
627
628
629 <li class="md-nav__item">
630 <a href="../../../view/templates/" class="md-nav__link">
631 Templates
632 </a>
633 </li>
634
635
636
637
638
639
640
641 <li class="md-nav__item">
642 <a href="../../../view/css/" class="md-nav__link">
643 CSS
644 </a>
645 </li>
646
647
648
649 </ul>
650 </nav>
651 </li>
652
653
654
655
656
657
658
659
660
661
662
663 <li class="md-nav__item md-nav__item--nested">
664
665
666 <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_4" type="checkbox" id="__nav_4" >
667
668 <label class="md-nav__link" for="__nav_4">
669 JavaScript API
670 <span class="md-nav__icon md-icon"></span>
671 </label>
672 <nav class="md-nav" aria-label="JavaScript API" data-md-level="1">
673 <label class="md-nav__title" for="__nav_4">
674 <span class="md-nav__icon md-icon"></span>
675 JavaScript API
676 </label>
677 <ul class="md-nav__list" data-md-scrollfix>
678
679
680
681
682
683 <li class="md-nav__item">
684 <a href="../../../javascript/general-usage/" class="md-nav__link">
685 General Usage
686 </a>
687 </li>
688
689
690
691
692
693
694
695
696 <li class="md-nav__item md-nav__item--nested">
697
698
699 <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_4_2" type="checkbox" id="__nav_4_2" >
700
701 <label class="md-nav__link" for="__nav_4_2">
702 New API
703 <span class="md-nav__icon md-icon"></span>
704 </label>
705 <nav class="md-nav" aria-label="New API" data-md-level="2">
706 <label class="md-nav__title" for="__nav_4_2">
707 <span class="md-nav__icon md-icon"></span>
708 New API
709 </label>
710 <ul class="md-nav__list" data-md-scrollfix>
711
712
713
714
715
716 <li class="md-nav__item">
717 <a href="../../../javascript/new-api_writing-a-module/" class="md-nav__link">
718 Writing a module
719 </a>
720 </li>
721
722
723
724
725
726
727
728 <li class="md-nav__item">
729 <a href="../../../javascript/new-api_data-structures/" class="md-nav__link">
730 Data Structures
731 </a>
732 </li>
733
734
735
736
737
738
739
740 <li class="md-nav__item">
741 <a href="../../../javascript/new-api_core/" class="md-nav__link">
742 Core Functions
743 </a>
744 </li>
745
746
747
748
749
750
751
752 <li class="md-nav__item">
753 <a href="../../../javascript/new-api_dom/" class="md-nav__link">
754 DOM
755 </a>
756 </li>
757
758
759
760
761
762
763
764 <li class="md-nav__item">
765 <a href="../../../javascript/new-api_events/" class="md-nav__link">
766 Event Handling
767 </a>
768 </li>
769
770
771
772
773
774
775
776 <li class="md-nav__item">
777 <a href="../../../javascript/new-api_ajax/" class="md-nav__link">
778 Ajax
779 </a>
780 </li>
781
782
783
784
785
786
787
788 <li class="md-nav__item">
789 <a href="../../../javascript/new-api_dialogs/" class="md-nav__link">
790 Dialogs
791 </a>
792 </li>
793
794
795
796
797
798
799
800 <li class="md-nav__item">
801 <a href="../../../javascript/new-api_browser/" class="md-nav__link">
802 Browser and Screen Sizes
803 </a>
804 </li>
805
806
807
808
809
810
811
812 <li class="md-nav__item">
813 <a href="../../../javascript/new-api_ui/" class="md-nav__link">
814 User Interface
815 </a>
816 </li>
817
818
819
820 </ul>
821 </nav>
822 </li>
823
824
825
826
827
828
829
830 <li class="md-nav__item">
831 <a href="../../../javascript/legacy-api/" class="md-nav__link">
832 Legacy API
833 </a>
834 </li>
835
836
837
838
839
840
841
842 <li class="md-nav__item">
843 <a href="../../../javascript/helper-functions/" class="md-nav__link">
844 Helper Functions
845 </a>
846 </li>
847
848
849
850
851
852
853
854 <li class="md-nav__item">
855 <a href="../../../javascript/code-snippets/" class="md-nav__link">
856 Code Snippets
857 </a>
858 </li>
859
860
861
862 </ul>
863 </nav>
864 </li>
865
866
867
868
869
870
871
872
873
874
875
876 <li class="md-nav__item md-nav__item--nested">
877
878
879 <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_5" type="checkbox" id="__nav_5" >
880
881 <label class="md-nav__link" for="__nav_5">
882 Package Components
883 <span class="md-nav__icon md-icon"></span>
884 </label>
885 <nav class="md-nav" aria-label="Package Components" data-md-level="1">
886 <label class="md-nav__title" for="__nav_5">
887 <span class="md-nav__icon md-icon"></span>
888 Package Components
889 </label>
890 <ul class="md-nav__list" data-md-scrollfix>
891
892
893
894
895
896 <li class="md-nav__item">
897 <a href="../../../package/package-xml/" class="md-nav__link">
898 package.xml
899 </a>
900 </li>
901
902
903
904
905
906
907
908
909 <li class="md-nav__item md-nav__item--nested">
910
911
912 <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_5_2" type="checkbox" id="__nav_5_2" >
913
914 <label class="md-nav__link" for="__nav_5_2">
915 PIPs
916 <span class="md-nav__icon md-icon"></span>
917 </label>
918 <nav class="md-nav" aria-label="PIPs" data-md-level="2">
919 <label class="md-nav__title" for="__nav_5_2">
920 <span class="md-nav__icon md-icon"></span>
921 PIPs
922 </label>
923 <ul class="md-nav__list" data-md-scrollfix>
924
925
926
927
928
929 <li class="md-nav__item">
930 <a href="../../../package/pip/" class="md-nav__link">
931 Overview
932 </a>
933 </li>
934
935
936
937
938
939
940
941 <li class="md-nav__item">
942 <a href="../../../package/pip/acl-option/" class="md-nav__link">
943 aclOption
944 </a>
945 </li>
946
947
948
949
950
951
952
953 <li class="md-nav__item">
954 <a href="../../../package/pip/acp-menu/" class="md-nav__link">
955 acpMenu
956 </a>
957 </li>
958
959
960
961
962
963
964
965 <li class="md-nav__item">
966 <a href="../../../package/pip/acp-search-provider/" class="md-nav__link">
967 acpSearchProvider
968 </a>
969 </li>
970
971
972
973
974
975
976
977 <li class="md-nav__item">
978 <a href="../../../package/pip/acp-template/" class="md-nav__link">
979 acpTemplate
980 </a>
981 </li>
982
983
984
985
986
987
988
989 <li class="md-nav__item">
990 <a href="../../../package/pip/bbcode/" class="md-nav__link">
991 bbcode
992 </a>
993 </li>
994
995
996
997
998
999
1000
1001 <li class="md-nav__item">
1002 <a href="../../../package/pip/box/" class="md-nav__link">
1003 box
1004 </a>
1005 </li>
1006
1007
1008
1009
1010
1011
1012
1013 <li class="md-nav__item">
1014 <a href="../../../package/pip/clipboard-action/" class="md-nav__link">
1015 clipboardAction
1016 </a>
1017 </li>
1018
1019
1020
1021
1022
1023
1024
1025 <li class="md-nav__item">
1026 <a href="../../../package/pip/core-object/" class="md-nav__link">
1027 coreObject
1028 </a>
1029 </li>
1030
1031
1032
1033
1034
1035
1036
1037 <li class="md-nav__item">
1038 <a href="../../../package/pip/cronjob/" class="md-nav__link">
1039 cronjob
1040 </a>
1041 </li>
1042
1043
1044
1045
1046
1047
1048
1049 <li class="md-nav__item">
1050 <a href="../../../package/pip/event-listener/" class="md-nav__link">
1051 eventListener
1052 </a>
1053 </li>
1054
1055
1056
1057
1058
1059
1060
1061 <li class="md-nav__item">
1062 <a href="../../../package/pip/file/" class="md-nav__link">
1063 file
1064 </a>
1065 </li>
1066
1067
1068
1069
1070
1071
1072
1073 <li class="md-nav__item">
1074 <a href="../../../package/pip/language/" class="md-nav__link">
1075 language
1076 </a>
1077 </li>
1078
1079
1080
1081
1082
1083
1084
1085 <li class="md-nav__item">
1086 <a href="../../../package/pip/media-provider/" class="md-nav__link">
1087 mediaProvider
1088 </a>
1089 </li>
1090
1091
1092
1093
1094
1095
1096
1097 <li class="md-nav__item">
1098 <a href="../../../package/pip/menu/" class="md-nav__link">
1099 menu
1100 </a>
1101 </li>
1102
1103
1104
1105
1106
1107
1108
1109 <li class="md-nav__item">
1110 <a href="../../../package/pip/menu-item/" class="md-nav__link">
1111 menuItem
1112 </a>
1113 </li>
1114
1115
1116
1117
1118
1119
1120
1121 <li class="md-nav__item">
1122 <a href="../../../package/pip/object-type/" class="md-nav__link">
1123 objectType
1124 </a>
1125 </li>
1126
1127
1128
1129
1130
1131
1132
1133 <li class="md-nav__item">
1134 <a href="../../../package/pip/object-type-definition/" class="md-nav__link">
1135 objectTypeDefinition
1136 </a>
1137 </li>
1138
1139
1140
1141
1142
1143
1144
1145 <li class="md-nav__item">
1146 <a href="../../../package/pip/option/" class="md-nav__link">
1147 option
1148 </a>
1149 </li>
1150
1151
1152
1153
1154
1155
1156
1157 <li class="md-nav__item">
1158 <a href="../../../package/pip/page/" class="md-nav__link">
1159 page
1160 </a>
1161 </li>
1162
1163
1164
1165
1166
1167
1168
1169 <li class="md-nav__item">
1170 <a href="../../../package/pip/pip/" class="md-nav__link">
1171 pip
1172 </a>
1173 </li>
1174
1175
1176
1177
1178
1179
1180
1181 <li class="md-nav__item">
1182 <a href="../../../package/pip/script/" class="md-nav__link">
1183 script
1184 </a>
1185 </li>
1186
1187
1188
1189
1190
1191
1192
1193 <li class="md-nav__item">
1194 <a href="../../../package/pip/smiley/" class="md-nav__link">
1195 smiley
1196 </a>
1197 </li>
1198
1199
1200
1201
1202
1203
1204
1205 <li class="md-nav__item">
1206 <a href="../../../package/pip/sql/" class="md-nav__link">
1207 sql
1208 </a>
1209 </li>
1210
1211
1212
1213
1214
1215
1216
1217 <li class="md-nav__item">
1218 <a href="../../../package/pip/style/" class="md-nav__link">
1219 style
1220 </a>
1221 </li>
1222
1223
1224
1225
1226
1227
1228
1229 <li class="md-nav__item">
1230 <a href="../../../package/pip/template/" class="md-nav__link">
1231 template
1232 </a>
1233 </li>
1234
1235
1236
1237
1238
1239
1240
1241 <li class="md-nav__item">
1242 <a href="../../../package/pip/template-listener/" class="md-nav__link">
1243 templateListener
1244 </a>
1245 </li>
1246
1247
1248
1249
1250
1251
1252
1253 <li class="md-nav__item">
1254 <a href="../../../package/pip/user-group-option/" class="md-nav__link">
1255 userGroupOption
1256 </a>
1257 </li>
1258
1259
1260
1261
1262
1263
1264
1265 <li class="md-nav__item">
1266 <a href="../../../package/pip/user-menu/" class="md-nav__link">
1267 userMenu
1268 </a>
1269 </li>
1270
1271
1272
1273
1274
1275
1276
1277 <li class="md-nav__item">
1278 <a href="../../../package/pip/user-notification-event/" class="md-nav__link">
1279 userNotificationEvent
1280 </a>
1281 </li>
1282
1283
1284
1285
1286
1287
1288
1289 <li class="md-nav__item">
1290 <a href="../../../package/pip/user-option/" class="md-nav__link">
1291 userOption
1292 </a>
1293 </li>
1294
1295
1296
1297
1298
1299
1300
1301 <li class="md-nav__item">
1302 <a href="../../../package/pip/user-profile-menu/" class="md-nav__link">
1303 userProfileMenu
1304 </a>
1305 </li>
1306
1307
1308
1309 </ul>
1310 </nav>
1311 </li>
1312
1313
1314
1315
1316
1317
1318
1319 <li class="md-nav__item">
1320 <a href="../../../package/database-php-api/" class="md-nav__link">
1321 Database PHP API
1322 </a>
1323 </li>
1324
1325
1326
1327 </ul>
1328 </nav>
1329 </li>
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341 <li class="md-nav__item md-nav__item--nested">
1342
1343
1344 <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_6" type="checkbox" id="__nav_6" >
1345
1346 <label class="md-nav__link" for="__nav_6">
1347 Migration
1348 <span class="md-nav__icon md-icon"></span>
1349 </label>
1350 <nav class="md-nav" aria-label="Migration" data-md-level="1">
1351 <label class="md-nav__title" for="__nav_6">
1352 <span class="md-nav__icon md-icon"></span>
1353 Migration
1354 </label>
1355 <ul class="md-nav__list" data-md-scrollfix>
1356
1357
1358
1359
1360
1361
1362 <li class="md-nav__item md-nav__item--nested">
1363
1364
1365 <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_6_1" type="checkbox" id="__nav_6_1" >
1366
1367 <label class="md-nav__link" for="__nav_6_1">
1368 Migrating from WSC 5.3
1369 <span class="md-nav__icon md-icon"></span>
1370 </label>
1371 <nav class="md-nav" aria-label="Migrating from WSC 5.3" data-md-level="2">
1372 <label class="md-nav__title" for="__nav_6_1">
1373 <span class="md-nav__icon md-icon"></span>
1374 Migrating from WSC 5.3
1375 </label>
1376 <ul class="md-nav__list" data-md-scrollfix>
1377
1378
1379
1380
1381
1382 <li class="md-nav__item">
1383 <a href="../../../migration/wsc53/php/" class="md-nav__link">
1384 PHP API
1385 </a>
1386 </li>
1387
1388
1389
1390
1391
1392
1393
1394 <li class="md-nav__item">
1395 <a href="../../../migration/wsc53/session/" class="md-nav__link">
1396 Session Handling and Authentication
1397 </a>
1398 </li>
1399
1400
1401
1402
1403
1404
1405
1406 <li class="md-nav__item">
1407 <a href="../../../migration/wsc53/javascript/" class="md-nav__link">
1408 JavaScript
1409 </a>
1410 </li>
1411
1412
1413
1414
1415
1416
1417
1418 <li class="md-nav__item">
1419 <a href="../../../migration/wsc53/templates/" class="md-nav__link">
1420 Templates
1421 </a>
1422 </li>
1423
1424
1425
1426
1427
1428
1429
1430 <li class="md-nav__item">
1431 <a href="../../../migration/wsc53/libraries/" class="md-nav__link">
1432 Third Party Libraries
1433 </a>
1434 </li>
1435
1436
1437
1438 </ul>
1439 </nav>
1440 </li>
1441
1442
1443
1444
1445
1446
1447
1448
1449 <li class="md-nav__item md-nav__item--nested">
1450
1451
1452 <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_6_2" type="checkbox" id="__nav_6_2" >
1453
1454 <label class="md-nav__link" for="__nav_6_2">
1455 Migrating from WSC 5.2
1456 <span class="md-nav__icon md-icon"></span>
1457 </label>
1458 <nav class="md-nav" aria-label="Migrating from WSC 5.2" data-md-level="2">
1459 <label class="md-nav__title" for="__nav_6_2">
1460 <span class="md-nav__icon md-icon"></span>
1461 Migrating from WSC 5.2
1462 </label>
1463 <ul class="md-nav__list" data-md-scrollfix>
1464
1465
1466
1467
1468
1469 <li class="md-nav__item">
1470 <a href="../../../migration/wsc52/php/" class="md-nav__link">
1471 PHP API
1472 </a>
1473 </li>
1474
1475
1476
1477
1478
1479
1480
1481 <li class="md-nav__item">
1482 <a href="../../../migration/wsc52/templates/" class="md-nav__link">
1483 Templates and Languages
1484 </a>
1485 </li>
1486
1487
1488
1489
1490
1491
1492
1493 <li class="md-nav__item">
1494 <a href="../../../migration/wsc52/libraries/" class="md-nav__link">
1495 Third Party Libraries
1496 </a>
1497 </li>
1498
1499
1500
1501 </ul>
1502 </nav>
1503 </li>
1504
1505
1506
1507
1508
1509
1510
1511
1512 <li class="md-nav__item md-nav__item--nested">
1513
1514
1515 <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_6_3" type="checkbox" id="__nav_6_3" >
1516
1517 <label class="md-nav__link" for="__nav_6_3">
1518 Migrating from WSC 3.1
1519 <span class="md-nav__icon md-icon"></span>
1520 </label>
1521 <nav class="md-nav" aria-label="Migrating from WSC 3.1" data-md-level="2">
1522 <label class="md-nav__title" for="__nav_6_3">
1523 <span class="md-nav__icon md-icon"></span>
1524 Migrating from WSC 3.1
1525 </label>
1526 <ul class="md-nav__list" data-md-scrollfix>
1527
1528
1529
1530
1531
1532 <li class="md-nav__item">
1533 <a href="../../../migration/wsc31/php/" class="md-nav__link">
1534 PHP API
1535 </a>
1536 </li>
1537
1538
1539
1540 </ul>
1541 </nav>
1542 </li>
1543
1544
1545
1546
1547
1548
1549
1550
1551 <li class="md-nav__item md-nav__item--nested">
1552
1553
1554 <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_6_4" type="checkbox" id="__nav_6_4" >
1555
1556 <label class="md-nav__link" for="__nav_6_4">
1557 Migrating from WSC 3.0
1558 <span class="md-nav__icon md-icon"></span>
1559 </label>
1560 <nav class="md-nav" aria-label="Migrating from WSC 3.0" data-md-level="2">
1561 <label class="md-nav__title" for="__nav_6_4">
1562 <span class="md-nav__icon md-icon"></span>
1563 Migrating from WSC 3.0
1564 </label>
1565 <ul class="md-nav__list" data-md-scrollfix>
1566
1567
1568
1569
1570
1571 <li class="md-nav__item">
1572 <a href="../../../migration/wsc30/php/" class="md-nav__link">
1573 PHP API
1574 </a>
1575 </li>
1576
1577
1578
1579
1580
1581
1582
1583 <li class="md-nav__item">
1584 <a href="../../../migration/wsc30/javascript/" class="md-nav__link">
1585 JavaScript API
1586 </a>
1587 </li>
1588
1589
1590
1591
1592
1593
1594
1595 <li class="md-nav__item">
1596 <a href="../../../migration/wsc30/templates/" class="md-nav__link">
1597 Templates
1598 </a>
1599 </li>
1600
1601
1602
1603
1604
1605
1606
1607 <li class="md-nav__item">
1608 <a href="../../../migration/wsc30/css/" class="md-nav__link">
1609 CSS
1610 </a>
1611 </li>
1612
1613
1614
1615
1616
1617
1618
1619 <li class="md-nav__item">
1620 <a href="../../../migration/wsc30/package/" class="md-nav__link">
1621 Package Components
1622 </a>
1623 </li>
1624
1625
1626
1627 </ul>
1628 </nav>
1629 </li>
1630
1631
1632
1633
1634
1635
1636
1637
1638 <li class="md-nav__item md-nav__item--nested">
1639
1640
1641 <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_6_5" type="checkbox" id="__nav_6_5" >
1642
1643 <label class="md-nav__link" for="__nav_6_5">
1644 Migrating from WCF 2.1
1645 <span class="md-nav__icon md-icon"></span>
1646 </label>
1647 <nav class="md-nav" aria-label="Migrating from WCF 2.1" data-md-level="2">
1648 <label class="md-nav__title" for="__nav_6_5">
1649 <span class="md-nav__icon md-icon"></span>
1650 Migrating from WCF 2.1
1651 </label>
1652 <ul class="md-nav__list" data-md-scrollfix>
1653
1654
1655
1656
1657
1658 <li class="md-nav__item">
1659 <a href="../../../migration/wcf21/php/" class="md-nav__link">
1660 PHP API
1661 </a>
1662 </li>
1663
1664
1665
1666
1667
1668
1669
1670 <li class="md-nav__item">
1671 <a href="../../../migration/wcf21/templates/" class="md-nav__link">
1672 Templates
1673 </a>
1674 </li>
1675
1676
1677
1678
1679
1680
1681
1682 <li class="md-nav__item">
1683 <a href="../../../migration/wcf21/css/" class="md-nav__link">
1684 CSS
1685 </a>
1686 </li>
1687
1688
1689
1690
1691
1692
1693
1694 <li class="md-nav__item">
1695 <a href="../../../migration/wcf21/package/" class="md-nav__link">
1696 Package Components
1697 </a>
1698 </li>
1699
1700
1701
1702 </ul>
1703 </nav>
1704 </li>
1705
1706
1707
1708 </ul>
1709 </nav>
1710 </li>
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722 <li class="md-nav__item md-nav__item--nested">
1723
1724
1725 <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_7" type="checkbox" id="__nav_7" >
1726
1727 <label class="md-nav__link" for="__nav_7">
1728 Tutorials
1729 <span class="md-nav__icon md-icon"></span>
1730 </label>
1731 <nav class="md-nav" aria-label="Tutorials" data-md-level="1">
1732 <label class="md-nav__title" for="__nav_7">
1733 <span class="md-nav__icon md-icon"></span>
1734 Tutorials
1735 </label>
1736 <ul class="md-nav__list" data-md-scrollfix>
1737
1738
1739
1740
1741
1742
1743 <li class="md-nav__item md-nav__item--nested">
1744
1745
1746 <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_7_1" type="checkbox" id="__nav_7_1" >
1747
1748 <label class="md-nav__link" for="__nav_7_1">
1749 Tutorial Series
1750 <span class="md-nav__icon md-icon"></span>
1751 </label>
1752 <nav class="md-nav" aria-label="Tutorial Series" data-md-level="2">
1753 <label class="md-nav__title" for="__nav_7_1">
1754 <span class="md-nav__icon md-icon"></span>
1755 Tutorial Series
1756 </label>
1757 <ul class="md-nav__list" data-md-scrollfix>
1758
1759
1760
1761
1762
1763 <li class="md-nav__item">
1764 <a href="../../../tutorial/series/overview/" class="md-nav__link">
1765 Overview
1766 </a>
1767 </li>
1768
1769
1770
1771
1772
1773
1774
1775 <li class="md-nav__item">
1776 <a href="../../../tutorial/series/part_1/" class="md-nav__link">
1777 Part 1
1778 </a>
1779 </li>
1780
1781
1782
1783
1784
1785
1786
1787 <li class="md-nav__item">
1788 <a href="../../../tutorial/series/part_2/" class="md-nav__link">
1789 Part 2
1790 </a>
1791 </li>
1792
1793
1794
1795
1796
1797
1798
1799 <li class="md-nav__item">
1800 <a href="../../../tutorial/series/part_3/" class="md-nav__link">
1801 Part 3
1802 </a>
1803 </li>
1804
1805
1806
1807 </ul>
1808 </nav>
1809 </li>
1810
1811
1812
1813 </ul>
1814 </nav>
1815 </li>
1816
1817
1818
1819 </ul>
1820</nav>
1821 </div>
1822 </div>
1823 </div>
1824
1825
1826
1827 <div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" >
1828 <div class="md-sidebar__scrollwrap">
1829 <div class="md-sidebar__inner">
1830
1831<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
1832
1833
1834
1835
1836
1837 <label class="md-nav__title" for="__toc">
1838 <span class="md-nav__icon md-icon"></span>
1839 Table of contents
1840 </label>
1841 <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
1842
1843 <li class="md-nav__item">
1844 <a href="#introductory-example" class="md-nav__link">
1845 Introductory Example
1846 </a>
1847
1848</li>
1849
1850 <li class="md-nav__item">
1851 <a href="#listening-to-events" class="md-nav__link">
1852 Listening to Events
1853 </a>
1854
1855</li>
1856
1857 <li class="md-nav__item">
1858 <a href="#firing-events" class="md-nav__link">
1859 Firing Events
1860 </a>
1861
1862 <nav class="md-nav" aria-label="Firing Events">
1863 <ul class="md-nav__list">
1864
1865 <li class="md-nav__item">
1866 <a href="#example-using-parameters-argument" class="md-nav__link">
1867 Example: Using $parameters argument
1868 </a>
1869
1870</li>
1871
1872 </ul>
1873 </nav>
1874
1875</li>
1876
1877 <li class="md-nav__item">
1878 <a href="#advanced-example-additional-form-field" class="md-nav__link">
1879 Advanced Example: Additional Form Field
1880 </a>
1881
1882</li>
1883
1884 </ul>
1885
1886</nav>
1887 </div>
1888 </div>
1889 </div>
1890
1891
1892 <div class="md-content" data-md-component="content">
1893 <article class="md-content__inner md-typeset">
1894
1895
1896
1897 <h1 id="events">Events<a class="headerlink" href="#events" title="Permanent link">#</a></h1>
1898<p>WoltLab Suite's event system allows manipulation of program flows and data without having to change any of the original source code.
1899At many locations throughout the PHP code of WoltLab Suite Core and mainly through inheritance also in the applications and plugins, so called <em>events</em> are fired which trigger registered <em>event listeners</em> that get access to the object firing the event (or at least the class name if the event has been fired in a static method).</p>
1900<p>This page focuses on the technical aspects of events and event listeners, <a href="../../../package/pip/event-listener/">the eventListener package installation plugin page</a> covers how you can actually register an event listener.
1901A comprehensive list of all available events is provided <a href="../event_list/">here</a>.</p>
1902<h2 id="introductory-example">Introductory Example<a class="headerlink" href="#introductory-example" title="Permanent link">#</a></h2>
1903<p>Let's start with a simple example to illustrate how the event system works.
1904Consider this pre-existing class:</p>
1905<div class="highlight"><pre><span></span><code><span class="o">&lt;?</span><span class="nx">php</span>
1906<span class="k">namespace</span> <span class="nx">wcf\system\example</span><span class="p">;</span>
1907<span class="k">use</span> <span class="nx">wcf\system\event\EventHandler</span><span class="p">;</span>
1908
1909<span class="k">class</span> <span class="nc">ExampleComponent</span> <span class="p">{</span>
1910 <span class="k">public</span> <span class="nv">$var</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span>
1911
1912 <span class="k">public</span> <span class="k">function</span> <span class="nf">getVar</span><span class="p">()</span> <span class="p">{</span>
1913 <span class="nx">EventHandler</span><span class="o">::</span><span class="na">getInstance</span><span class="p">()</span><span class="o">-&gt;</span><span class="na">fireAction</span><span class="p">(</span><span class="nv">$this</span><span class="p">,</span> <span class="s1">&#39;getVar&#39;</span><span class="p">);</span>
1914
1915 <span class="k">return</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="na">var</span><span class="p">;</span>
1916 <span class="p">}</span>
1917<span class="p">}</span>
1918</code></pre></div>
1919
1920<p>where an event with event name <code>getVar</code> is fired in the <code>getVar()</code> method.</p>
1921<p>If you create an object of this class and call the <code>getVar()</code> method, the return value will be <code>1</code>, of course:</p>
1922<div class="highlight"><pre><span></span><code><span class="o">&lt;?</span><span class="nx">php</span>
1923
1924<span class="nv">$example</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">wcf\system\example\ExampleComponent</span><span class="p">();</span>
1925<span class="k">if</span> <span class="p">(</span><span class="nv">$example</span><span class="o">-&gt;</span><span class="na">getVar</span><span class="p">()</span> <span class="o">==</span> <span class="mi">1</span><span class="p">)</span> <span class="p">{</span>
1926 <span class="k">echo</span> <span class="s2">&quot;var is 1!&quot;</span><span class="p">;</span>
1927<span class="p">}</span>
1928<span class="k">else</span> <span class="k">if</span> <span class="p">(</span><span class="nv">$example</span><span class="o">-&gt;</span><span class="na">getVar</span><span class="p">()</span> <span class="o">==</span> <span class="mi">2</span><span class="p">)</span> <span class="p">{</span>
1929 <span class="k">echo</span> <span class="s2">&quot;var is 2!&quot;</span><span class="p">;</span>
1930<span class="p">}</span>
1931<span class="k">else</span> <span class="p">{</span>
1932 <span class="k">echo</span> <span class="s2">&quot;No, var is neither 1 nor 2.&quot;</span><span class="p">;</span>
1933<span class="p">}</span>
1934
1935<span class="c1">// output: var is 1!</span>
1936</code></pre></div>
1937
1938<p>Now, consider that we have registered the following event listener to this event:</p>
1939<div class="highlight"><pre><span></span><code><span class="o">&lt;?</span><span class="nx">php</span>
1940<span class="k">namespace</span> <span class="nx">wcf\system\event\listener</span><span class="p">;</span>
1941
1942<span class="k">class</span> <span class="nc">ExampleEventListener</span> <span class="k">implements</span> <span class="nx">IParameterizedEventListener</span> <span class="p">{</span>
1943 <span class="k">public</span> <span class="k">function</span> <span class="nf">execute</span><span class="p">(</span><span class="nv">$eventObj</span><span class="p">,</span> <span class="nv">$className</span><span class="p">,</span> <span class="nv">$eventName</span><span class="p">,</span> <span class="k">array</span> <span class="o">&amp;</span><span class="nv">$parameters</span><span class="p">)</span> <span class="p">{</span>
1944 <span class="nv">$eventObj</span><span class="o">-&gt;</span><span class="na">var</span> <span class="o">=</span> <span class="mi">2</span><span class="p">;</span>
1945 <span class="p">}</span>
1946<span class="p">}</span>
1947</code></pre></div>
1948
1949<p>Whenever the event in the <code>getVar()</code> method is called, this method (of the same event listener object) is called.
1950In this case, the value of the method's first parameter is the <code>ExampleComponent</code> object passed as the first argument of the <code>EventHandler::fireAction()</code> call in <code>ExampleComponent::getVar()</code>.
1951As <code>ExampleComponent::$var</code> is a public property, the event listener code can change it and set it to <code>2</code>.</p>
1952<p>If you now execute the example code from above again, the output will change from <code>var is 1!</code> to <code>var is 2!</code> because prior to returning the value, the event listener code changes the value from <code>1</code> to <code>2</code>.</p>
1953<p>This introductory example illustrates how event listeners can change data in a non-intrusive way.
1954Program flow can be changed, for example, by throwing a <code>wcf\system\exception\PermissionDeniedException</code> if some additional constraint to access a page is not fulfilled.</p>
1955<h2 id="listening-to-events">Listening to Events<a class="headerlink" href="#listening-to-events" title="Permanent link">#</a></h2>
1956<p>In order to listen to events, you need to register the event listener and the event listener itself needs to implement the interface <code>wcf\system\event\listener\IParameterizedEventListener</code> which only contains the <code>execute</code> method (see example above).</p>
1957<p>The first parameter <code>$eventObj</code> of the method contains the passed object where the event is fired or the name of the class in which the event is fired if it is fired from a static method.
1958The second parameter <code>$className</code> always contains the name of the class where the event has been fired.
1959The third parameter <code>$eventName</code> provides the name of the event within a class to uniquely identify the exact location in the class where the event has been fired.
1960The last parameter <code>$parameters</code> is a reference to the array which contains additional data passed by the method firing the event.
1961If no additional data is passed, <code>$parameters</code> is empty.</p>
1962<h2 id="firing-events">Firing Events<a class="headerlink" href="#firing-events" title="Permanent link">#</a></h2>
1963<p>If you write code and want plugins to have access at certain points, you can fire an event on your own.
1964The only thing to do is to call the <code>wcf\system\event\EventHandler::fireAction($eventObj, $eventName, array &amp;$parameters = [])</code> method and pass the following parameters:</p>
1965<ol>
1966<li><code>$eventObj</code> should be <code>$this</code> if you fire from an object context, otherwise pass the class name <code>static::class</code>.</li>
1967<li><code>$eventName</code> identifies the event within the class and generally has the same name as the method.
1968 In cases, were you might fire more than one event in a method, for example before and after a certain piece of code, you can use the prefixes <code>before*</code> and <code>after*</code> in your event names.</li>
1969<li><code>$parameters</code> is an optional array which allows you to pass additional data to the event listeners without having to make this data accessible via a property explicitly only created for this purpose.
1970 This additional data can either be just additional information for the event listeners about the context of the method call or allow the event listener to manipulate local data if the code, where the event has been fired, uses the passed data afterwards. </li>
1971</ol>
1972<h3 id="example-using-parameters-argument">Example: Using <code>$parameters</code> argument<a class="headerlink" href="#example-using-parameters-argument" title="Permanent link">#</a></h3>
1973<p>Consider the following method which gets some text that the methods parses.</p>
1974<div class="highlight"><pre><span></span><code><span class="o">&lt;?</span><span class="nx">php</span>
1975<span class="k">namespace</span> <span class="nx">wcf\system\example</span><span class="p">;</span>
1976<span class="k">use</span> <span class="nx">wcf\system\event\EventHandler</span><span class="p">;</span>
1977
1978<span class="k">class</span> <span class="nc">ExampleParser</span> <span class="p">{</span>
1979 <span class="k">public</span> <span class="k">function</span> <span class="nf">parse</span><span class="p">(</span><span class="nv">$text</span><span class="p">)</span> <span class="p">{</span>
1980 <span class="c1">// [some parsing done by default]</span>
1981
1982 <span class="nv">$parameters</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;text&#39;</span> <span class="o">=&gt;</span> <span class="nv">$text</span><span class="p">];</span>
1983 <span class="nx">EventHandler</span><span class="o">::</span><span class="na">getInstance</span><span class="p">()</span><span class="o">-&gt;</span><span class="na">fireAction</span><span class="p">(</span><span class="nv">$this</span><span class="p">,</span> <span class="s1">&#39;parse&#39;</span><span class="p">,</span> <span class="nv">$parameters</span><span class="p">);</span>
1984
1985 <span class="k">return</span> <span class="nv">$parameters</span><span class="p">[</span><span class="s1">&#39;text&#39;</span><span class="p">];</span>
1986 <span class="p">}</span>
1987<span class="p">}</span>
1988</code></pre></div>
1989
1990<p>After the default parsing by the method itself, the author wants to enable plugins to do additional parsing and thus fires an event and passes the parsed text as an additional parameter.
1991Then, a plugin can deliver the following event listener</p>
1992<div class="highlight"><pre><span></span><code><span class="o">&lt;?</span><span class="nx">php</span>
1993<span class="k">namespace</span> <span class="nx">wcf\system\event\listener</span><span class="p">;</span>
1994
1995<span class="k">class</span> <span class="nc">ExampleParserEventListener</span> <span class="k">implements</span> <span class="nx">IParameterizedEventListener</span> <span class="p">{</span>
1996 <span class="k">public</span> <span class="k">function</span> <span class="nf">execute</span><span class="p">(</span><span class="nv">$eventObj</span><span class="p">,</span> <span class="nv">$className</span><span class="p">,</span> <span class="nv">$eventName</span><span class="p">,</span> <span class="k">array</span> <span class="o">&amp;</span><span class="nv">$parameters</span><span class="p">)</span> <span class="p">{</span>
1997 <span class="nv">$text</span> <span class="o">=</span> <span class="nv">$parameters</span><span class="p">[</span><span class="s1">&#39;text&#39;</span><span class="p">];</span>
1998
1999 <span class="c1">// [some additional parsing which changes $text]</span>
2000
2001 <span class="nv">$parameters</span><span class="p">[</span><span class="s1">&#39;text&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="nv">$text</span><span class="p">;</span>
2002 <span class="p">}</span>
2003<span class="p">}</span>
2004</code></pre></div>
2005
2006<p>which can access the text via <code>$parameters['text']</code>.</p>
2007<p>This example can also be perfectly used to illustrate how to name multiple events in the same method.
2008Let's assume that the author wants to enable plugins to change the text before and after the method does its own parsing and thus fires two events:</p>
2009<div class="highlight"><pre><span></span><code><span class="o">&lt;?</span><span class="nx">php</span>
2010<span class="k">namespace</span> <span class="nx">wcf\system\example</span><span class="p">;</span>
2011<span class="k">use</span> <span class="nx">wcf\system\event\EventHandler</span><span class="p">;</span>
2012
2013<span class="k">class</span> <span class="nc">ExampleParser</span> <span class="p">{</span>
2014 <span class="k">public</span> <span class="k">function</span> <span class="nf">parse</span><span class="p">(</span><span class="nv">$text</span><span class="p">)</span> <span class="p">{</span>
2015 <span class="nv">$parameters</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;text&#39;</span> <span class="o">=&gt;</span> <span class="nv">$text</span><span class="p">];</span>
2016 <span class="nx">EventHandler</span><span class="o">::</span><span class="na">getInstance</span><span class="p">()</span><span class="o">-&gt;</span><span class="na">fireAction</span><span class="p">(</span><span class="nv">$this</span><span class="p">,</span> <span class="s1">&#39;beforeParsing&#39;</span><span class="p">,</span> <span class="nv">$parameters</span><span class="p">);</span>
2017 <span class="nv">$text</span> <span class="o">=</span> <span class="nv">$parameters</span><span class="p">[</span><span class="s1">&#39;text&#39;</span><span class="p">];</span>
2018
2019 <span class="c1">// [some parsing done by default]</span>
2020
2021 <span class="nv">$parameters</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;text&#39;</span> <span class="o">=&gt;</span> <span class="nv">$text</span><span class="p">];</span>
2022 <span class="nx">EventHandler</span><span class="o">::</span><span class="na">getInstance</span><span class="p">()</span><span class="o">-&gt;</span><span class="na">fireAction</span><span class="p">(</span><span class="nv">$this</span><span class="p">,</span> <span class="s1">&#39;afterParsing&#39;</span><span class="p">,</span> <span class="nv">$parameters</span><span class="p">);</span>
2023
2024 <span class="k">return</span> <span class="nv">$parameters</span><span class="p">[</span><span class="s1">&#39;text&#39;</span><span class="p">];</span>
2025 <span class="p">}</span>
2026<span class="p">}</span>
2027</code></pre></div>
2028
2029<h2 id="advanced-example-additional-form-field">Advanced Example: Additional Form Field<a class="headerlink" href="#advanced-example-additional-form-field" title="Permanent link">#</a></h2>
2030<p>One common reason to use event listeners is to add an additional field to a pre-existing form (in combination with template listeners, which we will not cover here).
2031We will assume that users are able to do both, create and edit the objects via this form.
2032The points in the program flow of <a href="../../pages/#abstractform">AbstractForm</a> that are relevant here are:</p>
2033<ul>
2034<li>adding object (after the form has been submitted):</li>
2035<li>reading the value of the field</li>
2036<li>validating the read value</li>
2037<li>
2038<p>saving the additional value after successful validation and resetting locally stored value or assigning the current value of the field to the template after unsuccessful validation</p>
2039</li>
2040<li>
2041<p>editing object:</p>
2042</li>
2043<li>on initial form request:<ol>
2044<li>reading the pre-existing value of the edited object</li>
2045<li>assigning the field value to the template</li>
2046</ol>
2047</li>
2048<li>after the form has been submitted:<ol>
2049<li>reading the value of the field</li>
2050<li>validating the read value</li>
2051<li>saving the additional value after successful validation</li>
2052<li>assigning the current value of the field to the template</li>
2053</ol>
2054</li>
2055</ul>
2056<p>All of these cases can be covered the by following code in which we assume that <code>wcf\form\ExampleAddForm</code> is the form to create example objects and that <code>wcf\form\ExampleEditForm</code> extends <code>wcf\form\ExampleAddForm</code> and is used for editing existing example objects.</p>
2057<div class="highlight"><pre><span></span><code><span class="o">&lt;?</span><span class="nx">php</span>
2058<span class="k">namespace</span> <span class="nx">wcf\system\event\listener</span><span class="p">;</span>
2059<span class="k">use</span> <span class="nx">wcf\form\ExampleAddForm</span><span class="p">;</span>
2060<span class="k">use</span> <span class="nx">wcf\form\ExampleEditForm</span><span class="p">;</span>
2061<span class="k">use</span> <span class="nx">wcf\system\exception\UserInputException</span><span class="p">;</span>
2062<span class="k">use</span> <span class="nx">wcf\system\WCF</span><span class="p">;</span>
2063
2064<span class="k">class</span> <span class="nc">ExampleAddFormListener</span> <span class="k">implements</span> <span class="nx">IParameterizedEventListener</span> <span class="p">{</span>
2065 <span class="k">protected</span> <span class="nv">$var</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
2066
2067 <span class="k">public</span> <span class="k">function</span> <span class="nf">execute</span><span class="p">(</span><span class="nv">$eventObj</span><span class="p">,</span> <span class="nv">$className</span><span class="p">,</span> <span class="nv">$eventName</span><span class="p">,</span> <span class="k">array</span> <span class="o">&amp;</span><span class="nv">$parameters</span><span class="p">)</span> <span class="p">{</span>
2068 <span class="nv">$this</span><span class="o">-&gt;</span><span class="nv">$eventName</span><span class="p">(</span><span class="nv">$eventObj</span><span class="p">);</span>
2069 <span class="p">}</span>
2070
2071 <span class="k">protected</span> <span class="k">function</span> <span class="nf">assignVariables</span><span class="p">()</span> <span class="p">{</span>
2072 <span class="nx">WCF</span><span class="o">::</span><span class="na">getTPL</span><span class="p">()</span><span class="o">-&gt;</span><span class="na">assign</span><span class="p">(</span><span class="s1">&#39;var&#39;</span><span class="p">,</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="na">var</span><span class="p">);</span>
2073 <span class="p">}</span>
2074
2075 <span class="k">protected</span> <span class="k">function</span> <span class="nf">readData</span><span class="p">(</span><span class="nx">ExampleEditForm</span> <span class="nv">$eventObj</span><span class="p">)</span> <span class="p">{</span>
2076 <span class="k">if</span> <span class="p">(</span><span class="k">empty</span><span class="p">(</span><span class="nv">$_POST</span><span class="p">))</span> <span class="p">{</span>
2077 <span class="nv">$this</span><span class="o">-&gt;</span><span class="na">var</span> <span class="o">=</span> <span class="nv">$eventObj</span><span class="o">-&gt;</span><span class="na">example</span><span class="o">-&gt;</span><span class="na">var</span><span class="p">;</span>
2078 <span class="p">}</span>
2079 <span class="p">}</span>
2080
2081 <span class="k">protected</span> <span class="k">function</span> <span class="nf">readFormParameters</span><span class="p">()</span> <span class="p">{</span>
2082 <span class="k">if</span> <span class="p">(</span><span class="nb">isset</span><span class="p">(</span><span class="nv">$_POST</span><span class="p">[</span><span class="s1">&#39;var&#39;</span><span class="p">]))</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="na">var</span> <span class="o">=</span> <span class="nb">intval</span><span class="p">(</span><span class="nv">$_POST</span><span class="p">[</span><span class="s1">&#39;var&#39;</span><span class="p">]);</span>
2083 <span class="p">}</span>
2084
2085 <span class="k">protected</span> <span class="k">function</span> <span class="nf">save</span><span class="p">(</span><span class="nx">ExampleAddForm</span> <span class="nv">$eventObj</span><span class="p">)</span> <span class="p">{</span>
2086 <span class="nv">$eventObj</span><span class="o">-&gt;</span><span class="na">additionalFields</span> <span class="o">=</span> <span class="nb">array_merge</span><span class="p">(</span><span class="nv">$eventObj</span><span class="o">-&gt;</span><span class="na">additionalFields</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;var&#39;</span> <span class="o">=&gt;</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="na">var</span><span class="p">]);</span>
2087 <span class="p">}</span>
2088
2089 <span class="k">protected</span> <span class="k">function</span> <span class="nf">saved</span><span class="p">()</span> <span class="p">{</span>
2090 <span class="nv">$this</span><span class="o">-&gt;</span><span class="na">var</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
2091 <span class="p">}</span>
2092
2093 <span class="k">protected</span> <span class="k">function</span> <span class="nf">validate</span><span class="p">()</span> <span class="p">{</span>
2094 <span class="k">if</span> <span class="p">(</span><span class="nv">$this</span><span class="o">-&gt;</span><span class="na">var</span> <span class="o">&lt;</span> <span class="mi">0</span><span class="p">)</span> <span class="p">{</span>
2095 <span class="k">throw</span> <span class="k">new</span> <span class="nx">UserInputException</span><span class="p">(</span><span class="s1">&#39;var&#39;</span><span class="p">,</span> <span class="s1">&#39;isNegative&#39;</span><span class="p">);</span>
2096 <span class="p">}</span>
2097 <span class="p">}</span>
2098<span class="p">}</span>
2099</code></pre></div>
2100
2101<p>The <code>execute</code> method in this example just delegates the call to a method with the same name as the event so that this class mimics the structure of a form class itself.
2102The form object is passed to the methods but is only given in the method signatures as a parameter here whenever the form object is actually used.
2103Furthermore, the type-hinting of the parameter illustrates in which contexts the method is actually called which will become clear in the following discussion of the individual methods:</p>
2104<ul>
2105<li><code>assignVariables()</code> is called for the add and the edit form and simply assigns the current value of the variable to the template.</li>
2106<li><code>readData()</code> reads the pre-existing value of <code>$var</code> if the form has not been submitted and thus is only relevant when editing objects which is illustrated by the explicit type-hint of <code>ExampleEditForm</code>.</li>
2107<li><code>readFormParameters()</code> reads the value for both, the add and the edit form.</li>
2108<li><code>save()</code> is, of course, also relevant in both cases but requires the form object to store the additional value in the <code>wcf\form\AbstractForm::$additionalFields</code> array which can be used if a <code>var</code> column has been added to the database table in which the example objects are stored.</li>
2109<li><code>saved()</code> is only called for the add form as it clears the internal value so that in the <code>assignVariables()</code> call, the default value will be assigned to the template to create an "empty" form.
2110 During edits, this current value is the actual value that should be shown.</li>
2111<li><code>validate()</code> also needs to be called in both cases as the input data always has to be validated.</li>
2112</ul>
2113<p>Lastly, the following XML file has to be used to register the event listeners (you can find more information about how to register event listeners on <a href="../../../package/pip/event-listener/">the eventListener package installation plugin page</a>):</p>
2114<div class="highlight"><pre><span></span><code><span class="cp">&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;</span>
2115<span class="nt">&lt;data</span> <span class="na">xmlns=</span><span class="s">&quot;http://www.woltlab.com&quot;</span> <span class="na">xmlns:xsi=</span><span class="s">&quot;http://www.w3.org/2001/XMLSchema-instance&quot;</span> <span class="na">xsi:schemaLocation=</span><span class="s">&quot;http://www.woltlab.com http://www.woltlab.com/XSD/2019/eventListener.xsd&quot;</span><span class="nt">&gt;</span>
2116 <span class="nt">&lt;import&gt;</span>
2117 <span class="nt">&lt;eventlistener</span> <span class="na">name=</span><span class="s">&quot;exampleAddInherited&quot;</span><span class="nt">&gt;</span>
2118 <span class="nt">&lt;eventclassname&gt;</span>wcf\form\ExampleAddForm<span class="nt">&lt;/eventclassname&gt;</span>
2119 <span class="nt">&lt;eventname&gt;</span>assignVariables,readFormParameters,save,validate<span class="nt">&lt;/eventname&gt;</span>
2120 <span class="nt">&lt;listenerclassname&gt;</span>wcf\system\event\listener\ExampleAddFormListener<span class="nt">&lt;/listenerclassname&gt;</span>
2121 <span class="nt">&lt;inherit&gt;</span>1<span class="nt">&lt;/inherit&gt;</span>
2122 <span class="nt">&lt;/eventlistener&gt;</span>
2123
2124 <span class="nt">&lt;eventlistener</span> <span class="na">name=</span><span class="s">&quot;exampleAdd&quot;</span><span class="nt">&gt;</span>
2125 <span class="nt">&lt;eventclassname&gt;</span>wcf\form\ExampleAddForm<span class="nt">&lt;/eventclassname&gt;</span>
2126 <span class="nt">&lt;eventname&gt;</span>saved<span class="nt">&lt;/eventname&gt;</span>
2127 <span class="nt">&lt;listenerclassname&gt;</span>wcf\system\event\listener\ExampleAddFormListener<span class="nt">&lt;/listenerclassname&gt;</span>
2128 <span class="nt">&lt;/eventlistener&gt;</span>
2129
2130 <span class="nt">&lt;eventlistener</span> <span class="na">name=</span><span class="s">&quot;exampleEdit&quot;</span><span class="nt">&gt;</span>
2131 <span class="nt">&lt;eventclassname&gt;</span>wcf\form\ExampleEditForm<span class="nt">&lt;/eventclassname&gt;</span>
2132 <span class="nt">&lt;eventname&gt;</span>readData<span class="nt">&lt;/eventname&gt;</span>
2133 <span class="nt">&lt;listenerclassname&gt;</span>wcf\system\event\listener\ExampleAddFormListener<span class="nt">&lt;/listenerclassname&gt;</span>
2134 <span class="nt">&lt;/eventlistener&gt;</span>
2135 <span class="nt">&lt;/import&gt;</span>
2136<span class="nt">&lt;/data&gt;</span>
2137</code></pre></div>
2138
2139
2140
2141
2142
2143
2144
2145 </article>
2146 </div>
2147 </div>
2148 </main>
2149
2150
2151<footer class="md-footer">
2152
2153 <nav class="md-footer__inner md-grid" aria-label="Footer">
2154
2155 <a href="../cronjobs/" class="md-footer__link md-footer__link--prev" rel="prev">
2156 <div class="md-footer__button md-icon">
2157 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11h12z"/></svg>
2158 </div>
2159 <div class="md-footer__title">
2160 <div class="md-ellipsis">
2161 <span class="md-footer__direction">
2162 Previous
2163 </span>
2164 Cronjobs
2165 </div>
2166 </div>
2167 </a>
2168
2169
2170 <a href="../form_builder/overview/" class="md-footer__link md-footer__link--next" rel="next">
2171 <div class="md-footer__title">
2172 <div class="md-ellipsis">
2173 <span class="md-footer__direction">
2174 Next
2175 </span>
2176 Overview
2177 </div>
2178 </div>
2179 <div class="md-footer__button md-icon">
2180 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11H4z"/></svg>
2181 </div>
2182 </a>
2183
2184 </nav>
2185
2186 <div class="md-footer-meta md-typeset">
2187 <div class="md-footer-meta__inner md-grid">
2188 <div class="md-footer-copyright">
2189
2190 <div class="md-footer-copyright__highlight">
2191 Copyright © 2020 WoltLab GmbH
2192 </div>
2193
2194 Made with
2195 <a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
2196 Material for MkDocs
2197 </a>
2198 </div>
2199 <div class="md-footer-copyright">
2200 <a href="https://www.woltlab.com/legal-notice/">Legal Notice</a>
2201 <a href="https://www.woltlab.com/privacy-policy/">Privacy Policy</a>
2202</div>
2203 </div>
2204 </div>
2205</footer>
2206
2207 </div>
2208 <div class="md-dialog" data-md-component="dialog">
2209 <div class="md-dialog__inner md-typeset"></div>
2210 </div>
2211 <script id="__config" type="application/json">{"base": "../../..", "features": [], "translations": {"clipboard.copy": "Copy to clipboard", "clipboard.copied": "Copied to clipboard", "search.config.lang": "en", "search.config.pipeline": "trimmer, stopWordFilter", "search.config.separator": "[\\s\\-]+", "search.placeholder": "Search", "search.result.placeholder": "Type to start searching", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.term.missing": "Missing"}, "search": "../../../assets/javascripts/workers/search.fb4a9340.min.js", "version": {"provider": "mike"}}</script>
2212
2213
2214 <script src="../../../assets/javascripts/bundle.ca5457b8.min.js"></script>
2215
2216
2217 </body>
2218</html>