Advanced Filtering (PRO)

This PRO feature extends NewsSync’s basic keyword filtering with two powerful capabilities:

• Regex filtering via the regex_filter shortcode attribute.
• Multi-keyword AND logic via the keywords_and shortcode attribute (all keywords must be present).

These features are disabled by default. Enable them in the PRO settings: Advanced Filtering → Yes.

How it works

• regex_filter accepts a regular expression (without surrounding delimiters). The pattern is tested against the concatenation of an item’s title and description.
• keywords_and accepts a comma-separated list of keywords. The filter keeps only items that contain all listed keywords (case-insensitive).
• When both attributes are provided, items must match both filters (intersection).

Shortcode examples

1) Simple regex example — keep items that mention WordPress or Gutenberg:

[newssync feed_url="https://example.com/feed" regex_filter="(WordPress|Gutenberg)" show_excerpt="yes"]

2) AND-keywords example — keep items containing both plugin and 2026:

[newssync feed_url="https://example.com/feed" keywords_and="plugin,2026" show_excerpt="yes"]

3) Combine multiple feeds with regex and AND keywords:

[newssync feed_url="https://example.com/feed1,https://example.com/feed2" regex_filter="security|vulnerability" keywords_and="update,critical"]

Date Range Filtering (PRO)

PRO adds shortcode attributes for date-based filtering:

• days — show items from the last N days (integer).
• date_from — show items on or after this date (YYYY-MM-DD or any strtotime-compatible date).
• date_to — show items on or before this date (YYYY-MM-DD). When provided, date_to includes the full day (23:59:59).

These filters run before the other advanced filters and are useful to scope feeds to a timeframe.

Examples:

[newssync feed_url="https://example.com/feed" days="7"]

[newssync feed_url="https://example.com/feed" date_from="2026-01-01" date_to="2026-01-31"]

Notes:

• Items are matched using the item’s date_timestamp if present, otherwise the plugin falls back to parsing the item’s date field.
• If the feed item’s date cannot be parsed, the item will be excluded by date filters.
• Combine with regex_filter ou keywords_and to further narrow results.

Content Cleaning (PRO)

PRO provides server-side content cleaning options to reduce unsafe or layout-breaking HTML when importing items. These options are available under PRO → Advanced.

• Strip Scripts & Iframes (default: yes) — removes <script>, <iframe>, <object>, and <embed> tags from imported HTML. Recommended for production sites to avoid executing remote scripts or embedding untrusted frames.
• Strip Inline Styles (default: no) — removes style="..." attributes from elements to avoid layout surprises caused by incoming CSS.
• Excerpt Source — choose how the post excerpt is derived: Default (description field) ou Use first paragraph (uses the first <p>...</p> of the cleaned content as the excerpt).

Examples:

[newssync feed_url="https://example.com/feed" days="7"]

Notes:

• Stripping may remove expected embeds or styling; test on staging first. If a feed contains required embeds, consider whitelisting or disabling stripping for that site.
• Excerpt extraction uses the cleaned HTML — if the first paragraph contains no text after cleaning, the excerpt will fall back to the description field.

Why it’s important

• Security: prevents execution of malicious JavaScript (XSS) and the inclusion of frames that can load untrusted content.
• Privacy & performance: stops external pages from being loaded automatically, reducing third-party requests and tracking.
• Visual stability: prevents inline CSS or embedded content from breaking your site’s layout or introducing unexpected styles.
• Content consistency: produces predictable, clean excerpts for listings, sharing and SEO.

Trade-offs / Precautions

• This cleaning may remove legitimate embeds (videos, widgets) or styles that are necessary for a feed item’s appearance. Test on a staging site before enabling in production.
• If a feed requires embeds, disable content cleaning for that feed or handle specific cases with whitelisting or custom filtering.

PHP example (developer testing)

You can simulate the shortcode filters in PHP using the newssync/items_before_render filter:

$items = /* array of items as returned by the provider */;
$atts = array( 'regex_filter' => '(WordPress|Gutenberg)' );
$filtered = apply_filters( 'newssync/items_before_render', $items, $atts, 'grid' );

Note: newssync_pro_advanced_filtering must be enabled in PRO settings for the filter to run.

Security & performance considerations

• Regexes can be expensive. Limit pattern length and complexity; use simple alternation where possible.
• Avoid untrusted user input in regex_filter unless you validate/sanitize patterns server-side.
• Enable per-request caps and use pagination/lazy-loading on large feeds to avoid timeouts.

Translation

This document is authored in English. For localized documentation, create a localized Markdown file inside the plugin doc/ folder using the naming pattern newssync-pro-advanced-filtering-LOCALE.md (for example newssync-pro-advanced-filtering-pt_PT.md). The plugin will prefer gettext strings if available and fall back to localized Markdown when present.

---

📚 Regex for Beginners

If you’re new to regular expressions (regex), this section will help you understand the basics!

What is Regex?

Regular Expression (Regex) = A pattern-matching language for text.

Think of it like “Find” in your text editor, but with superpowers! 🦸‍♂️

Basic Patterns

Pattern	Matches	Example
WordPress	Exact word “WordPress”	✅ “WordPress 6.0”
`word1\	word2`	Either “word1” OR “word2”	✅ “word1” ✅ “word2”
.	Any single character	a.c matches “abc”, “a2c”, “a c”
.*	Zero or more of any character	start.*end matches “start middle end”
[abc]	Any single character from set	[aeiou] matches any vowel
[0-9]	Any digit 0-9	20[0-9][0-9] matches 2000-2099
^	Start of text	^WordPress only matches at beginning
$	End of text	WordPress$ only matches at end

Common Use Cases

1. Match Multiple Keywords (OR)

Goal: Show articles about WordPress OR Gutenberg OR Block editor

Regex:

(WordPress|Gutenberg|Block editor)

Explanation:

• (...) = Group
• | = OR operator
• Matches if any of the three words appear

---

2. Filter by Year

Goal: Only show articles from 2025 or 2026

Regex:

202[56]

Explanation:

• 202 = Literal “202”
• [56] = Either 5 or 6
• Matches “2025” or “2026”

---

3. Find Email Addresses

Goal: Filter items that contain email addresses

Regex:

[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}

Explanation:

• [a-zA-Z0-9._%+-]+ = Username part (letters, numbers, symbols)
• @ = Literal “@”
• [a-zA-Z0-9.-]+ = Domain name
• \. = Literal “.” (escaped because . has special meaning)
• [a-zA-Z]{2,} = TLD (2+ letters: com, org, etc.)

---

4. Exclude Certain Words (NOT)

Goal: Show tech articles but EXCLUDE anything about Apple or iPhone

Regex:

^(?!.*(Apple|iPhone)).*tech.*

Explanation:

• ^ = Start of text
• (?!.*(Apple|iPhone)) = Negative lookahead (must NOT contain these words)
• .*tech.* = Must contain “tech”

⚠️ Advanced: Negative lookaheads are complex. For simple exclusion, use keyword filters instead.

---

5. Match Specific Domains/URLs

Goal: Only show items from techcrunch.com or theverge.com

Regex:

(techcrunch\.com|theverge\.com)

Explanation:

• \. = Escaped dot (literal “.”)
• | = OR operator

---

Special Characters (Need Escaping)

If you want to match these literally, add \ before them:

Character	Escape	Example
.	\.	example\.com (matches “example.com”)
?	\?	What\? (matches “What?”)
+	\+	C\+\+ (matches “C++”)
*	\*	5\*5 (matches “5*5”)
( )	\( \)	\(2026\) (matches “(2026)”)
[ ]	\[ \]	\[PRO\] (matches “[PRO]”)
$	\$	\$100 (matches “$100”)

---

Testing Your Regex (BEFORE Using in Plugin)

Use online tester: regex101.com

Steps:

1. Go to regex101.com
2. Paste your regex in “Regular Expression” field
3. Select “PCRE (PHP)” flavor (top-right)
4. Paste test text (article titles/descriptions) in “Test String” field
5. See matches highlighted in real-time ✅

Example test:

• Regex: (WordPress|Gutenberg)
• Test text: “WordPress 6.0 released with Gutenberg improvements”
• Result: Both “WordPress” and “Gutenberg” highlighted ✅

---

Common Mistakes (and Fixes)

Mistake 1: Forgetting to Escape Special Characters

❌ Wrong: example.com (matches “exampleXcom” too!) ✅ Right: example\.com (only matches dots)

---

Mistake 2: Using Surrounding Delimiters

❌ Wrong: /WordPress/i (plugin doesn’t use slashes) ✅ Right: WordPress (no delimiters needed)

---

Mistake 3: Case Sensitivity

❌ Wrong: wordpress (won’t match “WordPress”) ✅ Right: (W|w)ordpress ou [Ww]ordpress

Note: NewsSync regex is case-insensitive by default (both match). But good to know!

---

Mistake 4: Matching Too Much

❌ Wrong: .* (matches everything!) ✅ Right: Be specific: .*WordPress.* (must contain “WordPress”)

---

Practical Examples for NewsSync

Example 1: Tech News (Broad)

Goal: Articles about technology, software, coding

Regex:

(software|technology|coding|programming|developer|tech)

Use in shortcode:

[newssync feed_url="https://news.com/rss" regex_filter="(software|technology|coding|programming|developer|tech)"]

---

Example 2: Security Vulnerabilities Only

Goal: Only critical security updates

Regex:

(vulnerability|security.*update|CVE-|critical.*patch)

Explanation:

• security.*update = “security” followed by anything, then “update” (matches “security update” or “security system update”)

Use in shortcode:

[newssync feed_url="https://security.com/rss" regex_filter="(vulnerability|security.*update|CVE-|critical.*patch)"]

---

Example 3: Exclude Sponsored Content

Goal: Remove articles tagged as sponsored/ads

Regex (negative):

^(?!.*(sponsored|advertisement|promoted)).*

Alternative (simpler): Use keywords_and with positive keywords instead:

[newssync feed_url="..." keywords_and="news,article" regex_filter="^(?!.*(sponsored)).*"]

---

Example 4: Date-Specific (2025-2026 Only)

Regex:

202[56]

Better alternative: Use date filters (more reliable):

[newssync feed_url="..." date_from="2025-01-01" date_to="2026-12-31"]

---

Advanced: Combine Regex + Keywords_and

Goal: Articles about WordPress plugins, but ONLY from 2026

Shortcode:

[newssync
    feed_url="https://example.com/feed"
    regex_filter="(WordPress|plugin)"
    keywords_and="2026"
]

How it works:

1. Regex filters: Must contain “WordPress” OR “plugin”
2. Keywords_and: Must also contain “2026”
3. Result: Only items matching BOTH conditions

---

Learning Resources

Free tutorials:

• 📖 RegexOne — Interactive lessons (beginner-friendly)
• 📖 Regular-Expressions.info — Comprehensive guide
• 🎮 Regex Crossword — Fun puzzles to learn

Cheat sheets:

• regex101.com/library — Pre-made patterns
• Debuggex Cheat Sheet — Visual reference

---

Need Help?

Got a specific filtering need? Ask in support with:

1. ✅ What you want to match (examples)
2. ✅ What you want to exclude (examples)
3. ✅ Feed URL (or test data)

We can help craft the regex for you! 🚀

---