Merge lp:~methanal-developers/methanal/extend-tab-api into lp:methanal

[Jonathan Jacobs]

[Tristan Seligmann (mithrandi)]

review: Approve

[lp:~methanal-developers/methanal/extend-tab-api]

141. By Jonathan Jacobs on 2010-05-23

Rename private TabView method to be more accurate.

142. By Jonathan Jacobs on 2010-05-23

Fix test breakage.

=== modified file 'methanal/errors.py'
--- methanal/errors.py	2009-09-17 16:36:09 +0000
+++ methanal/errors.py	2010-05-23 13:10:50 +0000
@@ -9,3 +9,10 @@
     """
     An invalid enumeration value was specified.
     """
+
+
+
+class InvalidIdentifier(ValueError):
+    """
+    An invalid identifier was specified.
+    """

=== modified file 'methanal/js/Methanal/Tests/TestWidgets.js'
--- methanal/js/Methanal/Tests/TestWidgets.js	2010-03-15 18:58:03 +0000
+++ methanal/js/Methanal/Tests/TestWidgets.js	2010-05-23 13:10:50 +0000
@@ -430,6 +430,7 @@
             node, _tabIDs, _tabGroups, topLevel || false, _makeThrobber);
         Methanal.Tests.Util.makeWidgetChildNode(tabView, 'div', 'throbber');
         Methanal.Tests.Util.makeWidgetChildNode(tabView, 'ul', 'labels');
+        Methanal.Tests.Util.makeWidgetChildNode(tabView, 'div', 'contents');
         document.body.appendChild(node);
         Methanal.Util.nodeInserted(tabView);
         return tabView;
@@ -449,6 +450,7 @@
             'group': group || null})
         tabView.addChildWidget(tab);
         Methanal.Tests.Util.makeWidgetChildNode(tab, 'content');
+        tabView.nodeById('contents').appendChild(tab.node);
         Methanal.Util.nodeInserted(tab);
         return tab;
     },
@@ -585,7 +587,7 @@
      */
     function test_groups(self) {
         function checkGroup(group) {
-            var groupNode = tabView._groups[group.id];
+            var groupNode = tabView._groups[group.id].content;
             self.assertNotIdentical(groupNode, undefined);
             self.assertIdentical(
                 groupNode.getElementsByTagName('li').length,
@@ -614,7 +616,8 @@
 
     /**
      * Group visibility is determined by the visibility of the tabs it
-     * contains.
+     * contains. Removing all the tabs from a group will result in that group
+     * becoming invisible.
      */
     function test_groupVisibility(self) {
         var group1 = Methanal.Widgets.TabGroup(
@@ -627,7 +630,7 @@
         var tab3 = self.createTab(
             tabView, 'tab3', 'Tab 3', undefined, group1.id);
 
-        var node = tabView._groups[group1.id].parentNode;
+        var node = tabView._groups[group1.id].content.parentNode;
         tabView.hideTab(tab1);
         self.assertNodeVisible(node);
         tabView.hideTab(tab2);
@@ -636,4 +639,15 @@
         self.assertNodeHidden(node);
         tabView.showTab(tab3);
         self.assertNodeVisible(node);
+
+        // Stub out Nevow.Athena.Widget.detach.
+        function detach() {}
+
+        tab2.detach = detach;
+        tabView.removeTab(tab2);
+        self.assertNodeVisible(node);
+
+        tab3.detach = detach;
+        tabView.removeTab(tab3);
+        self.assertNodeHidden(node);
     });

=== modified file 'methanal/js/Methanal/Widgets.js'
--- methanal/js/Methanal/Widgets.js	2010-03-15 18:58:15 +0000
+++ methanal/js/Methanal/Widgets.js	2010-05-23 13:10:50 +0000
@@ -1440,25 +1440,158 @@
 
 
     /**
-     * Client-side handler for appending a tabs from the server-side.
-     */
-    function _appendTabsFromServer(self, widgetInfos, tabGroups) {
+     * Select the first visible tab.
+     */
+    function selectFirstVisibleTab(self) {
+        try {
+            self.selectTab(self.getFirstVisibleTab());
+        } catch (e) {
+            if (!(e instanceof Methanal.Widgets.UnknownTab)) {
+                throw e;
+            }
+        }
+    },
+
+
+    /**
+     * Client-side handler for updating tabs from the server-side.
+     *
+     * @param widgetInfos: New tab widgets to add.
+     *
+     * @type  tabIDsToRemove: C{Array} of C{String}
+     * @param tabIDsToRemove: Identifiers of L{methanal.widgets.Tab}s to remove.
+     *
+     * @param tabGroups: Tab groups.
+     */
+    function _updateTabsFromServer(self, widgetInfos, tabIDsToRemove, tabGroups) {
         self.throbber.start();
         self.tabGroups = tabGroups;
 
-        function _appendTab(widgetInfo) {
+        function _updateTab(widgetInfo) {
             var d = self.addChildWidgetFromWidgetInfo(widgetInfo);
-            d.addCallback(function (widget) {
-                self.tabIDs[widget.id] = true;
-                self.node.appendChild(widget.node);
-                Methanal.Util.nodeInserted(widget);
+            d.addCallback(function (tab) {
+                var oldTab = self._tabs[tab.id];
+                // If we are updating an existing tab then detach and remove
+                // the old one first. Selection state is transferred too.
+                if (oldTab !== undefined) {
+                    tab.selected = oldTab.selected;
+                    self._removeTabContent(oldTab);
+                }
+                self.tabIDs[tab.id] = true;
+                self.nodeById('contents').appendChild(tab.node);
+                Methanal.Util.nodeInserted(tab);
                 return null;
             });
             return d;
         }
 
-        var ds = Methanal.Util.map(_appendTab, widgetInfos);
-        return Divmod.Defer.gatherResults(ds);
+        var d = Divmod.Defer.gatherResults(
+            Methanal.Util.map(_updateTab, widgetInfos));
+        if (tabIDsToRemove.length > 0) {
+            d.addCallback(function () {
+                return self._removeTabsFromServer(tabIDsToRemove, tabGroups);
+            });
+        }
+        return d;
+    },
+
+
+    /**
+     * Remove a tab.
+     *
+     * Group visibility is updated too, meaning any groups that contain no
+     * visible tabs will be hidden.
+     */
+    function removeTab(self, tab) {
+        var d = self._removeTabContent(tab);
+        var label = self._labels[tab.id];
+        label.parentNode.removeChild(label);
+        delete self._labels[tab.id];
+        delete self._tabs[tab.id];
+        if (tab.group !== null) {
+            self._updateGroupVisiblity(tab.group);
+        }
+        return d;
+    },
+
+
+    /**
+     * Remove a tab widget's content.
+     */
+    function _removeTabContent(self, tab) {
+        self.nodeById('contents').removeChild(tab.node);
+        return tab.detach();
+    },
+
+
+    /**
+     * Client-side handler for removing tabs from the server-side.
+     *
+     * @type  tabIDs: C{Array} of C{String}
+     * @param tabIDs: Identifiers of L{methanal.widgets.Tab}s to remove.
+     *
+     * @param tabGroups: Tab groups.
+     */
+    function _removeTabsFromServer(self, tabIDs, tabGroups) {
+        self.tabGroups = tabGroups;
+        var wasSelected = false;
+
+        function _removeTab(tabID) {
+            var tab = self.getTab(tabID);
+            wasSelected |= tab.selected;
+            return self.removeTab(tab);
+        }
+
+        var d = Divmod.Defer.gatherResults(
+            Methanal.Util.map(_removeTab, tabIDs));
+
+        d.addCallback(function () {
+            // If one of the removed tabs was selected then select another one.
+            if (wasSelected) {
+                self.selectFirstVisibleTab();
+            }
+            return null;
+        });
+        return d;
+    },
+
+
+    /**
+     * Create or update a tab label.
+     *
+     * Tab group titles will be updated too.
+     */
+    function _createLabel(self, tab) {
+        var D = Methanal.Util.DOMBuilder(self.node.ownerDocument);
+        var label = D('li', {'class': 'methanal-tab-label'}, [
+            D('a', {}, [tab.title])]);
+        label.onclick = function onclick(node) {
+            self.selectTab(tab);
+        };
+
+        var labelClassName = tab.getLabelClassName();
+        if (labelClassName) {
+            Methanal.Util.addElementClass(label, labelClassName);
+        }
+
+        var labelParent = self.nodeById('labels');
+        if (tab.group !== null) {
+            var nodes = self._getGroupNodes(tab.group);
+            Methanal.Util.replaceNodeText(
+                nodes.label, self.getGroup(tab.group).title);
+            self._updateGroupVisiblity(tab.group);
+            labelParent = nodes.content;
+        }
+
+        var oldLabel = self._labels[tab.id];
+        // If a label for this tab already exists, then update that label.
+        if (oldLabel !== undefined) {
+            oldLabel.parentNode.replaceChild(label, oldLabel);
+        } else {
+            labelParent.appendChild(label);
+        }
+
+        self._labels[tab.id] = label;
     },
 
 
@@ -1470,22 +1603,24 @@
      */
     function _createGroupNode(self, id) {
         var title = self.getGroup(id).title;
-
         var D = Methanal.Util.DOMBuilder(self.node.ownerDocument);
-        var group = D('ul', {'class': 'methanal-tab-group-tabs'}, []);
-        self._groups[id] = group;
-        var groupInner = D(
+        var content = D('ul', {'class': 'methanal-tab-group-tabs'}, []);
+        var label = D('div', {'class': 'methanal-tab-group-label'}, [title]);
+        var inner = D(
             'li', {'class': 'methanal-tab-label methanal-tab-group'}, [
-                D('div', {'class': 'methanal-tab-group-label'}, [title]),
-                group]);
-        self.nodeById('labels').appendChild(groupInner);
+                label, content]);
+        self._groups[id] = {
+            'content': content,
+            'label': label};
+        self.nodeById('labels').appendChild(inner);
     },
 
 
     /**
-     * Get the DOM node for a group, creating it if it doesn't already exist.
+     * Get the DOM nodes for a group's container and label, creating them if
+     * they don't exist.
      */
-    function _getGroupNode(self, id) {
+    function _getGroupNodes(self, id) {
         if (!(id in self._groups)) {
             self._createGroupNode(id);
         }
@@ -1499,35 +1634,14 @@
      * A new label is created for C{tab}, based on L{Tab.title}, and an
      * C{onclick} handler attached.
      */
-    function appendTab(self, tab) {
-        function onclick(node) {
-            self.selectTab(tab);
-        }
-
-        var D = Methanal.Util.DOMBuilder(self.node.ownerDocument);
-        var label = D('li', {'class': 'methanal-tab-label'}, [
-            D('a', {}, [tab.title])]);
-        label.onclick = onclick;
-
-        var labelClassName = tab.getLabelClassName();
-        if (labelClassName) {
-            Methanal.Util.addElementClass(label, labelClassName);
-        }
-
-        self._labels[tab.id] = label;
+    function updateTab(self, tab) {
         self._tabs[tab.id] = tab;
-
-        var labelParent = self.nodeById('labels');
-        if (tab.group !== null) {
-            labelParent = self._getGroupNode(tab.group);
-            self._updateGroupVisiblity(tab.group);
-        }
-        labelParent.appendChild(label);
+        self._createLabel(tab);
 
         // If this tab's identifier matches the one we're supposed to select,
         // do it. Otherwise select this tab if its "selected" attribute is true
         // and no tab selection has been made yet.
-        if (tab.id == self._idToSelect) {
+        if (tab.id === self._idToSelect) {
             self._tabToSelect = tab;
         } else if (self._tabToSelect === undefined && tab.selected) {
             self._tabToSelect = tab;
@@ -1535,6 +1649,12 @@
     },
 
 
+    function appendTab(self, tab) {
+        Divmod.msg('DEPRECATED: Use Methanal.Widgets.TabView.updateTab');
+        return self.updateTab(tab);
+    },
+
+
     /**
      * Select a tab.
      *
@@ -1559,6 +1679,9 @@
         if (!self.fullyLoaded) {
             self._tabToSelect = tab;
             self._idToSelect = tab.id;
+        } else {
+            self._tabToSelect = undefined;
+            self._idToSelect = undefined;
         }
     },
 
@@ -1594,7 +1717,7 @@
 
         // Change the visibility of the group parent node, not the inner
         // container.
-        var groupNode = self._groups[groupID].parentNode;
+        var groupNode = self._getGroupNodes(groupID).content.parentNode;
         if (visible) {
             Methanal.Util.removeElementClass(groupNode, 'hidden');
         } else {
@@ -1638,13 +1761,7 @@
         tab.visible = false;
         // If we're hiding the selected tab, select the first visible tab.
         if (tab.selected) {
-            try {
-                self.selectTab(self.getFirstVisibleTab());
-            } catch (e) {
-                if (!(e instanceof Methanal.Widgets.UnknownTab)) {
-                    throw e;
-                }
-            }
+            self.selectFirstVisibleTab();
         }
 
         self._updateGroupVisiblity(tab.group);
@@ -1658,7 +1775,7 @@
      * finalised by calling L{_finishLoading}.
      */
     function loadedUp(self, tab) {
-        self.appendTab(tab);
+        self.updateTab(tab);
 
         delete self.tabIDs[tab.id];
         for (var id in self.tabIDs) {
@@ -1674,13 +1791,11 @@
      */
     function _finishLoading(self) {
         self.throbber.stop();
-        if (self.fullyLoaded) {
-            return;
-        }
-
-        self.fullyLoaded = true;
-        if (self._tabToSelect === undefined && self.childWidgets.length > 0) {
-            self._tabToSelect = self.childWidgets[0];
+        if (!self.fullyLoaded) {
+            self.fullyLoaded = true;
+            if (self._tabToSelect === undefined && self.childWidgets.length > 0) {
+                self._tabToSelect = self.childWidgets[0];
+            }
         }
         if (self._tabToSelect) {
             self.selectTab(self._tabToSelect);
@@ -1780,6 +1895,25 @@
 
 
     /**
+     * Set an Athena widget as the tab content.
+     */
+    function _setContentFromWidgetInfo(self, widgetInfo, abortFetch) {
+        var d = self.addChildWidgetFromWidgetInfo(widgetInfo);
+        d.addCallback(function (widget) {
+            if (abortFetch) {
+                return widget.detach();
+            } else {
+                self._setContent(widget.node);
+                self._currentWidget = widget;
+                Methanal.Util.nodeInserted(widget);
+            }
+            return null;
+        });
+        return d;
+    },
+
+
+    /**
      * Fetch the latest tab content from the server.
      *
      * If a fetch is already in progress it's result is discarded and a new
@@ -1801,16 +1935,7 @@
 
         var d = self.callRemote('getContent');
         d.addCallback(function (widgetInfo) {
-            return self.addChildWidgetFromWidgetInfo(widgetInfo);
-        });
-        d.addCallback(function (widget) {
-            if (abortFetch) {
-                return widget.detach();
-            } else {
-                self._setContent(widget.node);
-                self._currentWidget = widget;
-                Methanal.Util.nodeInserted(widget);
-            }
+            return self._setContentFromWidgetInfo(widgetInfo, abortFetch);
         });
         return d;
     },

=== modified file 'methanal/test/test_widgets.py'
--- methanal/test/test_widgets.py	2010-03-16 22:01:24 +0000
+++ methanal/test/test_widgets.py	2010-05-23 13:10:50 +0000
@@ -5,7 +5,7 @@
 
 from nevow import inevow
 
-from methanal import widgets
+from methanal import widgets, errors
 
 
 
@@ -24,12 +24,12 @@
 
     def test_create(self):
         """
-        Creating a L{TabView} widget initialises L{TabView._tabIDs} and
+        Creating a L{TabView} widget initialises L{TabView._tabsByID} and
         L{TabView.tabs} with the values originally specified.
         """
         self.assertEquals(
-            self.tabView._tabIDs,
-            set([u'id1', u'id2', u'id3']))
+            sorted(self.tabView._tabsByID.keys()),
+            [u'id1', u'id2', u'id3'])
         self.assertEquals(
             self.tabView.tabs,
             self.tabs)
@@ -38,7 +38,7 @@
     def test_createGroup(self):
         """
         Creating a L{methanal.widgets.TabView} widget initialises
-        L{methanal.widgets.TabView._tabIDs}, L{methanal.widgets.TabView.tabs}
+        L{methanal.widgets.TabView._tabsByID}, L{methanal.widgets.TabView.tabs}
         and L{methanal.widgets.TabView._tabGroups} with the values originally
         specified, tab groups are merged in and managed.
         """
@@ -49,71 +49,117 @@
             widgets.Tab(u'id5', u'Title 5', self.contentFactory)]
         tabView = widgets.TabView(tabs)
         self.assertEquals(
-            tabView._tabIDs,
-            set([u'id1', u'id2', u'id3', u'id4', u'id5']))
+            tabView.getTabIDs(),
+            [u'id1', u'id2', u'id3', u'id4', u'id5'])
         self.assertEquals(
             tabView._tabGroups,
             {u'group1': tabGroup})
 
 
-    def test_appendDuplicateTab(self):
-        """
-        Appending a L{methanal.widgets.Tab} widget with an C{id} attribute that
-        matches one already being managed raises C{ValueError}.
-        """
-        self.assertRaises(ValueError,
-            self.tabView.appendTab, self.tabView.tabs[0])
-
-
-    def test_appendTabs(self):
-        """
-        Appending tabs on the server side manages them and invokes methods
+    def test_updateTabs(self):
+        """
+        Updating tabs on the server side manages them and invokes methods
         on the client side to insert them.
         """
         self.result = None
 
         def callRemote(methodName, *a):
-            self.result = methodName == '_appendTabsFromServer'
+            self.result = methodName == '_updateTabsFromServer'
 
         tab = widgets.Tab(u'id4', u'Title 4', self.contentFactory)
         self.patch(self.tabView, 'callRemote', callRemote)
-        self.tabView.appendTabs([tab])
+        self.tabView.updateTabs([tab])
         self.assertTrue(self.result)
-        self.assertIn(u'id4', self.tabView._tabIDs)
+        self.assertNotIdentical(self.tabView.getTab(u'id4'), None)
         self.assertIdentical(self.tabView.tabs[-1], tab)
 
-
-    def test_appendDuplicateGroup(self):
-        """
-        Appending a L{methanal.widgets.TabGroup} widget with an C{id} attribute
-        that matches one already being managed raises C{ValueError}.
-        """
-        tabGroup = widgets.TabGroup(u'group1', u'Group', tabs=[
-            widgets.Tab(u'id4', u'Title 4', self.contentFactory)])
-        self.tabView._manageGroup(tabGroup)
-        self.assertRaises(ValueError,
-            self.tabView.appendGroup, tabGroup)
-
-
-    def test_appendGroup(self):
-        """
-        Appending a group on the server site manages it, and all the tabs it
+        replacementTab = widgets.Tab(u'id1', u'New title', self.contentFactory)
+        oldTab = self.tabView.getTab(u'id1')
+        self.tabView.updateTabs([replacementTab])
+        self.assertIdentical(self.tabView.getTab(u'id1'), replacementTab)
+        self.assertNotIn(oldTab, self.tabView.tabs)
+
+
+    def test_updateGroup(self):
+        """
+        Updating a group on the server site manages it, and all the tabs it
         contains, and invokes methods on the client side to insert them.
         """
         self.result = None
 
         def callRemote(methodName, *a):
-            self.result = methodName == '_appendTabsFromServer'
+            self.result = methodName == '_updateTabsFromServer'
 
         tab = widgets.Tab(u'id4', u'Title 4', self.contentFactory)
         group = widgets.TabGroup(u'group1', u'Group', tabs=[tab])
         self.patch(self.tabView, 'callRemote', callRemote)
-        self.tabView.appendGroup(group)
+        self.tabView.updateGroup(group)
         self.assertTrue(self.result)
-        self.assertIn(u'id4', self.tabView._tabIDs)
-        self.assertIn(u'group1', self.tabView._tabGroups)
+        self.assertNotIdentical(self.tabView.getTab(u'id4'), None)
+        self.assertNotIdentical(self.tabView.getGroup(u'group1'), None)
         self.assertIdentical(self.tabView.tabs[-1], tab)
 
+        # Update a group, and add a new tab.
+        newTab = widgets.Tab(u'id5', u'Title 5', self.contentFactory)
+        replacementGroup = widgets.TabGroup(
+            u'group1', u'New Group', tabs=[newTab])
+        self.tabView.updateGroup(replacementGroup)
+        self.assertIdentical(
+            self.tabView.getGroup(u'group1'), replacementGroup)
+        self.assertNotIdentical(self.tabView.getTab(u'id5'), None)
+        self.assertRaises(
+            errors.InvalidIdentifier, self.tabView.getTab, u'id4')
+        self.assertNotIn(tab, self.tabView.tabs)
+
+        # Remove a tab from a group.
+        self.tabView.removeTabs([newTab])
+        self.assertRaises(
+            errors.InvalidIdentifier, self.tabView.getTab, u'id5')
+        self.assertNotIn(newTab, self.tabView.getGroup(u'group1').tabs)
+
+
+    def test_removeTabs(self):
+        """
+        Removing tabs on the server side releases them and invokes methods on
+        the client side to remove them.
+        """
+        self.result = None
+
+        def callRemote(methodName, *a):
+            self.result = methodName == '_removeTabsFromServer'
+
+        self.patch(self.tabView, 'callRemote', callRemote)
+        tab = self.tabView.tabs[0]
+        self.tabView.removeTabs([tab])
+        self.assertTrue(self.result)
+        self.assertRaises(
+            errors.InvalidIdentifier, self.tabView.getTab, tab.id)
+
+
+    def test_invalidRemove(self):
+        """
+        Trying to remove an unmanaged tab results in C{ValueError} being
+        raised.
+        """
+        # Try a new tab.
+        self.assertRaises(ValueError,
+            self.tabView.removeTabs, [
+                widgets.Tab(u'id99', u'Title 1', self.contentFactory)])
+
+        # Try dupe an ID.
+        self.assertRaises(ValueError,
+            self.tabView.removeTabs, [
+                widgets.Tab(u'id1', u'Title 1', self.contentFactory)])
+
+
+    def test_repr(self):
+        """
+        L{methanal.widgets.TabView} has an accurate string representation.
+        """
+        self.assertEquals(
+            repr(self.tabView),
+            "<TabView topLevel=False tabs=%r>" % self.tabs)
+
 
 
 class StaticTabTests(unittest.TestCase):
@@ -140,6 +186,21 @@
         self.assertEquals(tab.contentFactory(), content * 2)
 
 
+    def test_repr(self):
+        """
+        L{methanal.widgets.Tab} (and by extension L{methanal.widgets.StaticTab})
+        has an accurate string representation.
+        """
+        tab = widgets.StaticTab(
+            id=u'id',
+            title=u'Title',
+            content=u'A content.')
+        self.assertEquals(
+            repr(tab),
+            "<StaticTab id=u'id' title=u'Title' selected=False group=None>")
+
+
+
 
 class TabGroupTests(unittest.TestCase):
     """
@@ -152,7 +213,40 @@
         tabs = [
             widgets.Tab(u'id1', u'Title 1', None),
             widgets.Tab(u'id2', u'Title 2', None)]
-        tabGroup = widgets.TabGroup(u'id', u'title', tabs=tabs)
+        tabGroup = widgets.TabGroup(u'id', u'Title', tabs=tabs)
         self.assertEquals(
             inevow.IAthenaTransportable(tabGroup).getInitialArguments(),
-            [u'id', u'title', [u'id1', u'id2']])
+            [u'id', u'Title', [u'id1', u'id2']])
+
+
+    def test_mergeGroups(self):
+        """
+        L{methanal.widgets.TabGroup.mergeGroups} will merge two
+        L{methanal.widgets.TabGroup}s together, preferring the metadata of the
+        second specified group.
+        """
+        tabs = [
+            widgets.Tab(u'id1', u'Title 1', None),
+            widgets.Tab(u'id2', u'Title 2', None)]
+        tabGroup1 = widgets.TabGroup(u'id', u'Title', tabs=tabs)
+        tabs = [
+            widgets.Tab(u'id3', u'Title 3', None)]
+        tabGroup2 = widgets.TabGroup(u'id', u'Hello', tabs=tabs)
+
+        newGroup = widgets.TabGroup.mergeGroups(tabGroup1, tabGroup2)
+        self.assertEquals(newGroup.id, u'id')
+        self.assertEquals(newGroup.title, u'Hello')
+        self.assertEquals(newGroup.tabs, tabGroup1.tabs + tabGroup2.tabs)
+
+
+    def test_repr(self):
+        """
+        L{methanal.widgets.TabGroup} has an accurate string representation.
+        """
+        tabs = [
+            widgets.Tab(u'id1', u'Title 1', None),
+            widgets.Tab(u'id2', u'Title 2', None)]
+        tabGroup = widgets.TabGroup(u'id', u'Title', tabs=tabs)
+        self.assertEquals(
+            repr(tabGroup),
+            "<TabGroup id=u'id' title=u'Title' tabs=%r>" % tabs)

=== modified file 'methanal/themes/methanal-base/methanal-tab-view.html'
--- methanal/themes/methanal-base/methanal-tab-view.html	2010-01-03 21:23:44 +0000
+++ methanal/themes/methanal-base/methanal-tab-view.html	2010-05-23 13:10:50 +0000
@@ -2,6 +2,6 @@
     <ul class="methanal-tab-labels" id="labels">
         <li id="throbber" class="methanal-tab-label" style="padding: 0 2px;"><img src="/static/Methanal/images/main-throbber.gif" style="height: 10px; width: 10px;" /></li>
     </ul>
-    <div style="clear: both;" nevow:render="tabContents" />
+    <div id="contents" style="clear: both;" nevow:render="tabContents" />
     <div class="terminator"></div>
 </div>

=== modified file 'methanal/widgets.py'
--- methanal/widgets.py	2010-03-14 01:24:31 +0000
+++ methanal/widgets.py	2010-05-23 13:10:50 +0000
@@ -11,6 +11,8 @@
 
 from twisted.internet.defer import maybeDeferred
 from twisted.python.components import registerAdapter
+from twisted.python.versions import Version
+from twisted.python.deprecate import deprecated
 
 from axiom.item import SQLAttribute
 
@@ -28,6 +30,7 @@
     ObjectSelectInput, SimpleForm, FormInput, LiveForm, SubmitAction,
     ActionButton, ActionContainer)
 from methanal.model import Value
+from methanal.errors import InvalidIdentifier
 
 
 
@@ -658,8 +661,8 @@
         the fragment part of the current URL to track which tab is selected,
         this behaviour supercedes L{Tab.selected}.
 
-    @type _tabIDs: C{set}
-    @ivar _tabIDs: Collection of unique tab IDs currently being managed.
+    @type _tabsByID: C{dict} mapping C{unicode} to L{methanal.widgets.Tab}
+    @ivar _tabsByID: Mapping of unique tab IDs to tabs currently being managed.
 
     @type _tabGroups: C{dict} mapping C{unicode} to
         L{methanal.widgets.TabGroup}
@@ -675,7 +678,7 @@
         @param tabs: Tab or tab groups to manage.
         """
         super(TabView, self).__init__(**kw)
-        self._tabIDs = set()
+        self._tabsByID = {}
         self._tabGroups = {}
         self.tabs = []
         self.topLevel = topLevel
@@ -689,76 +692,170 @@
                 self._manageTab(tabOrGroup)
 
 
+    def __repr__(self):
+        return '<%s topLevel=%r tabs=%r>' % (
+            type(self).__name__,
+            self.topLevel,
+            self.tabs)
+
+
     def _manageGroup(self, group):
         """
         Begin managing a L{methanal.widgets.TabGroup}.
 
-        Tabs contained in a group are B{not} managed, L{_manageTab} should be
-        called for each tab.
-
-        @raise ValueError: If the group's identifier matches one that is
-            already being managed.
+        Tabs contained in a group are B{not} managed automatically,
+        L{_manageTab} should be called for each tab.
         """
-        if group.id in self._tabGroups:
-            raise ValueError('%r is a duplicate tab group identifier in %r' % (
-                group.id, self))
         self._tabGroups[group.id] = group
 
 
-    def _manageTab(self, tab):
-        """
-        Begin managing a L{Tab} widget.
-
-        @raise ValueError: If the tab's identifier matches one that is already
-            being managed.
-        """
-        if tab.id in self._tabIDs:
+    def _manageTab(self, tab, overwrite=False):
+        """
+        Begin managing a L{methanal.widgets.Tab} widget.
+
+        If a tab identifier is already being managed it is released before
+        managing the new widget.
+        """
+        if tab.id in self._tabsByID:
+            self._releaseTab(self.getTab(tab.id))
+        self._tabsByID[tab.id] = tab
+        self.tabs.append(tab)
+        group = self._tabGroups.get(tab.group)
+        if group is not None:
+            group._manageTab(tab)
+
+
+    def _releaseTab(self, tab):
+        """
+        Stop managing a L{methanal.widgets.Tab} widget.
+        """
+        if tab not in self.tabs:
             raise ValueError(
-                '%r is a duplicate tab identifier in %r' % (tab.id, self))
-        self._tabIDs.add(tab.id)
-        self.tabs.append(tab)
-
-
+                '%r is not managed by %r' % (tab.id, self))
+        del self._tabsByID[tab.id]
+        self.tabs.remove(tab)
+        group = self._tabGroups.get(tab.group)
+        if group is not None:
+            group._releaseTab(tab)
+
+
+    def getTab(self, id):
+        """
+        Get a L{methanal.widgets.Tab} by its unique identifier.
+        """
+        tab = self._tabsByID.get(id)
+        if tab is None:
+            raise InvalidIdentifier(
+                u'%r is not a valid tab identifier in %r' % (id, self))
+        return tab
+
+
+    def getTabIDs(self):
+        """
+        Get a C{list} of all the tab IDs in the group.
+        """
+        return [tab.id for tab in self.tabs]
+
+
+    def getGroup(self, id):
+        """
+        Get a L{methanal.widgets.TabGroup} by its unique identifier.
+        """
+        group = self._tabGroups.get(id)
+        if group is None:
+            raise InvalidIdentifier(
+                u'%r is not a valid group identifier in %r' % (id, self))
+        return group
+
+
+    @deprecated(Version('methanal', 0, 2, 1))
     def appendTab(self, tab):
         """
-        Append a L{Tab} widget.
+        Append a L{methanal.widgets.Tab} widget.
 
         @return: A C{Deferred} that fires when the widget has been inserted on
             the client side.
         """
-        return self.appendTabs([tab])
-
-
-    def appendTabs(self, tabs):
+        return self.updateTabs([tab])
+
+
+    def updateTabs(self, tabs, tabsToRemove=None):
         """
-        Append many L{methanal.widgets.Tab} widgets.
-
-        All tab widgets are passed to the client side and appended there, and
-        added to the relevant groups.
-
-        @return: A C{Deferred} that fires when the widgets have been inserted on
+        Update many L{methanal.widgets.Tab} widgets.
+
+        All tab widgets are passed to the client side, updated there (or
+        appended if they didn't previously exist) and added to the relevant
+        groups. Use L{methanal.widgets.TabGroup.mergeGroups} to simulate adding
+        to an existing group.
+
+        @return: A C{Deferred} that fires when the widgets have been updated on
             the client side.
         """
         for tab in tabs:
             self._manageTab(tab)
             tab.setFragmentParent(self)
-        return self.callRemote('_appendTabsFromServer', tabs, self._tabGroups)
-
-
-    def appendGroup(self, group):
-        """
-        Append a L{methanal.widgets.TabGroup} and its tabs.
+
+        tabIDsToRemove = []
+        if tabsToRemove is not None:
+            tabIDsToRemove = [tab.id for tab in tabsToRemove]
+
+        return self.callRemote(
+            '_updateTabsFromServer', tabs, tabIDsToRemove, self._tabGroups)
+
+
+    appendTabs = deprecated(Version('methanal', 0, 2, 1))(updateTabs)
+
+
+    def removeTabs(self, tabs):
+        """
+        Remove many L{methanal.widgets.Tab} widgets.
+
+        Empty groups, caused by removing all contained tabs, are removed too.
+
+        @return: A C{Deferred} that fires when the widget has been removed on
+            the client side.
+        """
+        tabIDs = []
+        for tab in tabs:
+            tabIDs.append(tab.id)
+            self._releaseTab(tab)
+
+        return self.callRemote('_removeTabsFromServer', tabIDs, self._tabGroups)
+
+
+    def updateGroup(self, group):
+        """
+        Update a L{methanal.widgets.TabGroup} and its tabs.
+
+        Tabs specified in C{group} will replace those previously specified by
+        another group of the same name.
 
         @return: A C{Deferred} that fires when the widgets have been inserted on
             the client side.
         """
+        try:
+            oldGroup = self.getGroup(group.id)
+        except InvalidIdentifier:
+            oldGroup = None
+
+        tabsToRemove = []
+        if oldGroup is not None:
+            tabsToRemove = map(
+                self.getTab,
+                set(oldGroup.getTabIDs()) - set(group.getTabIDs()))
+            for tab in tabsToRemove:
+                self._releaseTab(tab)
+
         self._manageGroup(group)
-        return self.appendTabs(group.tabs)
+        return self.updateTabs(group.tabs, tabsToRemove)
+
+
+    appendGroup = deprecated(Version('methanal', 0, 2, 1))(updateGroup)
 
 
     def getInitialArguments(self):
         return [
-            dict.fromkeys(self._tabIDs, True),
+            dict.fromkeys(self._tabsByID.iterkeys(), True),
             self._tabGroups,
             self.topLevel]
 
@@ -774,7 +871,7 @@
 
 
 
-class TabGroup(record('id title tabs')):
+class TabGroup(object):
     """
     Visually group labels of L{methanal.widgets.Tab}s together.
 
@@ -792,15 +889,59 @@
 
     jsClass = u'Methanal.Widgets.TabGroup'
 
-    def __init__(self, *a, **kw):
-        super(TabGroup, self).__init__(*a, **kw)
-        for tab in self.tabs:
+    def __init__(self, id, title, tabs):
+        self.id = id
+        self.title = title
+        self.tabs = []
+        for tab in tabs:
+            self._manageTab(tab)
+
+
+    def __repr__(self):
+        return '<%s id=%r title=%r tabs=%r>' % (
+            type(self).__name__,
+            self.id,
+            self.title,
+            self.tabs)
+
+
+    def _manageTab(self, tab):
+        """
+        Manage a L{methanal.widgets.Tab} widget.
+        """
+        if tab not in self.tabs:
+            self.tabs.append(tab)
             tab.group = self.id
 
 
+    def _releaseTab(self, tab):
+        """
+        Stop managing a L{methanal.widgets.Tab} widget.
+        """
+        if tab in self.tabs:
+            self.tabs.remove(tab)
+            tab.group = None
+
+
+    def getTabIDs(self):
+        """
+        Get a C{list} of all the tab IDs in the group.
+        """
+        return [tab.id for tab in self.tabs]
+
+
+    @classmethod
+    def mergeGroups(cls, old, new):
+        """
+        Merge two L{methanal.widgets.TabGroup}s together.
+        """
+        return cls(new.id, new.title, old.tabs + new.tabs)
+
+
+    # IAthenaTransportable
+
     def getInitialArguments(self):
-        tabIDs = [tab.id for tab in self.tabs]
-        return [self.id, self.title, tabIDs]
+        return [self.id, self.title, self.getTabIDs()]
 
 
 
@@ -839,6 +980,15 @@
         self.group = group
 
 
+    def __repr__(self):
+        return '<%s id=%r title=%r selected=%r group=%r>' % (
+            type(self).__name__,
+            self.id,
+            self.title,
+            self.selected,
+            self.group)
+
+
     def getInitialArguments(self):
         return [getArgsDict(self)]
 
@@ -887,6 +1037,10 @@
         return tag[self.getContent()]
 
 
+    def updateRemoteContent(self):
+        pass
+
+
 
 class DynamicTab(Tab):
     """
@@ -909,3 +1063,9 @@
     being discarded and a new fetch occurring.
     """
     jsClass = u'Methanal.Widgets.DemandTab'
+
+    def updateRemoteContent(self):
+        """
+        Force the remote content to be updated.
+        """
+        return self.callRemote('_setContentFromWidgetInfo', self.getContent())