wp_enqueue_scripts

Transcript

1. wp_enqueue_scripts Beyond the Basics Nate Conley
2. Who is this talk for? You should have a basic understanding of PHP and WordPress hooks. $you = has_understanding( 'PHP' ) && has_understanding( 'WordPress' );
3. What are we talking about? (Almost) everything that I have learned through mistakes and code review on including assets in WordPress.
4. What are we talking about? • Asset: In our case, a CSS or JavaScript meant to be delivered to a web browser • To enqueue: adding to a queue
5. What are we talking about? • Telling WordPress to add our asset to its list • WordPress will use best practices to include our asset • WordPress will use the information that we pass into functions to include assets
6. Basic example
7. function my_scripts() { wp_enqueue_style( 'my-stylesheet', get_stylesheet_directory_uri() . '/my.css' ); } add_action( 'wp_enqueue_scripts', 'my_scripts' );
8. function my_scripts() { wp_enqueue_style( 'my-stylesheet', get_stylesheet_directory_uri() . '/my.css' ); } add_action( 'wp_enqueue_scripts', 'my_scripts' ); Create a prefixed function
9. function my_scripts() { wp_enqueue_style( 'my-stylesheet', get_stylesheet_directory_uri() . '/my.css' ); } add_action( 'wp_enqueue_script', 'my_scripts' ); hook function in wp_enqueue_scripts
10. function my_scripts() { wp_enqueue_style( 'my-stylesheet', get_stylesheet_directory_uri() . '/my.css' ); } add_action( 'wp_enqueue_script', 'my_scripts' ); call a WordPress function called wp_enqueue_style
11. Four functions
12. #1: wp_enqueue_style() Used to include CSS files
13. #1: wp_enqueue_style() wp_enqueue_style( string $handle, string $src = '', array $deps = array(), string|bool|null $ver = false, string $media = 'all' );
14. #2: wp_enqueue_script() Used to include JavaScript files
15. #2: wp_enqueue_script() wp_enqueue_script( string $handle, string $src = '', array $deps = array(), string|bool|null $ver = false, bool $in_footer = false );
16. $handle • Unique identifier for your style or script • Convention is to slugify it and prefix it 'my_prefixedScript' 'script' 'my-good-script'
17. $src • The URL to your asset • More to come on this in a few more slides!
18. $deps • An array of dependencies, using the $handle • You can cause fatal errors if a handle isn’t already registered or enqueued
19. $deps • Can also be used for assets registered in Core array( 'jquery', 'my-other-script' ) • List of included scripts: https://developer.wordpress.org/reference/functions/wp_enqueue_script/ • Don’t enqueue your own jQuery!
20. $ver • Do not use filemtime! It is unreliable across environments • Instead, use static versioning (Ex: 20181103.1100) • Static versioning is more explicit • WordPress will do this to break browser caching: <link href="main.css?ver=20181103.1100">
21. $media (for styles) • The media that this stylesheet should apply to. • Usually ‘all’ • You can also use a media query • Potentially useful for ‘print’ stylesheet
22. $footer (for scripts) true - Place JavaScript file call in the footer in the markup false - Place JavaScript file call in the head in the markup • Always true, unless any of these conditions are met: ◦ Is there a script placed in the header that relies on this script? ◦ Is this mission-critical and should it be placed before the body renders.
23. $footer (for scripts) • Remember, JavaScript usually impacts the performance of your site the most. • Bytes of JavaScript and bytes of Images, CSS, etc are not created equally.
24. #3 & #4: wp_register_style()or wp_register_script()
25. Registering an asset sets it up for later use via wp_enqueue_style()or wp_enqueue_script()
26. function my_scripts() { wp_register_style( 'my-stylesheet', get_stylesheet_directory_uri() '/my.css' ); } add_action( 'wp_enqueue_scripts', 'my_scripts' ); ...later wp_enqueue_style( 'my-stylesheet' );
27. Hooks • You don’t have to just use wp_enqueue_scripts • admin_enqueue_scripts • add_shortcode • Gutenberg - parameter passed
28. function my_scripts() { wp_register_style( 'my-stylesheet', plugin_dir_url( __FILE__ ) . 'my.css' ); } add_action( 'wp_enqueue_scripts', 'my_scripts' );
29. function my_scripts() { wp_register_style( 'my-stylesheet', plugin_dir_url( __FILE__ ) . 'my.css' ); } add_action( 'wp_enqueue_scripts', 'my_scripts' );
30. function my_scripts() { wp_register_style( 'my-stylesheet', plugin_dir_url( __FILE__ ) . 'my.css' ); } add_action( 'wp_enqueue_scripts', 'my_scripts' );
31. function my_shortcode() { return 'Hello World!'; } add_shortcode( 'my_shortcode', 'my_shortcode' );
32. function my_shortcode() { wp_enqueue_script( 'my-stylesheet' ); return 'Hello World!'; } add_shortcode( 'my_shortcode', 'my_shortcode' );
33. function my_scripts( $hook ) { if ( 'toplevel_page_mypage' !== $hook ) { return; } wp_enqueue_style( 'my-stylesheet' ); } add_action( 'admin_enqueue_scripts', 'my_scripts' );
34. function my_block() { wp_register_script( 'my-script', ... ); wp_register_style( 'my-style', ... ); register_block_type( 'my-block/my-block', array( 'editor_script' => 'my-script', 'editor_style' => 'my-style', ) ); } add_action( 'init', 'my_block' );
35. Two Rules #1: Never hardcode asset URLS #2: Only include assets where they are needed
36. Rule #1: Never hardcode • URLs can change • People can use custom file directory structures • WordPress has functions to help you!
37. get_stylesheet_directory_uri() • Use this function inside of a child theme. • If you use this in a parent theme, it will reference a child theme if active • Does not include a trailing slash https://test.com/wp-content/themes/child-theme
38. get_template_directory_uri() • Use this function if you are authoring a parent theme. • If you use this function within a child theme, this will reference the root of its parent theme • Does not include a trailing slash https://test.com/wp-content/themes/parent-theme
39. plugin_dir_url() • Use this function inside of a plugin (or a must-use plugin) • You can pass it the magic constant __FILE__ (two underscores) to get the directory of the current file plugin_dir_url( __FILE__ );
40. plugin_dir_url( __FILE__ ) my-plugin/my-plugin.php https://test.com/wp-content/plugins/my-plugin/
41. plugin_dir_url( __FILE__ ) my-plugin/lib/file.php https://test.com/wp-content/plugins/my-plugin/lib/
42. plugin_dir_url( __FILE__ ) mu-plugins/my-plugin.php https://test.com/wp-content/mu-plugins/
43. plugin_dir_url() To go one directory up: plugin_dir_url( dirname( __FILE__ ) );
44. plugin_dir_url( dirname( __FILE__ ) ) my-plugin/lib/file.php https://test.com/wp-content/plugins/my-plugin/
45. Never hardcode Bonus! content_url(); wp-content folder without trailing slash wp_upload_dir(); array of information about the uploads folder Even more: https://codex.wordpress.org/Determining_Plugin_and_Content_Directories
46. Rule #2: Only where needed • Send only assets that are needed to the frontend • Reduce bloat • Help the reputation of WordPress!
47. Rule #2: Only where needed Conditional tags (https://codex.wordpress.org/Conditional_Tags)
48. function my_scripts() { if ( ! is_home() ) { return; } wp_enqueue_style( 'my-stylesheet' ); } add_action( 'wp_enqueue_scripts', 'my_scripts' );
49. Rule #2: Only where needed global post object (https://codex.wordpress.org/Function_Reference/$post) This should only be used where there is no conditional tag for what you are checking for
50. function my_scripts() { global $post; if ( 1 !== $post->author ) { return; } wp_enqueue_style( 'my-stylesheet' ); } add_action( 'wp_enqueue_scripts', 'my_scripts' );
51. Rule #2: Only where needed get_current_screen https://codex.wordpress.org/Function_Reference/get_current_screen • For use on admin screens • Always check to make sure this function exists (not all admin pages have this function available)
52. function my_scripts() { if ( ! function_exists( 'get_current_screen' ) ) { return; } $screen = get_current_screen(); ... } add_action( 'admin_enqueue_scripts', 'my_scripts' );
53. Bonus tips! • Use wp_localize_script to pass data to a JavaScript file • WordPress will handle converting your data to a JavaScript object and printing it to the screen
54. wp_localize_script( 'my-handle', 'MY_OBJECT', array( 'hello' => esc_js( __( 'hello', 'my-domain' ) ), 'meta' => get_post_meta( get_the_ID(), 'meta', true ), ) ); The handle for your script
55. wp_localize_script( 'my-handle', 'MY_OBJECT', array( 'hello' => esc_js( __( 'hello', 'my-domain' ) ), 'meta' => get_post_meta( get_the_ID(), 'meta', true ), ) ); The name of your object
56. wp_localize_script( 'my-handle', 'MY_OBJECT', array( 'hello' => esc_js( __( 'hello', 'my-domain' ) ), 'meta' => get_post_meta( get_the_ID(), 'meta', true ), ) ); Your data
57. (JavaScript) console.log( MY_OBJECT.meta );
58. Bonus tips! Something going wrong with your enqueuing? Make sure you are using url, not path! Ex: plugin_dir_url(), not plugin_dir_path()
59. Bonus tips! Want to add attributes to your tags? Use the filter style_loader_tag or script_loader_tag
60. function defer_attribute( $tag, $handle ) { if ( 'my-script' !== $handle ) { return $tag; } return str_replace( ' src', ' defer=true src', $tag ); } add_filter( 'script_loader_tag', 'defer_attribute' );
61. Bonus tips! When defining constants, use trailingslashit() https://codex.wordpress.org/Function_Reference/trailingslashit Appends a trailing slash without double slashes define( 'MY_ASSETS_URL', trailingslashit( get_stylesheet_directory_uri() ) );
62. Bonus tips! Need a list of available scripts or styles? Use the global objects $wp_scripts or $wp_styles
63. Bonus tips! wp_add_inline_script(); https://developer.wordpress.org/reference/functions/wp_add_inline_script/ Used for executing a script inside of a registered script
64. Resources Theme Handbook (Including CSS & JavaScript) - https://developer.wordpress.org/themes/basics/including-css-javascript/ Plugin Handbook (Server Side PHP and Enqueueing) - https://developer.wordpress.org/plugins/javascript/enqueuing/
65. Questions?
66. nate conley Twitter: @nateconley123