# Picture Tag

**Version:** 1.4.2 
**Author:** Artilab

## Description

The Picture Tag plugin provides a way to render images in multiple formats (WebP, AVIF, JPEG) using the <picture> HTML element, enabling modern browsers to choose the most efficient format. The plugin allows users to define custom paths for WebP and AVIF images via the WordPress admin settings.
To convert images to WebP or AVIF formats, you will need to use third-party plugins. This plugin has been tested with the following:
WebP Express and AVIF, WebP Converter.

## Installation

1. Upload the plugin folder to the `/wp-content/plugins/` directory or install the plugin through the WordPress plugins screen directly.
2. Activate the plugin through the 'Plugins' screen in WordPress.
3. Navigate to `Settings > Picture Tag` to configure the custom paths for WebP and AVIF images.

## Settings

You can configure paths for WebP and AVIF images in the WordPress admin under:

- **Settings > Picture Tag**

The following default paths are set:
- **WebP Path:** `/../webp-express/webp-images/doc-root/wp-content/uploads`
- **AVIF Path:** `/../compressx-nextgen/uploads`

These paths can be customized based on your server configuration or folder structure.

## Usage

### Functions

The plugin provides several functions that can be used to output images in the `<picture>` tag format with support for WebP, AVIF, and JPEG:

### `arti_the_image( $image_id, $sizes = ['1x' => 'large', '2x' => 'full'], $attr = [] )`

**Description:**  
Outputs the `<picture>` HTML tag for an image with support for responsive image sizes and modern formats.

**Parameters:**
- `$image_id` *(int)*: The ID of the image attachment.
- `$sizes` *(array)*: An array mapping size labels (e.g., '1x', '2x') to WordPress image sizes (e.g., 'thumbnail', 'large', 'full').
- `$attr` *(array)*: Optional. An array of additional HTML attributes for the `<img>` tag (e.g., 'alt', 'title').

**Example:**
```php
arti_the_image( 123, ['1x' => 'medium', '2x' => 'large'], ['alt' => 'Sample Image'] );
```

### `arti_get_image_by_id( $image_id, $sizes = ['1x' => 'large', '2x' => 'full'], $attr = [] )`

**Description:**
Returns the <picture> HTML tag for an image as a string, allowing you to output it or store it for later use.

**Parameters:**

Same as arti_the_image().
**Example:**

```php
$image_html = arti_get_image_by_id( 123, ['1x' => 'medium', '2x' => 'large'], ['alt' => 'Sample Image'] );
echo $image_html;
```

### Shortcodes

The plugin provides a shortcode for generating <picture> tags directly in posts, pages, or widgets.

[arti_picture]

**Description:**
Use this shortcode to render a <picture> tag for images in your WordPress content.

**Attributes:**
1. id (required):
The ID of the image attachment in the WordPress Media Library.
2. size_1x (optional):
Specifies the WordPress image size for 1x resolution. Defaults to large.
3. size_2x (optional):
Specifies the WordPress image size for 2x resolution. Defaults to full.
4. alt (optional):
Alternative text for the image (for accessibility and SEO).
5. title (optional):
The title attribute for the image.
6. class (optional):
Additional CSS classes for the <img> tag.
7. loading (optional):
Specifies lazy loading behavior. Defaults to lazy.
Options: lazy, eager.
8. fetchpriority (optional):
Specifies the priority for resource fetching. Common values: high, low.
9. data-* (optional):
Supports custom data attributes for the `<img>` tag, allowing developers to pass additional metadata.

**Examples:**
*Basic Example:*
```code
[arti_picture id="123"]
```
This generates a <picture> tag with the image ID 123 and the default sizes (large for 1x and full for 2x).

*With Custom Sizes:*
[arti_picture id="123" size_1x="medium" size_2x="large"]
This specifies custom sizes for 1x and 2x resolutions.

*With Additional Attributes:*
[arti_picture id="123" size_1x="medium" size_2x="large" alt="Sample Image" title="Custom Title" class="custom-class" loading="eager"]
This adds custom alt, title, class, and loading attributes to the <img> tag.

## Filters
`arti_image_size`
Allows you to modify the image sizes array before it is used in the <picture> tag.

**Example:**

```php
add_filter( 'arti_image_size', function( $sizes, $image_id ) {
    return ['1x' => 'medium', '2x' => 'full'];
}, 10, 2 );
```

`arti_image_attr`
Allows you to modify the image attributes array before they are rendered.

**Example:**

```php
add_filter( 'arti_image_attr', function( $attr, $image_id ) {
    $attr['loading'] = 'lazy'; // Add lazy loading attribute
    return $attr;
}, 10, 2 );
```

`arti_image_html`
Allows you to modify the generated image HTML before it is returned.

**Example:**

```php
add_filter( 'arti_image_html', function( $html, $image_id, $sizes, $attr ) {
    return '<div class="custom-wrapper">' . $html . '</div>';
}, 10, 4 );
```

Custom Paths for WebP and AVIF Images
The plugin allows you to define custom paths for WebP and AVIF formats in the settings page. By default, the plugin assumes that the WebP and AVIF versions of your images are stored in directories relative to the WordPress uploads folder.

## The custom paths are configurable in:

Settings > Picture Tag > WebP Path
Settings > Picture Tag > AVIF Path
These paths will be used to locate the corresponding WebP and AVIF versions of your images. If the image does not exist in WebP or AVIF format, the plugin falls back to the default JPEG image.

## File Existence Check
The plugin checks whether the WebP and AVIF versions of an image exist before adding them to the <picture> tag. This ensures that only valid and available image sources are included.

## Example Template Usage
To use the arti_the_image() function in your theme template files:

```php
// Display the picture tag for an image with ID 123
arti_the_image( 123, ['1x' => 'medium', '2x' => 'large'], ['alt' => 'A beautiful image', 'class' => 'responsive-img'] );
```

This will output a responsive <picture> tag with WebP and AVIF support, where the original image is the fallback.