pseudocode demonstrating collector behavior

collector-pseudo.php

<?php

class DisplayController {
  protected function renderBlocks() {
    $collector = new \Drupal\Core\Asset\AssetCollector();
    $bag = new \Drupal\Core\Asset\AssetBag();
    $collector->setBag($bag);
    // So now there's a bag in the collector, and ONLY my code right here has
    // access to it.
    $collector->setDefaults('css', array('group' => CSS_AGGREGATE_DEFAULT));
    // And now the collector will ensure that that specific default value will
    // always be correctly injected into any CSS assets created by its factory
    // methods.

    foreach ($this->display->getBlocks() as $block) {
      // $block is now an instance of BlockPluginInterface with a getAssets()
      // method; it's got its configuration injected, blah blah. Ready to render.

      // set a default that's specific to THIS particular block, but that is not
      // the responsibility of the block plugin to define, or maybe even know about.
      $collector->setDefaults('css',
        array('module' => something_that_gets_the_module_that_defined_the_block_plugin($block)));

      // now, lock the object using a unique value that only this class, or even
      // possibly even this method, will have access to. this assures us that
      // the exact defaults we want will be propagated onto any produced assets.
      $collector->lock($this);

      // inject the collector. this both makes it easier for the block plugin
      // to designate the assets it needs (factories make that easier), and
      // we are assured that certain values will be set on any of those assets
      // created by the block.
      $block->getAssets($collector);


    }
    foreach ($bag->getJs() as $asset) {
      print $asset->getSourcePath(); // for our asset given below, this would print 'path/to/file.js'
      $asset->clearDependencies(); // who knows why we'd want to do this...but we could.
    }
    // now, my $bag has all the assets declared by the block. i can do whatever
    // i want, like merging it in to the bigger bag i already have on the
    // HtmlFragment i'm building up.
    $this->htmlFragment->addBag($bag);
  }
}

class Block {
  public function getAssets(\Drupal\Core\Asset\AssetCollector $collector) {
    // calling create automatically adds the asset to the bag injected in the collector
    $collector->create('css', 'file', 'path/to/file.css', array('weight' => -20));

    // but the collector also returns the created asset, so the block can call
    // methods that aren't exposed in the factory interface to do additional
    // things to the asset...which just updates it in place in the bag.
    $asset = $collector->createJsFileAsset('path/to/file.js');
    $asset->addDependency('system', 'jquery');
  }
}