Make WordPress Core


Ignore:
Timestamp:
05/25/2021 08:26:21 AM (3 years ago)
Author:
noisysocks
Message:

REST API: Add widget endpoints

Adds the sidebars, widgets and widget-types REST API endpoints from the
Gutenberg plugin.

Fixes #41683.
Props TimothyBlynJacobs, spacedmonkey, zieladam, jorgefilipecosta, youknowriad, kevin940726.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/widgets.php

    r50994 r50995  
    358358 * @since 5.3.0 Formalized the existing and already documented `...$params` parameter
    359359 *              by adding it to the function signature.
     360 * @since 5.8.0 Added show_instance_in_rest option.
    360361 *
    361362 * @global array $wp_registered_widgets            Uses stored registered widgets.
     
    370371 *     Optional. An array of supplementary widget options for the instance.
    371372 *
    372  *     @type string $classname   Class name for the widget's HTML container. Default is a shortened
    373  *                               version of the output callback name.
    374  *     @type string $description Widget description for display in the widget administration
    375  *                               panel and/or theme.
     373 *     @type string $classname             Class name for the widget's HTML container. Default is a shortened
     374 *                                         version of the output callback name.
     375 *     @type string $description           Widget description for display in the widget administration
     376 *                                         panel and/or theme.
     377 *     @type bool   $show_instance_in_rest Whether to show the widget's instance settings in the REST API.
     378 *                                         Only available for WP_Widget based widgets.
    376379 * }
    377380 * @param mixed      ...$params       Optional additional parameters to pass to the callback function when it's called.
     
    17971800    register_widget( 'WP_Widget_Custom_HTML' );
    17981801
     1802    register_widget( 'WP_Widget_Block' );
     1803
    17991804    /**
    18001805     * Fires after all default WordPress widgets have been registered.
     
    18041809    do_action( 'widgets_init' );
    18051810}
     1811
     1812/**
     1813 * Converts a widget ID into its id_base and number components.
     1814 *
     1815 * @since 5.8.0
     1816 *
     1817 * @param string $id Widget ID.
     1818 * @return array Array containing a widget's id_base and number components.
     1819 */
     1820function wp_parse_widget_id( $id ) {
     1821    $parsed = array();
     1822
     1823    if ( preg_match( '/^(.+)-(\d+)$/', $id, $matches ) ) {
     1824        $parsed['id_base'] = $matches[1];
     1825        $parsed['number']  = (int) $matches[2];
     1826    } else {
     1827        // Likely an old single widget.
     1828        $parsed['id_base'] = $id;
     1829    }
     1830
     1831    return $parsed;
     1832}
     1833
     1834/**
     1835 * Finds the sidebar that a given widget belongs to.
     1836 *
     1837 * @since 5.8.0
     1838 *
     1839 * @param string $widget_id The widget id to look for.
     1840 * @return string|null The found sidebar's id, or null if it was not found.
     1841 */
     1842function wp_find_widgets_sidebar( $widget_id ) {
     1843    foreach ( wp_get_sidebars_widgets() as $sidebar_id => $widget_ids ) {
     1844        foreach ( $widget_ids as $maybe_widget_id ) {
     1845            if ( $maybe_widget_id === $widget_id ) {
     1846                return (string) $sidebar_id;
     1847            }
     1848        }
     1849    }
     1850
     1851    return null;
     1852}
     1853
     1854/**
     1855 * Assigns a widget to the given sidebar.
     1856 *
     1857 * @since 5.8.0
     1858 *
     1859 * @param string $widget_id  The widget id to assign.
     1860 * @param string $sidebar_id The sidebar id to assign to. If empty, the widget won't be added to any sidebar.
     1861 */
     1862function wp_assign_widget_to_sidebar( $widget_id, $sidebar_id ) {
     1863    $sidebars = wp_get_sidebars_widgets();
     1864
     1865    foreach ( $sidebars as $maybe_sidebar_id => $widgets ) {
     1866        foreach ( $widgets as $i => $maybe_widget_id ) {
     1867            if ( $widget_id === $maybe_widget_id && $sidebar_id !== $maybe_sidebar_id ) {
     1868                unset( $sidebars[ $maybe_sidebar_id ][ $i ] );
     1869                // We could technically break 2 here, but continue looping in case the id is duplicated.
     1870                continue 2;
     1871            }
     1872        }
     1873    }
     1874
     1875    if ( $sidebar_id ) {
     1876        $sidebars[ $sidebar_id ][] = $widget_id;
     1877    }
     1878
     1879    wp_set_sidebars_widgets( $sidebars );
     1880}
     1881
     1882/**
     1883 * Calls the render callback of a widget and returns the output.
     1884 *
     1885 * @since 5.8.0
     1886 *
     1887 * @param string $widget_id Widget ID.
     1888 * @param string $sidebar_id Sidebar ID.
     1889 * @return string
     1890 */
     1891function wp_render_widget( $widget_id, $sidebar_id ) {
     1892    global $wp_registered_widgets, $wp_registered_sidebars;
     1893
     1894    if ( ! isset( $wp_registered_widgets[ $widget_id ] ) ) {
     1895        return '';
     1896    }
     1897
     1898    if ( isset( $wp_registered_sidebars[ $sidebar_id ] ) ) {
     1899        $sidebar = $wp_registered_sidebars[ $sidebar_id ];
     1900    } elseif ( 'wp_inactive_widgets' === $sidebar_id ) {
     1901        $sidebar = array();
     1902    } else {
     1903        return '';
     1904    }
     1905
     1906    $params = array_merge(
     1907        array(
     1908            array_merge(
     1909                $sidebar,
     1910                array(
     1911                    'widget_id'   => $widget_id,
     1912                    'widget_name' => $wp_registered_widgets[ $widget_id ]['name'],
     1913                )
     1914            ),
     1915        ),
     1916        (array) $wp_registered_widgets[ $widget_id ]['params']
     1917    );
     1918
     1919    // Substitute HTML `id` and `class` attributes into `before_widget`.
     1920    $classname_ = '';
     1921    foreach ( (array) $wp_registered_widgets[ $widget_id ]['classname'] as $cn ) {
     1922        if ( is_string( $cn ) ) {
     1923            $classname_ .= '_' . $cn;
     1924        } elseif ( is_object( $cn ) ) {
     1925            $classname_ .= '_' . get_class( $cn );
     1926        }
     1927    }
     1928    $classname_                 = ltrim( $classname_, '_' );
     1929    $params[0]['before_widget'] = sprintf( $params[0]['before_widget'], $widget_id, $classname_ );
     1930
     1931    /** This filter is documented in wp-includes/widgets.php */
     1932    $params = apply_filters( 'dynamic_sidebar_params', $params );
     1933
     1934    $callback = $wp_registered_widgets[ $widget_id ]['callback'];
     1935
     1936    ob_start();
     1937
     1938    /** This filter is documented in wp-includes/widgets.php */
     1939    do_action( 'dynamic_sidebar', $wp_registered_widgets[ $widget_id ] );
     1940
     1941    if ( is_callable( $callback ) ) {
     1942        call_user_func_array( $callback, $params );
     1943    }
     1944
     1945    return ob_get_clean();
     1946}
     1947
     1948/**
     1949 * Calls the control callback of a widget and returns the output.
     1950 *
     1951 * @since 5.8.0
     1952 *
     1953 * @param string $id Widget ID.
     1954 * @return string|null
     1955 */
     1956function wp_render_widget_control( $id ) {
     1957    global $wp_registered_widget_controls;
     1958
     1959    if ( ! isset( $wp_registered_widget_controls[ $id ]['callback'] ) ) {
     1960        return null;
     1961    }
     1962
     1963    $callback = $wp_registered_widget_controls[ $id ]['callback'];
     1964    $params   = $wp_registered_widget_controls[ $id ]['params'];
     1965
     1966    ob_start();
     1967
     1968    if ( is_callable( $callback ) ) {
     1969        call_user_func_array( $callback, $params );
     1970    }
     1971
     1972    return ob_get_clean();
     1973}
Note: See TracChangeset for help on using the changeset viewer.