Harnessing the Power of Modular Spyral Notebooks with import

Creating rich, interactive analyses in Spyral is one thing—but building notebooks that talk to one another is a whole new level of magic. Today, we’ll explore how Spyral’s little‑known Notebook.import method can transform your workflow, letting you build modular, reusable components and borrow functionality from other users in a snap.

---

Why Notebook Imports Matter

Imagine you’ve written a handful of utility functions for data cleaning, cookie management, or entity extraction—and you’d like to reuse those bits of code in a brand‑new project. Rather than copying and pasting messy chunks of code, you can simply import someone else’s notebook (or your own!) by URL and get instant access to its cells. This approach:

• Promotes Modular Design: Break large analyses into focused, maintainable notebooks.
• Enables Code Reuse: Leverage community‑contributed tools without reinventing the wheel.
• Speeds Development: Plug in prebuilt functionality and get straight to the fun part—insights.

Getting Started: Importing a Notebook by URL

Any Spyral notebook on the public portal can be imported via its URL. Let’s look at a real‑world example:

// Import the “cookies” notebook by its abbreviated URL
Spyral.Notebook.import('ajmacdonald@gh_cookies');

Here’s the breakdown:

1. UserName_NotebookName: The string you pass to import is the notebook’s owner and repository name, joined by an underscore.
2. Default Behavior: Without extra arguments, Spyral grabs the entire notebook.
3. Selective Imports: If you only need a single code cell, provide its cell number as a second argument:

   // Import just cell #3 from the cookies notebook
   Spyral.Notebook.import('ajmacdonald@gh_cookies', 3);

Example URL: https://voyant-tools.org/spyral/ajmacdonald@gh/cookies/
(Abbreviated as ajmacdonald@gh_cookies in code.)

A Practical Example: Building a “Prompter” Notebook

Armed with the cookies notebook, let’s create a tiny app that prompts the user for input and stores it in a browser cookie.

1. Import the Cookies Module

   Spyral.Notebook.import('ajmacdonald@gh_cookies');

2. Instantiate the Cookie Manager

   const myCookie = new Cookies();

3. Prompt and Store

   const userText = prompt("Enter some text:");
   myCookie.set('userInput', userText);
   console.log("Your input has been saved to a cookie!");

4. Try It Yourself
   Explore the full “prompter” notebook here: https://voyant-tools.org/spyral/ajmacdonald@gh/prompter/

Chaining Imports: The “Cookie Prompter” in Action

Why stop with two notebooks? Here’s a third example that imports our prompter notebook, runs it, and then immediately makes use of the cookie value elsewhere in your analysis:

https://voyant-tools.org/spyral/ajmacdonald@gh/lCBkxb/

While this demo simply shows a trivial prompt-and-store loop, you can easily imagine more powerful uses:

• API Tokens: Prompt for and securely cache an LLM or web‑service key.
• User Preferences: Remember UI settings across multiple notebook sessions.
• Experiment Flags: Toggle features on or off without rewriting code.

Exercise for the Reader: Entity Extraction Made Easy

Want a challenge? Check out this notebook, which provides a reusable function for filtering entities in your corpus:

https://voyant-tools.org/spyral/ajmacdonald@gh/working-with-entities/

1. Import it

   Spyral.Notebook.import('ajmacdonald@gh_working-with-entities');

2. Call the Helper

   const entities = getFilteredEntities({
     type: 'location',
     minFrequency: 5,
   });
   console.log(entities);

3. Build a Visualization
   The notebook includes an example chart—feel free to adapt it for your own data.

Next Steps and Screenshots

I’ll be adding screenshots shortly to illustrate each step visually, including:

• The import dialog in Spyral
• The cookies notebook interface
• The prompter running in the browser console
• A sample entity‑visualization chart

Stay tuned! And if you’ve built something cool using Notebook.import, share it in the comments below. Let’s keep the modular magic flowing.

---

Happy coding, and may your notebooks always collaborate!