-

Sun, 23 Oct 2022 09:46:46 +0000

Scott M. Stolz wrote the following post Sun, 23 Oct 2022 09:46:40 +0000

Design Decisions: Themes, Addons, Modules, Widgets

I am currently working on a new theme that will include some additional features. I am trying to package it so that it can be added to Hubzilla without interfering with core files.

The current structure I plan on using is:

/view/theme for the theme itself.
/widget for widgets required by the theme.
/ZotLabs/SiteModule for modules required by the theme.
/addon for optional features.

Is this the optimal file structure?

show all 16 Comments

Harald Eilertsen

Wed, 14 Dec 2022 17:55:24 +0000

I have no idea, but it looks sensible, I think.

One snag I can think of is that it will add a number of untracked files in the core git repo. This can confuse some people. And it doesn't allow for installing the theme just by cloning it's repo. But imo that is one of the problems of using git as the distribution method.

Scott M. Stolz

Wed, 14 Dec 2022 18:16:25 +0000

@Harald Eilertsen Supposedly there is a way to have multiple repositories update a website. Hubzilla already does that with the separate core and add-ons repositories. I'm not that familiar with git so hopefully I can find someone who knows how to show me or provide example code.

Scott M. Stolz

Wed, 14 Dec 2022 18:26:43 +0000 last edited: Wed, 14 Dec 2022 18:28:46 +0000

The challenge is that I'm creating multiple themes which all will share common resources like widgets and add-ons and modules.

Streams uses /Code/SiteWidget (or something like that) for widgets but I tried using /Zotlabs/SiteWidget for Hubzilla and it didn't work. That is forcing me to put widgets in the widgets folder.

If add-ons has a SiteAddon folder or something similar, I'm unaware of the correct path.

Dan d'Auge

Wed, 14 Dec 2022 18:28:51 +0000

I use the git pull command to update our hub. Example for the hubzilla core:

git remote set-url origin https://framagit.org/hubzilla/core.git
and
git pull https://framagit.org/hubzilla/core.git master

Wouldn't it be better if your work was directly available in the official(s) repository(s)?

Harald Eilertsen

Wed, 14 Dec 2022 18:34:36 +0000

@Scott M. Stolz Yeah, that's because the addon (and widget) repositories goes into their own subdirectory.

That is, the ./extend/addon/hzaddon directory is a separate git-repo that is not part of the core repo. Everything under it belongs to the hzaddons repo.

You can't have two repositories in the same root.

There's ways to work around it, though: put everything you need under your theme dir, and when the theme is activated the first time, it symlinks the different parts to their proper places in the file system. The addon logic do something similar for the installed addon repositories.

Scott M. Stolz

Wed, 14 Dec 2022 18:40:10 +0000 last edited: Wed, 14 Dec 2022 18:47:14 +0000

@Dan d'Auge

Wouldn't it be better if your work was directly available in the official(s) repository(s)?

I'd love all or part of it to be in the official repositories. But the challenge is that I have an entirely different use case than Streams or Hubzilla.

Hubzilla and Streams are focused on decentralized social media. I'm focused on commercializing the software so small businesses, content websites, and non-profits can build a website and have a social presence all-in-one.

Also, right now Neuhub is a proof of concept. No one took me seriously until they started seeing code developed. If the maintainers of Hubzilla and Streams want to incorporate my code, I'd love it.

The second challenge is that I am trying to support both Streams and Hubzilla, so having it in a separate repository speeds up development and testing. I also don't have to wait for the maintainers of Hubzilla or Streams to approve my submissions.

I'm guessing all or part of it will eventually find its way into Hubzilla. But that's not up to me.

P.S. When I say commercialize, I mean that commercial entities can use the software. Neuhub will always be MIT licensed.

Scott M. Stolz

Wed, 14 Dec 2022 18:55:53 +0000

@Harald Eilertsen The challenge is that I want to use the same widgets in multiple themes and don't want to have to update dozens of copies of the same file for one change.

Widgets aren't really a problem since I can give widgets unique names that won't conflict. It's unlikely that anyone else will prefix their widgets with "neuhub."

Add-ons are an issue though because as far as I can tell, the name of the addon and module must match the URL you want to use. So if you want to use example.com/article then your addon and module must be named Article. This can lead to conflicts if not managed.

Harald Eilertsen

Wed, 14 Dec 2022 19:16:30 +0000

@Scott M. Stolz

The challenge is that I want to use the same widgets in multiple themes

Makes sense.

One way could be to have separate repos for each (neuhub-widgets, neuhub-theme, neuhub-addons), and then just install each part separately using the ./util/add_{addon,widget,theme}_repo scripts.

Not sure what to do about path/module conflicts though. That's potentially a more tricky issue.

Scott M. Stolz

Wed, 14 Dec 2022 19:19:27 +0000

@Harald Eilertsen

One way could be to have separate repos for each (neuhub-widgets, neuhub-theme, neuhub-addons), and then just install each part separately using the ./util/add_{addon,widget,theme}_repo scripts.

My concern with that the themes are dependent on the widgets. I want to avoid a scenario where someone only downloads part of it and it doesn't work.

Harald Eilertsen

Wed, 14 Dec 2022 19:40:39 +0000

@Scott M. Stolz I understand that, but I'm not sure how to solve it elegantly as my understanding of architecture is right now. You can always check that everything is in place within the theme, and give a helpful error message if not.

Scott M. Stolz

Wed, 14 Dec 2022 20:34:37 +0000

@Harald Eilertsen That's true. A simple check to see if the required file exists would mitigate that. That would also mean that people could install the widgets without the themes if they wanted. Because the widgets will work without the themes, but the themes won't work without the widgets. Well, technically the themes will work without the widgets, but stuff would be missing.

On the topic of file conflicts...

Based on the .gitignore file, addon/, widget/, view/theme/*, and custom/ directories are safe places to upload stuff. I was also told Zotlabs/SiteModule is also a safe place to upload stuff (even though it is not in the .gitignore file).

That means that my addons, modules, widgets, and themes won't get overwritten by Hubzilla. The risk is that other addons, modules, and widgets written by third-parties might use the same names and same file locations, causing a conflict.

I can make my stuff so it doesn't conflict with Hubzilla, but I can't guarantee it won't conflict with someone else's custom code.

If I use repo scripts (like Hubzilla addons uses), how does that handle duplicate module and addon names?

Harald Eilertsen

Wed, 14 Dec 2022 22:51:23 +0000

@Scott M. Stolz

If I use repo scripts (like Hubzilla addons uses), how does that handle duplicate module and addon names?

It doesn't. That is, it will iterate over the subdirs in each repo in order, and symlink them to the addons dir. If the target dir already exist it will skip it.

So if addon repo A has a addon foo, and repo B also has a foo addon, only A's foo will be installed. But each addon can have their own modules within their subdir, so I don't think that's going to be a problem. I can check a bit more tomorrow.

Scott M. Stolz

Wed, 14 Dec 2022 23:25:29 +0000

@Harald Eilertsen I know that the module must have the same name of the URL. That can't be overridden. But if it were possible to change the addon name to something unique, then the modules would only conflict if the addon was enabled... in theory.

Harald Eilertsen

Thu, 15 Dec 2022 09:05:38 +0000 last edited: Thu, 15 Dec 2022 09:06:33 +0000

@Scott M. Stolz

I know that the module must have the same name of the URL

No, that's not entirely correct, you can register the URL you want, see for example the Superblock addon, where the module is called Mod_Superblock.php while the route is baseurl/superblock.

And these routes will override the modules provided in Zotlabs/SiteModule and Zotlabs/Module.

Modules in Zotlabs/SiteModule and Zotlabs/Module must have the same name as the route, only with a capital first letter.

Scott M. Stolz

Thu, 15 Dec 2022 10:55:26 +0000 last edited: Thu, 15 Dec 2022 10:58:40 +0000

So, we have covered widgets, themes, and addons.

How do we handle files in the custom folder or added to the Hubzilla core?

For example, Neuhub widgets are dependent on WidgetInterface, which is a file included in the Streams core but not the Hubzilla core. I've included the file in Neuhub so it gets uploaded to Hubzilla.

https://github.com/WisTex/Neuhub/blob/main/Zotlabs/Widget/WidgetInterface.php

And I will have some custom code that would be cumbersome to turn into an addon or module. For example, if I generate admin pages in PHPRunner, those would most likely be uploaded to its own folder.

Perhaps instead of depending on the ./util/add_{addon,widget,theme}_repo scripts, a util script that installs all of Neuhub would be better. Unless there is a a util for custom code too.

Harald Eilertsen

Thu, 15 Dec 2022 21:18:49 +0000 last edited: Thu, 15 Dec 2022 21:19:06 +0000

@Scott M. Stolz I haven't seen any other scripts suitable for handling completely custom code. Making your own is absolutely an option worth exploring I think. Could even be part of the setup routine for the theme. There's many ways leading to Rome, it's just about finding the one you're most comfortable with :)