Practical tips on getting started

[ndarilek]

This seems like a neat project. A while back I had the idea for something like a federated itch/Steam for games and other digital projects but didn't want to build it from scratch. Saw the Bandwagon presentation at FediForum and figured that's basically what I want to make, except scoped to games/books/other singular projects, and maybe with integration into launchers for fetching updates.

I think what might help me are practical getting started guides that might take me through how to build specific things/accomplish certain tasks. In particular, things I have questions about:

1. I feel like building this would be easier if I started with my current static site, replicated it in Emissary to figure out if I can, then packaged that work up into an app I then distributed. How do I do that? Can I create individual posts/pages to replicate my current site structure and then add ActivityPub types later? (E.g. I have a /news section, can I add the posts as generic AP types now, then add a News type later with additional customizations?) It seems like I need to know the schema/site design in advance, so I'd almost have to build twice--a generic site, then the actual version with my content.
2. How do I iterate on templates/schemas? Is there any kind of hot reloading? Can I place them in a scratchpad directory and just restart/reload as I iterate?
3. I'd like to learn how to build out certain specific content types/structures. Specifically:
   • A /news section with posts like /news/development-update-1, /news/initial-release, etc. as children, linked to something like a @[email protected] actor for just site news.
   • Individual actors with posts as children and maybe other top-level fields, rooted at something like /projects/, that can be followed for individual updates on those projects. That might be identical to the first point, now that I think of it. But /news would be more like a traditional blog, while /projects/projectname would be a hybrid of static content/external links/project-specific updates.
   • Posting rules such that I can cross-post/boost individual project news to the main news site, and similarly for dev updates and such. I'd like to post development-style updates to projects and maybe direct those to a /devlog root/actor if they're tagged a certain way or otherwise keyed as a devlog update.
   • Ways to place/host static files at arbitrary places in the hierarchy. I might want /projects/mygame/trailer.ogg to link to a trailer, optionally federating that out as a profile link but either way easily memorable if I need to toss out the link.

The docs seem solid but it's a bit tough to figure out how to start. My inclination is to try building my current site in Emissary but I'm not clear how to then extract those templates into something like Bandwagon for games. Thanks for any pointers.

[benpate]

Hello! This is a great topic, with lots of separate issues that I need to answer better in the documentation. Right now, Emissary is already a pretty complicated engine, but with woefully inadequate docs. Give me a bit of time to write up thorough answers for you?

[benpate]

On 2, yes. Schema and template CHANGES are hot reloaded whenever you make changes. The only thing you'll need to restart for is when you: 1) add a NEW schema or template to an existing directory, and 2) make changes to the underlying Go app (obviously).

[benpate]

On 3 -- The Bandwagon project is a pretty good example of making one content type that fits into another one. In it, albums fit (only) into custom profiles, and songs fit (only) into albums. This could certainly use more info, but this is an okay example for now.

Nested Directory Names

And, regarding directory names, even though a stream may be a "child" of another, it's always referenced on the top-level directory of the URL. So, if item "123" has a child "456" then you could go to https://myserver/123 or https://myserver/456 but the directories don't nest -- so https://myserver/123/456 is not possible. This is inconvenient, but it's important to Emissary for a couple of reasons. Primarily, these deeply nested routes would complicate the logic for defining custom actions that make Emissary templates work the way they do. If you see a route like: /abc/def -- is "def" the name of an action on item "abc"? Or is it its own stream named "def" that's just nested under its parent "abc"?

Static Files

You can include static files as resources in Themes and Templates -- just include a resources directory along with whatever files you need.

NOTE: if you want to include JS or CSS files, there's a better way. Put these text files into a bundle and Emissary will automatically combine and minify them for you. It's not WebPack, but it's still pretty neat.