@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
1@title Profile Menu User Guide
2@group userguide
3
4Master profile menus for projects and other objects.
5
6Overview
7========
8
9Some objects, like projects, have customizable menus called "profile menus".
10This guide discusses how to add, remove, reorder, configure and extend these
11menus.
12
13
14Supported Applications
15======================
16
17These applications currently support profile menus:
18
19| Application | Customization | Support |
20|-----|-----|-----|
21| Home | Global/Personal | Full |
22| Projects | Per Project | Full |
23| Favorites Menu | Global/Personal | Full |
24| People | None | //Read-Only// |
25
26
27Editing Menus
28=============
29
30You can only edit an object's menu if you can edit the object. For example, you
31must have permission to edit a project in order to reconfigure the menu for the
32project.
33
34To edit a menu, click {nav icon="cogs", name="Manage"} or {nav icon="pencil",
35name="Edit ..."} in the menu itself. If you are an administrator and the
36application supports Global/Personal customization, you'll have the option
37of editing either the Global settings or your own Personal menu, otherwise click
38{nav icon="th-list", name="Edit Menu"}. This brings you to the menu
39configuration interface which allows you to add and remove items, reorder the
40menu, edit existing items, and choose a default item.
41
42Menus are comprised of a list of items. Some of the items are builtin
43(for example, projects have builtin "Profile", "Workboard" and "Members"
44items). You can also add custom items. Builtin and custom items mostly
45behave in similar ways, but there are a few exceptions (for example, you can
46not completely delete builtin items).
47
48
49Adding Items
50============
51
52To add new items to a menu, use {nav icon="cog", name="Configure Menu"} and
53choose a type of item to add. See below for more details on available items.
54
55You can also find a link to this documentation in the same menu, if you want
56to reference it later.
57
58
59Reordering Items
60================
61
62To reorder items, drag and drop them to the desired position. Your changes
63will be reflected in the item ordering in the menu.
64
65
66Setting a Default
67=================
68
69The default item controls what content is shown when a user browses to the
70object's main page. For example, the default item for a project controls where
71the user ends up when they click a link to the project from another
72application.
73
74To choose a default item, click {nav icon="thumb-tack", name="Make Default"}.
75Not all kinds of items can be set as the default item. For example, you can not
76set a separator line as a default because the item can't be selected and has no
77content.
78
79If no default is explicitly selected, or a default is deleted or disabled, the
80first item which is eligible to be a default is used as the default item.
81
82
83Removing Items
84==============
85
86To remove items, click the {nav icon="times", name="Delete"} action.
87
88Builtin items can not be deleted and have a
89{nav icon="times", name="Disable"} action instead, which will hide them but
90not delete them. You an re-enable a disabled item with the
91{nav icon="plus", name="Enable"} action.
92
93A few items can not be hidden or deleted. For example, the
94{nav icon="cogs", name="Manage"} item must always be available in the menu
95because if you hid it by accident there would no longer be a way to access
96the configuration interface and fix the mistake.
97
98Removing or hiding an item does not disable the underlying functionality.
99For example, if you hide the "Members" item for a project, that just removes
100it from the menu. The project still has members, and users can still navigate
101to the members page by following a link to it from elsewhere in the application
102or entering the URI manually.
103
104
105Editing Items
106=============
107
108To edit an item, click the name of the item. This will show you available
109configuration for the item and allow you to edit it.
110
111Which properties are editable depends on what sort of item you are editing.
112Most items can be renamed, and some items have more settings available. For
113example, when editing a link, you can choose the link target and select an
114icon for the item.
115
116A few items have no configuration. For example, visual separator lines are
117purely cosmetic and have no available settings.
118
119
120Available Items
121===============
122
123When you add items, you can choose between different types of items to add.
124Which item types are available depends on what sort of object you are editing
125the menu for, but most objects support these items:
126
127
128 - {icon minus} **Divider**: Adds a visual separator to the menu. This is
129 purely cosmetic.
130 - {icon map-marker} **Label**: Lets you label sections of menu items.
131 This is also purely cosmetic.
132 - {icon link} **Link**: Allows you to create an item which links to
133 somewhere else in Phorge, or to an external site.
134 - {icon plus} **Form**: Provides quick access to custom and built-in forms
135 from any application that supports EditEngine.
136 - {icon briefcase} **Projects**: Provides quick access to a project.
137 - {icon globe} **Applications**: Provides quick access to your favorite
138 applications. Can be renamed.
139 - {icon tachometer} **Dashboard**: Provides quick access to your favorite
140 dashboard. These items will display with the current nav on the item
141 you've attached it to.
142
143
144To learn more about how an item works, try adding it. You can always delete
145it later if it doesn't do what you wanted.
146
147
148Dashboard Integration
149=====================
150
151Dashboards are directly integrated with Profile Menus. If you add a Dashboard
152to a Project or to a Home menu, that Dashboard will be presented in the
153context of that menu. This allows customization of different pages of content
154without having the user leave Home or the Project.
155
156To use a Dashboard to replace the default Home menu, install it as a Global
157Menu Item and move it to the topmost item. By default, the first Dashboard
158the menu renders will be selected as the default. Users that modify their
159personal Home menu, will have their topmost Dashboard be their default,
160overriding the Global settings.
161
162
163Writing New Item Types
164======================
165
166IMPORTANT: This feature is not stable, and the API is subject to change.
167
168To add new types of items, subclass @{class:PhabricatorProfileMenuItem}.