hellgate/writing_sigils.md

how to write a sigil

requirements

• a text editor
• a browser
• some knowledge of javascript

getting started

Say we want to write a sigil for "https://time.is" to get the current times around the world and serve them in gemtext format. Our first step is to create the file time.is and place it in the sigils directory.

writing the sigil

The only necessary part of any sigil is the call to window.electron.send_gemtext(). This function sends any data generated in the browser to the web server.

To start, we can write our sigil time.is to consist only of the line:

window.electron.send_gemtext("This is a test.")

Now, whenever you access "gemini://localhost?https://time.is" you will be greeted with:

This is a test.

Great! This is not very useful however, as we aren't getting any data from the page.

So, lets add some data! If we navigate to "https://time.is" using a web browser, we can see the current time for the user's location is displayed near the top of the page. Using the "inspect element" feature we can see that the current time is contained in a time element with the id clock. If we want to use this data in our sigil, we can access it using document.querySelector(), the same way we would in the browser console:

var current_time = document.querySelector("time#clock").innerText

Now, if we want our sigil to send that data, we simply write:

window.electron.send_gemtext(current_time)

So now our sigil time.is looks like this:

var current_time = document.querySelector("time#clock").innerText
window.electron.send_gemtext(current_time)

And now, when we access "gemini://localhost?https://time.is", we see:

4:29:36pm

(or whatever the time is in your current location)

If we want to display the current date as well, we can find it in the div element with id dd

var current_date = document.querySelector("div#dd").innerText

And send the entire thing as a string back to the web server:

var current_time = document.querySelector("time#clock").innerText
var current_date = document.querySelector("div#dd").innerText
window.electron.send_gemtext(current_time + "\n\n" + current_date)

Now, when we access "gemini://localhost?https://time.is" we see:

4:38:02pm

Friday, April 23, 2021

Of course, sigils can be much more powerful than this. For a good example of a more complex sigil, you can see the gitlab.com sigil for viewing gitlab repos.