2022-10-03, 06:30 AM
G'day MyBB admins, community members, and staff,
I invite you to explore the MyBB 1.9 code I've been writing, which is now - although quite rough, and not free from errors - ready for testing.
This code is focussed on the theme system, and in particular on the ACP Themes and Plugins modules.
You can download it from my personal 1.9 fork.
It is hopefully suitable for both installations and upgrades, but definitely not for production use. There are known errors, and it is incomplete.
All feedback is welcome, especially regarding the theme system and its ACP UI, but please first check the TODO list below in case the issue is already queued.
From tomorrow, I will be without my development environment for a few days. Leading up to that, I have worked hard to put together code that can be tested in the meantime. I will resume development when I return to my development environment.
I will try to respond to any feedback shared before I leave, in approximately seventeen hours.
A couple of points of note:
The basic idea
Please first see the official spec (linked above). The extensions/amendments to that spec of my code are basically as follows:
The theme system as a whole is independent of the database other than for global and user default theme settings: it is otherwise entirely filesystem-based.
Both themes proper and plugins can supply "themelets" (see the spec). Themelets in my code have two basic directories ("modes"):
Plugins must now be uploaded via a zip archive, which MyBB unpacks and auto-installs. This applies to both initial installation as well as upgrade. Changes have been made to plugin structure including the addition of a
Features from 1.8 not (yet) migrated
TODO
Aside from those yet-to-be-migrated features, here's a slightly cleaned up version of my TODO list for this code (which I continue to develop) in no particular order:
I invite you to explore the MyBB 1.9 code I've been writing, which is now - although quite rough, and not free from errors - ready for testing.
This code is focussed on the theme system, and in particular on the ACP Themes and Plugins modules.
You can download it from my personal 1.9 fork.
It is hopefully suitable for both installations and upgrades, but definitely not for production use. There are known errors, and it is incomplete.
All feedback is welcome, especially regarding the theme system and its ACP UI, but please first check the TODO list below in case the issue is already queued.
From tomorrow, I will be without my development environment for a few days. Leading up to that, I have worked hard to put together code that can be tested in the meantime. I will resume development when I return to my development environment.
I will try to respond to any feedback shared before I leave, in approximately seventeen hours.
A couple of points of note:
- Although I am a staff developer, I have developed this code without consultation beyond some exchanges, including on the spec, with dvz, who does not agree with all of my design decisions, and it is not official in any sense. It might or might not eventually be accepted by staff and the community, with or without modifications. At this point, it simply serves as a basis for exploration, evaluation, and comment. I have not even discussed with anybody else my intention to start this thread.
- There are some deliberate deviations from the official spec, however, I intend for inadvertent deviations (which exist) to be corrected.
The basic idea
Please first see the official spec (linked above). The extensions/amendments to that spec of my code are basically as follows:
The theme system as a whole is independent of the database other than for global and user default theme settings: it is otherwise entirely filesystem-based.
Both themes proper and plugins can supply "themelets" (see the spec). Themelets in my code have two basic directories ("modes"):
current and devdist. The current directory/mode is intended for production use: in this mode, board themes can be derived from installed core/original themes, with only board themes being mutable. The devdist directory is intended for developers of a core/original theme to work on that theme (and then from which to distribute a new release of the theme) without modifying the contents of the current (production) version of the theme. "Development and distribution" (devdist) mode can be toggled on/off from the top of every page in the ACP Themes module, as well as via the equivalent Board Settings » General Configuration » Development Mode (Themelets) setting.Plugins must now be uploaded via a zip archive, which MyBB unpacks and auto-installs. This applies to both initial installation as well as upgrade. Changes have been made to plugin structure including the addition of a
plugin.json resource file which replaces the *_info() plugin function.Features from 1.8 not (yet) migrated
- The equivalent of "Find Updated Templates".
- The Twig filesystem-based template equivalent of 1.8's
find_replace_templatesets().
- The Twig filesystem-based template equivalent of the 1.8 ACP Template module's "Search/Replace" functionality.
- Global templates. If the decision is to continue to support this feature, my suggestion is that it be supported via a unique theme with codename
board.global. This could derive from acore.globaltheme if it is decided that any core-supplied templates should be globals.
- Template Set semantics, in which a theme+stylesheets can be associated with an independent set of templates: on the current 1.9 approach, templates are part of the theme itself, rather than being a separate set. If the decision is that this functionality should be supported, my suggestion is to support it by allowing the specification for a theme of not just its parent, but also of its "parent for templates". Thus, it could inherit its stylesheets separately from its templates.
- Inheritance of theme properties and stylesheet manifest/ordering.
TODO
Aside from those yet-to-be-migrated features, here's a slightly cleaned up version of my TODO list for this code (which I continue to develop) in no particular order:
- On theme upgrade: if the
stylesheetsproperty has changed from the prior version, flag in derived themelets that it needs updating.
- Require on MyBB version upgrade that the upgrade script is always run so that at least (1) the version stored in the DB is always up to date, so we know which version number to archive the default theme to, and (2) the default theme actually *is* archived. To ensure that this requirement is met, on every page load, check the version stored in the DB against the version in code, and if they differ, refuse to show the page in question unless it is the upgrade script; for other pages, link to the upgrade script.
- When breaking inheritance upon saving a themelet resource in the ACP, store its inheritance data in the relevant JSON file.
- Update if required any ACP reporting modules where the log contents (esp. supplied arbitrary parameters) have been modified in
admin/modules/style/themes.php.
- Warn, upon attempting to export a theme, when changes applied by the 1.9 equivalent of
find_replace_templatesets(), and provide a simple means of reverting them prior to export.
- Remove redundant functions/files.
- Prevent the duplication of the core theme as a sibling.
- Ensure that the
derivationsproperty of the themeresources.jsonfile is correctly set when importing/duplicating themes.
- Check through admin/modules/style/themes.php for:
-
- Missing hooks.
- Missing admin logging for template-related actions.
-
- Update the functionality of the Browse Themes tab in the ACP Themes module.
- Update PHPDoc blocks as required.
- Check it's a directory not a file before warning in Plugins page that a staged plugin file is non-existent/unreadable.
- Check whether a plugin's/theme's codename matches its directory when installing/importing (in particular in
get_staged_plugins()andget_staged_themes()).
- Resolve the redundancy in which the VERSION constant in
inc/src/Application.phpis duplicated by MyBB::$version ininc/class_core.php.
- Update the System Health => Check Templates code to handle FS templates.
- Update debug_page() for FS templates.
- In xmlhttp.php, replace the commented-out eval()s with renderings of Twig templates (there don't yet seem to be appropriate existing Twig templates).
- Modify the plugin unzip code to use a temporary directory for initial unzip rather than the staging directory.
- Move hard-coded language strings in inc/functions_themes.php into a language file.
- Rather than alternative
_keyplugin.json properties, provide for this implicitly in the main property, per https://discord.com/channels/21587684763...4313283644
- Update copyright notices on all files: 1.8 => 1.9. Update copyright date notice for modded files to 2022.
- Generate and store information about new conflicts with board themes that descend from newly upgraded/downgraded themes (see the corresponding TODO currently on lines 509-510 in
admin/modules/style/themes.php).
- Add sub-tabs to the stylesheet property editing ACP page.
- Using Javascript, make the template listing collapsible/expandable.
- Add quick link actions in the template listing to add and/or delete subdirectories (recursively deleting all dirs/files in those subdirectories).
- When visiting the root ACP Theme page, check for themes in the staging directory, and offer to install or delete them (indicating whether it appears that they are already installed), as we already do for the ACP Plugins page.
- Add an "Archive this plugin's current themelet" button to the ACP Plugins page. Indicate to developers that immediately after releasing a plugin version they should click this button on their development installation. Then, they can go ahead and modify their plugin's themelet on that installation, and the plugin's version number can (when desired) be updated.
- Add to the requirements check a test for being able to write to the filesystem everywhere below the root in general, but to
inc/plugins,inc/themesdirectories, andinc/themes/core.defaultin particular.
- Disable the Twig cache when in development mode.
- Correct the upgrade message which says "All templates reverted" or something like that when what was actually accomplished was the installation of the core theme.
- Stipulate somewhere/somehow that stylesheet names may not begin with
ext.- that is reserved for indicating that the stylesheet is inherited from a plugin with the codename followext..
- Implement JSON file validation functions which check both for the existence of required properties and the non-existence of invalid properties: e.g.,
validate_theme_properties(),validate_plugin_properties(),validate_plugin_resources(), etc.
