NestContainer

O
K, that wasn't so complicated. This is. Occasionally we want to have a whole bunch of stuff in the same kind of container, but occasionally other things should intervene. Specifically, we need this functionality to put all of the names on the main people page, with the categories headlines interspersed. To represent the desired containment hierarchy graphically:
  • Container:
    • String: <h3>Faculty</h3>
    • BulletColumnsContainer:
      • Professor A
      • Professor B
      • Professor C
      • etc.
    • String: <h3>Masters in Computer Science Program</h3>
    • BulletColumnsContainer:
      • Instructor A
      • Instructor B
      • Instructor C
      • etc.
    • etc.

In this example, we have a BulletColumnsContainer nested within a Container. Most of the stuff that gets inserted into this nesting (people's names) ends up inside of a BulletColumnsContainer, but the occasional item (a headline) is outside of any BulletColumnsContainer, just in the Container.

We use NestContainer to accomplish this. A NestContainer object is constructed with a list of constructors for the different levels of containment. In the example above, it would be constructed like this: 

nc = NestContainer(Container, BulletColumnsContainer)
the object is then used like any other container (with the exception that it only supports the append method; this does not turn out to be a problematic restriction, and makes for more efficient code). When an object is inserted into the NestContainer (via nc.append(obj)), it is placed inside of a BulletColumnsContainer which itself is inside a Container which is inside whatever contains nc.

To convince NestContainer to insert an object higher up the containment hierarchy, use the NestContainer.Out(object, up) function. object is the object to be inserted, and up is the number of levels up through the containment hierarchy that the object should be inserted. So to insert the headlines in the example above (which are one level up from normal), we would use 

nc.append(NestContainer.Out("<h3>Faculty</h3>", 1))

So the constructed containment hierarchy looks like this:

  • NestContainer:
    • NestContainer.Out("<h3>Faculty</h3>", 1)
    • Professor A
    • Professor B
    • Professor C
    • etc.
    • NestContainer.Out("<h3>Masters in Computer Science Program</h3>", 1)
    • Instructor A
    • Instructor B
    • Instructor C

NestContainer takes care of turning that into the hierarchy described above.

This class is hard to understand without seeing it in action. Check out how it's used in the people page.