@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
fork

Configure Feed

Select the types of activity you want to include in your feed.

Document how to customize forms in ApplicationEditor

Summary:
Ref T9132. I think the featureset is approximatley stable, so here's some documentation.

I also cleaned up a handful of things in the UI and tried to make them more obvious or more consistent.

Test Plan: Read documentation.

Reviewers: chad

Reviewed By: chad

Maniphest Tasks: T9132

Differential Revision: https://secure.phabricator.com/D14718

+543 -16
+9 -9
src/applications/transactions/controller/PhabricatorEditEngineConfigurationDefaultCreateController.php
··· 37 37 } 38 38 39 39 if ($config->getIsDefault()) { 40 - $title = pht('Remove From "Create" Menu'); 40 + $title = pht('Unmark as Create Form'); 41 41 $body = pht( 42 - 'Remove this form from the application "Create" menu? It will still '. 43 - 'function properly, but no longer be reachable directly from the '. 44 - 'application.'); 45 - $button = pht('Remove From Menu'); 42 + 'Unmark this form as a create form? It will still function properly, '. 43 + 'but no longer be reachable directly from the application "Create" '. 44 + 'menu.'); 45 + $button = pht('Unmark Form'); 46 46 } else { 47 - $title = pht('Add To "Create" Menu'); 47 + $title = pht('Mark as Create Form'); 48 48 $body = pht( 49 - 'Add this form to the application "Create" menu? Users will '. 50 - 'be able to choose it when creating new objects.'); 51 - $button = pht('Add To Menu'); 49 + 'Mark this form as a create form? It will appear in the application '. 50 + '"Create" menus by default.'); 51 + $button = pht('Mark Form'); 52 52 } 53 53 54 54 return $this->newDialog()
+2 -2
src/applications/transactions/controller/PhabricatorEditEngineConfigurationViewController.php
··· 162 162 $defaultcreate_uri = "{$base_uri}/defaultcreate/{$form_key}/"; 163 163 164 164 if ($config->getIsDefault()) { 165 - $defaultcreate_name = pht('Remove from "Create" Menu'); 165 + $defaultcreate_name = pht('Unmark as "Create" Form'); 166 166 $defaultcreate_icon = 'fa-minus'; 167 167 } else { 168 - $defaultcreate_name = pht('Add to "Create" Menu'); 168 + $defaultcreate_name = pht('Mark as "Create" Form'); 169 169 $defaultcreate_icon = 'fa-plus'; 170 170 } 171 171
+18 -5
src/applications/transactions/editengine/PhabricatorEditEngine.php
··· 989 989 private function buildEditFormActions($object) { 990 990 $actions = array(); 991 991 992 - $actions[] = id(new PhabricatorActionView()) 993 - ->setName(pht('Show HTTP Parameters')) 994 - ->setIcon('fa-crosshairs') 995 - ->setHref($this->getEditURI($object, 'parameters/')); 996 - 997 992 if ($this->supportsEditEngineConfiguration()) { 998 993 $engine_key = $this->getEngineKey(); 999 994 $config = $this->getEditEngineConfiguration(); ··· 1012 1007 $view_uri = "/transactions/editengine/{$engine_key}/"; 1013 1008 1014 1009 $actions[] = id(new PhabricatorActionView()) 1010 + ->setLabel(true) 1011 + ->setName(pht('Configuration')); 1012 + 1013 + $actions[] = id(new PhabricatorActionView()) 1015 1014 ->setName(pht('View Form Configurations')) 1016 1015 ->setIcon('fa-list-ul') 1017 1016 ->setHref($view_uri); ··· 1024 1023 ->setWorkflow(!$can_manage); 1025 1024 } 1026 1025 1026 + $actions[] = id(new PhabricatorActionView()) 1027 + ->setLabel(true) 1028 + ->setName(pht('Documentation')); 1029 + 1030 + $actions[] = id(new PhabricatorActionView()) 1031 + ->setName(pht('Using HTTP Parameters')) 1032 + ->setIcon('fa-book') 1033 + ->setHref($this->getEditURI($object, 'parameters/')); 1034 + 1035 + $doc_href = PhabricatorEnv::getDoclink('User Guide: Customizing Forms'); 1036 + $actions[] = id(new PhabricatorActionView()) 1037 + ->setName(pht('User Guide: Customizing Forms')) 1038 + ->setIcon('fa-book') 1039 + ->setHref($doc_href); 1027 1040 1028 1041 return $actions; 1029 1042 }
+514
src/docs/user/userguide/forms.diviner
··· 1 + @title User Guide: Customizing Forms 2 + @group userguide 3 + 4 + Guide to prefilling and customizing forms in Phabricator applications. 5 + 6 + Overview 7 + ======== 8 + 9 + In most applications, objects are created by clicking a "Create" button from 10 + the main list view, and edited by clicking an "Edit" link from the main detail 11 + view. For example, you create a new task by clicking "Create Task", and edit it 12 + by clicking "Edit Task". 13 + 14 + The forms these workflows use can be customized to accommodate a number of 15 + different use cases. In particular: 16 + 17 + **Prefilling**: You can use HTTP GET parameters to prefill fields or copy 18 + fields from another object. This is a lightweight way to create a link with 19 + some fields set to initial values. For example, you might want to create a 20 + link to create a task which has some default projects or subscribers. 21 + 22 + **Custom Forms**: You can create custom forms which can have default values; 23 + locked, hidden, and reordered fields; and additional instructions. This can let 24 + you make specialized forms for creating certain types of objects, like a 25 + "New Bug Report" form with extra help text or a "New Security Issue" form with 26 + locked policies. 27 + 28 + **"Create" Defaults**: You can change the default form available to users for 29 + creating objects, or provide multiple default forms for them to choose between. 30 + This can let you simplify or specialize the creation process. 31 + 32 + **"Edit" Defaults**: You can change the default form users are given to edit 33 + objects, which will also affect their ability to take inline actions in the 34 + comment form if you're working in an application which supports comments. This 35 + can streamline the edit workflow for less experienced users. 36 + 37 + Anyone can use prefiling, but you must have permission to configure an 38 + application in order to modify the application's forms. By default, only 39 + administrators can configure applications. 40 + 41 + The remainder of this document walks through configuring these features in 42 + greater detail. 43 + 44 + 45 + Supported Applications 46 + ====================== 47 + 48 + These applications currently support form customization: 49 + 50 + | Application | Support | 51 + |-------------|---------| 52 + | Maniphest | Full 53 + | Paste | Full 54 + | Owners | Full 55 + 56 + This documentation is geared toward use in Maniphest because customizing task 57 + creation flows is the most common use case for many of these features, but the 58 + features discussed here work in any application with support. 59 + 60 + These features first became available in December 2015. Additional applications 61 + will support them in the future. 62 + 63 + Internally, this infrastructure is called `ApplicationEditor`, and the main 64 + component is `EditEngine`. You may see technical documentation, changelogs, or 65 + internal discussion using these terms. 66 + 67 + Prefilling 68 + ========== 69 + 70 + You can prefill the fields in forms by providing HTTP parameters. For example, 71 + if a form has a "Projects" field, you can generally prefill it by adding a 72 + `projects` parameter to the URI like this: 73 + 74 + ``` 75 + https://your.install.com/application/edit/?projects=skunkworks 76 + ``` 77 + 78 + The parameters available in each application vary, and depend on which fields 79 + the application supports. 80 + 81 + For full documentation on a particular form, navigate to that form (by 82 + selecting the "Create" or "Edit" action in the application) and then use 83 + {nav Actions > Show HTTP Parameters} to see full details on which parameters 84 + you can use and how to specify them. 85 + 86 + You can also use the `template` parameter to copy fields from an existing 87 + object that you have permission to see. Which fields are copied depend on the 88 + application, but usually content fields (like a name or title) are not copied 89 + while other fields (like projects, subscribers, and object states) are. 90 + The {nav Show HTTP Parameters} page has a full list of which fields will be 91 + copied. 92 + 93 + You can combine the `template` parameter with other prefilling. The `template` 94 + will act first, then prefilling will take effect. This allows you to overwrite 95 + template values with prefilled values. 96 + 97 + Some use cases for this include: 98 + 99 + **Lightweight Integrations**: If you want to give users a way to file tasks from 100 + an external application, this is an easy way to get a basic integration 101 + working. For example, you might have a tool for reviewing error logs in 102 + production that has a link to "File a Bug" about an error. The link could 103 + prefill the `title`, `body` and `projects` fields with details about the log 104 + message and a link back into the external tool. 105 + 106 + **Convenience**: You can create lightweight, ad-hoc links that make taking 107 + actions a little easier for users. For example, if you're sending out an email 108 + about a change you just made to a lot of people, you could include instructions 109 + like "If you run into any issues, assign a task to me with details: ..." and 110 + include a link which prefills you as the task assignee. 111 + 112 + **Searchbar Commands**: If you use a searchbar plugin which gives you shortcut 113 + commands, you can write a custom shortcut so a command like "bug ..." can 114 + quickly redirect you to a prefilled form. 115 + 116 + 117 + Creating New Forms 118 + ================== 119 + 120 + Beyond prefilling forms with HTTP parameters, you can create and save form 121 + configurations. This is more heavyweight than prefilling and allows you to 122 + customize, streamline, or structure a workflow more heavily. 123 + 124 + You must be able to configure an application in order to manage its forms. 125 + 126 + Form configurations can have special names (like "New Bug Report") and 127 + additional instruction text, and may prefill, lock, hide, and reorder fields. 128 + Prefilling and templating still work with custom form configurations, but only 129 + apply to visible fields. 130 + 131 + To create a new form configuration, navigate to an existing form via "Create" 132 + or "Edit" and choose {nav Actions > View Form Configurations}. This will show 133 + you a list of current configurations. 134 + 135 + You can also edit existing configurations, including the default configuration. 136 + 137 + You can use {nav Create Form} from this screen to create a new configuration. 138 + After setting some basic information you will be able to lock, hide, and 139 + reorder form fields, as well as set defaults. 140 + 141 + Clicking {nav Use Form} will take you to the permanent URI for this form. You 142 + can link to this form from elsewhere to take the user directly to your 143 + custom flow. 144 + 145 + You can adjust defaults using {nav Change Default Values}. These defaults are 146 + saved with the form, and do not require HTTP parameter prefilling. However, 147 + they work in conjunction with prefilling, and you can use prefilling or 148 + templating to overwrite the defaults for visible fields. 149 + 150 + If you set a default value for a field and lock or hide the field, the default 151 + you set will still be respected and can not be overridden with templating 152 + or prefilling. This allows you to force certain forms to create tasks with 153 + specific field values, like projects or policies. 154 + 155 + You can also set a view policy for a form. Only users who are able to view the 156 + form can use it to create objects. 157 + 158 + There are some additional options ("Mark as Create Form" and 159 + "Mark as Edit Form") which are more complicated and explained in greater 160 + detail later in this document. 161 + 162 + Some use cases for this include: 163 + 164 + **Tailoring Workflows**: If you have certain intake workflows like 165 + "New Bug Report" or "New Security Issue", you can create forms for them with 166 + more structure than the default form. 167 + 168 + You can provide detailed instructions and links to documentation in the 169 + "Preamble" for the form configuration. You might use this to remind users about 170 + reporting guidelines, help them fill out the form correctly, or link to other 171 + resources. 172 + 173 + You can hide fields that aren't important to simplify the workflow, or reorder 174 + fields to emphasize things that are important. For example, you might want to 175 + hide the "Priority" field on a bug report form if you'd like all bugs to come 176 + in at the default priority before they are triaged. 177 + 178 + You can set default view and edit policies, and optionally lock or hide those 179 + fields. This allows you to create a form that is locked to certain policy 180 + settings. 181 + 182 + **Simplifying Forms**: If you rarely (or never) use some object fields, you can 183 + create a simplified form by hiding the fields you don't use regularly, or 184 + hide these fields completely from the default form. 185 + 186 + 187 + Changing Creation Defaults 188 + ========================= 189 + 190 + You can control which form or forms are presented to users by default when 191 + they go to create new objects in an application. 192 + 193 + Using {nav Mark as "Create" Form} from the detail page for a form 194 + configuration, you can mark a form to appear in the create menu. 195 + 196 + When a user visits the application, Phabricator finds all the form 197 + configurations that are: 198 + 199 + - marked as "create" forms; and 200 + - visible to the user based on policy configuration; and 201 + - enabled. 202 + 203 + If there is only one such form, Phabricator renders a single "Create" button. 204 + (If there are zero forms, it renders the button but disables it.) 205 + 206 + If there are several such forms, Phabricator renders a dropdown which allows 207 + the user to choose between them. 208 + 209 + You can reorder these forms by returning to the configuration list and using 210 + {nav Reorder Create Forms} in the left menu. 211 + 212 + This logic is also used to select items for the global "Quick Create" menu 213 + in the main menu bar. 214 + 215 + Some use cases for this include: 216 + 217 + **Simplification**: You can modify the default form to reorder fields, add 218 + instructions, or hide fields you never use. 219 + 220 + **Multiple Intake Workflows**: If you have multiple distinct intake workflows 221 + like "New Bug Report" and "New Security Issue", you can mark several forms 222 + as "Create" forms and users will be given a choice between them when they go 223 + to create a task. 224 + 225 + These flows can provide different instructions and defaults to help users 226 + provide the desired information correctly. 227 + 228 + **Basic and Advanced Workflows**: You can create a simplified "Basic" workflow 229 + which hides or locks some fields, and a separate "Advanced" workflow which 230 + has all of the fields. 231 + 232 + If you do this, you can also restrict the visibility policy for the "Advanced" 233 + form to experienced users. If you do, newer users will see a button which 234 + takes them to the basic form, while advanced users will be able to choose 235 + between the basic and advanced forms. 236 + 237 + 238 + Changing Editing Defaults 239 + ========================= 240 + 241 + You can control which form users are taken to when they click "Edit" on an 242 + object detail page. 243 + 244 + Using {nav Mark as "Edit" Form} from the detail page for a form configuration, 245 + you can mark a form as a default edit form. 246 + 247 + When a user goes to edit an object, they are taken to the first form which is: 248 + 249 + - marked as an "edit" form; and 250 + - visible to them; and 251 + - enabled. 252 + 253 + You can reorder forms by going up one level and using {nav Reorder Edit Forms} 254 + in the left menu. This will let you choose which forms have precedence if 255 + a user has access to multiple edit forms. 256 + 257 + The default edit form also controls which which actions are available inline 258 + in the "Comment" form at the bottom of the detail page, for applications which 259 + support comments. If you hide or lock a field, corresponding actions will not 260 + be available. 261 + 262 + Some use cases for this include: 263 + 264 + **Simplification**: You can modify the default form to reorder fields, add 265 + instructions, or hide fields you never use. 266 + 267 + By default, applications tend to have just one form, which is both an edit form 268 + and a create form. You can split this into two forms (one edit form and one 269 + create form) and then simplify the create form without affecting the edit 270 + form. 271 + 272 + You might do this if there are some fields you still want access to that you 273 + never modify when creating objects. For example, you might always want to 274 + create tasks with status "Open", and just hide that field from from the create 275 + form completely. A separate edit form can still give you access to these fields 276 + if you want to adjust them later. 277 + 278 + **Basic and Advanced Workflows**: You can create a basic edit form (with fewer 279 + fields available) and an advanced edit form, then restrict access to the 280 + advanced form to experienced users. 281 + 282 + By ordering the forms as "Advanced", then "Basic", and applying a view policy 283 + to the "Advanced" form, you can send experienced users to the advanced form 284 + and less experienced users to the basic form. 285 + 286 + For example, you might use this to hide policy controls or task priorities from 287 + inexperienced users. 288 + 289 + 290 + Understanding Policies 291 + ====================== 292 + 293 + IMPORTANT: Simplifying workflows by restricting access to forms and fields does 294 + **not** enforce policy controls for those fields. 295 + 296 + The configurations described above which simplify workflows are advisory, and 297 + are intended to help users complete workflows quickly and correctly. A user who 298 + has very limited access to an application through forms will generally still be 299 + able to use other workflows (like Conduit, Herald, Workboards, email, and other 300 + applications and integrations) to directly or indirectly modify fields. 301 + 302 + For example, even if you lock a user out of all the forms in an application 303 + that have a "Subscribers" field, they can still add subscribers indirectly by 304 + using `@username` mentions. 305 + 306 + We do not currently plan to change this or introduce enforced, platform-wide 307 + field-level policy controls. These form customization features are generally 308 + aimed at helping well-intentioned but inexperienced users complete workflows 309 + quickly and correctly. 310 + 311 + 312 + Disabling Form Configurations 313 + ============================= 314 + 315 + You can disable a form configuration from the form configuration details screen, 316 + by selecting {nav Disable Form}. 317 + 318 + Disabled forms do not appear in any menus by default, and can not be used to 319 + create or edit objects. 320 + 321 + 322 + Use Case: Specialized Report Form 323 + ================================= 324 + 325 + A project might want to provide a specialized bug report form for a specific 326 + type of issue. For example, if you have an Android application, you might have 327 + an internal link in that application for employees to "Report a Bug". 328 + 329 + A simple way to do this would be to link to the default form and use HTTP 330 + parameter prefilling to set a project. You might end up with a link like this 331 + one: 332 + 333 + ``` 334 + https://your.install.com/maniphest/task/edit/?projects=android 335 + ``` 336 + 337 + A slightly more advanced method is to create a template task, then use it to 338 + prefill the form. For example, you might set some projects, subscribers, and 339 + custom field values on the template task. Then have the application link to 340 + the a URI that prefills using the template: 341 + 342 + ``` 343 + https://your.install.com/maniphest/task/edit/?template=123 344 + ``` 345 + 346 + This is a little easier to use, and lets you update the template later if you 347 + want to change anything about the defaults that the new tasks are created 348 + with. 349 + 350 + An even more advanced method is to create a new custom form configuration. 351 + You could call this something like "New Android Bug Report". In addition to 352 + setting defaults, you could lock, hide, or reorder fields so that the form 353 + only presents the fields that are relevant to the workflow. You could also 354 + provide instructions to help users file good reports. 355 + 356 + After customizing your form configuration, you'd link to the {nav Use Form} 357 + URI, like this: 358 + 359 + ``` 360 + https://your.install.com/maniphest/task/edit/form/123/ 361 + ``` 362 + 363 + You can also combine this with templating or prefilling to further specialize 364 + the flow. 365 + 366 + 367 + Use Case: Simple Report Flow 368 + ============================ 369 + 370 + An open source project might want to give new users a simpler bug report form 371 + with fewer fields and more instructions. 372 + 373 + To do this, create a custom form and configure it so it has only the relevant 374 + fields and includes any instructions. Once it looks good, mark it as a "Create" 375 + form. 376 + 377 + The "Create Task" button should now change into a menu and show both the 378 + default form and the new simpler form, as well as in the global "Quick Create" 379 + menu in the main menu bar. 380 + 381 + If you prefer the fields appear in a different order, use 382 + {nav Reorder Create Forms} to adjust the display order. (You could also rename 383 + the default creation flow to something like "Create Advanced Task" to guide 384 + users toward the best form). 385 + 386 + 387 + Use Case: Basic and Advanced Users 388 + ================================== 389 + 390 + An open source project or a company with a mixture of experienced and less 391 + experienced users might want to give only some users access to adjust advanced 392 + fields like "View Policy" and "Edit Policy" when creating tasks. 393 + 394 + Before configuring things like this, make sure you review "Understanding 395 + Policies" above. 396 + 397 + To do this, first customize four forms: 398 + 399 + - Basic Create 400 + - Advanced Create 401 + - Basic Edit 402 + - Advanced Edit 403 + 404 + You can customize these however you'd like. 405 + 406 + The "Advanced" forms should have more fields, while the "Basic" forms should 407 + be simpler. You may want to add additional instructions to the "Basic Create" 408 + form. 409 + 410 + Then: 411 + 412 + - Mark the two "Create" forms as create forms. 413 + - Mark the two "Edit" forms as edit forms. 414 + - Limit the visibility of the two "Advanced" forms to only advanced users 415 + (for example, "Members of Project: Elite Strike Force"). 416 + - Use {nav Reorder Edit Forms} to make sure the "Advanced" edit form is at 417 + the top of the list. The first visible form on this list will be used, so 418 + this makes sure advanced users see the advanced edit form. 419 + 420 + Basic users should now only have access to basic fields when creating, editing, 421 + and commenting on tasks, while advanced users will retain full access. 422 + 423 + 424 + Use Case: Security Issues 425 + ========================= 426 + 427 + If you want to make sure security issues are reported with the correct 428 + policies, you can create a "New Security Issue" form. On this form, prefill the 429 + View and Edit policies and lock or hide them, then lock or hide any additional 430 + fields (like projects or subscribers) that you don't want users to adjust. You 431 + might use a custom policy like this for both the View and Edit policies: 432 + 433 + > Allow: Members of Project "Security" 434 + > Allow: Task Author 435 + > Deny all other users 436 + 437 + This will make it nearly impossible for users to make policy mistakes, and will 438 + prevent other users from observing these tasks indirectly through Herald rules. 439 + 440 + You should review "Understanding Policies" above before pursuing this. In 441 + particular, note that the author may still be able to leak information about 442 + the report like this: 443 + 444 + - if they have access to a full-power edit form, they can edit the task 445 + //after// creating it and open the policies; or 446 + - regardless of their edit form access, they can use the Conduit API to 447 + change the task policy; or 448 + - regardless of any policy controls in Phabricator, they can screenshot, 449 + print, or forward email about the task to anyone; or 450 + - regardless of any technical controls in any software, they can decline to 451 + report the issue to you in the first place and sell it on the black market 452 + instead. 453 + 454 + This goals of this workflow are to: 455 + 456 + - prevent other users from observing security issues improperly through 457 + mechanisms like Herald; and 458 + - prevent mistakes by well-meaning reporters who are unfamiliar with 459 + the software. 460 + 461 + It is **not** aimed at preventing reporters who are already in possession of 462 + information from //intentionally// disclosing that information, since they have 463 + many other channels by which to do this anyway and no software can ever prevent 464 + it. 465 + 466 + 467 + Use Case: Upstream 468 + ================== 469 + 470 + This section describes the upstream configuration circa December 2015. The 471 + current configuration may not be exactly the same as the one described below. 472 + 473 + We run an open source project with a small core team, a moderate number 474 + of regular contributors, and a large public userbase. Access to the upstream 475 + Phabricator instance is open to the public. 476 + 477 + Although our product is fairly technical, we receive many bug reports and 478 + feature requests which are of very poor quality. Some users also ignore all the 479 + documentation and warnings and use the upstream instance as a demo/test 480 + instance to click as many buttons as they can. 481 + 482 + The goals of our configuration are: 483 + 484 + - Provide highly structured "New Bug Report" and "New Feature Request" 485 + workflows which make things as easy as possible to get right, in order 486 + to improve the quality of new reports. 487 + - Separate the userbase into "basic" and "advanced" users. Give the 488 + basic users simpler, more streamlined workflows, to make expectations 489 + more clear, improve report quality, and limit collateral damage from 490 + testing and fiddling. 491 + 492 + To these ends, we've configured things like this: 493 + 494 + **Community Project**: Advanced users are added to a "Community" project, which 495 + gives them more advanced access. Advanced forms are "Visible To: Members of 496 + Project Community". 497 + 498 + **Basic and Advanced Edit**: We have basic and advanced task edit forms. 499 + Members of the community project get access to the advanced one, while other 500 + users only have access to the basic one. 501 + 502 + **Bug, Feature and Advanced Create**: We have "New Bug", "New Feature" and 503 + "New Advanced Task" creation forms. 504 + 505 + The advanced form is the standard creation form, and is only accessible to 506 + community members. 507 + 508 + The basic forms have fewer fields, and each form provides tailored instructions 509 + which point users at relevant documentation to help them provide good reports. 510 + 511 + The basic versions of these forms also have their "Edit Policy" locked down to 512 + members of the "Community" project and the task author. This means that users 513 + generally can't mess around with other users' reports, but more experienced 514 + users can still help manage and resolve tasks.