=== RSS Control ===
Contributors: emoxie, mattpramschufer, freemius
Tags: rss control, rss, filter rss, google publisher center, google news
Requires at least: 4.0
Tested up to: 6.7.1
Requires PHP: 7.4
Stable tag: 4.0.0

Control your sites RSS feeds with additional query param options.

== Description ==
RSS Control is a powerful WordPress plugin that allows you to control and customize your RSS feeds through URL query parameters. These work on all feed types including the main feed, category feeds, tag feeds, and more.

**Free features** include filtering by category, tag, post type, date range, post IDs, and offset. You can also control excerpts, display featured images with custom styling, and include post titles in descriptions.

**Premium features** add support for custom taxonomy filtering, specialized feed formats (Google Publisher Center, Google News Showcase, NextDoor, Meta Commerce), call-to-action buttons, primary category output control, custom sort ordering, and a visual Feed URL Generator in the admin.

== Example ==
> https://yourdomain.com/feed/?cat=89&days_past=7&show_images=true&image_styles=border:4px; border-color:#000; float:left;

The example above will show posts from category 89 from the past 7 days. It will show featured images with a 4px black border floated to the left.

== Free Options ==

= cat =
Filter by category ID. Can be a single ID or comma-separated list. Prefix with `-` to exclude. See https://developer.wordpress.org/reference/classes/wp_query/#category-parameters

**Example:**
> https://yourdomain.com/feed/?cat=-3,10,22
The use of the NEGATIVE in front of the category ID says DO NOT INCLUDE posts from category 3.

= category_name =
Filter by category slug. Can be a single slug or comma-separated list. See https://developer.wordpress.org/reference/classes/wp_query/#category-parameters

**Example:**
> https://yourdomain.com/feed/?category_name=apples,bananas

= category_not_in =
Exclude posts from specified category IDs. See https://developer.wordpress.org/reference/classes/wp_query/#category-parameters

**Example:**
> https://yourdomain.com/feed/?category_not_in=3,10
Display posts that are not in category ids 3 and 10.

= tag =
Filter by tag ID. Can be a single ID or comma-separated list. Prefix with `-` to exclude. See https://developer.wordpress.org/reference/classes/wp_query/#tag-parameters

**Example:**
> https://yourdomain.com/feed/?tag=-3,10,22
The use of the NEGATIVE in front of the tag ID says DO NOT INCLUDE posts from tag 3.

= tag_not_in =
Exclude posts with specified tag IDs. See https://developer.wordpress.org/reference/classes/wp_query/#tag-parameters

**Example:**
> https://yourdomain.com/feed/?tag_not_in=3,10
Display posts that do not have any of the two tag ids 3 and 10.

= post_in =
Display specific posts by ID in the order specified. See https://developer.wordpress.org/reference/classes/wp_query/#post-page-parameters

**Example:**
> https://yourdomain.com/feed/?post_in=3,10,22
The order in which you add posts is the order in which they will appear in the feed.

= post_type =
Filter by post type. Can be a single post type or comma-separated list. Common types include post, page, attachment, or any custom post type slug. See https://developer.wordpress.org/reference/classes/wp_query/#post-type-parameters

**Example:**
> https://yourdomain.com/feed/?post_type=page
> https://yourdomain.com/feed/?post_type=post,page
Default is "post".

= offset =
Skip a number of posts from the beginning of the feed. See https://developer.wordpress.org/reference/classes/wp_query/#pagination-parameters

**Example:**
> https://yourdomain.com/feed/?offset=3
This will skip the 3 latest posts and start the feed with post 4.

= days_past =
Show posts from the past X number of days only.

**Example:**
> https://yourdomain.com/feed/?days_past=7
This will display the posts from the last 7 days in a feed.

= show_images =
Display the featured image in the content of the RSS feed.

**Example:**
> https://yourdomain.com/feed/?show_images=true
This will display featured image in the content of the RSS feed. The default image size is 696x385.

= image_width =
Set the width for the featured image. Requires `show_images=true`.

**Example:**
> https://yourdomain.com/feed/?show_images=true&image_width=300
This will set the inline style of the image to have width: 300px.

= image_height =
Set the height for the featured image. Requires `show_images=true`.

**Example:**
> https://yourdomain.com/feed/?show_images=true&image_height=300
This will set the inline style of the image to have height: 300px.

= image_size_unit =
Set the image size unit for the featured image (px, em, %, fr, etc). Requires `show_images=true`.

**Example:**
> https://yourdomain.com/feed/?show_images=true&image_width=100&image_size_unit=%
This will set the inline style of the image to have a width of 100%.

= image_styles =
Set additional inline CSS styles on the featured image. These come before the width & height. Requires `show_images=true`.

**Example:**
> https://yourdomain.com/feed/?show_images=true&image_styles=border:4px; border-color:#000; float:left;
This will set the inline style of the image to have a black border of 4px and float the image to the left.

= excerpt_length =
Control the length of the excerpt in number of WORDS.

**Example:**
> https://yourdomain.com/feed/?excerpt_length=20
This will return all feed items with the content of only 20 words.

= excerpt_more_text =
Set the text that appears when content is truncated. Normally it is either [...] or ...

**Example:**
> https://yourdomain.com/feed/?excerpt_length=20&excerpt_more_text=%5B...Read%20More%5D
This will return all feed items with the content of only 20 words ending with [...Read More].

= include_title_in_description =
Include the post title in the feed description/content, wrapped in an HTML tag.

**Example:**
> https://yourdomain.com/feed/?include_title_in_description=true
This will return all feed items with the title present in the description.

= title_tag =
Change the HTML tag that wraps the title. Requires `include_title_in_description=true`. DO NOT include the < or >, just the tag name.

**Example:**
> https://yourdomain.com/feed/?include_title_in_description=true&title_tag=div
This will wrap the title in a div tag instead of the default h1.

= title_styles =
Apply inline CSS styles to the title tag. Requires `include_title_in_description=true`.

**Example:**
> https://yourdomain.com/feed/?include_title_in_description=true&title_tag=div&title_styles=float:left;%20margin-right:30px;%20border:1px%20solid%20red;
This will apply the styles inline to the title tag.

== Premium Options ==

= orderby =
**INCLUDED IN PREMIUM VERSION**

Sort feed posts by a specified field. Common values: title, date, menu_order, ID, author. See https://developer.wordpress.org/reference/classes/wp_query/#order-orderby-parameters

**Example:**
> https://yourdomain.com/feed/?orderby=title
Default is "date" (by publish date).

= order =
**INCLUDED IN PREMIUM VERSION**

Set the sort order to ascending or descending. See https://developer.wordpress.org/reference/classes/wp_query/#order-orderby-parameters

**Example:**
> https://yourdomain.com/feed/?order=ASC
Default is "DESC".

= current_month =
**INCLUDED IN PREMIUM VERSION**

Show only posts from the current month.

**Example:**
> https://yourdomain.com/feed/?current_month=true
This will display only posts from the current month in the feed.

= disable_excerpt =
**INCLUDED IN PREMIUM VERSION**

Remove all content/excerpt from feed items entirely.

**Example:**
> https://yourdomain.com/feed/?disable_excerpt=true
This will remove the excerpt/content from all feed items.

= td_primary_cat =
**INCLUDED IN PREMIUM VERSION**

Filter posts by TagDiv Primary Category. This queries posts where the primary category (set by TagDiv themes/plugins) matches the specified category ID.

**Example:**
> https://yourdomain.com/feed/?td_primary_cat=53
Only works with posts that have the TagDiv primary category meta data set. Accepts a single category ID.

= only_primary_category =
**INCLUDED IN PREMIUM VERSION**

Show only the primary category in the feed's category nodes instead of all categories. Supports TagDiv, Yoast SEO, and RankMath primary category plugins. If no primary category is set, falls back to the first category.

**Example:**
> https://yourdomain.com/feed/?only_primary_category=tagdiv
> https://yourdomain.com/feed/?only_primary_category=yoast
> https://yourdomain.com/feed/?only_primary_category=rankmath
This modifies the category output in the feed, not the post query.

= taxonomy =
**INCLUDED IN PREMIUM VERSION**

Filter by custom taxonomy slug. Must be used with `taxonomy_term` or `taxonomy_term_not_in`. You can NOT use negative IDs in taxonomy filtering.

**Example:**
> https://yourdomain.com/feed/?taxonomy=genres&taxonomy_term=2

For filtering by multiple taxonomies simultaneously, use indexed parameters (1 through 10):

> https://yourdomain.com/feed/?taxonomy_1=position&taxonomy_term_1=3350&taxonomy_2=region&taxonomy_term_2=2702

= taxonomy_term =
**INCLUDED IN PREMIUM VERSION**

Specify term IDs to include. Can be a single ID or comma-separated list. Must be used with the `taxonomy` parameter. For multiple taxonomies, use indexed parameters (taxonomy_term_1, taxonomy_term_2, etc.).

**Example:**
> https://yourdomain.com/feed/?taxonomy=genres&taxonomy_term=2

= taxonomy_term_not_in =
**INCLUDED IN PREMIUM VERSION**

Exclude posts with specified taxonomy terms. Can be a single ID or comma-separated list. Must be used with the `taxonomy` parameter. For multiple taxonomies, use indexed parameters (taxonomy_term_not_in_1, taxonomy_term_not_in_2, etc.).

**Example:**
> https://yourdomain.com/feed/?taxonomy=genres&taxonomy_term=2&taxonomy_term_not_in=1
> https://yourdomain.com/feed/?taxonomy_1=position&taxonomy_term_not_in_1=3350,3347&taxonomy_2=region&taxonomy_term_not_in_2=2702

= image_thumbnail_size =
**INCLUDED IN PREMIUM VERSION**

Use a specific WordPress image size instead of manually setting width and height. Adds the image as a `media:content` element in the feed.

**Example:**
> https://yourdomain.com/feed/?show_images=true&image_thumbnail_size=medium
This will use the medium size image for all featured images. Only valid WordPress thumbnail sizes are supported (thumbnail, medium, large, or custom registered sizes). If the size is not found, the full size image will be used.

= include_button =
**INCLUDED IN PREMIUM VERSION**

Add a call-to-action button below the excerpt that links to the post.

**Example:**
> https://yourdomain.com/feed/?include_button=true
This will output a button that says "Read More".

= button_text =
**INCLUDED IN PREMIUM VERSION**

Change the button text from "Read More" to whatever you would like. Requires `include_button=true`.

**Example:**
> https://yourdomain.com/feed/?include_button=true&button_text=Click%20Me

= button_styles =
**INCLUDED IN PREMIUM VERSION**

Apply inline CSS styles to the button container. Requires `include_button=true`.

**Example:**
> https://yourdomain.com/feed/?include_button=true&button_styles=border-radius:200px;%20background-color:%23e1005f;%20margin-top:20px;
Please note that if you are using colors like #000 then you will need to encode the # symbol as %23.

= button_text_styles =
**INCLUDED IN PREMIUM VERSION**

Apply inline CSS styles to the button text. Requires `include_button=true`.

**Example:**
> https://yourdomain.com/feed/?include_button=true&button_text_styles=font-size:%2018px;
Please note that if you are using colors like #000 then you will need to encode the # symbol as %23.

= type =
**INCLUDED IN PREMIUM VERSION**

Specify a specialized RSS feed format for different platforms. Supported types: gpc, gns, nextdoor, meta-commerce.

**Google Publisher Center (gpc):**
> https://yourdomain.com/feed/?type=gpc
Adds the Media RSS namespace, creates full content in the content:encoded section, and adds featured image as a media:content element.

**Google News Showcase (gns):**
> https://yourdomain.com/feed/?type=gns
Adds the required Google News Showcase namespace and elements.

**NextDoor Newsroom (nextdoor):**
> https://yourdomain.com/feed/?type=nextdoor
Formats the feed for NextDoor News with media elements and featured image support.

**Meta Commerce (meta-commerce):**
> https://yourdomain.com/feed/?type=meta-commerce
Uses Google Shopping feed format for Meta Shopping campaigns. Articles are formatted as "products" with static values (availability="in stock", condition="new"). Use `meta_price` and `meta_currency` to set the price (defaults to "0.00 USD"). Works with all other RSS Control parameters.

= meta_price =
**INCLUDED IN PREMIUM VERSION**

Set the price value for Meta Commerce feed items. Used in the `g:price` element. Must be used with `type=meta-commerce`.

**Example:**
> https://yourdomain.com/feed/?type=meta-commerce&meta_price=9.99
Default is "0.00".

= meta_currency =
**INCLUDED IN PREMIUM VERSION**

Set the currency code for Meta Commerce feed items (e.g. USD, CAD, EUR, GBP). Used in the `g:price` element. Must be used with `type=meta-commerce`.

**Example:**
> https://yourdomain.com/feed/?type=meta-commerce&meta_price=9.99&meta_currency=CAD
Default is "USD".

All feed types can also be accessed via direct URL:
> https://yourdomain.com/feed/gpc/
> https://yourdomain.com/feed/gns/
> https://yourdomain.com/feed/nextdoor/
> https://yourdomain.com/feed/meta-commerce/

== Premium Admin Features ==

The premium version includes the following admin tools, found under **Tools > RSS Control**:

* **Feed URL Generator** - Visual form to build feed URLs by selecting parameters from dropdowns and inputs. Features AJAX-powered search for posts, categories, tags, and post types. Generates a ready-to-use URL with copy and open buttons.
* **Feed Preview** - Live preview of any feed URL showing the title, first 5 items, detected namespaces, media elements, and images.
* **Parameter Documentation** - Filterable reference for all query parameters with examples, grouped by category.

== Frequently Asked Questions ==

= I wish this plugin had XYZ feature =

While I try to do my best to incorporate new features all the time, I just implemented a new Feature Request board located at [https://emoxie.com/contact](https://emoxie.com/contact)

= Do you offer support? =

Yes, I do the absolute best I can to support the free version of the plugin. If you upgrade to the premium version you will have priority support, Google Publisher Center feed, feed URL generator, more feed options and much more.

= Do I need to URL-encode my parameter values? =

Yes, special characters in parameter values should be URL-encoded. For example, # becomes %23, spaces become %20, and [ becomes %5B. We recommend using https://www.urlencoder.org/ to encode style values.

= Can I combine multiple parameters? =

Yes! All parameters can be combined. For example:
> https://yourdomain.com/feed/?cat=5&days_past=30&show_images=true&excerpt_length=50&type=gpc

== Installation ==
Upload plugin through Admin > Plugins > Add New or upload directly to /wp-content/plugins via FTP and activate.

Once activated, you can find the plugin settings under **Tools > RSS Control**.

== Changelog ==

= 4.0.0 =
* FEATURE - Added post_type parameter for filtering by custom post types
* FEATURE - Added indexed taxonomy parameters (taxonomy_1 through taxonomy_10) for multiple simultaneous taxonomy filtering
* PREMIUM FEATURE - Added Meta Commerce feed type for Meta Shopping campaigns
* PREMIUM FEATURE - Added meta_price and meta_currency parameters for Meta Commerce feeds
* PREMIUM FEATURE - Added TagDiv Primary Category Filter (td_primary_cat parameter)
* PREMIUM FEATURE - Added Primary Category Output Control (only_primary_category parameter) with support for TagDiv, Yoast SEO, and RankMath
* BUG FIX - Fixed tag parameter not working with tag IDs (now uses tax_query approach)
* BUG FIX - Fixed category_name parameter causing 404 errors
* BUG FIX - Fixed category_name dropdown to use slugs instead of IDs
* BUG FIX - Fixed empty channel link in custom feed templates (GPC, Nextdoor, Meta Commerce) caused by Yoast SEO filter conflict
* UPDATE - Moved admin interface from Settings menu to Tools menu
* UPDATE - AJAX-powered dropdowns with search capability in feed builder
* UPDATE - Indexed taxonomy filter support
* UPDATE - Major architecture overhaul and code optimization
* UPDATE - Upgraded all composer dependencies
* UPDATE - Improved excerpt_length test reliability

= 3.0.16 =
* PREMIUM FEATURE - Fixed bug where if using post_image_size it would duplicate the images in the content.

= 3.0.15 =
* PREMIUM FEATURE - Added a specific feed for NextDoor News
* PREMIUM FEATURE - Added in new filter rss_control_include_media_namespaces which returns true by default, but if there are other plugins like RankMath that include the media namespaces you can disable this.
* UPDATE - Added additional fallback logic for posts that did not have a featured image.

= 3.0.14 =
* UPDATE - Updated all third-party vendor packages

= 3.0.13 =
* FEATURE - Added in the option to generate a rss feed based on specific posts

= 3.0.12 =
* FEATURE - Added option to pass category slugs into query string in addition to category IDs.
* UPDATE - Updated all third-party libraries.

= 3.0.11 =
* UPDATE - Updated all third-party libraries.

= 3.0.10 =
* UPDATE - Updated all third-party libraries.

= 3.0.9 =
* FEATURE - Added in Google News Showcase support for Premium users.

= 3.0.8 =
* UPDATE - Updated third-party vendor libraries to latest versions.

= 3.0.7 =
* FEATURE - Added ability to filter posts just for current month.
* FEATURE - Added images as media elements

= 3.0.6 =
* UPDATE - Removed the source=news.google.com parameter from GPC feeds as Google now no longer allows this.

= 3.0.5 =
* FEATURE - Added ability to change the order and order by values
* FEATURE - Added the ability to remove the excerpt
* UPDATE - Updated to latest version of vendor packages

= 3.0.4 =
* UPDATE - Google Analytics will not track encoded UTM variables, and without encoding the variables the RSS feeds will be invalid, so we are forced to remove the UTM tracking from feed URL and replace with a single ?source=news.google.com instead.

= 3.0.3 =
* BUG FIX - Updated UTM parameters in feed URLs to not be encoded.  Previously urls with UTM variables were being encoded which didn't allow for them to be picked up properly.

= 3.0.2 =
* BUG FIX - Fixed issue with image_thumbnail_size on edge case setups.

= 3.0.1 =
* BUG FIX - Fixed issue when using tag__not_in and category__not_in.

= 3.0.0 =
* UPDATE - Major Overhaul includes updated how-to section and optimized code.
* FEATURE - Implemented RSS Feed URL Generator for Premium Users
* UPDATE - Updated all vendor libraries to their latest versions

= 2.0.12 =
* UPDATE - Automatically append UTM variables to permalinks when using the GPC feed type.
* UPDATE - Updated third-party vendor libraries.

= 2.0.11 =
* UPDATE - Updated admin help docs to include link to urlencoder.org
* UPDATE - Added a default 10px margin top to email buttons.

= 2.0.10 =
* FEATURE - Added the ability to filter feed by custom taxonomies
* FEATURE - Added the ability to include a button to rss excerpts
* UPDATE - Updated to latest Freemius SDK

= 2.0.9 =
* FEATURE - Added the ability to specify type of feed for Google Publisher Console.
* FEATURE - Added in extra options for GPC feeds, namespaces, media elements, and full content

= 2.0.8 =
* UPDATE - Updated to the latest Freemius SDK

= 2.0.7 =
* UPDATE - Updated to the latest Freemius SDK

= 2.0.6 =
* UPDATE - Updated to the latest Freemius SDK
* BUG FIX - Fixed php warnings messages

= 2.0.5 =
* UPDATE - When displaying title in description include the permalink to link back to post
* BUG FIX - Adjusted priority on filter to account for when excerpt length and title in description are both active.

= 2.0.4 =
* FEATURE - Added in ability to include title in description
* FEATURE - Added in ability to change tag wrapping title
* FEATURE - Added in ability to apply inline styles to title tag
* UPDATE - Updated to latest Freemius SDK

= 2.0.3 =
* FEATURE - Added in ability to set the excerpt length
* FEATURE - Added in ability to set the more text when excerpts get truncated

= 2.0.2 =
* Implemented Freemius

= 2.0.1 =
* Initial WP.org version created and pushed to public

== Upgrade Notice ==
Major update with new feed types, taxonomy filtering, and admin improvements. Please test your existing feed URLs after upgrading.