From 3b46b5a4e353f5294992cc354fe75708ca5543c3 Mon Sep 17 00:00:00 2001 From: Toto Date: Mon, 1 Jun 2026 11:23:34 +0200 Subject: [PATCH] feat(search): add-metadata-filter SNK-1292 --- CLAUDE.md | 99 ++++++++++++++++++++++++++++++++++++++++++ docs/javascript/api.md | 43 ++++++++++++++++++ 2 files changed, 142 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..8fd5c39 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,99 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Repository Overview + +This is a **documentation repository** for LumApps Customizations API (SDK and CLI). It provides technical documentation for developers who want to extend LumApps sites using JavaScript and CSS customizations. + +The documentation is built using **Jekyll** with the `just-the-docs` theme and is organized into markdown files under the `/docs` directory. + +## Documentation Structure + +The documentation is organized hierarchically: + +- **Main entry point**: [docs/index.md](docs/index.md) - Customizations API overview +- **JavaScript API**: [docs/javascript.md](docs/javascript.md) and subdirectory [docs/javascript/](docs/javascript/) + - API reference: [docs/javascript/api.md](docs/javascript/api.md) + - Capabilities: [docs/javascript/capabilities.md](docs/javascript/capabilities.md) + - Best practices: [docs/javascript/best-pratices.md](docs/javascript/best-pratices.md) + - Development & deployment: [docs/javascript/development-and-deployment.md](docs/javascript/development-and-deployment.md) + - Use cases: [docs/javascript/use-cases.md](docs/javascript/use-cases.md) + - FAQ: [docs/javascript/faq.md](docs/javascript/faq.md) +- **CSS API**: [docs/css.md](docs/css.md) and subdirectory [docs/css/](docs/css/) + - API reference: [docs/css/api.md](docs/css/api.md) + - Best practices: [docs/css/best-practices.md](docs/css/best-practices.md) + - Development & deployment: [docs/css/development-and-deployment.md](docs/css/development-and-deployment.md) + - Use cases: [docs/css/use-cases.md](docs/css/use-cases.md) + +## Jekyll Configuration + +The site uses Jekyll with the following configuration: +- **Theme**: `pmarsceill/just-the-docs` (remote theme) +- **Config file**: [docs/_config.yml](docs/_config.yml) +- **Site title**: "LumApps Developers" + +All markdown files include YAML frontmatter with: +- `layout`: typically `default` +- `title`: page title +- `nav_order`: controls navigation order +- `parent` / `grand_parent`: defines hierarchical navigation +- `has_children`: indicates if the page has child pages + +## Key Customizations API Concepts + +### JavaScript API +The JavaScript Customizations API is based on callbacks that execute after the LumApps application loads. The main entry point is: + +```javascript +window.lumapps.customize(callback, configuration) +``` + +The callback receives parameters including: +- `targets` - where customizations can be placed (PAGE, HEADER, NAVIGATION, SEARCH_BOX, etc.) +- `placement` - position relative to target (ABOVE, BELOW, LEFT, RIGHT, etc.) +- `components` - reusable LumApps components (Message, Button, Dropdown, etc.) +- `constants` - constant values for component configuration +- `render` - function to render customizations +- `session` - current user session data +- `on` - event subscription +- `api` - Axios instance for AJAX requests +- `addWidgetFilters` - function to add custom filters to widgets +- `addSearchFilters` - function to add custom filters to global search and Ask AI + +### CSS API +CSS customizations allow developers to add custom styles to modify the visual appearance of LumApps sites. The API provides supported CSS classes and anchors that remain stable across releases. + +### Deployment Model +Customizations are deployed by adding JavaScript/CSS code to the site's `` tag through the LumApps administration UI (Style > Advanced > Head tag HTML). + +## Documentation Maintenance Guidelines + +When editing documentation: + +1. **Preserve frontmatter**: Always maintain the YAML frontmatter structure +2. **Navigation hierarchy**: Keep `parent`, `grand_parent`, and `nav_order` consistent +3. **Code examples**: Include practical JavaScript/CSS examples that demonstrate actual API usage +4. **Security considerations**: When documenting public site features, include security warnings (especially for `shouldRenderOnPublicSites`) +5. **Browser compatibility**: Mention browser support when relevant (LumApps supports latest 2 versions of Chrome, Firefox, Safari, Edge) +6. **Performance impact**: Document performance considerations for customizations (recommended 2-5KB total) +7. **API versioning**: Note when features are deprecated or breaking changes occur + +## Recent Updates + +Based on recent commits: +- **Search filters functionality added** - New `addSearchFilters` API for global search and Ask AI +- Widget filters functionality added to documentation +- Public sites customization documentation added +- MDI (Material Design Icons) documentation updated +- New targets added to the API +- Search extension result documentation added + +## When Working on This Repository + +- This is a **documentation-only** repository - no application code or build processes +- Changes are typically updates to markdown files in `/docs` +- Focus on clarity, completeness, and accurate code examples +- Ensure all links between documentation pages are correct +- Validate that YAML frontmatter is properly formatted +- Keep code examples consistent with the latest API version diff --git a/docs/javascript/api.md b/docs/javascript/api.md index 59001a7..7e283b6 100644 --- a/docs/javascript/api.md +++ b/docs/javascript/api.md @@ -17,6 +17,7 @@ The main entrypoint of this API is the object ```window.lumapps```. On this obje - [getInternalUrl](#getinternalurl) - [displayNotification](#displaynotification) - [addWidgetFilters](#addwidgetfilters) +- [addSearchFilters](#addsearchfilters) ## customize @@ -39,6 +40,7 @@ Where `callback` is a function that will receive a set of `parameters` and retur | `getLatestEvents` | Function that retrieves the latest events generated on the application. See more details for this function [here](#getLatestEvents) | | `state` | Object that provides state management capabilities. See more details for this function [here](#state) | | `addWidgetFilters` | Function that allows adding custom filters to widgets. Supports public site customizations when configured. See more details [here](#addwidgetfilters) | +| `addSearchFilters` | Function that allows adding custom filters to global search and Ask AI. Supports public site customizations when configured. See more details [here](#addsearchfilters) | | `onNavigation` (**deprecated**) | Function that will be executed once any widget in a content is rendered. See more details for this function [here](#on-widget-rendered) | | `onWidgetRendered` (**deprecated**) | Function that will be executed once the application has performed a navigation. See more details for this function [here](#on-navigation) | | `api` | [Axios](https://github.com/axios/axios) instance that allows the developer to execute AJAX requests. See more details for this function [here](#axios-api) | @@ -1466,6 +1468,47 @@ window.lumapps.customize(({ addWidgetFilters }) => { See the [Public Site Customizations Security](#public-site-customizations-security) section for more information about enabling and using public site customizations safely. +### addSearchFilters + +The `addSearchFilters` function allows you to add custom filters to global search and Ask AI features on your site. This function is available in two locations with different capabilities: + +#### Top-level function (Legacy) + +```js +window.lumapps.addSearchFilters(filterConfig); +``` + +**Important:** The top-level `window.lumapps.addSearchFilters()` function **does not support public site customizations**. Filters added using this method will only work for authenticated users. + +#### Within customize callback (Recommended) + +```js +window.lumapps.customize(({ addSearchFilters }) => { + addSearchFilters(filterConfig); +}, { shouldRenderOnPublicSites: true }); +``` + +**Important:** When using `addSearchFilters` within the `window.lumapps.customize` callback, the function **supports public site customizations** when the `shouldRenderOnPublicSites` configuration option is set to `true`. This allows search filters to work for both authenticated and anonymous users on public sites. + +**Recommendation:** Use the `addSearchFilters` function within the `customize` callback to ensure compatibility with public site customizations and future updates. + +```js +// Example: Adding search filters with public site support +window.lumapps.customize(({ addSearchFilters }) => { + addSearchFilters({ + // Your filter configuration here + }); +}, { shouldRenderOnPublicSites: true }); +``` + +**Use cases:** +- Filter search results based on custom metadata or business logic +- Apply contextual filters to Ask AI queries based on user attributes or session data +- Restrict search results to specific content types, communities, or categories +- Add dynamic filters based on user permissions or roles + +See the [Public Site Customizations Security](#public-site-customizations-security) section for more information about enabling and using public site customizations safely. + ### CSS classes Our Design System provides a set of classes that can be reused in order to style our components while maintaining a visual coherence with the rest of the site. These classes can be passed in when using the `className` option for each component, or when you are using the `RawHTML` component. These CSS classes need no custom CSS, they are available out-of-the-box. If you want to implement custom CSS, please take a look at that documentation [here](../css/README.md)