API reference

This document covers different APIs that Tome provides.

Events

  • \Drupal\tome_static\Event\TomeStaticEvents::COLLECT_PATHS (example)
    This event is fired when collecting paths for the static generator. It can be used to provide or modify paths, which is useful if there are specific paths you want to be included that Tome may have missed. If you want to exclude a path, consider setting the "tome_static_path_exclude" setting.
  • \Drupal\tome_static\Event\TomeStaticEvents::PATH_PLACEHOLDER (example)
    This event is fired when replacing a path placeholder. This is useful if you implemented the "TomeStaticEvents::COLLECT_PATHS" event and wanted to provide an entity specific route that is expensive to load, so instead you provided a placeholder. This is how Tome can process so many entity paths without running out of memory.
  • \Drupal\tome_static\Event\TomeStaticEvents::REQUEST_PREPARE (example)
    This event is fired when preparing for a new request. Drupal isn't really designed to handle multiple requests in one bootstrap, but Tome tries to get around this by resetting the global and container state to avoid any request specific behavior. This would be useful if you needed to reset a request specific cache for your own services.
  • \Drupal\tome_static\Event\TomeStaticEvents::MODIFY_HTML (example)
    This event is fired when finding paths related to an HTML document. You can use it to make any modifications to HTML, ideally related to finding paths to transform and add to the list of paths to invoke. Specifically, this is used for transforming links that include query parameters to paths that will work with the static site (i.e. ?page=1 -> /page/1).
  • \Drupal\tome_static\Event\TomeStaticEvents::MODIFY_DESTINATION (example)
    This event is fired when determining the destination for a path. If you've transformed a path in HTML with the "TomeStaticEvents::MODIFY_HTML" event, you'll also want to make sure the destination for that path matches your modifications. This event is fired before "index.html" is appended to paths without an extension.
  • \Drupal\tome_static\Event\TomeStaticEvents::FILE_SAVED
    This event is fired anytime a file is saved by the static generator, including static assets that are copied from the filesystem like images or stylesheets. This is the only unused event in Tome, and exists to enable other modules to sync the static export to an external service when they're saved.
  • \Drupal\tome_sync\Event\TomeSyncEvents::EXPORT_CONTENT (example)
    This event is fired after a single content entity is exported. This should not be be used to modify the JSON output of the exporter (use normalizers for that), but can be used to export assets  related to the content.
  • \Drupal\tome_sync\Event\TomeSyncEvents::DELETE_CONTENT (example)
    This event is fired after a single content entity is deleted.
  • \Drupal\tome_sync\Event\TomeSyncEvents::IMPORT_CONTENT (example)
    This event is fired after a single content entity is imported (created or updated).
  • \Drupal\tome_sync\Event\TomeSyncEvents::EXPORT_ALL (example)
    This event is fired after the entire export process is complete.
  • \Drupal\tome_sync\Event\TomeSyncEvents::IMPORT_ALL (example)
    This event is fired after the entire import process is complete. Note that this event is also fired after partial imports are complete.

Using the tome_static.generator service

Beyond what's documented in the static generator's interface, it can be hard to know how to accurately generate static pages manually. Here's a documented code snippet that goes over almost everything the static command and form does:

<?php

/** @var \Drupal\tome_static\StaticGeneratorInterface $static */
$static = \Drupal::service('tome_static.generator');

/** @var \Drupal\tome_static\RequestPreparer $request_preparer */
$request_preparer = \Drupal::service('tome_static.request_preparer');

// Prepare for a new request. This is necessary so that static caches in Drupal
// can be reset between multiple requests in one bootstrap.
$request_preparer->prepareForRequest();

// Request an arbitrary path. "$invoke_paths" at this point is anything that
// needs to be copied (an existing file) or requested (an image derivative,
// other paths, etc.)
$invoke_paths = $static->requestPath('/foo');

// Export paths will try to copy or remove as many paths as possible without
// making a new internal request.
$invoke_paths = $static->exportPaths($invoke_paths);

// The remaining invoke paths need to be handled in new requests.
foreach ($invoke_paths as $path) {
  // Since we are only trying to export one path, restrict new requests to
  // paths with extensions, which are probably RSS feeds and image derivatives.
  if (pathinfo($path, PATHINFO_EXTENSION)) {
    $request_preparer->prepareForRequest();
    // This could return more paths, but we're ignoring that for simplicity.
    $static->requestPath($path);
  }
}