kirby-library/index.php

<?php
/**
 * Copyright 2026, Dreytac <dreytac@hobbyhome.net>
 * 
 * This file is part of Kirby Library.
 *
 * Kirby Library is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License version 3 as published by the Free Software Foundation.
 *
 * Kirby Library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
 *
 * You should have received a copy of the GNU Affero General Public License along with Kirby Library. If not, see <https://www.gnu.org/licenses/>. 
 */

Kirby::plugin(
	name: "hobbyhome/library",
	extends: [
		"options" => [
			"assets" => [
				"css" => [
					# 100 => Url::path(kirby()->url("media") . "/plugins/hobbyhome/library/css/example.css", true),
				],
			],
		],
		"blueprints" => [
			"fields/link-locations" => __DIR__ . "/blueprints/fields/link-locations.yml",
			"fields/link-location" => __DIR__ . "/blueprints/fields/link-location.yml",
		],
		"snippets" => [
			"navbar/primary" => __DIR__ . "/snippets/navbar/primary.php",
		],
		"hooks" => [
			/**
			 * To add this hook to a plugin, change the option() call to use the plugins name.
			 * 
			 * @version 1.0
			 */
			"hobbyhome.getAssets" => function ($files = [], $type = "css") {
				foreach (option("hobbyhome.library.assets.{$type}", []) as $order => $file) {
					# Make sure no other file exists with the current sort order index.
					while (isset($files[$order])) {
						$order++;
					}

					$files[$order] = $file;
				}

				return $files;
			},
			/**
			 * To add this hook to a plugin, replace the foreach filter with any other method to generate the $newLinks[] array.
			 * 
			 * @version 1.0
			 * 
			 * Links in the array should have a minimum of the following options set:
			 * $newLinks[] => [
			 * 		"index"  => The sort index of the link,
			 * 		"url"    => The URL of the link,
			 * 		"text"   => The text of the link,
			 * 		"aria"   => Accessible version of the link text,
			 * 		"active" => True if this is the active link,
			 * ];
			 * 
			 * Optional supported options are:
			 * $newLinks[] = [
			 * 		"icon" 	 => An optional Font Awesome icon,
			 * 		"disabled" => True if this link should have the 'disabled' HTML attribute,
			 * 		"target"   => The value of the HTML link target attribute,
			 * 		"dropdown" => [
			 * 			[
			 * 				"divider" => True to display a divider in the dropdown menu,
			 * 			],
			 * 			[
			 * 				A link, as defined above, that should be displayed in the dropdown menu.
			 * 				These links will need to be sorted in the template. Index in this case
			 * 				doesn't have any purpose unless you process it in the template.
			 * 			],
			 * 		],
			 * ];
			 */
			"hobbyhome.getLinkList" => function ($links = [], $linkLocation = "primary") {
				$newLinks = [];

				# ---------------------------------------------------------------------------------
				# Replace this section with any method of generating the $newLinks[] array.
				# ---------------------------------------------------------------------------------
				$pages = site()->index(true)->filterBy("linkLocation", $linkLocation);

				foreach ($pages as $page) {
					if ($page->isDraft() && !($user = kirby()->user() and $user->role()->isAdmin())) {
						continue;
					}

					$newLinks[] = [
						"index" => $page->linkIndex()->toInt(),
						"url" => $page->url(),
						"icon" => ($page->linkIcon()->isNotEmpty()) ? kirbytag("fa", $page->linkIcon()) : "",
						"text" => ($page->linkText()->isNotEmpty()) ? $page->linkText() : $page->title(),
						"aria" => ($page->linkText()->isNotEmpty()) ? $page->linkText() : $page->title(),
						"active" => $page->isActive(),
					];
				}
				# ---------------------------------------------------------------------------------

				foreach ($newLinks as $link) {
					$index = $link["index"];

					# Make sure no other link exists with the current sort order index.
					while (isset($links[$index])) {
						$index++;
					}

					$links[$index] = $link;
				}

				return $links;
			},
		],
		"siteMethods" => [
			/**
			 * Fetch and sort a list of asset filenames.
			 * 
			 * @param string $type The type of asset filenames to fetch.
			 * 
			 * @return Array of asset filenames, sorted by index.
			 */
			"getAssets" => function ($type = "css") {
				$hookFiles = kirby()->apply("hobbyhome.getAssets", ["files" => [], "type" => $type], "files");
				$files = [];

				foreach ($hookFiles as $order => $file) {
					# If file exists, add MD5 query string to attempt to cache bust it.
					$md5 = F::exists(kirby()->root() . $file) ? md5_file(kirby()->root() . $file) : "";
					$files[$order] = url($file, ["query" => ["md5" => $md5]]);
				}

				ksort($files, SORT_NUMERIC);

				return $files;
			},
			/**
			 * Fetch and sort a list of links.
			 * 
			 * @param string $linkLocation The identifier key for the list of links.
			 * 
			 * @return Array of links, sorted by index.
			 */
			"getLinkList" => function ($linkLocation = "primary") {
				$links = kirby()->apply("hobbyhome.getLinkList", ["links" => [], "linkLocation" => $linkLocation], "links");
				ksort($links, SORT_NUMERIC);

				return $links;
			},
		],
	],
	info: [
		"authors" => [[
			"name" => "Dreytac",
			"email" => "dreytac@hobbyhome.net",
			"homepage" => "https://hobbyhome.net",
		]],
		"license" => "AGPL-3.0-only",
		"version" => "0.0.0",
	],
);