omz13 / kirby3-honehome
kirby3 plugin to handle homepage redirection
Installs: 60
Dependents: 0
Suggesters: 0
Security: 0
Stars: 6
Watchers: 2
Forks: 1
Open Issues: 1
Type:kirby-plugin
Requires
- php: >=7.1
- getkirby/composer-installer: ^1.1
Requires (Dev)
- getkirby/cms: ^3.0.1
- jakub-onderka/php-parallel-lint: ^1.0
- localheinz/composer-normalize: ^0.8.0
- omz13/omz13-coding-standard: dev-master
- phpmd/phpmd: ^2.6
- phpstan/phpstan: ^0.11
- phpstan/phpstan-strict-rules: ^0.11
- squizlabs/php_codesniffer: ^3.4
README
Coffee, Beer, etc.
This plugin was developed because I had an itch that needed scratching. I wanted a multi-language site to switch to the best-matching language indicated by a client's Accept-Language
instead of the default one set in the site. The code was nastier to do than I thought, it had some evil edge cases, and after being refactored became something quite elegant. That the format for languages in HTML and HTTP are subtly different was just what I needed make developing this more difficult than it should be (and if you look at the code, that is why there are tortuous substitutions between hyphens and underscores all over the place). The utf8
suffix was similarly a thing to work around.
A bit of trivia. When I started to work on this plugin, it was called HomeHome (because it made the home page twice as nice). And then one day I did a typo and called it HoneHome. But "hone" is a nice work because the plugin really "hones" the homepage. So it became HoneHome.
This plugin is free but if you use it in a commercial project to show your support you are welcome to:
Documentation
Purpose
For a kirby3 site, this plugin omz13/honehome does magical things to a site's homepage.
When would you use this plugin?
- You are running a multi-language site and you want:
- the homepage (default or replaced) to automagically switch to the language set by a browser's
Accept-Language
header (instead of defaulting to the site's default language). This is seriously cool. - pages to have the correct
lang
attribute (because it contains a helper function to do that what has to be done).
- the homepage (default or replaced) to automagically switch to the language set by a browser's
- You want to replace the homepage with a different page (e.g. for a blog-based site you would set this to the parent page for the blog posts).
The functional specification:
- In a multi-language installation, the homepage returns the localized homepage based on the best-match against a client's
Accept-Langauge
request. - Provides a page method (
honehomeLang
) to set the HTMLlang
attribute (which for multi-language installations is a very good thing to do). - A site's homepage can be set to a page specified from either a configuration file (
site/content/content.php
) or a panel content field (content/site.txt
viasite/blueprints/site.yml
).
Roadmap
The non-binding list of planned features and implementation notes are:
- MVP
- debug headers only in debug mode
- stan to level 7
Installation
Pick one of the following per your epistemological model:
composer require omz13/kirby3-honehome
; the plugin will automagically appear insite/plugins
.- Download a zip of the latest release - master.zip - and copy the contents to your
site/plugins/kirby3-honehome
. git submodule add https://github.com/omz13/kirby3-honehome.git site/plugins/kirby3-honehome
.
Configuration
The following mechanisms can be used to modify the plugin's behavior and your kirby site.
site/snippets/header.php
If you are running kirby as a multi-language system, for the multi-language to work nicely, you needed pages to indicate what language they are in. This plugin contains a page method - honehomeLang( string $default = 'en' ) : string
- to return the locale in the correct format for use as an <html>
elements lang
attribute.
TL;DR: change your site/snippets/header.php
so the opening <html>
sets the lang
attribute:
<html lang="<?= $page->honehomeLang('en') ?>">
via site/config/config.php
-
omz13.honehome.disable
- optional - defaultfalse
- a boolean which, iftrue
, disables the plugin (except for thehonehomeLang
page method. -
omz13.honehome.homelanding
- optional - a string which is the name of the page to be used for the homepage. This setting takes priority over that specified in c.f.homelanding
content field.
Content fields in content/site.txt
(via blueprint site/blueprints/site.yml
)
The plugin uses the following content fields. These are all optional; if missing or empty, they are assumed to be not applicable vis-à-via their indicated functionality.
homelanding
- text - optional - the name of the page to be used when the homepage is to be replaced by a different landing page. This is subservient to c.f.omz13.honehome.homelanding
inconfig.php
.
Blueprints
Here is a sample snippet that you could use in site/blueprints/site.yml
so you could change the homepage to any visible children in the root. Clearly you would want to be more flexible, by perhaps filtering on a template, but it gives an idea.
fields: homelanding: label: en: Home Override de: Überschreiben Sie die Homepage mit fr: Ignorer la page d'accueil avec nl: Negeer Homepage met sv: Åsidosätt hemsida med type: select options: query query: site.children.visible width: 1/3
Use
-
Install and Configure as above.
-
Use a web browser or whatever to access the home page.
-
If it works, see Coffee, Beer, etc above.
-
If it doesn't work... file an issue.
Debug mode
If the kirby site is in debug mode:
- Page requests to the homepage will have a header
X-omz13-hh-...
that contains debugging information. Yes, it outputs a lot of debugging information, but it does help locate where my code is a pile of stinking bits.
Disclaimer
This plugin is provided "as is" with no guarantee. Use it at your own risk and always test it yourself before using it in a production environment. If you find any issues, please create a new issue.