001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017: package org.apache.wicket.extensions.breadcrumb;
018:
019: import java.util.List;
020:
021: import org.apache.wicket.IClusterable;
022: import org.apache.wicket.extensions.breadcrumb.panel.BreadCrumbPanel;
023:
024: /**
025: * Bread crumbs provide a means to track certain history of client actions.
026: * Bread crumbs are typically rendered as a list of links, and are useful when
027: * users 'dig deeper' into the site structure so that they can find their way
028: * back again and have a notion of where they currently are.
029: * <p>
030: * Bread crumbs in the original sense just represent where people are in a site
031: * hierarchy. For example, when browsing a product site, bread crumbs could look
032: * like this:
033: *
034: * <pre>
035: * Home > Products & Solutions > Hardware > Desktop Systems
036: * </pre>
037: *
038: * or
039: *
040: * <pre>
041: * World > Europe > The Netherlands > Utrecht
042: * </pre>
043: *
044: * These items would be rendered as links to the corresponding site location.
045: * </p>
046: * Classes that implement this interface are responsible for managing such a
047: * bread crumb structure. A {@link BreadCrumbBar typical implementation} regards
048: * bread crumbs as a stack. When
049: * {@link #setActive(IBreadCrumbParticipant) a bread crumb is activated} that
050: * was not in the stack yet, it would add it to the stack, or when a bread crumb
051: * is activated that is already on the stack, it would roll back to the
052: * corresponding depth.
053: * <p>
054: * This model does not make any presumptions on how it should interact with
055: * components. Just that there is a list of
056: * {@link IBreadCrumbParticipant bread crumb participants}, and the notion of a
057: * currently active bread crumb participant.
058: * </p>
059: * <p>
060: * A {@link IBreadCrumbParticipant bread crumb participant} is not an actual
061: * bread crump, but rather a proxy to components that represent a certain
062: * location relative to other bread crumbs in this model, and a means to get the
063: * bread crumb title, which is typically rendered as a link label of the actual
064: * bread crumb. The actual bread crumbs are supposed to be rendered by a
065: * component that works together with this model. I choose this model as this
066: * would suit what I think is one of the nicest patterns:
067: * {@link BreadCrumbPanel bread crumb aware panels}.
068: * </p>
069: *
070: * @author Eelco Hillenius
071: */
072: public interface IBreadCrumbModel extends IClusterable {
073: /**
074: * Adds a bread crumb model listener.
075: *
076: * @param listener
077: * The listener to add
078: */
079: void addListener(IBreadCrumbModelListener listener);
080:
081: /**
082: * Lists the bread crumb participants in this model.
083: *
084: * @return The bread crumbs particpants, as list with
085: * {@link IBreadCrumbParticipant bread crumb participants}.
086: */
087: List allBreadCrumbParticipants();
088:
089: /**
090: * Gets the currently active participant, if any.
091: *
092: * @return The currently active participant, may be null
093: */
094: IBreadCrumbParticipant getActive();
095:
096: /**
097: * Removes a bread crumb model listener.
098: *
099: * @param listener
100: * The listener to remove
101: */
102: void removeListener(IBreadCrumbModelListener listener);
103:
104: /**
105: * Sets the {@link IBreadCrumbParticipant bread crumb} as the active one.
106: * Implementations should call
107: * {@link IBreadCrumbModelListener#breadCrumbAdded(IBreadCrumbParticipant) bread crumb added}
108: * when the bread crumb was not yet part of the model, and
109: * {@link IBreadCrumbModelListener#breadCrumbRemoved(IBreadCrumbParticipant) bread crumb removed}
110: * for every crumb that was removed as the result of this call.
111: *
112: * @param breadCrumbParticipant
113: * The bread crump that should be set as the currently active
114: */
115: void setActive(IBreadCrumbParticipant breadCrumbParticipant);
116: }
|