[GitHub/WoltLab/woltlab.github.io.git] / 5.3 / javascript_new-api_events.html

<!DOCTYPE html>
<head>
    <meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="description" content="">
<meta name="keywords" content=" ">
<title>Event Handling - JavaScript API | WoltLab Suite 5.3 Documentation</title>

<link rel="stylesheet" href="https://docs.woltlab.com/5.3/css/syntax.css">
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:400,300,600">
<link rel="stylesheet" href="https://docs.woltlab.com/5.3/css/font-awesome.min.css">
<!--<link rel="stylesheet" type="text/css" href="css/bootstrap.min.css">-->
<link rel="stylesheet" href="https://docs.woltlab.com/5.3/css/modern-business.css">
<link rel="stylesheet" href="https://docs.woltlab.com/5.3/css/lavish-bootstrap.css">
<link rel="stylesheet" href="https://docs.woltlab.com/5.3/css/customstyles.css">
<link rel="stylesheet" href="https://docs.woltlab.com/5.3/css/theme-blue.css?v=3">

<script src="https://docs.woltlab.com/5.3/js/jquery.min.js"></script>
<script src="https://docs.woltlab.com/5.3/js/jquery.cookie.min.js"></script>
<script src="https://docs.woltlab.com/5.3/js/jquery.navgoco.min.js"></script>
<script src="https://docs.woltlab.com/5.3/js/bootstrap.min.js"></script>
<script src="https://docs.woltlab.com/5.3/js/anchor.min.js"></script>
<script src="https://docs.woltlab.com/5.3/js/toc.js"></script>
<script src="https://docs.woltlab.com/5.3/js/customscripts.js"></script>

<link rel="shortcut icon" href="https://docs.woltlab.com/5.3/images/favicon.ico">

<link rel="alternate" type="application/rss+xml" title="woltlab.github.io" href="https://docs.woltlab.com/5.3feed.xml">

    <script>
        $(document).ready(function() {
            // Initialize navgoco with default options
            $("#mysidebar").navgoco({
                caretHtml: '',
                accordion: true,
                openClass: 'active', // open
                save: false, // leave false or nav highlighting doesn't work right
                cookie: {
                    name: 'navgoco',
                    expires: false,
                    path: '/'
                },
                slide: {
                    duration: 400,
                    easing: 'swing'
                }
            });

            $("#collapseAll").click(function(e) {
                e.preventDefault();
                $("#mysidebar").navgoco('toggle', false);
            });

            $("#expandAll").click(function(e) {
                e.preventDefault();
                $("#mysidebar").navgoco('toggle', true);
            });

        });

    </script>
    <script>
        $(function () {
            $('[data-toggle="tooltip"]').tooltip()
        })
    </script>
    

</head>
<body>
  <!-- Navigation -->
<nav class="navbar navbar-inverse navbar-fixed-top">
    <div class="container topnavlinks">
        <div class="navbar-header">
            <button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#bs-example-navbar-collapse-1">
                <span class="sr-only">Toggle navigation</span>
                <span class="icon-bar"></span>
                <span class="icon-bar"></span>
                <span class="icon-bar"></span>
            </button>
            <a class="fa fa-home fa-lg navbar-brand" href="index.html">&nbsp;<span class="projectTitle"> WoltLab Suite 5.3 Documentation</span></a>
        </div>
        <div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1">
            <ul class="nav navbar-nav navbar-right">
                <!-- entries without drop-downs appear here -->
                
                
                <li><a href="https://www.woltlab.com" target="_blank">woltlab.com</a></li>
                
                
                <li><a href="https://github.com/WoltLab/WCF/" target="_blank">Code on github.com</a></li>
                
                
                <!-- entries with drop-downs appear here -->
                <!-- conditional logic to control which topnav appears for the audience defined in the configuration file.-->
                
                
                <!--comment out this block if you want to hide search-->
                <li>
                    <!--start search-->
                    <div id="search-demo-container">
                        <input type="text" id="search-input" placeholder="search...">
                        <ul id="results-container"></ul>
                    </div>
                    <script src="https://docs.woltlab.com/5.3/js/jekyll-search.js" type="text/javascript"></script>
                    <script type="text/javascript">
                            SimpleJekyllSearch.init({
                                searchInput: document.getElementById('search-input'),
                                resultsContainer: document.getElementById('results-container'),
                                dataSource: 'https://docs.woltlab.com/5.3/search.json',
                                searchResultTemplate: '<li><a href="{url}" title="Event Handling - JavaScript API">{title}</a></li>',
                    noResultsText: 'No results found.',
                            limit: 10,
                            fuzzy: true,
                    })
                    </script>
                    <!--end search-->
                </li>
            </ul>
        </div>
        </div>
        <!-- /.container -->
</nav>


  <div class="container">
    <div class="col-lg-12">&nbsp;</div>

    <div class="row">
      <div class="col-md-3">
        

<ul id="mysidebar" class="nav">
    <li class="sidebarTitle">WoltLab Suite 5.3</li>

    
            <li>
                <a href="#">Getting Started</a>
                <ul>
                    
                        
                                <li data-identifier="index"><a href="index.html">Introduction</a></li>
                            
                        
                                <li data-identifier="getting-started_quick-start"><a href="getting-started_quick-start.html">Quick Start</a></li>
                            
                        
                </ul>
            </li>
        
            <li>
                <a href="#">PHP API</a>
                <ul>
                    
                        
                                <li data-identifier="php_pages"><a href="php_pages.html">Pages</a></li>
                            
                        
                                <li data-identifier="php_database-objects"><a href="php_database-objects.html">Database Objects</a></li>
                            
                        
                                <li data-identifier="php_database-access"><a href="php_database-access.html">Database Access</a></li>
                            
                        
                                <li data-identifier="php_exceptions"><a href="php_exceptions.html">Exceptions</a></li>
                            
                        
                            <li class="subfolders">
                                <a href="#">API</a>
                                <ul>
                                    
                                        
                                            <li data-identifier="php_api_caches"><a href="php_api_caches.html">Caches</a></li>
                                        
                                    
                                            <li data-identifier="php_api_comments"><a href="php_api_comments.html">Comments</a></li>
                                        
                                    
                                            <li data-identifier="php_api_cronjobs"><a href="php_api_cronjobs.html">Cronjobs</a></li>
                                        
                                    
                                            <li data-identifier="php_api_events"><a href="php_api_events.html">Events</a></li>
                                        
                                    
                                            <li data-identifier="php_api_form_builder"><a href="php_api_form_builder.html">Form Builder</a></li>
                                        
                                    
                                            <li data-identifier="php_api_package_installation_plugins"><a href="php_api_package_installation_plugins.html">Package Installation Plugins</a></li>
                                        
                                    
                                            <li data-identifier="php_api_user_activity_points"><a href="php_api_user_activity_points.html">User Activity Points</a></li>
                                        
                                    
                                            <li data-identifier="php_api_user_notifications"><a href="php_api_user_notifications.html">User Notifications</a></li>
                                        
                                    
                                            <li data-identifier="php_api_sitemaps"><a href="php_api_sitemaps.html">Sitemaps</a></li>
                                        
                                    
                                </ul>
                            </li>
                        
                    
                                <li data-identifier="php_code-style"><a href="php_code-style.html">Code Style</a></li>
                            
                        
                                <li data-identifier="php_apps"><a href="php_apps.html">Apps</a></li>
                            
                        
                                <li data-identifier="php_gdpr"><a href="php_gdpr.html">GDPR</a></li>
                            
                        
                </ul>
            </li>
        
            <li>
                <a href="#">Languages, Templates & CSS</a>
                <ul>
                    
                        
                                <li data-identifier="view_languages"><a href="view_languages.html">Languages</a></li>
                            
                        
                                <li data-identifier="view_templates"><a href="view_templates.html">Templates</a></li>
                            
                        
                                <li data-identifier="view_css"><a href="view_css.html">CSS</a></li>
                            
                        
                </ul>
            </li>
        
            <li>
                <a href="#">JavaScript API</a>
                <ul>
                    
                        
                                <li data-identifier="javascript_general-usage"><a href="javascript_general-usage.html">General Usage</a></li>
                            
                        
                            <li class="subfolders">
                                <a href="#">New API</a>
                                <ul>
                                    
                                        
                                            <li data-identifier="javascript_new-api_writing-a-module"><a href="javascript_new-api_writing-a-module.html">Writing a module</a></li>
                                        
                                    
                                            <li data-identifier="javascript_new-api_data-structures"><a href="javascript_new-api_data-structures.html">Data Structures</a></li>
                                        
                                    
                                            <li data-identifier="javascript_new-api_core"><a href="javascript_new-api_core.html">Core Functions</a></li>
                                        
                                    
                                            <li data-identifier="javascript_new-api_dom"><a href="javascript_new-api_dom.html">DOM</a></li>
                                        
                                    
                                            <li class="active" data-identifier="javascript_new-api_events"><a href="javascript_new-api_events.html">Event Handling</a></li>
                                        
                                    
                                            <li data-identifier="javascript_new-api_ajax"><a href="javascript_new-api_ajax.html">Ajax</a></li>
                                        
                                    
                                            <li data-identifier="javascript_new-api_dialogs"><a href="javascript_new-api_dialogs.html">Dialogs</a></li>
                                        
                                    
                                            <li data-identifier="javascript_new-api_browser"><a href="javascript_new-api_browser.html">Browser and Screen Sizes</a></li>
                                        
                                    
                                            <li data-identifier="javascript_new-api_ui"><a href="javascript_new-api_ui.html">User Interface</a></li>
                                        
                                    
                                </ul>
                            </li>
                        
                    
                                <li data-identifier="javascript_legacy-api"><a href="javascript_legacy-api.html">Legacy API</a></li>
                            
                        
                                <li data-identifier="javascript_helper-functions"><a href="javascript_helper-functions.html">Helper Functions</a></li>
                            
                        
                                <li data-identifier="javascript_code-snippets"><a href="javascript_code-snippets.html">Code Snippets</a></li>
                            
                        
                </ul>
            </li>
        
            <li>
                <a href="#">Package Components</a>
                <ul>
                    
                        
                                <li data-identifier="package_package-xml"><a href="package_package-xml.html">package.xml</a></li>
                            
                        
                                <li data-identifier="package_pip"><a href="package_pip.html">PIPs</a></li>
                            
                        
                </ul>
            </li>
        
            <li>
                <a href="#">Migration</a>
                <ul>
                    
                        
                            <li class="subfolders">
                                <a href="#">Migrating from WSC 5.2</a>
                                <ul>
                                    
                                        
                                            <li data-identifier="migration_wsc-52_php"><a href="migration_wsc-52_php.html">PHP API</a></li>
                                        
                                    
                                            <li data-identifier="migration_wsc-52_templates"><a href="migration_wsc-52_templates.html">Templates and Languages</a></li>
                                        
                                    
                                            <li data-identifier="migration_wsc-52_libraries"><a href="migration_wsc-52_libraries.html">Third Party Libraries</a></li>
                                        
                                    
                                </ul>
                            </li>
                        
                            <li class="subfolders">
                                <a href="#">Migrating from WSC 3.1</a>
                                <ul>
                                    
                                        
                                            <li data-identifier="migration_wsc-31_php"><a href="migration_wsc-31_php.html">PHP API</a></li>
                                        
                                    
                                </ul>
                            </li>
                        
                            <li class="subfolders">
                                <a href="#">Migrating from WSC 3.0</a>
                                <ul>
                                    
                                        
                                            <li data-identifier="migration_wsc-30_php"><a href="migration_wsc-30_php.html">PHP API</a></li>
                                        
                                    
                                            <li data-identifier="migration_wsc-30_javascript"><a href="migration_wsc-30_javascript.html">JavaScript API</a></li>
                                        
                                    
                                            <li data-identifier="migration_wsc-30_templates"><a href="migration_wsc-30_templates.html">Templates</a></li>
                                        
                                    
                                            <li data-identifier="migration_wsc-30_css"><a href="migration_wsc-30_css.html">CSS</a></li>
                                        
                                    
                                            <li data-identifier="migration_wsc-30_package"><a href="migration_wsc-30_package.html">Package Components</a></li>
                                        
                                    
                                </ul>
                            </li>
                        
                            <li class="subfolders">
                                <a href="#">Migrating from WCF 2.1</a>
                                <ul>
                                    
                                        
                                            <li data-identifier="migration_wcf-21_php"><a href="migration_wcf-21_php.html">PHP API</a></li>
                                        
                                    
                                            <li data-identifier="migration_wcf-21_templates"><a href="migration_wcf-21_templates.html">Templates</a></li>
                                        
                                    
                                            <li data-identifier="migration_wcf-21_css"><a href="migration_wcf-21_css.html">CSS</a></li>
                                        
                                    
                                            <li data-identifier="migration_wcf-21_package"><a href="migration_wcf-21_package.html">Package Components</a></li>
                                        
                                    
                                </ul>
                            </li>
                        
                    
                </ul>
            </li>
        
            <li>
                <a href="#">Tutorials</a>
                <ul>
                    
                        
                                <li data-identifier="tutorial_tutorial-series"><a href="tutorial_tutorial-series.html">Tutorial Series</a></li>
                            
                        
                </ul>
            </li>
        
    
</ul>

<script>
(function() {
    var sidebar = $('#mysidebar');
    var item = sidebar.find('.active');
    if (item.length === 0) {
        var parent = '';
        if (parent) {
            sidebar.find('li[data-identifier="' + parent + '"]').addClass('active');
        }
    }

    sidebar.find(".active").parents('li').toggleClass("active");
})();
</script>

      </div>

      <div class="col-md-9">
        <div class="post-header">
   <h1 class="post-title-main">Event Handling - JavaScript API</h1>
</div>


<div class="post-content">

   
<!-- this handles the automatic toc. use ## for subheads to auto-generate the on-page minitoc. if you use html tags, you must supply an ID for the heading element in order for it to appear in the minitoc. -->
<script>
$( document ).ready(function() {
  // Handler for .ready() called.

$('#toc').toc({ minimumHeaders: 0, listType: 'ul', showSpeed: 0, headers: 'h2,h3,h4' });

/* this offset helps account for the space taken up by the floating toolbar. */
$('#toc').on('click', 'a', function() {
  var target = $(this.getAttribute('href'))
    , scroll_target = target.offset().top

  $(window).scrollTop(scroll_target - 10);
  return false
})
  
});
</script>

<div id="toc"></div>

    
  <h2 id="eventkey"><code class="language-plaintext highlighter-rouge">EventKey</code></h2>

<p>This class offers a set of static methods that can be used to determine if some
common keys are being pressed. Internally it compares either the <code class="language-plaintext highlighter-rouge">.key</code> property
if it is supported or the value of <code class="language-plaintext highlighter-rouge">.which</code>.</p>

<div class="language-js highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nx">require</span><span class="p">([</span><span class="dl">"</span><span class="s2">EventKey</span><span class="dl">"</span><span class="p">],</span> <span class="kd">function</span><span class="p">(</span><span class="nx">EventKey</span><span class="p">)</span> <span class="p">{</span>
  <span class="nx">elBySel</span><span class="p">(</span><span class="dl">"</span><span class="s2">.some-input</span><span class="dl">"</span><span class="p">).</span><span class="nx">addEventListener</span><span class="p">(</span><span class="dl">"</span><span class="s2">keydown</span><span class="dl">"</span><span class="p">,</span> <span class="kd">function</span><span class="p">(</span><span class="nx">event</span><span class="p">)</span> <span class="p">{</span>
    <span class="k">if</span> <span class="p">(</span><span class="nx">EventKey</span><span class="p">.</span><span class="nx">Enter</span><span class="p">(</span><span class="nx">event</span><span class="p">))</span> <span class="p">{</span>
      <span class="c1">// the `Enter` key was pressed</span>
    <span class="p">}</span>
  <span class="p">});</span>
<span class="p">});</span>
</code></pre></div></div>

<h3 id="arrowdownevent-keyboardevent-boolean"><code class="language-plaintext highlighter-rouge">ArrowDown(event: KeyboardEvent): boolean</code></h3>

<p>Returns true if the user has pressed the <code class="language-plaintext highlighter-rouge">↓</code> key.</p>

<h3 id="arrowleftevent-keyboardevent-boolean"><code class="language-plaintext highlighter-rouge">ArrowLeft(event: KeyboardEvent): boolean</code></h3>

<p>Returns true if the user has pressed the <code class="language-plaintext highlighter-rouge">←</code> key.</p>

<h3 id="arrowrightevent-keyboardevent-boolean"><code class="language-plaintext highlighter-rouge">ArrowRight(event: KeyboardEvent): boolean</code></h3>

<p>Returns true if the user has pressed the <code class="language-plaintext highlighter-rouge">→</code> key.</p>

<h3 id="arrowupevent-keyboardevent-boolean"><code class="language-plaintext highlighter-rouge">ArrowUp(event: KeyboardEvent): boolean</code></h3>

<p>Returns true if the user has pressed the <code class="language-plaintext highlighter-rouge">↑</code> key.</p>

<h3 id="commaevent-keyboardevent-boolean"><code class="language-plaintext highlighter-rouge">Comma(event: KeyboardEvent): boolean</code></h3>

<p>Returns true if the user has pressed the <code class="language-plaintext highlighter-rouge">,</code> key.</p>

<h3 id="enterevent-keyboardevent-boolean"><code class="language-plaintext highlighter-rouge">Enter(event: KeyboardEvent): boolean</code></h3>

<p>Returns true if the user has pressed the <code class="language-plaintext highlighter-rouge">↲</code> key.</p>

<h3 id="escapeevent-keyboardevent-boolean"><code class="language-plaintext highlighter-rouge">Escape(event: KeyboardEvent): boolean</code></h3>

<p>Returns true if the user has pressed the <code class="language-plaintext highlighter-rouge">Esc</code> key.</p>

<h3 id="tabevent-keyboardevent-boolean"><code class="language-plaintext highlighter-rouge">Tab(event: KeyboardEvent): boolean</code></h3>

<p>Returns true if the user has pressed the <code class="language-plaintext highlighter-rouge">↹</code> key.</p>

<h2 id="eventhandler"><code class="language-plaintext highlighter-rouge">EventHandler</code></h2>

<p>A synchronous event system based on string identifiers rather than DOM elements,
similar to the PHP event system in WoltLab Suite. Any components can listen to
events or trigger events itself at any time.</p>

<h3 id="identifiying-events-with-the-developer-tools">Identifiying Events with the Developer Tools</h3>

<p>The Developer Tools in WoltLab Suite 3.1 offer an easy option to identify existing
events that are fired while code is being executed. You can enable this watch
mode through your browser’s console using <code class="language-plaintext highlighter-rouge">Devtools.toggleEventLogging()</code>:</p>

<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>&gt; Devtools.toggleEventLogging();
&lt;   Event logging enabled
&lt; [Devtools.EventLogging] Firing event: bar @ com.example.app.foo
&lt; [Devtools.EventLogging] Firing event: baz @ com.example.app.foo
</code></pre></div></div>

<h3 id="addidentifier-string-action-string-callback-data-object--void-string"><code class="language-plaintext highlighter-rouge">add(identifier: string, action: string, callback: (data: Object) =&gt; void): string</code></h3>

<p>Adding an event listeners returns a randomly generated UUIDv4 that is used to
identify the listener. This UUID is required to remove a specific listener through
the <code class="language-plaintext highlighter-rouge">remove()</code> method.</p>

<h3 id="fireidentifier-string-action-string-data-object"><code class="language-plaintext highlighter-rouge">fire(identifier: string, action: string, data?: Object)</code></h3>

<p>Triggers an event using an optional <code class="language-plaintext highlighter-rouge">data</code> object that is passed to each listener
by reference.</p>

<h3 id="removeidentifier-string-action-string-uuid-string"><code class="language-plaintext highlighter-rouge">remove(identifier: string, action: string, uuid: string)</code></h3>

<p>Removes a previously registered event listener using the UUID returned by <code class="language-plaintext highlighter-rouge">add()</code>.</p>

<h3 id="removeallidentifier-string-action-string"><code class="language-plaintext highlighter-rouge">removeAll(identifier: string, action: string)</code></h3>

<p>Removes all event listeners registered for the provided <code class="language-plaintext highlighter-rouge">identifier</code> and <code class="language-plaintext highlighter-rouge">action</code>.</p>

<h3 id="removeallbysuffixidentifier-string-suffix-string"><code class="language-plaintext highlighter-rouge">removeAllBySuffix(identifier: string, suffix: string)</code></h3>

<p>Removes all event listeners for an <code class="language-plaintext highlighter-rouge">identifier</code> whose action ends with the value
of <code class="language-plaintext highlighter-rouge">suffix</code>.</p>


    <div class="tags">
        
    </div>

    
</div>

      </div>
    </div>
  </div>

  <div class="footerBox">
    <div class="container">
      <div class="footerBoxLeft">
        
        <a target="_blank" href="https://github.com/woltlab/woltlab.github.io/blob/master/pages/javascript/javascript_new-api_events.md" class="btn btn-default githubEditButton no_icon" role="button"><i class="fa fa-github fa-lg"></i> Edit on GitHub</a>
        <p>Site last generated: Mar 5, 2021</p>
      </div>
      <div class="footerBoxRight">
        <a class="no_icon" href="https://www.woltlab.com"><img src="https://docs.woltlab.com/5.3/images/woltlab-black.png" srcset="https://docs.woltlab.com/5.3/images/woltlab-black@2x.png 2x" height="40" width="204" alt=""></a>
      </div>
    </div>
  </div>

  <div class="pageFooter">
    <div class="container">
      &copy; 2001 ‐ 2021 <a class="no_icon" href="https://www.woltlab.com">WoltLab GmbH</a>. All rights reserved. | <a class="no_icon" href="https://www.woltlab.com/legal-notice/">Legal Notice</a> | <a class="no_icon" href="https://www.woltlab.com/privacy-policy/">Privacy Policy</a>
    </div>
  </div>
</body>

</html>