Make WordPress Core


Ignore:
Timestamp:
12/03/2013 05:05:53 PM (11 years ago)
Author:
lancewillett
Message:

Twenty Fourteen: update comment blocks to match inline docs standards. Props DrewAPicture, see #25837.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-content/themes/twentyfourteen/inc/featured-content.php

    r26361 r26556  
    33 * Twenty Fourteen Featured Content
    44 *
    5  * This module allows you to define a subset of posts to be displayed in the
    6  * theme's Featured Content area.
     5 * This module allows you to define a subset of posts to be displayed
     6 * in the theme's Featured Content area.
    77 *
    8  * For maximum compatibility with different methods of posting users will
    9  * designate a featured post tag to associate posts with. Since this tag now
    10  * has special meaning beyond that of a normal tags, users will have the
    11  * ability to hide it from the front-end of their site.
     8 * For maximum compatibility with different methods of posting users
     9 * will designate a featured post tag to associate posts with. Since
     10 * this tag now has special meaning beyond that of a normal tags, users
     11 * will have the ability to hide it from the front-end of their site.
    1212 */
    1313class Featured_Content {
    1414
    1515    /**
    16      * The maximum number of posts that a Featured Content area can contain. We
    17      * define a default value here but themes can override this by defining a
    18      * "max_posts" entry in the second parameter passed in the call to
    19      * add_theme_support( 'featured-content' ).
     16     * The maximum number of posts a Featured Content area can contain.
     17     *
     18     * We define a default value here but themes can override
     19     * this by defining a "max_posts" entry in the second parameter
     20     * passed in the call to add_theme_support( 'featured-content' ).
    2021     *
    2122     * @see Featured_Content::init()
     23     *
     24     * @since Twenty Fourteen 1.0
     25     *
     26     * @static
     27     * @access public
     28     * @var int
    2229     */
    2330    public static $max_posts = 15;
    2431
    2532    /**
    26      * Instantiate
     33     * Instantiate.
    2734     *
    2835     * All custom functionality will be hooked into the "init" action.
     36     *
     37     * @static
     38     * @access public
     39     * @since Twenty Fourteen 1.0
    2940     */
    3041    public static function setup() {
     
    3344
    3445    /**
    35      * Conditionally hook into WordPress
     46     * Conditionally hook into WordPress.
    3647     *
    3748     * Theme must declare that they support this module by adding
     
    4152     * We'll just return early instead.
    4253     *
    43      * @uses Featured_Content::$max_posts
     54     * @static
     55     * @access public
     56     * @since Twenty Fourteen 1.0
    4457     */
    4558    public static function init() {
     
    8699     * Has to run on wp_loaded so that the preview filters of the customizer
    87100     * have a chance to alter the value.
     101     *
     102     * @static
     103     * @access public
     104     * @since Twenty Fourteen 1.0
    88105     */
    89106    public static function wp_loaded() {
     
    95112
    96113    /**
    97      * Get featured posts
    98      *
    99      * @uses Featured_Content::get_featured_post_ids()
    100      *
    101      * @return array
     114     * Get featured posts.
     115     *
     116     * @static
     117     * @access public
     118     * @since Twenty Fourteen 1.0
     119     *
     120     * @return array Array of featured posts.
    102121     */
    103122    public static function get_featured_posts() {
     
    125144     * Sets the "featured_content_ids" transient.
    126145     *
    127      * @return array Array of post IDs
     146     * @static
     147     * @access public
     148     * @since Twenty Fourteen 1.0
     149     *
     150     * @return array Array of post IDs.
    128151     */
    129152    public static function get_featured_post_ids() {
     
    171194
    172195    /**
    173      * Returns an array with IDs of posts maked as sticky.
    174      *
    175      * @return array
     196     * Return an array with IDs of posts maked as sticky.
     197     *
     198     * @static
     199     * @access public
     200     * @since Twenty Fourteen 1.0
     201     *
     202     * @return array Array of sticky posts.
    176203     */
    177204    public static function get_sticky_posts() {
     
    181208
    182209    /**
    183      * Delete transient
     210     * Delete featured content ids transient.
    184211     *
    185212     * Hooks in the "save_post" action.
     213     *
    186214     * @see Featured_Content::validate_settings().
     215     *
     216     * @static
     217     * @access public
     218     * @since Twenty Fourteen 1.0
    187219     */
    188220    public static function delete_transient() {
     
    191223
    192224    /**
    193      * Exclude featured posts from the home page blog query
    194      *
    195      * Filter the home page posts, and remove any featured post ID's from it. Hooked
    196      * onto the 'pre_get_posts' action, this changes the parameters of the query
    197      * before it gets any posts.
    198      *
    199      * @uses Featured_Content::get_featured_post_ids();
    200      * @param WP_Query $query
    201      * @return WP_Query Possibly modified WP_Query
     225     * Exclude featured posts from the home page blog query.
     226     *
     227     * Filter the home page posts, and remove any featured post ID's from it.
     228     * Hooked onto the 'pre_get_posts' action, this changes the parameters of
     229     * the query before it gets any posts.
     230     *
     231     * @static
     232     * @access public
     233     * @since Twenty Fourteen 1.0
     234     *
     235     * @param WP_Query $query WP_Query object.
     236     * @return WP_Query Possibly-modified WP_Query.
    202237     */
    203238    public static function pre_get_posts( $query ) {
     
    234269
    235270    /**
    236      * Reset tag option when the saved tag is deleted
    237      *
    238      * It's important to mention that the transient needs to be deleted, too.
    239      * While it may not be obvious by looking at the function alone, the transient
    240      * is deleted by Featured_Content::validate_settings().
     271     * Reset tag option when the saved tag is deleted.
     272     *
     273     * It's important to mention that the transient needs to be deleted,
     274     * too. While it may not be obvious by looking at the function alone,
     275     * the transient is deleted by Featured_Content::validate_settings().
    241276     *
    242277     * Hooks in the "delete_post_tag" action.
     278     *
    243279     * @see Featured_Content::validate_settings().
     280     *
     281     * @static
     282     * @access public
     283     * @since Twenty Fourteen 1.0
    244284     *
    245285     * @param int $tag_id The term_id of the tag that has been deleted.
     
    259299
    260300    /**
    261      * Hide featured tag from displaying when global terms are queried from the front-end
     301     * Hide featured tag from displaying when global terms are queried from the front-end.
    262302     *
    263303     * Hooks into the "get_terms" filter.
    264304     *
    265      * @param array $terms A list of term objects. This is the return value of get_terms().
     305     * @static
     306     * @access public
     307     * @since Twenty Fourteen 1.0
     308     *
     309     * @param array $terms      List of term objects. This is the return value of get_terms().
    266310     * @param array $taxonomies An array of taxonomy slugs.
    267      * @return array $terms
     311     * @return array A filtered array of terms.
    268312     *
    269313     * @uses Featured_Content::get_setting()
     
    296340
    297341    /**
    298      * Hide featured tag from display when terms associated with a post object are queried from the front-end
     342     * Hide featured tag from display when terms associated with a post object
     343     * are queried from the front-end.
    299344     *
    300345     * Hooks into the "get_the_terms" filter.
    301346     *
    302      * @param array $terms A list of term objects. This is the return value of get_the_terms().
    303      * @param int $id The ID field for the post object that terms are associated with.
     347     * @static
     348     * @access public
     349     * @since Twenty Fourteen 1.0
     350     *
     351     * @param array $terms    A list of term objects. This is the return value of get_the_terms().
     352     * @param int   $id       The ID field for the post object that terms are associated with.
    304353     * @param array $taxonomy An array of taxonomy slugs.
    305      * @return array $terms
     354     * @return array Filtered array of terms.
    306355     *
    307356     * @uses Featured_Content::get_setting()
     
    334383
    335384    /**
    336      * Register custom setting on the Settings -> Reading screen
    337      *
    338      * @uses Featured_Content::render_form()
    339      * @uses Featured_Content::validate_settings()
     385     * Register custom setting on the Settings -> Reading screen.
     386     *
     387     * @static
     388     * @access public
     389     * @since Twenty Fourteen 1.0
    340390     *
    341391     * @return void
     
    347397    /**
    348398     * Add settings to the Customizer.
     399     *
     400     * @static
     401     * @access public
     402     * @since Twenty Fourteen 1.0
    349403     *
    350404     * @param WP_Customize_Manager $wp_customize Theme Customizer object.
     
    387441     * Enqueue the tag suggestion script.
    388442     *
     443     * @static
     444     * @access public
    389445     * @since Twenty Fourteen 1.0
    390446     */
     
    394450
    395451    /**
    396      * Get settings
    397      *
    398      * Get all settings recognized by this module. This function will return
    399      * all settings whether or not they have been stored in the database yet.
    400      * This ensures that all keys are available at all times.
    401      *
    402      * In the event that you only require one setting, you may pass its name
    403      * as the first parameter to the function and only that value will be returned.
    404      *
    405      * @uses Featured_Content::sanitize_quantity()
     452     * Get featured content settings.
     453     *
     454     * Get all settings recognized by this module. This function
     455     * will return all settings whether or not they have been stored
     456     * in the database yet. This ensures that all keys are available
     457     * at all times.
     458     *
     459     * In the event that you only require one setting, you may pass
     460     * its name as the first parameter to the function and only that
     461     * value will be returned.
     462     *
     463     * @static
     464     * @access public
     465     * @since Twenty Fourteen 1.0
    406466     *
    407467     * @param string $key The key of a recognized setting.
     
    430490
    431491    /**
    432      * Validate settings
    433      *
    434      * Make sure that all user supplied content is in an
    435      * expected format before saving to the database. This
    436      * function will also delete the transient set in
    437      * Featured_Content::get_featured_content().
    438      *
    439      * @uses Featured_Content::self::sanitize_quantity()
    440      * @uses Featured_Content::self::delete_transient()
    441      *
    442      * @param array $input
    443      * @return array $output
     492     * Validate featured content settings.
     493     *
     494     * Make sure that all user supplied content is in an expected
     495     * format before saving to the database. This function will also
     496     * delete the transient set in Featured_Content::get_featured_content().
     497     *
     498     * @static
     499     * @access public
     500     * @since Twenty Fourteen 1.0
     501     *
     502     * @param array $input Array of settings input.
     503     * @return array Validated settings output.
    444504     */
    445505    public static function validate_settings( $input ) {
     
    470530        $output['hide-tag'] = isset( $input['hide-tag'] ) && $input['hide-tag'] ? 1 : 0;
    471531
     532        // Delete the featured post ids transient.
    472533        self::delete_transient();
    473534
     
    476537
    477538    /**
    478      * Sanitize quantity
     539     * Sanitize quantity of featured posts.
     540     *
     541     * @static
     542     * @access public
     543     * @since Twenty Fourteen 1.0
    479544     *
    480545     * @param int $input The value to sanitize.
    481546     * @return int A number between 1 and FeaturedContent::$max_posts.
    482      *
    483      * @uses Featured_Content::$max_posts
    484547     */
    485548    public static function sanitize_quantity( $input ) {
     
    494557        return $quantity;
    495558    }
    496 }
     559
     560} // Featured_Content
    497561
    498562Featured_Content::setup();
Note: See TracChangeset for help on using the changeset viewer.