=== Vizou Quickloop ===
Requires at least: 6.0
Tested up to: 6.8
Stable tag: 1.0.8
Requires PHP: 8.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html
A shortcode for adding posts to a page with customizable display options and class-specific templates.

== Description ==

The Vizou Quickloop plugin allows adding posts to any post or page via a shortcode with multiple parameters. Web devs can edit the layout directly using template files in their theme directory. Control which post elements display using exclude/include parameters. Create multiple custom layouts using class-specific templates for precise control over different display scenarios.

NEW in v1.0.8: Enhanced class-specific template support! Use different templates for different layouts by creating files like `vizou-quickloop-template-gallery.php` or `vizou-quickloop-template-featured.php` in your theme. Multiple classes are now supported - the first class determines the template, additional classes can be used for CSS styling.

== Installation ==

Upload the plugin files to the /wp-content/plugins/plugin-name directory, or upload through the WordPress plugins screen directly
Activate the plugin through the 'Plugins' screen in WordPress

== FAQ ==

Visit https://explicable.ca for more detailed documentation.

Use shortcode [vizou-quickloop] with post query parameters as in these examples:

**Basic Usage:**

Get 2 posts from category 2 and order them ascending by menu order
[vizou-quickloop cat="2" posts_per_page="2" orderby="menu_order" order="asc"]

Get a single post
[vizou-quickloop p="35"]

Get 5 posts from category 2 and skip the first one
[vizou-quickloop cat="2" posts_per_page="5" offset="1"]

Add a custom class to the container and its posts
[vizou-quickloop cat="9" posts_per_page="1" class="featured"]

**Display Control:**

Hide specific post elements (excerpt and date)
[vizou-quickloop cat="1" posts_per_page="-1" exclude="excerpt,date"]

Show only title and thumbnail
[vizou-quickloop cat="2" include="title,thumbnail"]

Hide read more link and date
[vizou-quickloop cat="3" exclude="permalink,date"]

**Class-Specific Templates:**

Use different templates for different layouts
[vizou-quickloop cat="5" class="gallery"]
This will use `vizou-quickloop-template-gallery.php` if it exists in your theme

Create a featured posts section with custom layout
[vizou-quickloop cat="1" posts_per_page="3" class="featured-hero"]
This will use `vizou-quickloop-template-featured-hero.php`

Use multiple classes - first for template, others for CSS styling
[vizou-quickloop cat="2" class="listing past featured"]
This will use `vizou-quickloop-template-listing.php` and apply all classes to the container

Sidebar list with compact layout
[vizou-quickloop cat="2" class="sidebar-list"]
This will use `vizou-quickloop-template-sidebar-list.php`

**Available Elements:**
- `title` - Post title with link
- `excerpt` - Post excerpt text
- `thumbnail` - Featured image with link
- `date` - Publication date
- `permalink` - Read more link

**Parameters:**

Query Parameters:
- `cat` - Category ID
- `p` - Specific post ID
- `tag` - Tag slug
- `posts_per_page` - Number of posts (-1 for all)
- `orderby` - Sort field (menu_order, date, title, etc.)
- `order` - Sort direction (asc, desc)
- `offset` - Skip first X posts
- `class` - Custom CSS class + template selector (supports multiple classes)

Display Parameters:
- `exclude` - Comma-separated list of elements to hide
- `include` - Comma-separated list of elements to show (exclusive)

Note: `exclude` takes precedence over `include`. If neither is specified, all elements display.

**Template Override:**

The plugin supports a template hierarchy for maximum flexibility:

1. **Class-specific templates** (highest priority): `vizou-quickloop-template-{first-class}.php`
2. **General template** (fallback): `vizou-quickloop-template.php`
3. **Built-in template** (default): Plugin's internal template

**Creating Templates:**

**General Template:**
Override the default layout by copying and pasting from START to END LAYOUT (located in the plugin main file) into a document called "vizou-quickloop-template.php" in your theme root. Upload that to your theme.

**Class-Specific Templates:**
Create templates named `vizou-quickloop-template-{class}.php` where {class} is your first class name (lowercase, hyphens only). Examples:
- `vizou-quickloop-template-gallery.php` for `class="gallery"` or `class="gallery grid"`
- `vizou-quickloop-template-featured-hero.php` for `class="featured-hero"` or `class="featured-hero large"`
- `vizou-quickloop-template-listing.php` for `class="listing"` or `class="listing past featured"`

**Multiple Class Support:**
When using multiple classes like `class="gallery grid responsive"`:
- The first class (`gallery`) determines which template to use
- All classes are applied to the HTML container for CSS styling
- This allows for template variations using additional CSS classes

**Template Variables:**
All custom templates have access to these variables:
- `$vizou_loop` - The WP_Query object
- `$atts` - Array of shortcode attributes  
- `$display_options` - Array of display flags for conditional element display

**Using Display Options in Templates:**
```php
<?php if ($display_options['title']) : ?>
    <h3><?php the_title(); ?></h3>
<?php endif; ?>

<?php if ($display_options['thumbnail']) : ?>
    <?php the_post_thumbnail('large'); ?>
<?php endif; ?>

<?php if ($display_options['date']) : ?>
    <time><?php the_date(); ?></time>
<?php endif; ?>

<?php if ($display_options['excerpt']) : ?>
    <?php the_excerpt(); ?>
<?php endif; ?>

<?php if ($display_options['permalink']) : ?>
    <a href="<?php the_permalink(); ?>">Read more</a>
<?php endif; ?>
```

**Class Name Sanitization:**
Class names are automatically sanitized for template filenames:
- `Featured Posts` becomes `featured-posts`
- `Gallery_Grid` becomes `gallery-grid`
- `News Sidebar` becomes `news-sidebar`

**Use Cases for Class-Specific Templates:**
- **Gallery layouts**: Grid of thumbnails only
- **Featured posts**: Large hero sections with big images
- **Sidebar widgets**: Compact lists with minimal styling
- **News feeds**: Custom styling for different content types
- **Portfolio displays**: Specialized layouts for showcasing work
- **Product listings**: E-commerce style layouts
- **Team listings**: Custom layouts for staff/team member displays

== Changelog ==

= 1.0.8 =
* Enhanced class-specific template support with multiple class handling
* First class now determines template, additional classes used for CSS styling
* Improved `vizou_get_template_path()` function to extract first class properly
* Updated admin interface with better multiple class examples
* Enhanced documentation for multiple class usage scenarios
* Backward compatible with existing single class implementations

= 1.0.7 =
* Added class-specific template support
* New template hierarchy: class-specific → general → built-in
* Enhanced admin interface with Class Templates tab
* Improved template loading with `vizou_get_template_path()` function
* Added class name sanitization for secure filename generation
* Updated documentation with class template examples
* Backward compatible with existing general templates

= 1.0.6 =
* Added display control with exclude/include parameters
* New display elements: title, excerpt, thumbnail, date, permalink
* Enhanced admin interface with tabbed documentation
* Added copy-to-clipboard functionality for shortcode examples
* Improved template override documentation
* Better parameter validation and sanitization

= 1.0.5 =
* Initial release with basic shortcode functionality
* Template override support
* Query parameter support
* Performance optimizations