A Spark-y search

[khalwat]

EDIT: Updated the code below to conform to the Spark 0.0.7 API changes (thank you, Ben!)

So to play with Spark, I decided to implement the same auto-complete search that I use on the nystudio107.com website for finding articles.

The existing nystudio107.com implementation works using an Autocomplete Vue component on the frontend, which pings an Element API endpoint.

Here's what the HTML/Vue code looks like:

        <div id="auto-complete" class="nav-search open" style="position: relative; padding-top: 1rem;">
            <input type="text" aria-label="search" id="searchbox-placeholder" name="search" placeholder="search" autocomplete="off" class="autocomplete-input" v-bind:class="{ hidden: menuOpen}">
            <autocomplete
                    name="search"
                    ref="searchInput"
                    id="searchbox"
                    url="/api/search"
                    anchor="title"
                    label="blogSummary"
                    placeholder="search"
                    min="1"
                    :on-select="itemSelected"
                    :process="processJsonData"
            >
            </autocomplete>
        </div>

...and here's what the Element API endpoint looks like:

        'endpoints' => [
            'api/search' => [
                'elementType' => Entry::class,
                'paginate' => false,
                'criteria' => [
                    'section' => ['blog', plugins],
                    'with' => [
                        'blogCategory',
                        'blogTags',
                    ],
                    'limit' => 9,
                    'search' => $request->getParam('q') ?? '',
                    'orderBy' => 'score'
                ],

So then I decided to try to implement this via Spark/Datastar. Here's what the index page looks like:

        <section data-store="{ search: ''}">
            <h3>Spark search</h3>

            <input
                data-model="search"
                data-on-input.debounce_500ms="{{ spark('spark/_fragments/search-results.twig') }}"
                placeholder="Search..."
                type="text"
            />
            <div id="search-results">
            </div>
        </section>

What this does is it says the <input> element's value should have a two-way binding with the search item in our data store, and any time text is input into the field, it should render the spark/_fragments/search-results.twig template, and replace the <div id="search-results> DOM element with the one that is returned by rendering the aforementioned Twig template.

The .debounce_500ms just tells it to delay rendering the template until nothing additional has changed in the <input> element for 500ms... to prevent slamming the backend with a get requests.

...and here's what the Twig code looks like for the fragment that it loads via Spark:

{# @var store \attributes\stores\AutocompleteSearch #}

<div id="search-results">
    {% set results = [] %}
    {% if store.search is not empty %}
        {% set results = craft.entries()
            .section(['demo'])
            .limit(9)
            .search(store.search)
            .orderBy('score')
            .all() %}
    {% endif %}
    <ul>
        {% for result in results %}
            <li><a href="{{ result.url }}">{{ result.title }}</a></li>
        {% else %}
            <p>No results</p>
        {% endfor %}
    </ul>
</div>

This is mostly just standard Twig. The only two things to note are that the search Twig variable is automatically set, because it's in our store... and the {% fragment %} tag causes Spark to render out an "Event" that includes some instructions for what Datastar should do with it, as well as the rendered HTML.

...and here's what it looks like in the browser (yes, it's ugly, I didn't format anything):

spark-autocomplete-demo.mov

If you're wondering what the {# @var store \attributes\stores\AutocompleteSearch #} is, I'm leveraging PHP 8 Attributes to add a class that describes the store data structure so I can get nice auto-complete in PHPstorm:

It's really easy, you just create a little stub class and away you go:

<?php
namespace attributes\stores;

use Attribute;
use putyourlightson\spark\models\StoreModel;

#[Attribute]
class AutocompleteSearch extends StoreModel
{
    /** @var string $search The string to search for */
    public string $search;
}

Overall, I think the Spark/Datastar implementation seems a whole lot easier, and it's nice to be able to work with Twig the way you're used to working with Twig.

It didn't take too long to figure out the concepts needed to make it work, and it felt pretty good to use.

I'm still not extremely well-versed with how Datastar works, but the main things I needed to learn when using Spark with it are:

• You need a data-store property on an HTML element in the main template's DOM to hold your state for use by Datastar/Spark
• Everything used by Datastar is preceded with data- so it's just leveraging HTML data attributes
• Everything in the data-store is available in your Twig templates that are rendered by Spark, as regular old Twig variables
• Datastar uses element ids to figure out what parts of the DOM to replace when Spark renders a template
• You can pass state back to the store from a Twig template using {% do spark.setStore({ }) %}
• The data-on- lets you do things when various JavaScript events happen; it's just JavaScript that you put in there. Spark outputs the JavaScript you need when you use things like {{ spark.get() }}
• {% fragment %} tells Spark that what is in that tag pair is an HTML fragment that should be sent back. A template can have as many fragments as you like, so multiple DOM elements can be individually replaced with one request

Unrelated to Spark (because it generates this for you), but relevant to Datastar if you're looking at how it works under the hood:

• The $ symbol is used to prefix items in your store, so for instance $search references the search item in your store
• The $$ symbols are used to prefix various baked-in Datastar functions like $$get() or $$put()

Like I said, just scratching the surface, but pretty cool!

[bencroker]

Perfect implementation, thanks for sharing!

Everything used by Datastar is preceded with data- so it's just leveraging HTML data attributes

Hence the name (data-*) 😊

Spark outputs the JavaScript you need when you use things like {{ spark.get() }}.

spark.get() just renders an endpoint URL (no JavaScript) containing a tamper-proof configuration containing the current site, the template path and the passed in variables.

{% fragment %} tells Spark that what is in that tag pair is an HTML fragment that should be sent back. A template can have as many fragments as you like, so multiple DOM elements can be individually replaced with one request.

That’s right. As the response is a stream of server-sent events, the Datastar process each fragment in real-time as it is sent to the browser. So in theory, if you send a regular fragment followed by a long-running fragment (one that hits a third-party API, for example), the first fragment will be processed on the front-end as soon as it is received, and the long-running fragment will follow whenever it completes rendering.

The fragment tag also accepts a set of options, but I haven’t documented this feature just yet as we’re working through some changes in Datastar’s API. We are also working on improving the docs, so learning about the Datastar features should get better over time.

{# Settles the fragment after 500ms – useful for transitions. %}
{% fragment with { settle: 500 } %}
    ...
{% endfragment %}

[wsydney76]

Being forced to revisit an old project, where such a search (the result list as dropdown) was implemented as an Alpine JS component: Would love to see how frontend keyboard/mouse events would be handled in Spark, such as

• move focus inside result list with keyup/keydown, without leaving the list,
• move focus inside result list with tab/shift tab, and closing the dropdown when leaving
• close dropdown and move focus to text input when pressing ESC or clicking outside.

Supporting those things were the main reason to use Alpine only (may be it would have been possible to build that on top of Sprig, but I didn't want to mix two frameworks..)

[bencroker]

@wsydney76 it sounds like all of these things would be handled at the Datastar level. There's an active channel in the htmx Discord server, in case you run into any issues: https://discord.gg/JUKb6RpJ

[khalwat]

@wsydney76 check out: https://datastar.fly.dev/guide/batteries_included

data-on-*
This is a way to add event listeners to elements. It’s a simple way to do v-on in Vue or x-on in Alpine. Any valid addEventListener event type can be used. For example, click, mouseover, dblclick, etc.

Datastar takes a lot of inspiration from Alpine.

[wsydney76]

Thanks @khalwat @bencroker

Took a look into it as an old man's brain sport, looks promising, however my first impression is that it would take a lot of learning/try-and-error work right now to accomplish such fine grained polished user interactions, e.g. for things handled in Alpines Focus Plugin.

So stopping for now in favor of outdoor activities, but wishing every success.

[delaneyj]

you have things like data-scroll-into-view.focus in Datastar. Also by being hypermedia focused a lot of the more complicated features of Alpine dissolve away. If there is something you can't do please reach out on the Datastar discord

[khalwat]

@bencroker you say:

spark.get() just renders an endpoint URL (no JavaScript) containing a tamper-proof configuration containing the current site, the template path and the passed in variables.

...but it is rendering JavaScript, unless I'm misunderstanding something.

If I do {{ spark.get('some/template/') }} this maps to $$get('action/spark/response') with the appropriate parameters passed in, which is just JavaScript because $$get() is the Datastar Javascript function to get the endpoint data, and it can be mixed and matched with regular old JavaScript, like this example: https://datastar.fly.dev/examples/dialogs_browser

<button
  id="dialogs"
  data-store="{prompt:'foo',confirm:false}"
  data-fetch-url=""
  data-on-click="$prompt=prompt('Enter a string',$prompt);$confirm=confirm('Are you sure?');$confirm && $$get('/examples/dialogs___browser/sure')"
>
  Click Me
</button>

So you should be able to do something like this:

<button
  id="dialogs"
  data-store="{prompt:'foo',confirm:false}"
  data-fetch-url=""
  data-on-click="$prompt=prompt('Enter a string',$prompt);$confirm=confirm('Are you sure?');$confirm && {{ spark.get('/examples/dialogs___browser/sure.twig') }}"
>
  Click Me
</button>

It looks weird because of the $'s that preface store values and the $$ that prefix Datastar functions, but it's just JavaScrip that I assume gets eval'd somewhere in Datastar's guts, no?

[bencroker]

Ok, fair enough. Technically it ouputs a Datastar action command ($$get(), $$post(), etc.), containing a URL to the Spark endpoint.

[khalwat]

Ok, fair enough. Technically it ouputs a Datastar action command ($$get(), $$post(), etc.), containing a URL to the Spark endpoint.

Which is just JavaScript! 😋

[bencroker]

It’s not JavaScript though, you can’t run it in a browser unless Datastar is loaded on the page 😊

[khalwat]

That's like saying it's not JavaScript if you use JQuery. It is just JavaScript, it is just JavaScript that depends on a particular package being loaded... but all of the expressions, operators, etc. is just JavaScript.

The entire expression is just JavaScript... the fact that it uses a function provided by Datastar doesn't make it not JavaScript... and that function may end up being a very small part of the data-on-* JavaScript code.

[delaneyj]

Both are right! Datastar is basically about using minimal JS to make your code declarative yet have fine grain signals

[khalwat]

Related: Proposed Spark API changes -> #5

[delaneyj]

Like I said, just scratching the surface, but pretty cool!

Thanks, Datastar author here. Any questions don't hesitate to ask!

[croxton]

Just a note about the revised API (as of about an hour ago!), for anyone recreating @khalwat 's search example above:

The index template would look something like this:

<section data-store="{ search: ''}">
    <h3>Spark search</h3>

    <input
        data-model="search"
        data-on-input.debounce_500ms="$$get('{{ sparkUrl('spark/_fragments/search-results.twig', {}, true) }}')"
        placeholder="Search..."
        type="text"
    />
    <div id="search-results">
    </div>
</section>

And the template spark/_fragments/search-results.twig would look like this:

<div id="search-results">
    {% set search = store.get('search') ?? '' %}
    {% set results = [] %}
    {% if search is not empty %}
        {% set results = craft.entries()
            .section(['demo'])
            .limit(9)
            .search(search)
            .orderBy('score')
            .all() %}
    {% endif %}
    <ul>
        {% for result in results %}
            <li><a href="{{ result.url }}">{{ result.title }}</a></li>
        {% else %}
            <p>No results</p>
        {% endfor %}
    </ul>
</div>

[khalwat]

Maybe put the API thoughts over here @bencroker @croxton ? #5

[croxton]

No strong opinions yet on the specifics of the API, but I'm hoping to dig in a bit deeper this weekend and will let certainly you know!

[khalwat]

Here's the video: https://craftquest.io/livestreams/intro-to-spark-and-datastar

[bencroker]

FYI the code can (optionally) be simplified to the following using the Spark 0.0.6 syntax.

data-on-input.debounce_500ms="{{ spark('spark/_fragments/search-results.twig') }}"

[khalwat]

@croxton I updated the example code to work with Spark's 0.0.7's syntax.