=== Tag Display ===  
Contributors: s7ntech    
Tags: tags, display, shortcode, customization, tag cloud  
Requires at least: 5.0  
Tested up to: 6.8 
Requires PHP: 7.2  
Stable tag: 2.2.0
License: GPLv2 or later  
License URI: https://www.gnu.org/licenses/gpl-2.0.html  

Tag Display is a WordPress plugin to display post tags with multiple templates, custom colors, and full control over output.

== Description ==  

Tag Display lets you show WordPress tags anywhere on your site - choose from five ready-made templates or build your own from the theme folder.

1. **Default** - Tag buttons with hover effects.
2. **Minimal** - Comma-separated text links, no extra markup.
3. **Tag Cloud** - Font sizes proportional to post count.
4. **Outlined** - Transparent background with colored border, pill-style.
5. **Hashtag** - Tags prefixed with `#`, social-style.

**Features:**
- Five tag templates: buttons, inline text, tag cloud, outlined pills, hashtag.
- Native Gutenberg block with sidebar controls (no shortcode needed).
- Shortcode support: `[s7n_tag_display]` or `[s7n_tag_display template="minimal"]`.
- Admin settings page with live template preview and color picker.
- Automatic or manual tag display (before or after content).
- Tag ordering: alphabetical, by post count, or random.
- Limit the number of tags shown and exclude specific tags by slug.
- Post count next to each tag (e.g. *WordPress (12)*) - opt-in per instance or globally.
- Support for custom taxonomies alongside WordPress tags.
- SEO options: rel="nofollow" and target="_blank" for tag links.
- Theme template override: place a custom template file in your theme folder to take over the output.
- **Smart Visibility**: automatically hide, collapse, or SEO-hide tags when the count falls below a configurable threshold - improving both SEO and UX.
- **Content Density Analysis**: trigger Smart Visibility based on the ratio of tags to words in the post, not just tag count.
- **Per-instance FORCE bypass**: disable Smart Visibility for a single shortcode or block without touching global settings.

== Installation ==

1. Upload the `tag-display` folder to the `/wp-content/plugins/` directory.
2. Activate the plugin through the 'Plugins' menu in WordPress.
3. Go to **Tag Display** in the main WordPress menu to configure templates, colors, tag ordering, and auto-display options.
4. Display tags in one of three ways:
   * **Shortcode** - add `[s7n_tag_display]` to any post or page.
   * **Gutenberg block** - search for "Tag Display" in the block inserter.
   * **Automatic** - enable auto-display in **Tag Display → Content Types** to add tags to every post automatically.

== Frequently Asked Questions ==

= How do I use the plugin? =
Activate the plugin, then go to **Tag Display** in the main WordPress menu to pick a template and configure colors. From there, add tags to your posts in one of three ways:

1. **Shortcode** - paste `[s7n_tag_display]` into any post or page.
2. **Gutenberg block** - search for "Tag Display" in the block inserter.
3. **Automatic** - enable auto-display in **Tag Display → Content Types** and tags appear on every post without touching the editor.

= Can I change the template style? =
Yes. Choose between Default, Minimal, Cloud, Outlined, and Hashtag templates:

* From the settings page: **Tag Display → General Settings → Default Template**.
* Via shortcode: `[s7n_tag_display template="outlined"]`
* Via Gutenberg block: select the block and use the **Template** option in the sidebar.

= How do I use the Gutenberg block? =
In the block editor, click the **+** button and search for "Tag Display". Add the block to your post. Use the sidebar panel (**Display Settings**, **Link Options**, **Title**) to override the template, ordering, tag limit, and other options for that specific block - independently of the global settings.

= What shortcode attributes are available? =
All attributes are optional and override the global settings for that specific instance:

`[s7n_tag_display template="hashtag" order="count_desc" max="8" exclude="news,draft" nofollow="true" new_tab="true" show_count="true" title="Related topics:"]`

* `template` - `default`, `minimal`, `cloud`, `outlined`, `hashtag`
* `order` - `alpha_asc`, `alpha_desc`, `count_desc`, `count_asc`, `random` (default: global setting)
* `max` - maximum number of tags to show, e.g. `max="5"` (0 = all)
* `exclude` - comma-separated slugs to hide, e.g. `exclude="news,uncategorized"`
* `nofollow` - `true` to add `rel="nofollow"` to tag links
* `new_tab` - `true` to open links in a new tab
* `show_count` - `true` to show the post count next to each tag, e.g. *WordPress (12)*
* `title` - custom label above the tags, e.g. `title="Topics:"` (empty string hides the title)

= How do I limit or sort the tags? =
Open **Tag Display → General Settings**:

* **Tag Order** - alphabetical (A→Z / Z→A), by post count (most/least used), or random.
* **Max Tags** - show only the first N tags (0 = show all).
* **Exclude Tags** - comma-separated slugs of tags to always hide.

These settings can also be overridden per-instance via shortcode or Gutenberg block.

= How do I hide specific tags? =
In **Tag Display → General Settings → Exclude Tags**, enter the slugs (not names) of the tags you want to hide, separated by commas. Example: `news, uncategorized, draft`.

To find a tag's slug, go to **Posts → Tags** in the WordPress admin.

= Can I display tags automatically without a shortcode? =
Yes. Go to **Tag Display → Content Types**, enable auto-display for posts, pages, or custom post types, and choose whether tags appear **before** or **after** the content.

= How do I add rel="nofollow" or open links in a new tab? =
Go to **Tag Display → General Settings** and enable the **rel="nofollow"** or **Open in new tab** checkboxes. These can also be set per-instance via shortcode (`nofollow="true"`, `new_tab="true"`) or Gutenberg block sidebar.

= Can I create a fully custom template from my theme? =
Yes. Place a file named `tag-display-template-{name}.php` in your theme (or child theme) root folder, where `{name}` is the template you want to override: `default`, `minimal`, `cloud`, `outlined`, or `hashtag`.

Example: to override the default template, create `wp-content/themes/your-theme/tag-display-template-default.php`.

The plugin picks it up on the next page load. A commented example file is included in the plugin's `examples/` folder.

The following variables are available in your custom template:

* `$tags` - array of WP_Term objects (`->name`, `->slug`, `->count`)
* `$display_title` - label text above the tags
* `$display_nofollow` - boolean, whether to add `rel="nofollow"`
* `$display_new_tab` - boolean, whether to open links in a new tab
* `$display_show_count` - boolean, whether to show post count next to each tag

= What is Smart Visibility and how do I use it? =
Smart Visibility automatically adapts tag display based on how many tags a post has - improving both SEO and user experience. When the count falls below a configurable threshold, the plugin applies the behavior you choose:

* **Hide** - suppresses the tag block entirely (no HTML output). Best for SEO: avoids thin tag sections.
* **Hidden** - renders tags with `display:none` so they are present in the DOM but invisible. Useful when you want to toggle them via JavaScript without a page reload.
* **Collapse** - renders a "Show tags" button; the visitor can expand the list on click. Best for UX on posts with few tags.
* **SEO hidden** - tags are visually invisible to visitors but present in the DOM for search crawlers.

To enable it, go to **Tag Display → Smart Visibility**, turn on the toggle, set your **Minimum Tag Threshold** (default: 3), and pick a behavior. When a post has at least as many tags as the threshold, it displays normally - Smart Visibility is completely transparent.

**Content Density Analysis (advanced):** you can also trigger Smart Visibility based on tag density - the ratio of tags to words in the post. Enable "Content Density Analysis" in the Smart Visibility tab and set a density threshold (default: 0.005, which equals 1 tag per 200 words). If the density is below the threshold, the selected behavior applies even if the tag count meets the minimum.

**Per-instance override via shortcode:**

`[s7n_tag_display smart="true" min="3" behavior="collapse"]`

* `smart` - `true` to enable, `false` to force-disable for this instance regardless of the global setting
* `min` - minimum tag threshold for this instance
* `behavior` - `hide`, `hidden`, `collapse`, or `seo`; use `force` to bypass Smart Visibility entirely for this instance

= Is it compatible with the latest WordPress version? =
Tested up to WordPress 6.8. If you run into a compatibility issue, open a thread on the support forum.

== Screenshots ==

1. General Settings
2. Content Types
3. Appearance
4. Smart Visibility
5. Click Tracking - statistics tab with top tags and period filter
6. Template Preview
7. Help

== Changelog ==

= 2.2.0 =
* Added native click tracking: tag clicks are recorded in a dedicated database table (no external services).
* New "Click Tracking" admin tab with enable/disable toggle, statistics table (top 10 tags), period filter (7/30 days / all time), and reset button.
* Click data is automatically cleaned up after 90 days via WP Cron (scheduled on activation).
* All tag templates emit `data-track-tag` and `data-track-post` attributes when tracking is enabled.
* Uninstall routine drops the tracking table and removes all plugin options.
* Updated Italian translations for all new strings.

= 2.1.0 =
* Added Mode field in Smart Visibility admin: Auto, Density, UX, Disabled - replaces the Enable toggle when set.
* Added behavior `replace`: when tags are below threshold, a related posts list is shown instead (WP_Query cascade: shared tags → shared categories, up to 5 results, transient-cached 1h).
* New template `tag-display-related-posts.php` with configurable title via admin field.
* Transient cache automatically invalidated when post terms change (`set_object_terms` hook).
* Admin: new "Related Topics Title" field; behavior dropdown includes "Replace".
* Added CSS for `.s7n-related-posts` (neutral, theme-inheriting, responsive).
* Updated Italian translations for all new strings.

= 2.0.0 =
* Added content density analysis: Smart Visibility can now trigger based on tag density (tags per word) in addition to tag count.
* New behavior: "Hidden" - renders tags with `display:none` (DOM present, togglable via JavaScript) without a full PHP re-render.
* Added FORCE bypass: `[s7n_tag_display smart="false"]` or `behavior="force"` disables Smart Visibility for a single instance.
* Admin: new "Content Density Analysis" field in Smart Visibility tab with density threshold setting (default: 0.005).
* Updated translations: new strings for density and hidden behavior in `.pot` and `it_IT.po/.mo`.

= 1.9.0 =
* Added Smart Visibility: automatically hide, collapse, or SEO-hide tags when the post has fewer tags than a configurable threshold.
* Three behaviors: Hide (no output), Collapse (expandable with a button), SEO Hidden (invisible to visitors, present for crawlers).
* New admin tab: Tag Display → Smart Visibility with enable toggle, threshold setting, and behavior selector.
* Shortcode support: smart, min, and behavior attributes for per-instance override.
* Added Italian translations for all new strings.

= 1.8.1 =
* Fixed extra space before comma separator in Minimal template (frontend and admin preview).

= 1.8.0 =
* Moved settings menu to top-level WordPress admin navigation for easier access.
* Added automatic redirect to the settings page after plugin activation.

= 1.7.0 =
* Added internationalization (i18n) support: plugin strings are now translatable.
* Added Italian translation (it_IT).
* Added Text Domain header to plugin file.
* Fixed two admin strings missing translation wrappers.

= 1.6.0 =
* Modernized admin UI: new card-based layout, updated tab navigation, section wrappers, improved color picker area.
* Updated Template Preview tab: 5 cards with header/badge/body structure, fixed nesting bug (Outlined and Hashtag cards were incorrectly nested inside Tag Cloud).
* Updated Help tab: 5-template documentation, Gutenberg block guide, full shortcode attribute reference, theme override instructions.
* Updated WordPress.org screenshots to reflect current admin UI with all 5 templates.
* Updated version in package.json and block.json to match plugin version.

= 1.5.0 =
* Added theme template override: place `tag-display-template-{name}.php` in your theme folder to fully customize the output.
* Added `examples/tag-display-template-custom.php` with a fully commented template starter.
* Override is applied automatically for both shortcode and Gutenberg block rendering.

= 1.4.0 =
* Added native Gutenberg block (dynamic block, server-side rendered) with InspectorControls for all display options.
* Added Outlined template: transparent background with colored border pill-style buttons.
* Added Hashtag template: social-style tags prefixed with # (Instagram/Twitter look).
* Admin: improved admin preview cards for Outlined and Hashtag templates with live color updates.
* Admin: template select now switches to Template Preview tab and highlights the matching card in real-time.

= 1.3.0 =
* Added tag ordering options: alphabetical (A→Z / Z→A), by post count (most/least used), and random.
* Added maximum tags limit: show only the first N tags (admin setting + shortcode attribute).
* Added tag exclusion: comma-separated list of slugs to exclude from display.
* Added auto-display position: choose to insert tags before or after the post content.
* Added rel="nofollow" option for tag links (SEO).
* Added target="_blank" option to open tag links in a new tab.
* Added post count display option: show number of posts next to each tag (e.g. WordPress (12)).
* Extended shortcode with new attributes: order, max, exclude, nofollow, new_tab, show_count, title.
* Admin: added Reset to Defaults button for color settings.
* Admin: active tab is now remembered across page loads (localStorage).
* Admin: added unsaved-changes sticky notice when form fields are modified.
* Admin: changing the Default Template now switches to the Template Preview tab and highlights the matching card.

= 1.2.1 =
* Fixed tag cloud template: font sizes now scale proportionally to actual tag post counts instead of random values.
* Fixed accessibility: added :focus-visible outlines to all template links for keyboard navigation.
* Fixed accessibility: tag title changed from non-semantic div to p element with ARIA heading role.
* Added :active state on Default and Cloud template links.
* Added :visited state on Default and Minimal template links.
* Added prefers-reduced-motion support to disable CSS transitions for users who prefer it.
* Added reset for box-shadow, border-bottom and background-image that themes may add to links.
* Added tablet responsive breakpoint at 768px.
* Fixed admin preview links using href="#" (prevented scroll jump on click).
* Fixed admin color picker: hover style now updates a single persistent style tag instead of creating new ones on every change.

= 1.2.0 =  
* Added support for custom taxonomies.  
* Terms from selected custom taxonomies are now displayed alongside WordPress tags.  
* Updated templates to use get_term_link() for better compatibility with custom taxonomies.  
* Added new admin setting to select which custom taxonomies to include.  

= 1.0.0 =  
* Initial release.  
* Added three customizable templates.  
* Integrated shortcode support.  
* Created admin settings page.  

== License ==  

This plugin is licensed under the GPLv2 or later.