Using the API

1. Using the API

2. Learning Objectives By the end of this lecture, you should be able to: • Identify what is meant by an ‘API’ • Know how to look up functions in the API • Know how to identify the arguments accepted by a function along with their datatypes • Know how to identify whether or not a function returns a value • Understand how the jQuery interpreter decides which version of a function to invoke when you have multiple functions with the same exact name • Identify reasons why you should always study and experiment with the sample code – whether from an API or from other programmers

3. What is an API? API stands for ‘application programming interface’. In the programming context, an API typically refers to a library of functions, variables or constants, classes, and objects. The majority of these terms likely to not mean anything to you at the moment. When we refer to the jQuery API, we are referring first and foremost to the jQuery library – that is, the entire list of functions that are available to you once your web page has been linked to the jQuery library. So the jQuery API is, essentially, nothing more than the list of all functions (and other related items) that make up jQuery. When programmers refer to ‘referencing the API’ or ‘looking up something in the API’, they are typically referring to accessing the documentation that lists all of the items available to you in that particular language. In addition to listing all of the functions, constants, and other things available to programmers, the API gives additional information on just what you can and can not expect those items to do for you. We will spend a few minutes now discussing how to access and use the jQuery API. You SHOULD expect to be confused by some of what you see. That’s okay, as we proceed through the course, you will become increasingly comfortable with how to use and interpret the API documentation.

4. Using the API The official jQuery API can be found at: http://api.jquery.com/ We wil learn about using the API by examining the documentation for the css()function in some detail. To look up the css() function, I simply navigate to the jQuery page, and in the Search box, I type css() After clicking the search button, we find the following (as of August 2015):

5. Looking up a function in the API Clicking on the css() function brings up all kinds of information. Let’s focus on the two functions highlighted by the red arrows: css(propertyName) and css(propertyName, value) What this list of functions tells you is that there are various different ways of invoking this function called css(). Let’s focus on the two highlighted ones: • One way to invoke this function (the top arrow) is by providing ONE argument representing a property name • Another way to invoke this function is by providing TWO arguments: The first argument should be a property name, followed by a comma, and then the second argument must be a property value.

6. A given function can be invoked in different ways The API will tell us about the various different ways in which a given function can be invoked. For the css() function, scrolling down a little brings us to: We are now seeing more about the version of the css() function that takes exactly one argument that they (the people who created this function) call ‘propertyName’. Note the following: • On the upper right-hand side, we are told that this function ‘returns’ a value. In addition, we are told that the data-type returned by this function is a String. • If you are not familiar with at least the basic rudiments of data types, be sure to review this topic – it is important! • The gray box then tells us a little bit more about this ‘propertyName’ argument that is expected. We are told that the argument we are expected to provide in order to invoke this function must be a String (as opposed to, say, an integer). • We are then told that this argument should be the name of a CSS property.

7. The ‘Fine Print’ The .css() method is a convenient way to get a style property from the first matched element, especially in light of the different ways browsers access most of those properties (the getComputedStyle() method in standards-based browsers versus the currentStyle and runtimeStyle properties in Internet Explorer) and the different terms browsers use for certain properties. For example, Internet Explorer's DOM implementation refers to the float property as styleFloat, while W3C standards-compliant browsers refer to it as cssFloat. For consistency, you can simply use "float", and jQuery will translate it to the correct value for each browser. Also, jQuery can equally interpret the CSS and DOM formatting of multiple-word properties. For example, jQuery understands and returns the correct value for both .css( "background-color" ) and .css( "backgroundColor" ). Different browsers may return CSS color values that are logically but not textually equal, e.g., #FFF, #ffffff, and rgb(255,255,255). Shorthand CSS properties (e.g. margin, background, border) are not supported. For example, if you want to retrieve the rendered margin, use: $( elem ).css( "marginTop" ) and $( elem ).css( "marginRight" ), and so on. Moving further down the page, we see the following – much of which will make little sense to you: As you can probably see, this is where things frequently get even more confusing. The reason is that many of the concepts discussed in the documentation are not yet familiar to you. However, it is still important to peruse these details as there are many issues that you will want to be aware of. For example: • In the 2nd paragraph, we are told that this function will accept not only the “official” version of a CSS property such as ‘background-color’, it will also accept the DOM version (which we won’t use much) called ‘backgroundColor’. • We are also told that the returned string will NOT be of the form ‘red’ or ‘blue’, etc. Rather, it will come in the form of a hex code such as #FFF000 or as an rgb value. We are told that which version gets returned by the function (hex or rgb) depends on the browser. • We are told that “shortcut” CSS properties such as ‘border’ can NOT be used. • Recall that instead of specifying border-top, border-bottom, etc, CSS allows us to use the ‘border’ shortcut to set all four borders at once. However, the API tells us that if you want to set the borders using the css() function, you must set each one individually.

8. Sample Code Frequently, the API will also provide code examples. You should always try to go through at least part of these. As we have been continually emphasizing throughout the course, one of the very, very best ways of becoming good at programming – whatever the language – is by looking at examples of other people’s code and then experimenting with it yourself.

9. A given function can be invoked in different ways We have just finished discussing one version of the css() function, namely, a version that takes one argument representing the name of the CSS property we are asking about. That function then returns a String representing the current value that the property is set to. However, the API now tells us about another version of the css() function that is available to us. The API shows it as: .css(propertyName, value) .This version accepts two arguments. • The first argument represents a property that you wish to assign or to modify. • The second argument represents the value that you want to set the property to. • IMPORTANT: Note the allowable datatypes. The second argument can be a String. You would pass a String if the argument was, say, the name of a font. However, the second argument can also be a Number. You might pass a number as your second argument if, say, you wanted to adjust the size of a border. EXAMPLES: $('someSelection').css('background-color','green'); $('someSelection').css('font-family','Arial'); $('someSelection').css('margin', 5);

10. A given function can be invoked in different ways Note that this function returns ‘jQuery’. This return type is a relatively complicated object that we will ignore for now. For NOW, whenever you see ‘jQuery as the return type, you can almost think of it as a function that does not return any value of particular use (at this time). This is fine – some functions such as this one, do not have any real need to return a value. The particular job of this function is to simply change the value of a CSS property – it does not really need to “return” anything!

11. Which version gets invoked??? As you can see, the API for the css() function shows us that there are multiple versions of this function available to us. Different versions of a single function sometimes do completely diffferent things! In fact, that is the case here – one version tells us the value of a property, while the other version changes the value of a property. So, if there are multiple versions of the same function, HOW does jQuery decide WHICH particular version of the function to invoke? ANSWER:It depends on the argument list. If, say, the programmer types $('someSelection').css('font-family'); then jQuery will invoke the version of the css() function that expects a property name. If the programmer types $('someSelection').css('font-family', 'Arial'); then jQuery will invoke the version of the css() function that expects a property name followed by a property value.

12. LOOK AT THE SAMPLE CODE!!! As mentioned a few minutes ago, do not neglect to study the sample code. Doing so will frequently: • Help you understand the code that much better. • Identify misconceptions (this is extremely common). • Give you new ideas on how you might apply the function in question. • Challenge you to try and intepret unfamiliar code. All of these points are extremely useful as you work on becoming a skilled and highly-valued programmer.