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 `*.sr.ht` sigil for viewing sourcehut
repos.