[Feature Request] Implement mod.php catalog and index for overboards #94

Maybe check upstream.
As of now trying to open the catalog or the index from a mod session results in an error, as the functionality simply isn't there.

A pain point is that to even just know which boards to include in anything of an overboard, one needs to load the appropriate config file and it's settings from there

This will likely need an upstream refactor on how mod pages are resolved.
Notably, the overboard is generated by a "theme" (vichan nonsense name for plugins), and vichan mod page resolution is tightly copuled to vichan internals.
The page resolution functions have no way to know that themes even exist, much less ask theme to generate pages for theme.

The idea is: refactor themes to use an object interface. A theme plugin should be queriable by vichan to know which pages it adds (and what's the name of such pages), while the ability to write any output should be sequested away from the themes and instead enabled via dependency injection.
In this manner, the theme doesn't have to know if or where exactly to write the page.

interface ThemePlugin {
  /**
   * Returns an array of key-value pairs, where each cople is the name of the pages the plugin offers to generate and the path ot would like vichan to put them in.
   * Eg
   *  [
   *    'news' => 'news.html',
   *    'overboard_index' => '/overboard/index.html',
   *    'overboard_catalog' => '/overboard/catalog.html',
   *    ...
   *  ]
   */
  function query_pages();
  
  /**
   * Tells the theme plugin to build some pages.
   * $application is the application god-object to provide cache, db access, etc.
   * $output_controller is an interface of some kind which wraps the write calls and enables vichan to redirect the theme writes to whereever it wants.
   * $request_info: bad name for an object/array/whatever that holds information about the request, if the user is a mod, is from tor, etc.
   * $pages is an array with the pages that the theme should generate. Null for all.
   *
   * Returns an key-value array of built pages, where each key is the name of the page (see query_pages()) and the value a twig handle/html string/something that contains the page to be displayed by vichan
   */
  function build_pages($application, $output_controller, $request_info, $pages);
}

Also we need to find a way to pass info.php content to it. Maybe just use the function info.php names to load the theme plugin?

This will likely need an upstream refactor on how mod pages are resolved. Notably, the overboard is generated by a "theme" (vichan nonsense name for plugins), and vichan mod page resolution is tightly copuled to vichan internals. The page resolution functions have no way to know that themes even exist, much less ask theme to generate pages for theme. The idea is: refactor themes to use an object interface. A theme plugin should be queriable by vichan to know which pages it adds (and what's the name of such pages), while the ability to write any output should be sequested away from the themes and instead enabled via dependency injection. In this manner, the theme doesn't have to know if or where exactly to write the page. ```php interface ThemePlugin { /** * Returns an array of key-value pairs, where each cople is the name of the pages the plugin offers to generate and the path ot would like vichan to put them in. * Eg * [ * 'news' => 'news.html', * 'overboard_index' => '/overboard/index.html', * 'overboard_catalog' => '/overboard/catalog.html', * ... * ] */ function query_pages(); /** * Tells the theme plugin to build some pages. * $application is the application god-object to provide cache, db access, etc. * $output_controller is an interface of some kind which wraps the write calls and enables vichan to redirect the theme writes to whereever it wants. * $request_info: bad name for an object/array/whatever that holds information about the request, if the user is a mod, is from tor, etc. * $pages is an array with the pages that the theme should generate. Null for all. * * Returns an key-value array of built pages, where each key is the name of the page (see query_pages()) and the value a twig handle/html string/something that contains the page to be displayed by vichan */ function build_pages($application, $output_controller, $request_info, $pages); } ``` Also we need to find a way to pass info.php content to it. Maybe just use the function info.php names to load the theme plugin?

We also need a way to tell vichan to add the theme links to the dashboard

Still needs a good way to add an overboard as a thing to the system.
This version just implicitly declares it by adding an index to it

class PageInfo {
  /**
   * PATH_* constants: where Vichan should put the page.
   * This is needed to set up the output redirector and correctly resolve urls in mod.php
   */
  public const int PATH_APPEND_INDEX = 1; // Append the page in the site's root.
  public const int PATH_APPEND_STD_BOARDS = 1 << 1; // Append the page to all standard boards.
  public const int PATH_APPEND_OVER_BOARDS = 1 << 2; // Append the page to all overboards.

  /**
   * ACCESS_* constants: which kind of user SHOULD access the page. This is only really an hint for Vichan used for page resolution. The theme should still check the permissions of the user it's generating the page for.
   */
  public const int ACCESS_JANITOR_ONLY = 1 << 3; // Accessible only by janitors and above.
  public const int ACCESS_MODERATOR_ONLY = 1 << 4; // Accessible only by moderators and above.
  public const int ACCESS_ADMIN_ONLY = 1 << 5; // Accessible only by administrators.
  public const int ACCESS_STAFF_ONLY = ACCESS_JANITOR_ONLY; // Accessible only by staff members (syntactic sugar).

  /**
   * LINK_IN_* constants: where Vichan should put links to the page. Some places may try use $full_name to display the page, and fallback to $path otherwise. Some places may only use $path.
   */
  public const int LINK_IN_TOP_BAR = 1 << 6; // Link the page in the top bar.
  public const int LINK_IN_HOME = 1 << 7; // Link the page in the site's home.
  public const int LINK_IN_STAFF_DASH_EXTRA = 1 << 8; // Link the page in the staff's dashboard among the extras.
  public const int LINK_IN_THREAD_RETURN_BAR = 1 << 9; // Link the page in the return button bar of a thread. See #14
  
  public const int EXTRA_DECLARE_OVER_BOARD = 1 << 10; // Use to declare an overboard. If set, the PATH_APPEND_* and LINK_* constants are ignored. The relative page name will never be passed to buildPages().


  public int $flags; // A bitfield set with this class constants.
  public string $path; // Page path relative to the root set by PATH_* constants.
  public string $full_name; // Required if any LINK_IN_* or EXTRA_DECLARE_OVER_BOARD are set. Indicates the full name of the page or the board. Ignored otherwise.
}

interface ThemePlugin {
  /**
   * Called once to initialize the theme.
   * $context Vichan's god-object to provide cache, db access, etc.
   * $theme_info An array with the values set in the relative info.php. It's contents may have been cached by Vichan.
   * $theme_settings A key-value array with the theme's settings.
   */
  function setInfo(Context $context, array $theme_info, array $theme_settings);

  /**
   * Returns an array of key-value pairs, where each couple is the name of the pages the plugin offers to generate and a PageInfo object.
   * Vichan may cache this array.
   * Eg
   *  [
   *    'news' => PageInfo('/news.html', PATH_APPEND_INDEX | LINK_IN_TOP_BAR | LINK_IN_HOME | LINK_IN_STAFF_DASH_EXTRA, "News"),
   *    'edit_news' => PageInfo('/edit_news.html', PATH_APPEND_INDEX | ACCESS_MODERATOR_ONLY | LINK_IN_STAFF_DASH_EXTRA, "Edit news"),
   *    'overboards_index' => PageInfo('/index.html', PATH_APPEND_OVER_BOARDS | PATH_LINK_IN_INDEX),
   *    'random_overboard' => PageInfo('/r', EXTRA_DECLARE_OVERBOARD, "Random"),
   *    'sfw_overboard' => PageInfo('/sfw', EXTRA_DECLARE_OVERBOARD, "SFW"),
   *    'dump' => PageInfo('/dump', EXTRA_DECLARE_OVERBOARD | ACCESS_STAFF_ONLY, "Dump"),
   *    ...
   *  ]
   */
  function queryPages(): array;

  /**
   * Tells the theme plugin to build some pages.
   * $output_controller An interface of some kind which wraps the write calls and enables Vichan to redirect the theme's writes to whereever it wants.
   * $request_info Bad name for an object/array/whatever that holds information about the request, if the user is a mod, is from tor, IP, etc.
   * $pages array|string|null An array with the pages that the theme should generate. A single string for to generate a single page. Null for all.
   *
   * Returns an key-value array of built pages, where each key is the name of the page (see queryPages()) and the value a twig handle/html string/something that contains the page to be displayed by Vichan
   */
  function buildPages($output_controller, $request_info, mixed $pages): array;
}

Still needs a good way to add an overboard as a thing to the system. This version just implicitly declares it by adding an index to it ```php class PageInfo { /** * PATH_* constants: where Vichan should put the page. * This is needed to set up the output redirector and correctly resolve urls in mod.php */ public const int PATH_APPEND_INDEX = 1; // Append the page in the site's root. public const int PATH_APPEND_STD_BOARDS = 1 << 1; // Append the page to all standard boards. public const int PATH_APPEND_OVER_BOARDS = 1 << 2; // Append the page to all overboards. /** * ACCESS_* constants: which kind of user SHOULD access the page. This is only really an hint for Vichan used for page resolution. The theme should still check the permissions of the user it's generating the page for. */ public const int ACCESS_JANITOR_ONLY = 1 << 3; // Accessible only by janitors and above. public const int ACCESS_MODERATOR_ONLY = 1 << 4; // Accessible only by moderators and above. public const int ACCESS_ADMIN_ONLY = 1 << 5; // Accessible only by administrators. public const int ACCESS_STAFF_ONLY = ACCESS_JANITOR_ONLY; // Accessible only by staff members (syntactic sugar). /** * LINK_IN_* constants: where Vichan should put links to the page. Some places may try use $full_name to display the page, and fallback to $path otherwise. Some places may only use $path. */ public const int LINK_IN_TOP_BAR = 1 << 6; // Link the page in the top bar. public const int LINK_IN_HOME = 1 << 7; // Link the page in the site's home. public const int LINK_IN_STAFF_DASH_EXTRA = 1 << 8; // Link the page in the staff's dashboard among the extras. public const int LINK_IN_THREAD_RETURN_BAR = 1 << 9; // Link the page in the return button bar of a thread. See #14 public const int EXTRA_DECLARE_OVER_BOARD = 1 << 10; // Use to declare an overboard. If set, the PATH_APPEND_* and LINK_* constants are ignored. The relative page name will never be passed to buildPages(). public int $flags; // A bitfield set with this class constants. public string $path; // Page path relative to the root set by PATH_* constants. public string $full_name; // Required if any LINK_IN_* or EXTRA_DECLARE_OVER_BOARD are set. Indicates the full name of the page or the board. Ignored otherwise. } interface ThemePlugin { /** * Called once to initialize the theme. * $context Vichan's god-object to provide cache, db access, etc. * $theme_info An array with the values set in the relative info.php. It's contents may have been cached by Vichan. * $theme_settings A key-value array with the theme's settings. */ function setInfo(Context $context, array $theme_info, array $theme_settings); /** * Returns an array of key-value pairs, where each couple is the name of the pages the plugin offers to generate and a PageInfo object. * Vichan may cache this array. * Eg * [ * 'news' => PageInfo('/news.html', PATH_APPEND_INDEX | LINK_IN_TOP_BAR | LINK_IN_HOME | LINK_IN_STAFF_DASH_EXTRA, "News"), * 'edit_news' => PageInfo('/edit_news.html', PATH_APPEND_INDEX | ACCESS_MODERATOR_ONLY | LINK_IN_STAFF_DASH_EXTRA, "Edit news"), * 'overboards_index' => PageInfo('/index.html', PATH_APPEND_OVER_BOARDS | PATH_LINK_IN_INDEX), * 'random_overboard' => PageInfo('/r', EXTRA_DECLARE_OVERBOARD, "Random"), * 'sfw_overboard' => PageInfo('/sfw', EXTRA_DECLARE_OVERBOARD, "SFW"), * 'dump' => PageInfo('/dump', EXTRA_DECLARE_OVERBOARD | ACCESS_STAFF_ONLY, "Dump"), * ... * ] */ function queryPages(): array; /** * Tells the theme plugin to build some pages. * $output_controller An interface of some kind which wraps the write calls and enables Vichan to redirect the theme's writes to whereever it wants. * $request_info Bad name for an object/array/whatever that holds information about the request, if the user is a mod, is from tor, IP, etc. * $pages array|string|null An array with the pages that the theme should generate. A single string for to generate a single page. Null for all. * * Returns an key-value array of built pages, where each key is the name of the page (see queryPages()) and the value a twig handle/html string/something that contains the page to be displayed by Vichan */ function buildPages($output_controller, $request_info, mixed $pages): array; } ```

Issue: we declare a plugin with PAGE_PATH_APPEND_OVER_BOARDS, then eventually we call buildPage(). How do we tell the plugin which board/page configuration are we trying to access?

We cannot let plugins query Vichan for the overboards to generate data for queryPages(), as it will introduce a dependency in the order by which plugins are called

Solution: $request_info in buildPages() should include the board name as an optional field that may be left unspecified by Vichan.

Or do we have a case where Vichan may have to specify some but not all boards? Do we have a case where there may be a multiplicity of paths the page is supposed to be appended to, that aren't boards?

Taken #14 into account