Hello everyone ,

We've been super busy over here at October CMS, designing and coding up the highly anticipated eCommerce features. These are new tools to provide a stable and robust foundation for managing your online business operations and commerce web applications. Today, we are proud to introduce the next step in this direction: The Currency plugin (v2) for October CMS! Let's take a look at what's included in this release.

What's New in Currency Plugin v2?

• Default Currency Feature: For those who are not using multisite, the Currency plugin preserves the default currency feature. This allows for straightforward currency display, making it easier to manage prices in a single currency without any extra configuration.

• Multisite Support with Primary and Display Currencies: If you're using multisite, the Currency plugin v2 offers even more flexibility. You can set a primary currency for setting pricing and a display currency for showing prices to your customers, with the potential for currency conversion. This ensures that your prices are always clear and accurate, no matter where your customers are located.

• Improved Currency Conversion: A major enhancement in this version is the ability to manage foreign exchange rates manually. We had trouble finding a reliable currency exchange service that didn't cost high monthly fees, so we added the ability to manage the rates yourself. You can integrate with third-party providers to automate the retrieval of the latest currency conversion rates, and we've included drivers from Fixer and fastFOREX out of the box.

Ready to Get Started?

To help you make the most of the new Currency plugin, we've prepared a quick tutorial to help you get started. It walks you through the basic functionality and showcases the powerful features this plugin offers. Follow along to see how you can start using it today!

Install the Currency Plugin

Let's take a look at the new currency plugin. It has no dependencies on other plugins so it should be a straight forward process to get up and running.

First install the plugin by following these steps:

1. Navigate to Settings → System Updates
2. Click Install Packages
3. Search for the Currency plugin by Responsiv Software (Responsiv.Currency)
4. Click the Install button

Alternatively, you can install the plugin using the following command in the console.

php artisan plugin:install responsiv.currency

Set Up the Active Currencies

Now that we have the plugin installed, navigate to Settings → Currencies to view some of the currencies that are configured by default. Here it is possible to add, remove and modify the available currencies used in the system.

Let's disable the Australian Dollar and the Pound Sterling by selecting each one in the list and unchecking the Enabled checkbox. Now we have two active currencies to work with, including a default currency.

• USD - U.S. Dollar (Default)
• EUR - Euro

Create a Simple Product

Now let's create a Product blueprint using Tailor.

1. Open the Editor
2. Select New Blueprint → Entry in the Tailor section
3. Name the file shop/product.yaml
4. Click Save to save the file

Inside the file place the following contents and click Save & Migrate.

handle: Shop\Product
type: entry
name: Product
drafts: false
multisite: false

fields:
    price:
        label: Price
        type: currency

A new Content menu item should appear in the main menu.

1. Click on the menu item named Content → Product
2. Click New Product to create a product
3. Enter a title for the product, for example, Running Shoes
4. Assign it a price of 150
5. Click the Save & Close button.

This will store the price in the default currency that we've set up (USD).

Create a Page to Display the Product

Next let's create a CMS page to display the product on the frontend website.

1. Navigate to the Editor
2. Click Create → CMS Page in the CMS section
3. Enter a title for the page, for example, View Product
4. Assign it a URL of /product/:slug
5. Click the Components button to display the list of available components
6. Select the Tailor → Section component to add it to the page
7. Open the section component
8. Select the Shop\Product blueprint for the handle field
9. Set the Lookup Column to Slug and check the Default View checkbox

Add the following content to the Markup field and click Save to save the page.

<h1>{{ section.title }}</h1>

<p>Price: {{ section.price|currency }}</p>

Next, navigate back to the product entry we created in the previous step via Content → Product. Open the product and click the Preview button to see our CMS page.

Set Up a Multisite Environment

The Multisite implementation provided by October CMS is a powerful tool for implementing context for your website, such as locations or languages. The Currency Plugin adds two additional fields to your Site Definitions, allowing you to specify a Base Currency and Display Currency. These are useful when storing and reading currency values, including any currency conversions.

To demonstrate this, let's create two site definitions for our currencies.

1. Navigate to Settings → Site Definitions
2. Select the Primary site and rename it to America
3. Click Save & Close, then Create Site
4. Enter the name Italy for the new site
5. Switch the Enabled switch to enable the site
6. Set the Display Currency as Euro
7. Select the Configuration tab and check the Use a CMS route prefix checkbox
8. Enter /it for the route prefix
9. Click Save & Close to create the new site

Now we have two sites that we can use for managing our products.

Scenario 1: Automatic Currency Conversion with Multisite

Let's assume we have customers in two different regions of the world, and they prefer to see prices in their local currency. In summary, here is how this system should work:

• Store the price values in USD for both sites
• Display prices in USD for America
• Display prices in Euro for Italy (using currency conversion)

First, we'll need to set up currency conversion. Before proceeding, we've searched Google for the latest exchange rate (USD to EUR) and it shows a rate of 0.91 as of today.

1. Navigate to Settings → Exchange Rates
2. Click the Generate Pairs button
3. Click Confirm to generate the currency pairs
4. Click on the newly created USD:EUR pair
5. Click on Create Rate Data to manually enter the rate data
6. Enter 0.91 for the Rate Value and click Create
7. Click Save & Close on the Rate form

We have successfully configured the exchange rate between the US Dollar and the Euro.

Next, navigate to Editor and edit the View Product page we created in earlier steps. Now let's configure the page to use the site definition for currency conversion.

Update the markup to the pass { site: true } to the |currency Twig filter. This will instruct the filter to display the price using the site parameters. In this case, we've set up our site to have the Italy site to display the currency in Euros.

Here is what the markup should look like, and afterwards, click Save.

<h1>{{ section.title }}</h1>

<p>Price: {{ section.price|currency({ site: true }) }}</p>

Next, navigate to Content → Product, open the product and click the Preview button to see our CMS page for the America site. The price should be displayed in USD.

Return to the admin panel, switch the site to Italy and click the Preview button. The price should be displayed in Euros, converted from the USD value.

We have successfully implemented currency conversion in the Currency plugin.

Scenario 2: Storing Multiple Currencies with Multisite

Let's assume we have two offices in different parts of the world, and our staff members prefer to enter the currency values in their own currency. In summary, here is how this system should work:

• Store the price values in USD for America
• Store the price values in Euro for Italy
• Display prices in the stored currency (without currency conversion)

To start, the Italy site should be set to both store and display the currency in Euros. To store the currency values in Euros.

1. Navigate to Settings → Site Definitions
2. Select the Italy site
3. Set the Base Currency as Euro
4. Set the Display Currency as Euro
5. Click Save & Close to update the site

Now let's enable multisite in the Product blueprint using Tailor, this will allow each site to have its own product attributes. Navigate to Editor and edit the shop/product.yaml blueprint we created in earlier steps. Inside the file update the multisite property to true and click Save & Migrate.

multisite: true

Next, navigate to Content → Product and open the product to inspect it. When selecting a different site and you should be prompted to duplicate the record.

When the America site is selected, the Price input should be in USD. With the Italy site selected, the Price input should be in EUR. The price can now be adjusted manually for each selected site. Previewing the record for each site will show the stored price accordingly. Since the stored currency is the same as the displayed currency, the currency conversion step is not required.

Now, we have successfully stored multisite currency values using the Currency plugin. Thanks for following along!

More Documentation

This Currency plugin has some articles included in the official October CMS documentation.

You can find more documentation on the Currency plugin product page and you are welcome to inspect the source code on GitHub.

What's Next?

Stay tuned for the upcoming release of the Pay plugin, the next key component in your eCommerce tool belt. The Pay plugin enables you to manage invoices and accept payments seamlessly, adding another layer of professionalism and performance to your October CMS-powered site. Also in the pipeline, we're preparing the release of a new and improved dashboard.

We hope you enjoy the new features and look forward to seeing how they enhance your developer experience. As always, your feedback is invaluable to us, so please don't hesitate to share your thoughts. Until next time, happy coding!