.one()

jQuery

previous page next page

.one()

Categories: Events > Event Handler Attachment

.one( events [, data ], handler(eventObject) ) Returns: jQuery

Description: Attach a handler to an event for the elements. The handler is executed at most once per element.

  • version added: 1.1.one( events [, data ], handler(eventObject) )

    • events
      Type: String
      A string containing one or more JavaScript event types, such as "click" or "submit," or custom event names.
    • data
      Type: PlainObject
      An object containing data that will be passed to the event handler.
    • handler(eventObject)
      Type: Function()
      A function to execute at the time the event is triggered.

  • version added: 1.7.one( events [, selector ] [, data ], handler(eventObject) )

    • events
      Type: String
      One or more space-separated event types and optional namespaces, such as "click" or "keydown.myPlugin".
    • selector
      Type: String
      A selector string to filter the descendants of the selected elements that trigger the event. If the selector is null or omitted, the event is always triggered when it reaches the selected element.
    • data
      Type: Anything
      Data to be passed to the handler in event.data when an event is triggered.
    • handler(eventObject)
      Type: Function()
      A function to execute when the event is triggered. The value false is also allowed as a shorthand for a function that simply does return false.

  • version added: 1.7.one( events [, selector ] [, data ] )

    • events
      Type: PlainObject
      An object in which the string keys represent one or more space-separated event types and optional namespaces, and the values represent a handler function to be called for the event(s).
    • selector
      Type: String
      A selector string to filter the descendants of the selected elements that will call the handler. If the selector is null or omitted, the handler is always called when it reaches the selected element.
    • data
      Type: Anything
      Data to be passed to the handler in event.data when an event occurs.

The first form of this method is identical to .bind(), except that the handler is unbound after its first invocation. The second two forms, introduced in jQuery 1.7, are identical to .on() except that the handler is removed after the first time the event occurs at the delegated element, whether the selector matched anything or not. For example:

1
2
3
4
5
6
 
                                

                                  

                                    $("#foo").one("click", function() {
                                  

                                

                                

                                  

                                      alert("This will be displayed only once.");
                                  

                                

                                

                                  

                                    });
                                  

                                

                                

                                  

                                    $("body").one("click", "#foo", function() {
                                  

                                

                                

                                  

                                      alert("This displays if #foo is the first thing clicked in the body.");
                                  

                                

                                

                                  

                                    });

After the code is executed, a click on the element with ID foo will display the alert. Subsequent clicks will do nothing. This code is equivalent to:

1
2
3
4
 
                                

                                  

                                    $("#foo").on("click", function( event ) {
                                  

                                

                                

                                  

                                      alert("This will be displayed only once.");
                                  

                                

                                

                                  

                                      $(this).off( event );
                                  

                                

                                

                                  

                                    });

In other words, explicitly calling .off() from within a regularly-bound handler has exactly the same effect.

If the first argument contains more than one space-separated event types, the event handler is called once for each event type.

Examples:

Example: Tie a one-time click to each div.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
 
                                  

                                    

                                      
                                        <!DOCTYPE html>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <html>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <head>
                                      
                                    

                                  

                                  

                                    

                                        <style>
                                    

                                  

                                  

                                    

                                      div { width:60px; height:60px; margin:5px; float:left;
                                    

                                  

                                  

                                    

                                      background:green; border:10px outset;
                                    

                                  

                                  

                                    

                                      cursor:pointer; }
                                    

                                  

                                  

                                    

                                      p { color:red; margin:0; clear:left; }
                                    

                                  

                                  

                                    

                                      
                                        </style>
                                      
                                    

                                  

                                  

                                    

                                        <script src="http://code.jquery.com/jquery-latest.js"></script>
                                    

                                  

                                  

                                    

                                      
                                        </head>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <body>
                                      
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                      
                                        <div>
                                        </div>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <div>
                                        </div>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <div>
                                        </div>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <div>
                                        </div>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <div>
                                        </div>
                                      
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                      <p>Click a green square...</p>
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                      
                                        <script>
                                        
                                      
                                    

                                  

                                  

                                    

                                      var n = 0;
                                    

                                  

                                  

                                    

                                      $("div").one("click", function() {
                                    

                                  

                                  

                                    

                                        var index = $("div").index(this);
                                    

                                  

                                  

                                    

                                        $(this).css({
                                    

                                  

                                  

                                    

                                          borderStyle:"inset",
                                    

                                  

                                  

                                    

                                          cursor:"auto"
                                    

                                  

                                  

                                    

                                        });
                                    

                                  

                                  

                                    

                                        $("p").text("Div at index #" + index + " clicked." +
                                    

                                  

                                  

                                    

                                            "  That's " + ++n + " total clicks.");
                                    

                                  

                                  

                                    

                                      });
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                      
                                        </script>
                                      
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                      
                                        </body>
                                      
                                    

                                  

                                  

                                    

                                      
                                        </html>

Example: To display the text of all paragraphs in an alert box the first time each of them is clicked:

1
2
3
 
                                  

                                    

                                      $("p").one("click", function(){
                                    

                                  

                                  

                                    

                                      alert( $(this).text() );
                                    

                                  

                                  

                                    

                                      });
 POWERED BYHERONOTE
previous page start next page