Appearance
Widgets
Recent posts, categories, archives, menu, search, tag cloud, image and pages widgets, also as shortcodes.
kitloom/widgets · admins: kitloom/widgets-filament, kitloom/widgets-nova
WordPress's standard widgets on the site: the recent posts, recent comments, calendar, categories, archives, menu, search, tag cloud, image, pages and meta widgets a site moved from WordPress has in its sidebars are drawn again, with the markup WordPress gave them — so the theme's old widget CSS still applies — and each one is a shortcode too, for putting the same thing into a page.
The forms for these widgets on the admin's widgets page come with kitloom/widgets-filament or kitloom/widgets-nova. Without this module such widgets are left off the site and shown read-only in the admin.
Widget zones
A zone — WordPress's sidebar — is not declared in the theme: it is added on the Widgets page itself, on the Zones tab, with an id and a name, and is there to fill the moment it is saved. The theme draws it by id (widgets.in('promo'), or [sidebar id="promo"] in any text), so a new column of widgets is an admin change, not a code change — where WordPress needs register_sidebar() in the theme. A theme may still declare the zones it needs, and a site moved from WordPress shows the zones its layout already holds. The whole story is on Menus & Widgets.
The widgets
Each widget keeps its settings where WordPress keeps them (the option widget_{type}, under its number) and under WordPress's names, so a widget set up in WordPress keeps working as it was. The title is the widget's own: the sidebar draws it above the widget, the shortcode has none. Left empty, it is WordPress's for the type, in the visitor's language: "Recent Posts", "Categories", "Archives", "Pages", "Recent Comments", "Meta", and for a tag cloud "Tags" or the taxonomy's name; Navigation Menu, Search, Image and Calendar have none.
| Widget | What it shows | Settings |
|---|---|---|
Recent Posts (recent-posts) | the newest published posts, each linked, optionally with its date in the site's date format | number — how many (5); show_date — with dates |
Categories (categories) | the categories that have posts, by name; a menu that opens the chosen one with dropdown | count — the number of posts after each; hierarchical — subcategories under their parents (a parent without posts of its own stays when its children have some); dropdown |
Archives (archives) | the months that have published posts, newest first, each linked to its month | count; dropdown |
Navigation Menu (nav_menu) | one of the site's menus with its submenus; the item of the page being shown is marked current-menu-item, the items above it current-menu-ancestor (the one right above also current-menu-parent), a link to the home page menu-item-home | nav_menu — the menu |
Search (search) | the search form; what was searched for stays in the field | — |
Tag Cloud (tag_cloud) | the 45 most used terms of a taxonomy, by name, the busier ones larger (8 to 22 points) | taxonomy — tags by default, or any taxonomy with archives; count — the number of posts after each |
Image (media_image) | an image from the media library in one of its sizes, with a caption under it | attachment_id — the image; size (medium); alt — empty: the image's own alternative text; caption; link_type — none, file (the image itself), post (the attachment's page; the image itself when the site has no attachment pages), custom (link_url); link_target_blank — a new tab |
Pages (pages) | the published pages as a tree; the page being shown is marked current_page_item, its parent current_page_parent, the pages above it current_page_ancestor — and on any other page (a post, an archive) the posts page is current_page_parent, as in WordPress | sortby — menu_order (page order, then title), post_title or ID; exclude — page IDs, separated by commas; the pages under them are left out too |
Calendar (calendar) | the month as a table: days with published posts link to that day's archive, today is marked, and links under it lead to the nearest earlier and later months with posts. A month or day archive shows its month, any other page the current month in the site's time zone. The week starts on the day set in the site's settings ("Week Starts On"); month and day names follow the site's language. Left out while the site has no published posts | — |
Recent Comments (recent-comments) | the newest approved comments: who wrote it (linked to their site when they gave one) and on which post, linked to the comment; comments on a post with a password are not shown | number — how many (5) |
Meta (meta) | for a visitor, "Log in" — the site's login page; for a signed-in user, "Site Admin" and a "Log out" button | — |
A widget with nothing to show — no posts, a menu that is gone, no tags in use, no image — is left off the page, title and all, as in WordPress.
Meta leaves out what WordPress also lists there: the "Register" link (the registration page is the theme's, when it has one), the links to the entries and comments feeds (the site has no feeds) and the link to WordPress.org. "Site Admin" leads to the installed admin — the Filament panel or Nova — or where kitloom-widgets.meta.admin_url says. "Log out" is a small form, not a link: signing out of the site is a POST /logout, which a link cannot send.
RSS is not here: the site leaves it out, and the admin shows it read-only.
Blocks
Since WordPress 5.8 the widgets screen saves blocks, and some blocks — the latest posts, the archives, the search form — are saved only as a note that says "draw this here" (<!-- wp:latest-posts {"postsToShow":3} /-->). WordPress draws them when the page is shown; this module draws eight of them the same way, wherever they are: in a sidebar, in a post or page, in a reusable pattern. Their markup and classes are WordPress's, so the theme's block styles apply.
| Block | Drawn with | What it ignores |
|---|---|---|
| Latest Posts | how many, the order (newest, oldest, A→Z, Z→A), categories, author, list or grid with its columns, the featured image (its size, alignment, largest width and height, linked to the post or not), the author's name, the date, the excerpt (with its length and a "Read more" link) or the full text | — |
| Archives | by month or by year, the number of posts, as a list or a menu, the label shown or hidden | weekly and daily archives (shown by month) |
| Categories | as a list or a menu, nested, with the number of posts, empty ones, only the top level, the label | other taxonomies than categories |
| Search | the label (shown or hidden), the placeholder, the button's text or icon, the button beside the field, inside it or none, what the field remembers | the field's width; a button that opens the field (shown as a button beside it); bold or italics in the label |
| Tag Cloud | the taxonomy, how many terms, the smallest and largest size, the number of posts | — |
| Page List | all published pages as a tree, or only those under one page; the home page, the page being shown and the pages above it are marked | — |
| Calendar | the Calendar widget's table; a month and year chosen in the editor fix the month shown | the block's colours; not drawn while the site has no published posts |
| Latest Comments | how many, the date, an excerpt of each comment or its full text, or neither (older blocks' "excerpt" switch too) | avatars — they would ask Gravatar, another service, for each commenter |
Colours, fonts and spacing set on a block in the editor are not applied — the alignment, the extra CSS class and the HTML anchor are. Without posts the Latest Posts block is an empty list, the Archives block says "No archives to show.", the Categories block "No categories", the Latest Comments block "No comments to show."; a Tag Cloud without tags and a Page List without pages are left out — all as in WordPress. Other dynamic blocks (the RSS feed, the navigation, the site editor's template blocks) are not drawn: they are left out of the page.
Shortcodes
The shortcode is the widget's type with _ for -, and its attributes are the widget's settings:
| Shortcode | Example |
|---|---|
[recent_posts] | [recent_posts number="3" show_date="1"] |
[categories] | [categories count="1" hierarchical="1"], [categories dropdown="1"] |
[archives] | [archives count="1"], [archives dropdown="1"] |
[nav_menu] | [nav_menu nav_menu="main"] — the menu's slug, or its ID |
[search] | [search] |
[tag_cloud] | [tag_cloud taxonomy="post_tag" count="1"] |
[media_image] | [media_image attachment_id="12" size="large" link_type="file" caption="The reading room"], [media_image url="https://…/photo.jpg" width="300" height="200"] |
[pages] | [pages sortby="post_title" exclude="2,7"] |
[recent_comments] | [recent_comments number="3"] |
[calendar] | [calendar] |
[meta] | [meta] |
Flags take 1, true, yes or on. The tags are plain on purpose, the names a site's content is likely to use; another module or the theme that registers the same tag later replaces ours, and kitloom-widgets.shortcodes.register set to false leaves them all unregistered (the widgets stay).
For developers
- A type is a
Kitloom\Site\Contracts\WidgetTypetaggedWidgetTypes::TAGand aShortcodeHandlerat once (src/Types);defaultTitle($widget)answers the empty title through__(), with its line inlang/fr.json;Type::settings($data)writes a form's values in the types WordPress writes (numberan integer,show_datea boolean,count/hierarchical/dropdownas 1 or 0,nav_menuandattachment_idintegers) — both admins' forms call it. - A theme or module draws a type its own way by declaring a
WidgetTypewith the same base: of two, the one declared later wins. - Eight types are also a
Kitloom\Site\Contracts\BlockType(core/latest-posts,core/latest-comments,core/calendar,core/archives,core/categories,core/search,core/tag-cloud,core/page-list): they are taggedBlockTypes::TAGtoo, and the site'sBlockRendererfinds them by block name. ABlockTypetagged later with the same block name replaces ours. Block attributes are read withSupport\BlockAttributes, block.json's defaults when one is missing. Kitloom\Widgets\WidgetOptionsholds the choices the forms offer (menus, taxonomies, image sizes).
AI agents
With kitloom/ai installed, an agent whose user has edit_theme_options reads Appearance → Widgets (widgets_list: every zone with its widgets in order, the inactive widgets, and each type with the settings it takes) and sets a zone's widgets as a whole list (widgets_save): a widget kept by its id changes only in the settings it sends, a new one is given by type and settings, and one named from another zone or from the inactive widgets moves into this zone. Settings are written as the admins' forms write them. A widget left out of the list goes to the inactive widgets with its settings, as in WordPress when one is dragged there — nothing an agent does deletes a widget. A widget of a type the module does not know (a theme's, a WordPress plugin's) is kept where it is but not edited. Naming a zone the site does not have, with a label, adds it. kitloom-widgets.ai.register false — no widget tools.
Configuration
config/kitloom-widgets.php (php artisan vendor:publish --tag=kitloom-widgets-config): shortcodes.register, meta.admin_url (KITLOOM_WIDGETS_ADMIN_URL) — where Meta's "Site Admin" leads, a path or a full address; empty, the installed admin's own — filament.register / nova.register — the forms in each admin — and ai.register, the tools for AI agents.
Tests
From the application that installs the package: php vendor/bin/phpunit --testsuite Widgets.