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-<path>} 021 * <p> 022 * Primary menu items will not have a separator. 023 * 024 * @return the path to the menu item 025 */ 026 @Nonnull 027 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 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 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 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 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 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 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 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 boolean isDynamic(); 103 104}