001package jmri.server.web.spi;
002
003import java.util.Locale;
004import javax.annotation.CheckForNull;
005import javax.annotation.Nonnull;
006
007/**
008 * Provide a menu item used in the navigation bar on the JMRI web server.
009 * <p>
010 * <strong>Note:</strong> the results of two or more WebMenuItems having the
011 * same path is undefined.
012 *
013 * @author Randall Wood (C) 2016
014 */
015public interface WebMenuItem {
016
017    /**
018     * Get the path to the menu item. This should be the same regardless of
019     * locale. Use forward slashes ({@literal / }) to separate menu items to
020     * create sub menus. Menu items will have the id {@code navbar-&lt;path&gt;}
021     * <p>
022     * Primary menu items will not have a separator.
023     *
024     * @return the path to the menu item
025     */
026    @Nonnull
027    public String getPath();
028
029    /**
030     * Get the URL for the menu item. This may be an absolute URL path in the
031     * JMRI web service, a URL that resolves to some other public location, or a
032     * JavaScript trigger. If null, the menu item will not have a link. If the
033     * HREF starts with {@literal ng-click:}, it will be treated as a JavaScript
034     * trigger instead of a URL.
035     *
036     * @return the hyper-reference or null if the item is not a link
037     */
038    @CheckForNull
039    public String getHref();
040
041    /**
042     * Get the icon for the menu item. This icon needs to be the class
043     * attributes for the HTML span element that contains the icon. It is
044     * recommended that this icon be one of the
045     * <a href="http://fontawesome.io/icons/">Font Awesome</a> or
046     * <a href="http://www.patternfly.org/styles/icons/#_">Patternfly</a> icons
047     * as these icon sets will be available.
048     * <p>
049     * Icons will only be displayed for items in the primary menu.
050     *
051     * @return the class(es) for the icon or null if no icon is to be used
052     */
053    @CheckForNull
054    public String getIconClass();
055
056    /**
057     * Get the title for the menu item. This is displayed in the menu.
058     *
059     * @param locale the client locale
060     * @return the localized title
061     */
062    @Nonnull
063    public String getTitle(@Nonnull Locale locale);
064
065    /**
066     * The relative position of the menu item. If two menu items have the same
067     * relative position, they will be sorted in order by the path. For items
068     * within a sub menu, this position only applies to the sub menu.
069     *
070     * @return the relative position
071     */
072    public int getPosition();
073
074    /**
075     * Indicate if the menu item should have a separator before it. Note that if
076     * there are multiple items with the same position, they will be grouped on
077     * the same side of the separator if any of the items requires a separator.
078     *
079     * @return true if there should be a separator before the item; false
080     *         otherwise
081     */
082    public boolean isSeparatedBefore();
083
084    /**
085     * Indicate if the menu item should have a separator after it. Note that if
086     * there are multiple items with the same position, they will be grouped on
087     * the same side of the separator if any of the items requires a separator.
088     *
089     * @return true if there should be a separator after the item; false
090     *         otherwise
091     */
092    public boolean isSeparatedAfter();
093
094    /**
095     * Indicate if the menu item is the anchor for a dynamic menu. A dynamic
096     * menu is one that is built on as needed, often by JavaScript executed on
097     * the client.
098     *
099     * @return true if the menu item is an anchor for a dynamic menu; false
100     *         otherwise
101     */
102    public boolean isDynamic();
103
104}