WordPress.org

Make WordPress Core

Changes between Version 6 and Version 7 of Ticket #46370


Ignore:
Timestamp:
03/05/2019 06:04:54 PM (15 months ago)
Author:
westonruter
Comment:

I've updated the proposed definition of wp_enqueue_font() to pass args as an array instead of many positional params.

Legend:

Unmodified
Added
Removed
Modified
  • Ticket #46370 – Description

    v6 v7  
    3030The [https://developers.google.com/web/fundamentals/performance/optimizing-content-efficiency/webfont-optimization Web Fundamentals documentation] provides an example of an optimal CSS structure for loading fonts. E.g.,
    3131
    32 {{{
     32{{{#!css
    3333@font-face {
    3434  font-family: 'Awesome Font';
     
    6565The process of enqueuing a font should allow a developer to specify the name of the font, and to provide an optional level of detail/control over specific aspects (versions, weights, file locations). Where details/specifics aren’t provided, sensible fallbacks and defaults should be assumed.
    6666
    67 I suggest the following structure:
     67I suggest the following structure function definition:
    6868
    69 {{{
    70 wp_enqueue_font(
    71   string $handle,                    // The name of the font
    72   string|array|bool $src = false,    // The source(s) of the font files
    73   string $style          = 'normal', // The style of the font
    74   int $weight            = 400,      // The weight of the font
    75   string $display        = 'auto'    // Display/swap behaviour
    76   string $range          = false,    // A unicode range value
    77   string|bool $external  = false,    // Externalise the CSS file/code
    78   bool $preload          = true      // Should the resource be preloaded
    79   bool $in_footer        = false     // Output the CSS/file in the footer
    80 )
     69{{{#!php
     70<?php
     71/**
     72 * Enqueue font.
     73 *
     74 * @param string            $handle The name of the font.
     75 * @param string|array|bool $src    The source(s) of the font files.
     76 * @param array $params {
     77 *      Params.
     78 *
     79 *      @type string      $style     The style of the font.
     80 *      @type int         $weight    The weight of the font.
     81 *      @type string      $display   Display/swap behaviour.
     82 *      @type string      $range     A unicode range value.
     83 *      @type string|bool $external  Externalise the CSS file/code.
     84 *      @type bool        $preload   Should the resource be preloaded.
     85 *      @type bool        $in_footer Output the CSS/file in the footer.
     86 * }
     87 */
     88function wp_enqueue_font( $handle, $src = false, $params = array() ) {
     89        $params = wp_parse_args(
     90                $params,
     91                array(
     92                        'style'     => 'normal',
     93                        'weight'    => 400,
     94                        'display'   => 'auto',
     95                        'range'     => false,
     96                        'external'  => false,
     97                        'preload'   => true,
     98                        'in_footer' => false,
     99                )
     100        );
     101
     102        // ...
    81103}}}
     104
     105Note that the args after `$src` are in an associative array to avoid having to supply positional params with default values and to make it easier to easily identify the parameters. Something similar could be done for `wp_register_script()` and `wp_register_style()`.
    82106
    83107== Starting from simplicity
    84108A simple implementation of this, which omits much of the detail and utilises default behaviours, might look something like:
    85109
    86 {{{
     110{{{#!php
     111<?php
    87112wp_enqueue_font(
    88113  'Awesome Font',
    89   '/fonts/awesome-font-400.woff2',
    90   '', // $style
    91   '', // $weight
    92   '', // $display
    93   '', // $range
    94   '', // $external
    95   '', // $preload
    96   ''  // $in_footer
    97 )
     114  '/fonts/awesome-font-400.woff2'
     115);
    98116}}}
    99117
    100118In this example, we’ve only specified the bare minimum information required to enqueue a font - a name and a location. But there’s enough here that we can generate the following CSS:
    101119
    102 {{{
     120{{{#!css
    103121@font-face {
    104122  font-family: 'Awesome Font';
     
    119137Whilst our `$src` variable can accept a simple string, more advanced usage should specify multiple versions and their formats. That looks like this (maintaining the rest of our ‘simplest implementation’ approach):
    120138
    121 {{{
     139{{{#!php
     140<?php
    122141wp_enqueue_font(
    123142  'Awesome Font',
     
    127146    'truetype'          => '/fonts/awesome-font-400.ttf',
    128147    'embedded-opentype' => '/fonts/awesome-font-400.eot',
    129   ),
    130   '', // $style
    131   '', // $weight
    132   '', // $display
    133   '', // $range
    134   '', // $external
    135   '', // $preload
    136   ''  // $in_footer
    137 )
     148  )
     149);
    138150}}}
    139151