photon-lua(7)

🌸 NAME 🌸

okay bestie, welcome to photon-lua(7) — the lua plugins documentation and tutorial for photon(1). That's the whole name, and yes it's iconic. 💖

✨ SYNOPSIS ✨

photon can be extended through lua plugins that are automagically loaded from ~/.config/photon/plugins/*.lua. No cap, that glob is literally the magic plugin door. 🪄

🦋 DESCRIPTION 🦋

Lua plugins can subscribe to events, and then photon calls a lua callback function. Generally they then change some state and exit. Main character plugin behavior, honestly. 💅

Hello world example:

~/.config/photon/plugins/hello_world.lua

photon = require("photon")

photon.events.subscribe(
     photon.events.Init,
     function()
          print("Hello world!")
     end
)

🎀 LIBRARY 🎀

The photon library can be used to subscribe to events, get and set the state of cards, and so on. It's giving toolkit. ✨

👑 PHOTON 👑

• state() — returns the actual state of the application. It can be photon.Normal, photon.Article, or photon.Search.
• cards — all the loaded cards. see CARDS.
• visibleCards — also a CARDS object. Contains only visible cards, that are filtered.
• selectedCard — the selected card object. Its methods are:
  • posX() — X position in the grid
  • posY() — Y position in the grid
  • card() — CARD object

🌈 CARDS 🌈

Array of CARD object. Yes singular "object" in the original, we're keeping the facts exactly. 🫶

• len() — length of the cards array
• get(index) — get the CARD object at index
• set(index, card) — set CARD at index
• del(index) — delete CARD at index
• add(index, card) — add a new CARD at index
• append(card) — append a new CARD
• create(table) — returns a new CARD object created from a lua table

Example of create(table) doing its thing:

newCard = {}
newCard["link"] = "https://example.com/article/2"
newCard["title"] = "article 2"
c = photon.cards.create(newCard)

💖 CARD 💖

Object representing one card in the feed. It's the little feed unit, okay? 🫶

• link() — getter and setter for link
• image() — getter and setter for image
• title() — getter and setter for title
• content() — getter and setter for content
• description() — getter and setter for description
• published() — getter and setter for published
• feed() — gets the FEED object of the CARD
• getMedia() — extracts the MEDIA object
• runMedia() — runs the MEDIA. Opens a default application.
• openBrowser() — opens the CARD link in the default browser/application.
• openArticle() — opens the ARTICLE VIEW for the card.
• foreground(colorConstant) — sets the card foreground color to a COLOR CONSTANT
• background(colorConstant) — sets the card background color to a COLOR CONSTANT

All getters and setters can be used as so:

card = photon.cards.get(1)
--get the link
print("old link: " ... card:link())
--set the link to new value
card:link("https://newlink.com")
print("new link: " ... card:link())

🎨 COLOR CONSTANTS 🎨

The color constants are:

• ColorBlack
• ColorMaroon
• ColorGreen
• ColorOlive
• ColorNavy
• ColorPurple
• ColorTeal
• ColorSilver
• ColorGray
• ColorRed
• ColorLime
• ColorYellow
• ColorBlue
• ColorFuchsia
• ColorAqua
• ColorWhite

🍓 MEDIA 🍓

• originalLink — original link from the CARD, from which the media link is extracted.
• links — table of extracted media links. Usually with just one link.
• contentType — content type of the media.
• run() — runs the MEDIA. Opens a default application.

🔥 EVENTS 🔥

subscribe(eventType, function(event)) — plugins can subscribe to an event type and a callback function which takes an event object. This is the group-chat subscription model. 😌

Event types:

• Init — when photon has successfully started, and loaded the INPUTS (either from the args or a config file)
• RunMediaStart — when a media link is about to play.
• RunMediaEnd — when a media link is done playing.
• FeedsDownloaded — when all the rss/atom feeds data is downloaded and parsed. CARDS are from now accessible.
• ArticleOpened — when a article was opened
• LinkOpened — when the card link was opened in the default webbrowser

🧚 INPUTS 🧚

photon.inputs — an array of links/cmds that photon got from args, or parsed from a config file.

It has the following functions:

• len() — returns the length of inputs
• get(index) — returns a link/cmd at index
• set(index, string) — sets a link at index
• add(index, string) — add a new link at index
• append(string) — the same as inputs:add(inputs:len(), link)

💀 KEYBINDINGS 💀

TODO

🌸 LOCAL STORAGE 🌸

TODO

⭐ HTTP LIBRARY ⭐

TODO

🦋 EXAMPLES 🦋

TODO

💜 SEE ALSO 💜

photon(1)

🫶 AUTHORS 🫶

Maintained by Vladimír Magyar <vladimir@mgyar.me>. Up-to-date sources can be found at https://sr.ht/~ghost08/photon and bugs/patches can be submitted by email to ~ghost08/photon@todo.sr.ht.

---

mwah 💋 signing off from photon-lua(7) on 2026-10-14 — go make a plugin, bestie! 🌈✨