Check your version

This video covers a topic in Drupal 7 which may or may not be the version you're using. We're keeping this tutorial online as a courtesy to users of Drupal 7, but we consider it archived.

Alternate resources: 

Drupal API documentation

Video loading...

  • 0:02
    Drupal API Documentation Joe Shindelar
  • 0:08
    In this chapter, we're going to take a look at where you find documentation
  • 0:11
    about all of Drupal's internal APIs, functions,
  • 0:14
    and how you can interact with Drupal under the hood.
  • 0:17
    One of Drupal's greatest strengths is its documentation.
  • 0:21
    Almost everything in Drupal is highly documented
  • 0:23
    and the home for all of that documentation is api.drupal.org.
  • 0:28
    When you download Drupal core, half of what you're getting
  • 0:32
    in that tarball package is Drupal core,
  • 0:34
    the PHP that makes up Drupal and how it actually executes.
  • 0:37
    The other half is actually documentation.
  • 0:40
    Almost all of the functions in Drupal are extensively documented.
  • 0:44
    And what's really cool is you can actually view
  • 0:46
    all of that documentation right here on api.drupal.org.
  • 0:50
    So let's take a look at some of the information
  • 0:52
    that's available and how to find what you're looking for.
  • 0:55
    When you first come to api.drupal.org,
  • 0:58
    this is the overview page that you're presented with.
  • 1:00
    Up at the top, you can choose which version of Drupal
  • 1:03
    you'd like to view documentation for.
  • 1:05
    Right now you can view documentation for Drupal 5, 6, 7,
  • 1:09
    the current version, or 8.
  • 1:11
    The documentation page will always default to showing you
  • 1:13
    the current version, so Drupal 7 in this case.
  • 1:17
    And then you see a list of links to sort of high-level topics
  • 1:20
    that you may want to view information about,
  • 1:23
    Drupal's module system or the Hooks system,
  • 1:25
    the database abstraction layer, the menu system,
  • 1:28
    the search system, themeing and so forth.
  • 1:30
    Clicking on any of these links will take you to a page
  • 1:33
    with additional information about these high-level topics.
  • 1:36
    If I click on the Hooks system, for example,
  • 1:40
    I get some documentation that explains a little bit about
  • 1:42
    how hooks in Drupal work
  • 1:44
    and then a list of all of the possible hooks
  • 1:46
    that I might want to implement.
  • 1:49
    This is a pretty big list.
  • 1:50
    It's pretty cool too because I do get to see all of the possible hooks
  • 1:53
    that you can implement in a module.
  • 1:55
    We'll learn a lot about hooks throughout the course of this series.
  • 1:59
    The other thing that I can do is search for things.
  • 2:01
    If I'd like to search for documentation about a particular hook,
  • 2:04
    I can type it into the search field over here.
  • 2:07
    So let's say I want to look up documentation on hook_form, look at that,
  • 2:11
    and it actually does an autocomplete for me.
  • 2:14
    I know that I'm looking for hook_form_alter,
  • 2:16
    so once it comes up in the list here, I can click on it
  • 2:19
    and it'll show me the documentation for that hook.
  • 2:22
    So it's showing me hook_form_alter,
  • 2:24
    an example function signature and some documentation for it.
  • 2:27
    Now hook_form_alter allows me to perform alterations
  • 2:30
    before a form is rendered.
  • 2:32
    It also shows me a list of all of the parameters
  • 2:36
    that are passed into that function
  • 2:38
    and gives me information about each of those.
  • 2:40
    And if I continue scrolling down,
  • 2:42
    it shows me related topics, so it says,
  • 2:44
    oh, this is actually a hook and if I wanted to learn more
  • 2:47
    about hooks, I could click here to see Hooks,
  • 2:49
    but I might also want to see the hook_form_FORM_ID_alter,
  • 2:53
    because that's related to this one.
  • 2:55
    And finally, what's really cool, for all of the hook implementations,
  • 2:59
    it displays in the code section down here,
  • 3:02
    an example of how you could implement that hook inside of your own module.
  • 3:06
    Pro tip, something I end up doing a lot is actually coming to api.drupal.org,
  • 3:11
    looking up hook documentation and then just copying and pasting
  • 3:14
    this code into my module and renaming it
  • 3:16
    and sort of using that as a starting point for implementing it inside of my own module.
  • 3:21
    In addition to hook documentation,
  • 3:23
    you can also view documentation for any of Drupal's built-in functions.
  • 3:27
    So hook_form_alter isn't actually a function that you would ever call in Drupal,
  • 3:31
    this is just documentation about that particular hook.
  • 3:34
    There's other functions though that I might want to use
  • 3:36
    inside of Drupal like format_date.
  • 3:39
    So I could view the documentation for the format_date function
  • 3:42
    and what I see here is similar to what we saw for the hook_form_alter,
  • 3:46
    it shows me the name of the function,
  • 3:47
    I can click to see it in different versions of Drupal, the documentation for that,
  • 3:52
    and then documentation about the parameters
  • 3:54
    that this function takes.
  • 3:56
    In this case, format_date is a function
  • 3:58
    that I would probably actually call from inside of my own code.
  • 4:01
    It tells me what parameters I would pass to it
  • 4:03
    when I call the function, it tells me what the return value
  • 4:06
    is going to be when the function returns something.
  • 4:09
    If you see up here at the top,
  • 4:10
    you can see how the format_date function has changed between the version in Drupal 5
  • 4:15
    and the version in Drupal 6.
  • 4:17
    So from 4.6 to 5, this is the function signature that was used for format_date,
  • 4:22
    and then from Drupal 6 to Drupal 8, this is the function signature.
  • 4:25
    You can see that there's a langcode parameter added to the function signature.
  • 4:30
    And then finally, when you scroll down to the bottom,
  • 4:33
    I can again see related topics and I can see the code down here.
  • 4:38
    In this case, what it's actually showing is the code
  • 4:41
    that makes up the format_date function.
  • 4:43
    So this is the actual code inside of common.inc that is the format_date function.
  • 4:49
    For any of these pieces of code, I can start to navigate around
  • 4:52
    and I can actually click on any of the Drupal functions in this code.
  • 4:56
    So I could click on variable_get here
  • 5:00
    and it'll take me to the documentation for that function.
  • 5:03
    So this is another nice way that you can kind of learn about
  • 5:05
    how some of the things in Drupal work under the hood.
  • 5:08
    You can almost sort of read it like a novel.
  • 5:10
    Another really handy thing on api.drupal.org is this here,
  • 5:14
    where it says 517 functions call variable_get().
  • 5:17
    What this does is it gives me a list of all of the places
  • 5:21
    in Drupal core that are calling the variable_get function.
  • 5:24
    So these are all the functions that are calling variable_get().
  • 5:28
    And I can go to any one of these functions, like,
  • 5:32
    we'll say block_help and when I'm viewing that function,
  • 5:36
    I can see how that particular function is making use of variable_get()
  • 5:41
    and get some ideas about how I might use it in my own module.
  • 5:44
    There's a couple other things to look at.
  • 5:45
    If we go back to the main page, so clicking on the API tab up here at the top,
  • 5:50
    we said that there's this list of sort of high-level topics
  • 5:53
    in the center here and these are ones that are sort of called out
  • 5:56
    because they're sort of the most commonly referenced pieces of documentation.
  • 6:01
    Down here at the bottom, there's this link for Forms API Reference.
  • 6:06
    This one is documentation for all of the Form API elements.
  • 6:09
    This is a sort of gold mine for how you can build forms in Drupal.
  • 6:14
    It is extensive, it's also very long, so you're probably going to need a cup of coffee
  • 6:18
    before you start going through all of this.
  • 6:19
    But as a module developer, I'm constantly coming back
  • 6:22
    to this page and referring to it.
  • 6:24
    We'll talk more about the Form API in a coming series.
  • 6:28
    Back on the main page again, you can also click on the word
  • 6:31
    Topics over here on the right.
  • 6:33
    And if I click on Topics, what I get is a list of more
  • 6:37
    of those sort of high-level topics of documentation.
  • 6:40
    The ones that are in the middle of the main page
  • 6:42
    are ones that are sort of considered to be most likely read
  • 6:45
    and most likely used, but here I can see all of the groups of functions
  • 6:50
    and documentation and so forth.
  • 6:53
    So I can come here and I can say, oh,
  • 6:55
    what I really want to do inside of my module is make use of Drupal's locking mechanisms,
  • 7:00
    its functions to coordinate long running operations across requests.
  • 7:03
    And if I click on that, what I'm presented with is,
  • 7:07
    at the top, a bit of documentation about sort of high-level
  • 7:11
    how the locking mechanism system works and why it was built and so forth.
  • 7:16
    And then if I scroll down, I can see all the different functions
  • 7:19
    and possibly methods that I need to use in order to implement
  • 7:23
    or make use of Drupal's Locking API.
  • 7:26
    Another cool thing that I like to do is use the Drupal Examples project.
  • 7:31
    If you go to drupal.org/project/examples, there's the Examples for Developers project,
  • 7:37
    which is actually a whole set of modules that you can download into your Drupal site.
  • 7:41
    And this is really cool because what it is,
  • 7:43
    is a bunch of modules that implement all of these different APIs within Drupal.
  • 7:48
    So for example, if I wanted to learn how to interact
  • 7:52
    with Drupal's Image Manipulation API,
  • 7:55
    I could download and take a look at the code inside of this image example module.
  • 7:59
    And I can see there's a version of it for Drupal 7
  • 8:02
    and that it has tests and so forth.
  • 8:04
    This is really cool and these are actually handy
  • 8:07
    and it shows you a complete example of how you would do something,
  • 8:10
    so not just documentation about one particular function
  • 8:12
    but an example, and they're all very well-documented
  • 8:16
    of how the whole email system works
  • 8:18
    and how you could actually send an email using your module.
  • 8:22
    And finally, if I go back to api.drupal.org,
  • 8:27
    here's a cool trick, I can actually search for the word examples.
  • 8:33
    And what this does is actually pull up all of those example modules
  • 8:37
    from the Example project, which are indexed by api.drupal.org
  • 8:41
    and I can look at the code for any one of those and start to see how those work.
  • 8:45
    So if I wanted to take a look at the email example,
  • 8:48
    I could do so here and I could see
  • 8:51
    all of the different functions that are used inside of that.
  • 8:55
    I might take a look at email_example_mail
  • 8:57
    which is an implementation of hook_mail,
  • 8:59
    if I wanted to see how that particular module was doing it.
  • 9:02
    Again, a good example for how I might do it in my own code.
  • 9:07
    So api.drupal.org is great because it contains documentation
  • 9:10
    about all of Drupal's internal functions
  • 9:13
    and it contains the documentation from all of these example projects.
  • 9:17
    What it doesn't have is documentation about all of the modules that are in contrib.
  • 9:22
    However, because this site is all built off of a module
  • 9:26
    called the API module, which can parse Drupal code
  • 9:29
    and turn into documentation, it's possible for others
  • 9:32
    to set up their own API sites as well.
  • 9:35
    So api.drupal.org, probably one of the handiest tools
  • 9:39
    that you'll find for looking up information about
  • 9:42
    Drupal's internal functions and APIs
  • 9:44
    and how you can use them inside of your own modules.
  • 9:47
    [drupalize me]

Drupal API Documentation

Loading...

In this video you'll learn how to use api.drupal.org the canonical source for information about Drupal's hooks, APIs, and code documentation in order to find out information about implementing a particular hook, making use of a particular function or library of functions, and even gaining a better understanding of some of the big picture concepts behind Drupal's code and APIs.

Additional resources:
There are no resources for this video. If you believe there should be, please contact us.