Ryan Wang
7fab0c6039
Add a new .agents/skills/halo-theme-dev skill providing Halo theme development resources: two theme templates (theme-vite and theme-minimal) with theme.yaml/settings, Vite config, package.json, CSS and JS assets, and a full set of Thymeleaf template files/partials. Include comprehensive reference docs (structure & config, finder APIs, global variables, annotations, static resources, packaging, official plugins, thymeleaf tips) and an agents/openai.yaml interface. Also update project files: modify package.json, update tsconfig.json, add skills-lock.json, rename vite-env.d.ts and remove obsolete src/main.ts and src/styles/main.css while populating src/ with the new template files.
54 lines
2.9 KiB
Markdown
54 lines
2.9 KiB
Markdown
# Finder API
|
|
|
|
Finder APIs query data from **any template location** regardless of the current route — ideal for sidebars, footers, and other global data needs.
|
|
|
|
## Available Finders
|
|
|
|
| Finder | Purpose |
|
|
| ------ | ------- |
|
|
| `postFinder` | Post list / detail / prev-next / archives |
|
|
| `categoryFinder` | Category list / tree structure / breadcrumbs |
|
|
| `tagFinder` | Tag list / detail |
|
|
| `menuFinder` | Menus and menu items |
|
|
| `singlePageFinder` | Single page list / detail |
|
|
| `commentFinder` | Comments and replies |
|
|
| `contributorFinder` | Contributors |
|
|
| `siteStatsFinder` | Site statistics |
|
|
| `themeFinder` | Theme information |
|
|
| `pluginFinder` | Plugin information |
|
|
|
|
## Key Usage Pattern
|
|
|
|
Use `th:with` to bind the result in the current scope:
|
|
|
|
```html
|
|
<div th:with="menu = ${menuFinder.getPrimary()}">
|
|
<a
|
|
th:each="item : ${menu.menuItems}"
|
|
th:href="${item.status.href}"
|
|
th:text="${item.status.displayName}"
|
|
></a>
|
|
</div>
|
|
```
|
|
|
|
## Common Notes
|
|
|
|
- `postFinder.list({...})` is the recommended unified query method (all parameters are optional); it supersedes the deprecated `list(page, size)`, `listByCategory(...)`, etc.
|
|
- `metadata.name` is the unique resource identifier — it is not the display name (`displayName`/`title`).
|
|
- Pair `settings.yaml` `categorySelect`/`tagSelect` inputs with Finder queries so users can configure query parameters in Console instead of hard-coding them in templates.
|
|
|
|
## Online Docs
|
|
|
|
> **Do not rely on training data for Finder API method signatures — Halo evolves across versions and your training data may be outdated or incomplete. Always fetch the relevant doc before writing code that calls a specific Finder method.**
|
|
|
|
- postFinder: https://raw.githubusercontent.com/halo-dev/docs/refs/heads/main/docs/developer-guide/theme/finder-apis/post.md
|
|
- categoryFinder: https://raw.githubusercontent.com/halo-dev/docs/refs/heads/main/docs/developer-guide/theme/finder-apis/category.md
|
|
- tagFinder: https://raw.githubusercontent.com/halo-dev/docs/refs/heads/main/docs/developer-guide/theme/finder-apis/tag.md
|
|
- menuFinder: https://raw.githubusercontent.com/halo-dev/docs/refs/heads/main/docs/developer-guide/theme/finder-apis/menu.md
|
|
- singlePageFinder: https://raw.githubusercontent.com/halo-dev/docs/refs/heads/main/docs/developer-guide/theme/finder-apis/single-page.md
|
|
- commentFinder: https://raw.githubusercontent.com/halo-dev/docs/refs/heads/main/docs/developer-guide/theme/finder-apis/comment.md
|
|
- contributorFinder: https://raw.githubusercontent.com/halo-dev/docs/refs/heads/main/docs/developer-guide/theme/finder-apis/contributor.md
|
|
- siteStatsFinder: https://raw.githubusercontent.com/halo-dev/docs/refs/heads/main/docs/developer-guide/theme/finder-apis/site-stats.md
|
|
- themeFinder: https://raw.githubusercontent.com/halo-dev/docs/refs/heads/main/docs/developer-guide/theme/finder-apis/theme.md
|
|
- pluginFinder: https://raw.githubusercontent.com/halo-dev/docs/refs/heads/main/docs/developer-guide/plugin/api-reference/server/finder-for-theme.md
|