=== metals-api.com ===  	
Contributors: metals-api
Tags: metals, api, prices, gold, silver, platinum, palladium, commodities, financial
Requires at least: 5.0
Tested up to: 6.8
Stable tag: 2.7
Requires PHP: 7.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html
 
== Description ==

This plugin enables you to display real-time metal prices in multiple currencies. It provides two main shortcodes for displaying live prices and multi-metal tables with automatic refresh capabilities.

== Installation ==

There are two main methods to install this plugin in WordPress.

Installation through the WordPress dashboard:
- Go to the Plugins section in the WordPress admin panel.
- Click on "Add New" and select "Upload Plugin."
- Upload the .zip file of the plugin and click on "Install Now."

Manual installation using WP File Manager:
- Extract the plugin files on your computer.
- Use the WordPress file manager, WP File Manager, to access the /wp-content/plugins/ directory.
- Upload the extracted plugin folder to this directory.

== Configuration ==

Before getting started, it is necessary to activate the plugin from the "Plugins" menu in WordPress. To do this:
- Search for the plugin name in the list of installed plugins.
- Click on the "Activate" option.

Once activated:
- Go to Metals API > Settings in the WordPress admin panel.
- Enter the API key (Metals API Key) in the corresponding field. You can find this key in the Metals API dashboard.

That's it! The plugin has been successfully configured. Now, go to Metals API > Shortcodes in the WordPress admin panel to explore the different commands and combinations available for use with the plugin.

== How to Add Shortcodes ==

There are several ways to incorporate shortcodes into your WordPress site:

1. **In Pages or Posts (Gutenberg Editor):**
   - Create or edit a page/post
   - Add a "Shortcode" block
   - Paste your shortcode directly into the block
   - Example: [metal_live_price symbol="XAU"]

2. **In Pages or Posts (Classic Editor):**
   - Create or edit a page/post
   - Switch to "Text" mode (not Visual)
   - Paste your shortcode directly in the content area
   - Example: [metal_live_price symbol="XAU"]

3. **In Widgets:**
   - Go to Appearance > Widgets
   - Add a "Text" or "Shortcode" widget
   - Paste your shortcode in the widget content area

4. **In Theme Templates (PHP files):**
   - Edit your theme's PHP template files
   - Use: <?php echo do_shortcode('[metal_live_price symbol="XAU"]'); ?>

5. **In Sidebars:**
   - Use the same widget method as described above
   - Shortcodes work in any text widget that supports them

== Available Shortcodes ==

=== 1. Metal Live Price ===

**Purpose:** Display the current price of a single metal with additional information and configurable refresh.

**Basic Usage:**
[metal_live_price symbol="XAU"]

**Full Example:**
[metal_live_price symbol="XAU" base="USD" decimals="2" show-unit="true" show-currency="true" show-updated="true" refresh="AUTO"]

**Expected Output:**
Gold (XAU)
$2,365.44 / oz
Updated: Mar 3, 2025 — 14:20 UTC

**Parameters:**
- symbol (default: "XAU") - Metal code (XAU=Gold, XAG=Silver, XPT=Platinum, XPD=Palladium, etc.)
- base (default: "USD") - Base currency (USD, EUR, GBP, etc.)
- decimals (default: 2) - Number of decimal places
- show-unit (default: "true") - Show unit (per oz). Use "false" to hide.
- show-currency (default: "true") - Show currency symbol. Use "false" to hide.
- show-updated (default: "true") - Show update timestamp. Use "false" to hide.
- refresh (default: "AUTO") - Refresh interval. Use "AUTO" for page load refresh, or a number in minutes (1-1440) for automatic refresh.

**Refresh Options:**
- refresh="AUTO" - Updates when the page is loaded
- refresh="5" - Automatically refreshes every 5 minutes
- refresh="60" - Automatically refreshes every hour
- refresh="1440" - Automatically refreshes every 24 hours (maximum)

**Usage Examples:**
- Simple: [metal_live_price symbol="XAU"]
- With refresh: [metal_live_price symbol="XAG" refresh="10"]
- Custom currency: [metal_live_price symbol="XAU" base="EUR" decimals="3"]

=== 2. Metals Table ===

**Purpose:** Display a table with multiple metals and their prices. Ideal for financial blogs, economic media, brokers, agribusiness, etc.

**Basic Usage:**
[metals_table symbols="XAU,XAG,XPT,XPD"]

**Full Example:**
[metals_table symbols="XAU,XAG,XPT,XPD" base="USD" decimals="2" show-unit="true" show-currency="true" show-updated="true" refresh="AUTO"]

**Expected Output:**
A formatted table showing:
- Metal column with name and code
- Price column with currency symbol
- Unit column (if enabled)
- Update timestamp below table (if enabled)

**Parameters:**
- symbols (default: "XAU,XAG,XPT,XPD") - Comma-separated list of metal codes
- base (default: "USD") - Base currency for all metals
- decimals (default: 2) - Number of decimal places
- show-unit (default: "true") - Show unit column. Use "false" to hide.
- show-currency (default: "true") - Show currency symbol. Use "false" to hide.
- show-updated (default: "false") - Show update timestamp below table. Use "true" to show.
- refresh (default: "AUTO") - Refresh interval. Use "AUTO" for page load refresh, or a number in minutes (1-1440) for automatic refresh.

**Refresh Options:**
- refresh="AUTO" - Updates when the page is loaded
- refresh="15" - Automatically refreshes every 15 minutes
- refresh="30" - Automatically refreshes every 30 minutes
- refresh="1440" - Automatically refreshes every 24 hours (maximum)

**Usage Examples:**
- Precious metals: [metals_table symbols="XAU,XAG,XPT,XPD"]
- Two metals: [metals_table symbols="XAU,XAG"]
- With auto-refresh: [metals_table symbols="XAU,XAG,XPT,XPD" refresh="30"]
- Custom settings: [metals_table symbols="XAU,XAG" base="EUR" decimals="3" show-updated="true"]

=== Available Metal Codes ===

**Precious Metals:**
- XAU - Gold
- XAG - Silver
- XPT - Platinum
- XPD - Palladium

== Step-by-Step Guide: Adding Shortcodes to Your Site ==

**Method 1: Adding to a Page or Post**

1. Log in to your WordPress admin dashboard
2. Navigate to Pages > Add New (or Posts > Add New)
3. Give your page/post a title
4. In the content editor:
   - If using Gutenberg: Click the "+" button, search for "Shortcode" block, add it, and paste your shortcode
   - If using Classic Editor: Switch to "Text" tab and paste your shortcode directly
5. Click "Publish" or "Update"
6. View your page/post to see the shortcode in action

**Method 2: Adding to a Widget/Sidebar**

1. Go to Appearance > Widgets
2. Find the sidebar where you want to add the shortcode
3. Add a "Text" or "Shortcode" widget
4. Paste your shortcode in the widget content area
5. Click "Save"
6. Visit your site to see the widget with the shortcode

**Method 3: Adding to Theme Templates (Advanced)**

1. Go to Appearance > Theme Editor (or use FTP)
2. Select the template file you want to edit (e.g., single.php, page.php)
3. Add the following code where you want the shortcode to appear:
   <?php echo do_shortcode('[metal_live_price symbol="XAU"]'); ?>
4. Save the file
5. Refresh your site to see the changes

**Method 4: Adding to PHP Code**

If you're writing custom PHP code, use:
<?php echo do_shortcode('[metal_live_price symbol="XAU"]'); ?>

== Troubleshooting ==

**Shortcode not displaying:**
- Make sure the plugin is activated
- Verify your API key is configured in Metals API > Settings
- Check that the shortcode syntax is correct (no typos, proper quotes)
- Try viewing the page in a different browser or clear your cache

**Prices not updating:**
- Check your API key is valid and active
- Verify you have an active internet connection
- Check the refresh parameter - "AUTO" only updates on page load
- For automatic refresh, use a numeric value (e.g., refresh="5")

**Table not showing all metals:**
- Verify all metal codes are correct
- Check that metals are separated by commas (no spaces)
- Ensure your API plan supports all requested metals

== Additional Information ==

For detailed documentation, parameter descriptions, and examples, visit:
- Metals API > Shortcodes in your WordPress admin panel

For API information and available metals:
- Visit https://metals-api.com/