-
Notifications
You must be signed in to change notification settings - Fork 71
Action and Filter Hooks
There are numerous action and filter hooks throughout the plugin to allow for advanced users to customize virtually any aspect of the article before it's sent to Apple News. Many larger publishers have used these hooks to create detailed custom templates or modify the post content specifically for Apple News. If you're unfamiliar with hooks in WordPress, the core documentation on actions and filters is a great place to start.
We're providing documentation here on these hooks so everyone is aware of what's available, but as always it's best to view them in the source code and see them in action if you need more clarity on how they can be used. We've listed all hooks below alphabetically, but if you click through for more details on a hook, there is a link to the source file to make it easy for you to find them if needed.
Action hooks are used to trigger custom functions that rely on knowing when a specific piece of code executes or to insert additional content on template pages. They sometimes are accompanied by parameters that are relevant to the specific action.
-
apple_news_after_async_push- Optional actions to be taken after an async push completes. -
apple_news_after_bulk_export_table- Allows for custom HTML to be printed after the bulk export table. -
apple_news_after_clean_up- Actions to be taken after postmeta is cleaned up for a post. -
apple_news_before_async_push- Optional actions to be taken before an async push starts.
do_action( 'apple_news_extra_tablenav' );
This action allows you to add additional filter or navigational options to the Apple News list table.
do_action( 'apple_news_before_delete', $remote_id, $this->id );
This action fires before an article is deleted from Apple News. $remote_id is the Apple News ID and $this->id corresponds to the WordPress post ID.
do_action( 'apple_news_after_delete', $remote_id, $this->id );
This action fires after an article is deleted from Apple News. $remote_id is the Apple News ID and $this->id is the WordPress post ID.
do_action( 'apple_news_do_fetch_exporter', $this->id );
This action fires before the Apple News Exporter is initialized, which is the class that is primarily responsible for directing the conversion from WordPress to Apple News format. If you needed to modify the post in some way prior to this process starting, this is a good place to hook. $this->id is the WordPress post ID.
do_action( 'apple_news_before_push', $this->id );
This action fires before a post is pushed to Apple News. $this->id is the WordPress post ID.
do_action( 'apple_news_after_push', $this->id, $result );
This action fires after a post is pushed to Apple News. $this->id is the WordPress post ID and $result contains an array with the full API response from Apple News.
do_action( 'apple_news_before_bulk_export_table' )
This allows you to insert content or take an action before the table on the bulk export screen.
do_action( 'apple_news_before_index_table' )
This allows you to insert content or take an action before the Apple News list table.
do_action( 'apple_news_after_index_table' )
This allows you to insert content or take an action after the Apple News list table.
admin/partials/page-options-section.php, admin/partials/page-options-section-hidden.php, and admin/partials/page-theme-edit.php
do_action( 'apple_news_before_setting_group', $group )
This allows you to insert content or take an action before a specific group of settings on the Apple News settings page. $group contains an array of information about the group.
do_action( 'apple_news_after_setting_group', $group )
This allows you to insert content or take an action after a specific group of settings on the Apple News settings page. $group contains an array of information about the group.
do_action( 'apple_news_before_setting', $setting_name, $setting_meta )
This allows you to insert content or take an action before a specific setting field on the Apple News settings page. $setting_name contains the name of the field and $setting_meta contains an array of information about the field.
do_action( 'apple_news_after_setting', $setting_name, $setting_meta )
This allows you to insert content or take an action after a specific setting field on the Apple News settings page. $setting_name contains the name of the field and $setting_meta contains an array of information about the field.
do_action( 'apple_news_before_single_settings' )
This allows you to insert content or take an action at the top of the single post publish page for Apple News.
do_action( 'apple_news_after_single_settings' )
This allows you to insert content or take an action at the bottom of the single post publish page for Apple News.
do_action( 'apple_news_before_clean_up' );
This action fires before the workspace is cleaned up. The workspace is simply a set of meta values that store information about the post, such as images and errors that occur during publishing. It's no longer needed once the post is published so this information is removed to not clutter your database. This hook might be useful if you wanted to do something with this information prior to clean up.
Filter hooks are used to modify a variable. The first parameter is always the data to be modified and additional parameters may also be provided that are relevant to that specific filter. If you're hooking a filter your function must return the data, even if unmodified, or it will simply delete the value.
apply_filters( 'apple_news_bulk_export_capability', 'manage_options' )
Modifies the capability required to bulk publish posts to Apple News. Defaults to manage_options.
apply_filters( 'apple_news_publish_capability', self::get_capability_for_post_type( 'publish_posts', $post->post_type ) )
Modifies the capability required to publish a single post to Apple News. Defaults to the equivalent of publish_posts for the given post type.
apply_filters( 'apple_news_list_capability', 'manage_options' )
Modifies the capability required to view the Apple News list. Defaults to manage_options.
apply_filters( 'apple_news_settings_capability', 'manage_options' )
Modifies the capability required to edit Apple News settings. Defaults to manage_options.
apply_filters( 'apple_news_publish_meta_box_context', 'side' )
Changes the context (i.e. column) where the Apple News meta box appears by default on the post edit screen. Defaults to side. For proper usage, please read the documentation on add_meta_box.
apply_filters( 'apple_news_publish_meta_box_priority', 'high' )
Changes the priority (i.e. vertical location) where the Apple News meta box appears by default on the post edit screen. Defaults to side. For proper usage, please read the documentation on add_meta_box.
apply_filters( 'apple_news_column_default', $default, $column_name, $item )
Allows you to set the value for any column in any row on the Apple News list. $default contains the current value, $column_name contains the column name and $item contains an array of information about the current row.
esc_html( $item->post_title ),
absint( $item->ID ),
$this->row_actions( $actions ) // can't be escaped but all elements are fully escaped above
)
Allows you to change the title of a post in the title column. Values contain the post title, post ID and available row actions, in that order.
apply_filters( 'apple_news_export_list_columns', array(
'cb' => '<input type="checkbox">',
'title' => __( 'Title', 'apple-news' ),
'updated_at' => __( 'Last updated at', 'apple-news' ),
'status' => __( 'Apple News Status', 'apple-news' ),
'sync' => __( 'Sync Status', 'apple-news' ),
)
Allows you to add, edit or delete the columns on the Apple News list table.
apply_filters( 'apple_news_bulk_actions', array(
Admin_Apple_Index_Page::namespace_action( 'push' ) => __( 'Publish', 'apple-news' ),
)
Allows you to add, edit or delete available bulk actions on the Apple News list table.
apply_filters( 'apple_news_export_table_get_posts_args', $args )
Allows you to manipulate the $args sent to WP_Query to populate the posts on the Apple News list table.
apply_filters( 'apple_news_export_table_pagination_args', array(
'total_items' => $total_items,
'per_page' => $this->per_page,
'total_pages' => ceil( $total_items / $this->per_page ),
) )
Allows you to manipulate the arguments for paginating the Apple News list table.
apply_filters( 'apple_news_publish_statuses', array(
'' => __( 'Show All Statuses', 'apple-news' ),
'published' => __( 'Published', 'apple-news' ),
'not_published' => __( 'Not Published', 'apple-news' ),
'pending' => __( 'Pending', 'apple-news' ),
'deleted' => __( 'Deleted', 'apple-news' ),
)
If you've added custom statuses to Apple News, this allows you to make them available for filtering the Apple News list table.
apply_filters( 'apple_news_post_status_cache_expiration', $cache_expiration, $state )
Allows you to modify the cache time for API responses. Most responses are cached to avoid repeatedly hitting the API, which would slow down your admin dashboard. $cache_expiration is the current cache time and $state corresponds to the current Apple News API status for that post. Different statuses are cached for different times since some are more likely to change quickly than others.
apply_filters( 'apple_news_notice_message', $message, $type )
Allows you to change any success, info or error notice that appears in the dashboard. $message contains the text of the message and $type indicates whether it indicates info, success or error.
apply_filters( 'apple_news_publish_capability', Apple_News::get_capability_for_post_type( 'publish_posts', $post->post_type ) )
apply_filters( 'apple_news_delete_capability', Apple_News::get_capability_for_post_type( 'delete_posts', $post->post_type ) )
Modifies the capability required to delete a single post from Apple News. Defaults to the equivalent of delete_posts for the post type in question.
apply_filters( 'apple_news_section_taxonomy', 'category' )
Modifies which taxonomy is used for section mapping.
apply_filters( 'apple_news_settings_capability', 'manage_options' )
Modifies the capability required to edit Apple News settings. Defaults to manage_options.
apply_filters( 'apple_news_settings_sections', $this->sections )
Modifies the available sections on the settings page.
apply_filters( 'apple_news_settings_capability', 'manage_options' )
Modifies the capability required to edit Apple News settings. Defaults to manage_options.
apply_filters( 'apple_news_loaded_settings', $this->loaded_settings )
Modifies the current settings in the database immediately after they're loaded. However, it does not change the settings in the database.
apply_filters( 'apple_news_field_description_output_html', '<br/><i>' . $description . '</i>', $name )
Modifies the HTML output for the description of any field. $name contains the field name.
apply_filters( 'apple_news_settings_capability', 'manage_options' )
Modifies the capability required to edit Apple News settings. Defaults to manage_options.
apply_filters( 'apple_news_exporter_title', $post->post_title, $post->ID )
Modifies the title of a specific post for Apple News.
apply_filters( 'apple_news_exporter_excerpt', $excerpt, $post->ID )
Modifies the excerpt a specific post for Apple News.
apply_filters( 'apple_news_exporter_post_thumb', $post_thumb, $post->ID )
Modifies the thumbnail used for a post for Apple News.
apply_filters( 'apple_news_exporter_byline', $byline, $post->ID )
Modifies the byline of the post for Apple News.
apply_filters( 'apple_news_exporter_content_pre', $post->post_content, $post->ID )
Modifies the contents of a post before the_content filter is called. This could be useful to remove shortcodes or oEmbeds that are known to be incompatible with Apple News before they are rendered.
apply_filters( 'apple_news_exporter_content', $content, $post->ID )
Modifies the contents of a post after the_content filter is called. This could be useful to remove content known to be incompatible with Apple News.
apply_filters( 'apple_news_content_settings', $settings )
Modifies the settings used for formatting content.
apply_filters( 'apple_news_is_post_in_sync', $in_sync, $this->id, $api_time, $local_time )
Modifies whether or not the post is in sync with Apple News. By default, the plugin simply compares the last modified time to the last time it was pushed to Apple News. If you want to apply custom logic, you can do that by modifying $in_sync. The most common use case is to not update posts based on custom criteria. $this->id contains the post ID. $api_time contains the timestamp when the article was last pushed to Apple News. $local_time contains a timestamp with the last time the post was updated in WordPress.
apply_filters( 'apple_news_skip_push', false, $this->id )
Allows you to stop publication of a post to Apple News based on your own custom logic. A common use case is to not publish posts with a certain category or tag. By default this is always false as all posts are published once they reach this step. $this->id contains the post ID.
apply_filters( 'apple_news_publish_capability', Apple_News::get_capability_for_post_type( 'publish_posts', $post->post_type ) )
Modifies the capability required to publish a single post to Apple News. Defaults to the equivalent of publish_posts for the post type in question.
apply_filters( 'apple_news_json_editor_ace_theme', 'ace/theme/textmate', $component, $field_name );
Modifies the JSON editor theme. $field_name contains the name of the component being edited. $field_name contains the name of the specific field.
apply_filters( 'apple_news_post_types', get_post_types( array(
'public' => true,
'show_ui' => true,
), 'objects' )
Modifies the post types available for selection in the Post Type Options settings.
apply_filters( 'apple_news_section_settings', $this->settings, $page );
Modifies the setting values for the settings page. $this->settings contains an array of settings. $page contains the name of the settings page.
apply_filters( 'apple_news_section_groups', $this->groups, $page )
Modifies the groups for the settings page. This could be used to add or remove a group or reorder them. $this->groups contains an array of groups. $page contains the name of the settings page.
apply_filters( 'apple_news_field_description_output_html', '<br/><i>' . $description . '</i>', $name )
Modifies the HTML output for the description of any field. $name contains the field name.
apply_filters( 'apple_news_initialize_components', self::$components )
Allows you to add custom component classes to the plugin. See the source code for more details on how this is used and for more information on components, please read the Apple News Format Reference.
apply_filters( 'apple_news_register_component', $classname, $shortname )
Allows you to modify a specific component class before it's registered. $classname contains the PHP class name for the component and $shortname contains the internal name used to refer to this component. This would allow you to replace an existing component class with your own custom version.
apply_filters( 'apple_news_postmeta_json_token', $value, $post_id, $meta_key )
Allows for filtering a postmeta value used in Apple News JSON.
apply_filters( 'apple_news_exporter_language', get_bloginfo( 'language' ), $this->content_id() )
Allows the language to be filtered before being sent to Apple. The language is pulled from the WordPress settings. $this->content_id() contains the post ID. Introduced in v1.4.0.
apply_filters( 'apple_news_generate_json', $json, $this->content_id() )
One of the most powerful filters available. This allows you to change any aspect of the final JSON right before it is sent to Apple News. Some sites use this to replace the content with their own custom templates. $json actually contains a PHP array representation of the JSON right before it's encoded for easy editing. $this->content_id() contains the post ID.
apply_filters( 'apple_news_markdown_hyperlink', $node->getAttribute( 'href' ) )
Modifies the URL for a specific hyperlink if for some reason it needed to be reformatted for Apple News, such as to add tracking parameters to track traffic originating from Apple News.
apply_filters( 'apple_news_parse_html', $content, $html )
Allows for filtering of the formatted content before return.
apply_filters( 'apple_news_parse_markdown', $this->parse_nodes( $nodes ), $nodes )
Modifies the nodes that were parsed from the content into markdown format. $this->parse_nodes( $nodes ) contains the resulting array of markdown. $nodes contains an array of the HTML nodes from the body content prior to markdown conversion.
apply_filters( 'apple_news_fonts_list', self::$_fonts )
Modifies the list of fonts available for use in themes. Use this filter to add a custom font that has been loaded into your Apple News channel. The font must be available on your system. TrueType font names must be used (which may differ from the filename of the font itself). Introduced in v1.4.0.
apply_filters( 'apple_news_bundle_source', $source, $filename, $this->content_id )
Modifies the path to a bundled asset. $source contains the full path to the asset. $filename contains only the filename. $this->content_id contains the post ID. This is most commonly used to replace an image asset before publishing to Apple News.
apply_filters( 'apple_news_write_json', $content, $this->content_id )
Similar to apple_news_generate_json, but modifies the JSON before it's written to the workspace. $this->content_id contains the post ID.
apply_filters( 'apple_news_get_json', $json, $this->content_id )
Similar to apple_news_generate_json, but modifies the JSON as it's retrieved from the workspace. $this->content_id contains the post ID.
apply_filters( 'apple_news_get_bundles', get_post_meta( $this->content_id, self::BUNDLE_META_KEY ), $this->content_id )
Modifies the list of bundled assets. This is an array of images that were located in the post and need to be sent to Apple News. $this->content_id contains the post ID.
apply_filters( 'apple_news_get_errors', get_post_meta( $this->content_id, self::ERRORS_META_KEY ), $this->content_id )
Modifies the list of errors encountered during publishing. This would allow you to manipulate this list prior to them being used for validation against your alert settings and before they are displayed as notices in the dashboard.
apply_filters( 'apple_news_advertising_settings', $advertising_settings, $this->content_id() )
Modifies the advertising settings for a post before publishing to Apple News. $advertising_settings contains the default settings specified on the settings page. $this->content_id() contains the current post ID. This is useful for creating custom rules that enable or disable advertisements for individual posts.
apply_filters( 'apple_news_bundle_source', $source, $filename, $this->content_id )
Modifies the path to a bundled asset. $source contains the full path to the asset. $filename contains only the filename. $this->content_id contains the post ID. This is most commonly used to replace an image asset before publishing to Apple News.
apply_filters( 'apple_news_component_layouts', $this->layouts )
Modifies available component layouts. For more information on component layouts, please read the Apple News Format Reference.
apply_filters( 'apple_news_component_styles', $this->styles )
Modifies available component styles. Introduced in v1.4.0.
apply_filters( 'apple_news_characters_per_line_anchored', $cpl, $body_size, $body_orientation, $body_font )
Allows for filtering of the estimated characters per line.
apply_filters( 'apple_news_layout', array(
'columns' => intval( $this->get_setting( 'layout_columns' ) ),
'width' => intval( $this->get_setting( 'layout_width' ) ),
'margin' => intval( $this->get_setting( 'layout_margin' ) ), // Defaults to 100
'gutter' => intval( $this->get_setting( 'layout_gutter' ) ), // Defaults to 20
), $this->content_id() )
Modifies the layout settings from the Apple News formatting options. The second parameter $this->content_id() is the current post ID, allowing you to use this to manipulate these settings for specific posts.
apply_filters( 'apple_news_metadata', $meta, $this->content_id() )
Modifies the metadata for a post. $meta is an array of metadata about the post. For more information on metadata, please read the Apple News Format Reference. $this->content_id() contains the current post ID.
apply_filters( 'apple_news_component_text_styles', $this->styles )
Modifies available component text styles. For more information on component text styles, please read the Apple News Format Reference.
apply_filters( 'apple_news_' . $this->get_component_name() . '_json', $this->json )
This dynamic hook modifies the final JSON output produced by a specific component.
apply_filters( 'apple_news_' . $this->get_component_name() . '_html_enabled', $enabled )
This dynamic hook modifies the html_enabled property of a specific component. Introduced in v1.4.0.
apply_filters( 'apple_news_build_image_src', $matches[1], $text )
Modifies the path to a specific image. $matches[1] contains the image src and $text contains the post content where it was located.
apply_filters( 'apple_news_apply_hanging_punctuation', $modified_text, $text )
Allows for modification of a quote with hanging punctuation enabled.
apply_filters( 'apple_news_build_table_html', $this->parser->parse( $html ) )
Allows for table HTML to be filtered before being applied. Introduced in v1.4.0.
apply_filters( 'apple_news_request_args', array(
'timeout' => 30, // required because we need to package all images
'reject_unsafe_urls' => true,
) )
Modifies the arguments sent to the WordPress HTTP API, which is used to communicate with Apple News. Please only modify these settings if you are certain and read the core documentation on the HTTP API.
apply_filters( 'apple_news_notification_headers', '' )
Add headers (such as From:) to notification messages. Introduced in v1.4.4.
apply_filters( 'apple_news_post_args', wp_parse_args( $args, $this->default_args ), $post_id )
Modifies the arguments sent to the WordPress HTTP API but only for POST requests.
apply_filters( 'apple_news_delete_args', wp_parse_args( $args, $this->default_args ) )
Modifies the arguments sent to the WordPress HTTP API but only for DELETE requests.
apply_filters( 'apple_news_get_args', wp_parse_args( $args, $this->default_args ) )
Modifies the arguments sent to the WordPress HTTP API but only for GET requests.
apply_filters( 'apple_news_api_post_meta', $meta, $post_id )
Adds custom metadata to the request. This is different than the metadata added to a post. For more information on API meta, please read the Apple News API Reference.
For support, please file an issue here on GitHub or visit the WordPress.org support forum.