diff --git a/browser/package.json b/browser/package.json index 381888d2f..ea861ac7b 100644 --- a/browser/package.json +++ b/browser/package.json @@ -61,7 +61,7 @@ "cli" ] }, - "packageManager": "pnpm@8.6.12", + "packageManager": "pnpm@8.15.2", "dependencies": { "eslint-plugin-import": "^2.26.0" } diff --git a/browser/svelte/package.json b/browser/svelte/package.json index 2d27a4ac2..c6f4907a5 100644 --- a/browser/svelte/package.json +++ b/browser/svelte/package.json @@ -26,7 +26,6 @@ "module": "./dist/index.js", "main-dev": "src/index.ts", "name": "@tomic/svelte", - "packageManager": "pnpm@7.13.3", "peerDependencies": { "@tomic/lib": "workspace:*" }, diff --git a/docs/book.toml b/docs/book.toml index 63573aed7..a160b96ac 100644 --- a/docs/book.toml +++ b/docs/book.toml @@ -10,7 +10,6 @@ git-repository-url = "https://github.com/atomicdata-dev/atomic-server" edit-url-template = "https://github.com/atomicdata-dev/atomic-server/edit/develop/docs/{path}" additional-css = ["atomic.css"] additional-js = ["discord.js"] -fold.enable = true [output.html.fold] enable = true diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 488d97f6e..88eb3ceab 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -42,10 +42,12 @@ - [Fetching data](astro-guide/7-fetching-data.md) - [Using ResourceArray to display a list of projects](astro-guide/8-pojects.md) - [Using Collections to build the blogs page](astro-guide/9-blogs.md) + - [Using the search API to build a search bar](astro-guide/10-search.md) # Specification - [Atomic Data Core](core/concepts.md) + - [Serialization](core/serialization.md) - [JSON-AD](core/json-ad.md) - [Querying](core/querying.md) diff --git a/docs/src/astro-guide/10-search.md b/docs/src/astro-guide/10-search.md new file mode 100644 index 000000000..a2f3f337a --- /dev/null +++ b/docs/src/astro-guide/10-search.md @@ -0,0 +1,194 @@ +# Making a search bar for blogposts + +## Using the search API + +AtomicServer comes with a fast full-text search API out of the box. +@tomic/lib provides some convenient helper functions on Store to make using this API very easy. + +To use search all you need to do is: + +```typescript +const results = await store.search('how to make icecream'); +``` + +The method returns an array of subjects of resources that match the given query. + +To further refine the query, we can pass a filter object to the method like so: + +```typescript +const results = await store.search('how to make icecream', { + filters: { + [core.properties.isA]: myPortfolio.classes.blogpost, + }, +}); +``` + +This way the result will only include resources that have an `is-a` of `blogpost`. + +## Running code on the client + +To make a working search bar, we will have to run code on the client. +Astro code only runs on the server but there are a few ways to have code run on the client. +The most commonly used option would be to use a frontend framework like React or Svelte but Astro also allows script tags to be added to components that will be included in the `` of the page. + +To keep this guide framework-agnostic we will use a script tag and a web component but feel free to use any framework you're more comfortable with, the code should be simple enough to adapt to different frameworks. + +First, we need to make a change to our environment variables because right now they are not available to the client and therefore `getStore` will not be able to access `ATOMIC_SERVER_URL`. +To make an environment variable accessible to the client it needs to be prefixed with `PUBLIC_`. + +In `.env` change `ATOMIC_SERVER_URL` to `PUBLIC_ATOMIC_SERVER_URL`. + +```env +// .env +PUBLIC_ATOMIC_SERVER_URL= +ATOMIC_HOMEPAGE_SUBJECT= +``` + +Now update `src/helpers/getStore.ts` to reflect the name change. + +```typescript +// src/helpers/getStore.ts +import { Store } from '@tomic/lib'; +import { initOntologies } from '../ontologies'; + +let store: Store; + +export function getStore(): Store { + if (!store) { + store = new Store({ + serverUrl: import.meta.env.PUBLIC_ATOMIC_SERVER_URL, + }); + + initOntologies(); + } + + return store; +} +``` + +## Creating the search bar + +In `src/components` create a file called `Search.astro`. + +```html + + + +``` + +If you've never seen web components before, `` is our custom element that starts as just an empty shell. +We then add a `