ianreid / switcher
A flexible and easy-to-use sites switcher for Craft CMS.
Installs: 257
Dependents: 2
Suggesters: 0
Security: 0
Stars: 0
Watchers: 1
Forks: 0
Open Issues: 0
Type:craft-plugin
Requires
- craftcms/cms: ^3.0|^4.0|^5.0
Requires (Dev)
- craftcms/phpstan: dev-main
- craftcms/rector: dev-main
README
Switcher for Craft CMS
Requirements
This plugin requires Craft CMS ^4.x or ^5.x
Installation
To install the plugin, follow these instructions.
-
In your terminal, go to your Craft project:
cd /path/to/project -
Then tell Composer to load the plugin:
composer require ianreid/switcher -w && php craft plugin/install switcher
Overview
The Switcher plugin for Craft CMS provides a Twig function for generating a site switcher on your webpage. This switcher can be configured to display sites from the current group or all groups.
Twig function
The getSwitcherSites() Twig function comes with several parameters.
getSwitcherSites()
Recommended usage
We suggest setting the source on a per-template basis. You can establish a fallback to entry, which allows you to set the variable for elements like categories, products, or an array of custom routes.
1. Define an availableSites variable in your main layout file
{% set availableSites = getSwitcherSites(switcherCustomSource|default(entry ?? null)) %}
In this variable, we use the switcherCustomSource variable as the source, with entry as the fallback, and then null.
You can then pass this variable to your navbar or any file that includes a site/languages switcher to prevent a redundant query.
By defining an availableSites variable at the top of your main layout file, you can also use it for the og:locale:alternate meta in the head, the <link rel=alternate>, etc.
2. Determine your source in your page template
For any craft\base\Element other than Entry (the default in the previous example), you can do the following in your page template :
{% set switcherCustomSource = product %}
or
{% set switcherCustomSource = category %}
or for an array (ex: with custom routes)
{% set switcherCustomSource = [
{'uri':'cart', 'siteId': 1},
{'uri':'panier', 'siteId': 2},
{'uri':'cesta', 'siteId': 3},
]
%}
Output
The function returns an array of items with two keys: "url" and "site". The "url" key is the site's URL, and the "site" key is the site model.
array [
0 => array [
"url" => "http://yoursite.com/uri"
"site" => craft\models\Site {}
]
1 => array [
"url" => "http://yoursite.com/en/uri"
"site" => craft\models\Site {}
]
]
Site Switcher Examples
Basic usage
{% if availableSites|length %}
{% for item in availableSites %}
<a
href="{{ url(item.url) }}"
hreflang="{{item.site.language}}"
lang="{{item.site.language}}"
>
{{ item.site.language }}
</a>
{% endfor %}
{% endif %}
Grouping Sites by Groups
{% if availableSites|length %}
{% set availableSitesByGroup = availableSites|group(lang => lang.site.group) %}
{% for group, langs in availableSitesByGroup %}
<h3 class="text-9 text-blue-500">{{ group }}</h3>
{% for item in langs %}
<a
href="{{ url(item.url) }}"
hreflang="{{item.site.language}}"
lang="{{item.site.language}}"
>
{{ item.site.language }}
</a>
{% endfor %}
{% endfor %}
{% endif %}
Displaying Only the First Two Letters of the Language
{% if availableSites|length %}
{% for item in availableSites %}
<a
href="{{ url(item.url) }}"
hreflang="{{item.site.language}}"
lang="{{item.site.language}}"
>
{{ item.site.language [0:2]|capitalize }}
</a>
{% endfor %}
{% endif %}
Using for og:locale:alternate in <head>
Use your previously created availableSites variable if you wish to apply the same parameters, or create a different variable if not.
💡 You must define your variable PRIOR to the following meta property.
<meta property="og:locale" content="{{ currentSite.language }}">
{% if availableSites|length %}
{% for item in availableSites %}
<meta property="og:locale:alternate" content="{{ item.site.language }}">
{% endfor %}
{% endif %}
💡 All these examples can be adjusted based on the function parameters.
This plugin is brought to you by Ian Reid Langevin