# Shortcodes for the AUX WordPress theme
A shortcode is registered with the name of each file in this directory. Each is autoloaded and run through registerShortcodes(). See: inc/WP_AUX/Services/ShortcodeService.php

## Why are we auto-registering shortcodes?

Registering shortcodes in functions.php can clutter other code and make it harder to track changes. 

We provided for auto-registering shortcodes to make it easier for anyone to create shortcodes in a compartmentalized and change-trackable way. This architecture works even better with AUX component "partials" to create version-correct AUX components.

Auto-registering shortcodes are a great way to dip your toe in the water of developing in the AUX PHP theme.

## Creating shortcodes in a child theme
Every file in the `shortcodes` folder (and in the `shortcodes` folder of your child theme) represents a different shortcode. The name of the file becomes the name/tag of the shortcode available in Wordpress. No further registration or output handling is required. It's all in the file.

Just "echo" the desired output of your shortcode in the file and you're done.

### How to create a shortcode in a child theme
In your child theme folder:
1. Create a folder with the name "shortcodes".
1. Copy one of the shortcode files from this folder to your child theme's shortcodes folder.
1. Rename the file to match the shortcode name you want to use or leave it the same if you want to override the shortcode in the parent theme.
1. Update your new shortcode file to add your functionality.

### Configuring a shortcode
Use the "[File Header](https://codex.wordpress.org/File_Header)" in the top of the file to configure the shortcode. Supported properties include:
* Name
* Description
* Alias: If a file should handle a shortcode different from the file name, define other shortcodes the file should handle as a comma-separated list.

### Documenting a shortcode
Use the [docblock documentation format](https://docs.phpdoc.org/guide/guides/docblocks.html) to define the variables that are avilable in the shortcode. All shortcodes support "attributes", which are passed as an array. Be sure and document the expected/supported attributes of your shortcode.

Additionally, shortcodes can be written as `[shortcode]Text Content[/shortcode]`, where the inner contents of the shortcode are passed in the "content" variable.

## Example
### Filename: nifty.php
```php
<?php
/**
 * Name: My Nifty Shortcode
 * Description: Nifty child theme feature that renders an AUX Alert
 * Alias: prettynifty
 *
 * @var string $content Text content of the nifty alert feature
 * @var array{
 *   type: string|null,
 *   title: string|null
 * } $attributes
 */

declare(strict_types=1);

use WP_AUX\Entities\AuxFramework\Partials\AlertEntity;

$alert = AlertEntity::create(
  $attributes['type'] ?? 'info',
  $attributes['title'] ?? '',
  $content,
);

echo $alert;
```

### Usage
```
[nifty type="warning" title="Nifty Notice"]This notice sure is nifty.[/nifty]
```
