Extending your site using third-party JavaScript libraries

You can create rich interactive websites that go beyond what is included in the Drupal Gardens modules by using built-in, custom, or third-party JavaScript libraries.

You can set up your libraries at two levels:

• Page level - To use your libraries throughout your site, add the JavaScript libraries at the page level. For an example, see Adding tabs to your content using jQuery.
• Block level - If you want to limit the use of your embedded service to one page, and not use it throughout your entire site, consider using blocks. For more information, see Using JavaScript at the block level.

Your JavaScript library can either be a file that is local to your site or an external URL. Using an external URL is preferred over inserting JavaScript code directly in custom blocks because it can be added to either the header or footer, which prevents the parsing and execution of the JavaScript code from stalling the loading and rendering of your web page, providing better performance for each page. Further, the JavaScript will be aggregated, so multiple JavaScript files required for a single page will result in a single download, and the browser will cache the JavaScript and avoid downloading the JavaScript on subsequent page loads.

JavaScript code that is not required for every page can be associated with a block and still take advantage of the aggregation and deferred parsing and execution that results in faster page renders.

Using JavaScript at the page level

1. In the admin menu, select Modules, enable the JavaScript libraries module, and then click Save configuration.
2. Find a JavaScript or jQuery library that does what you want. You can perform a Google search to find these libraries.
3. Download and save the libraries to your computer. If your library depends on jQuery, please read about jQuery in Drupal Gardens.
4. Go to Configuration > JavaScript libraries.
5. Either select a built-in library (e.g., jQuery UI:Button) or add a custom library using the Custom tab and adding the libraries in the header or footer.
6. For custom libraries, if your file is on an external web server, use the External URL option. Otherwise, use the File option to upload the JavaScript file.

   If you want your library to load on every page view, select the Header or Footer region. If you only want to load your library on specific pages, set the region to Disabled. In this case you will create a custom block and place it on the appropriate pages and associate this JavaScript file with that block.

7. Click Save.
8. Edit your content, view, or block to add the appropriate CSS/HTML to your page to get the desired effect or functionality. Make sure to use the HTML tab of the WYSIWYG editor.

   

For an example, see how to add a handy Tabs control using jQuery UI Tabs to your content.

Using common JavaScript libraries across multiple sites

If you have multiple sites that need to use your new JavaScript libraries, you can create a separate site to manage all of your libraries in one location, and then create external cross-references from your other sites. This method is beneficial when you need to update your libraries across all of your sites. You can update the libraries on the main site (make sure you keep the same filename), which automatically updates every site that references those libraries. You can also roll back the changes if needed.

Using JavaScript on specific pages

For libraries that are only needed on a few pages, create a custom block that has visibility rules such that the block appears only on those pages. Associate the appropriate JavaScript file(s) with the block using the JavaScript vertical tab near the bottom of the form.

Your JavaScript file will only appear in the list if it is not associated with a region in the JavaScript library configuration. The JavaScript vertical tab does not appear when creating a new custom block, but it will appear when editing that block.

Make sure that your block is placed into a region on the page and is visible on the appropriate pages, then select the libraries you want associated with this block and save the block.

Using JavaScript at the block level

Using JavaScript and other "code snippets" on your site can allow you to embed external services and create many effects and usability enhancements. (PHP is not supported due to security implications.) Examples include Facebook "Like" widget, Twitter widgets, iFrames, retail badges, Google Adwords, and commerce widgets. To ensure your site is secure, only allow people with trusted roles to insert JavaScript on your site.

1. Go to Structure > Blocks, and then click the Add block link.
2. Describe what your script will do in the Block description, but leave the Block title blank.
3. In the Block body, select Full HTML format, and then enter your script in the body field.

   

4. If you are not limited as to where your block should be placed, position the block into one of the lower regions of your theme (Footer first, Footer second, or copyright).
5. You can leave the block visible on all pages, but if your script is complex, you can restrict the pages on which it displays in the Visibility settings at the bottom of the page.

For more information, see Blocks.

Note: If your JavaScript or code does not render, you may need to create a new text format, such as Raw HTML. For more information, see Create a new Text format.

jQuery in Drupal Gardens

Drupal includes the powerful jQuery and jQuery UI libraries. While the jQuery JavaScript object is available on every page load, using jQuery UI requires that you explicitly load it following the steps described in Using JavaScript at the page level.

Important: Many web services provide scripts which include a copy of jQuery. This will introduce conflicts into your site, because Drupal Gardens already includes jQuery. Watch for code that includes jQuery, and remove it before saving. Here is an example:

Notes:

• To see the version of jQuery used by Drupal Gardens go to Configuration > JavaScript libraries and look at the Version column.
• Drupal 7 doesn't let you use $ as a shortcut for jQuery, unless you wrap your code like this:
  function($){ // your code here }(jQuery);

  This creates an anonymous function inside of which $ equals jQuery, then immediately executes it. Alternatively, you can just use the jQuery variable in your functions, or you can assign var $ = jQuery; inside any function where you want to use the shortcut.