Use external data as source for shortcode

[junedtan]

Is the scenario below possible?

We have this shortcode:

{{< wpi-artwork id="71596" >}}
possibly with additional parameters, like so:
{{< wpi-artwork id="71596" with-catalogue="1" with-exhibitions="1">}}

This shortcode calls a GET REST API that returns a JSON. The resulting content then is fed into Quire templating structure and the real API call is done on "quire build" (doesn't have to also be called on "quire preview", as long as we can detect preview mode on the template file and output something else like "This section will be replaced by artwork info with id of 71596 on build").

If that's not possible, what about similar scenario but instead of calling API in real time we read the data from a CSV file (better still, a readable file containing a global variable definition with a certain format - JSON maybe?) that's in the project folder? The idea is to code some external script (maybe with php or something) that calls the APIs and produces a CSV or whatever compatible other formats - YAML maybe?) that is readable in the shortcode's template. The script is run separately and its output file is then copied to Quire's project folder.

I'm envisioning something like this on wpi-artwork.html:

{{$artwork = call_the_api('https://something.com/api/get-artwork/'+id-of-artwork-from-shortcode-argument);}}
or
{{$artwork = $global_array[id-of-artwork-from-shortcode-argument];}}

{{$artwork['title']}}

{{$artwork['description']}}

{{foreach ($artwork['exhibitions'] as $exhibition)}}

{{$exhibition['year']}}

{{endforeach}}

[Erin-Cecele]

Thank you for the question @junedtan.

@cbutcosk - do you have any feedback or input based on your work incorporating Georgia O'Keeffe Museum's Linked Art-based linked data infrastructure in the museum's recent Quire project?

[cbutcosk]

@junedtan @Erin-Cecele This isn't available out of the box in quire, but 11ty makes it straightforward to define a custom shortcode in javascript and have it do fetch() calls against a REST api, or optionally create a collection of that object data for later use (though it would have to be a collection of your own naming, WPIObjects or such). We did something similar for Exhibiting O'Keeffe by combining the Eleventy Fetch Plugin (which even handles caching for previews / prod builds) and some mundane JSON unpacking. In our case we didn't end up using the shortcode in that publication, but shortcodes can emit legal DOM nodes in any of the templating languages 11ty supports and they will render cleanly on-page.

So you'd have to do some custom coding, but 11ty enables a lot of customization of data injection and rendering behaviors if you're comfortable hacking away at JavaScript. In our case we packaged all that up into a plugin that we add in the project's .eleventy.js file:

const dataReferencesPlugin = function(eleventyConfig, options) {

  eleventyConfig.addShortcode("datareference",function(ident) {
    // >> fetch() and API source based on `ident` 
    return oneLine`<span id="${slugify(ident)}-blank"></span>`
  })

}

let dataReferencesPluginOptions = {
      defaultProfile: "gokm-elastic", 
      endpoints: [ 
          { 
            profile: "gokm-elastic", 
            url: "https://ex.org/gokm/entity/", 
            auth: { "type": "basic", username: "UUU", password: "PPP" } 
          } 
      ]}
  eleventyConfig.addPlugin(dataReferencesPlugin,dataReferencesPluginOptions)

We didn't end up using this particular shortcode due to development time. But you can imagine stuffing whatever custom processing or REST api calls in that shortcode, and they will happily take whatever parameters you provide. 11ty-fetch does transparent caching in the background so it's not too gnarly in terms of endpoint-thrashing.

I should say though that another method we considered but ultimately did not use was to simply write a script driven by a piece of UI or a file (text of newline-sep'd IDs or a CSV), which would drive a download from the O'Keeffe API and format the data appropriately to be used as catalogue data like any other Quire object. This has the advantage of not requiring any real JS knowledge and data points are available to all the fun Quire business pieces. It doesn't sound like your use case, but thought I'd mention it as fit a CI/CD dev flow nicely (ie, content data updates were just another commit so if something failed to build we could isolate the source) and gives a dev options without descending into javascript async function madness (said with all respect for that paradigm!).

Anyway, phew, that is kind of a lot but hopefully of some help? The takeaway to me in this problem space is: at its best moments 11ty is a tree of javascript funcs any of which you can replace pretty much at will, so there are a multitude of places you can inject data that your content creators need.

[Erin-Cecele]

Just chiming in to say thank you to @cbutcosk for the detailed information you've provided. This will be very helpful for the community.

[junedtan]

Thanks for the reply, @cbutcosk @Erin-Cecele ! While I get the gist of it, turns out we have a change in requirements to be more like "If that's not possible" part of my original post. It's then the php script that calls the API instead of having to do that in Quire. My follow-up question then is what is the best format that's recognizable by Quire that the script can produce? I'd imagine whatever is in the resulting file can be read by custom Quire shortcodes in order to render the corresponding template.

I'm wondering how to define a global variable but it's stored in a file. maybe .yaml? .csv? After "quire new" the file then can be stored somewhere in the project folder and read in the shortcode code.

[cbutcosk]

@junedtan GMTA, Scripting a dump of data is a very sensible approach. 😀

Any data file in the content dir gets pulled up into the data cascade and is available across templates, so you have a great deal of flexibility in choosing a file interface. If you follow the figure / object JSON Schemas you might not even have to implement a custom shortcode, just drop objects.yaml and figures.yaml files that would just be available for use in quire shortcodes, etc. But anyway those are just part of the project's Global Data Files in data/ so you can define whatever data interface suits your needs and it's available on every page template and many 11ty contexts.