Something went wrong. Try again.
@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
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518@title User Guide: Customizing Forms@group userguideGuide to prefilling and customizing forms in Phorge applications.Overview========In most applications, objects are created by clicking a "Create" button fromthe main list view, and edited by clicking an "Edit" link from the main detailview. For example, you create a new task by clicking "Create Task", and edit itby clicking "Edit Task".The forms these workflows use can be customized to accommodate a number ofdifferent use cases. In particular:**Prefilling**: You can use HTTP GET parameters to prefill fields or copyfields from another object. This is a lightweight way to create a link withsome fields set to initial values. For example, you might want to create alink to create a task which has some default projects or subscribers.**Custom Forms**: You can create custom forms which can have default values;locked, hidden, and reordered fields; and additional instructions. This can letyou make specialized forms for creating certain types of objects, like a"New Bug Report" form with extra help text or a "New Security Issue" form withlocked policies.**"Create" Defaults**: You can change the default form available to users forcreating objects, or provide multiple default forms for them to choose between.This can let you simplify or specialize the creation process.**"Edit" Defaults**: You can change the default form users are given to editobjects, which will also affect their ability to take inline actions in thecomment form if you're working in an application which supports comments. Thiscan streamline the edit workflow for less experienced users.Anyone can use prefilling, but you must have permission to configure anapplication in order to modify the application's forms. By default, onlyadministrators can configure applications.The remainder of this document walks through configuring these features ingreater detail.Supported Applications======================These applications currently support form customization:| Application | Support ||-------------------|---------|| Maniphest | Full| Owners | Full| Paste | Full| ApplicationEditor | MetaThis documentation is geared toward use in Maniphest because customizing taskcreation flows is the most common use case for many of these features, but thefeatures discussed here work in any application with support.These features first became available in December 2015. Additional applicationswill support them in the future.Internally, this infrastructure is called `ApplicationEditor`, and the maincomponent is `EditEngine`. You may see technical documentation, changelogs, orinternal discussion using these terms.Prefilling==========You can prefill the fields in forms by providing HTTP parameters. For example,if a form has a "Projects" field, you can generally prefill it by adding a`projects` parameter to the URI like this:```https://phorge.example.com/application/edit/?projects=skunkworks```The parameters available in each application vary, and depend on which fieldsthe application supports.For full documentation on a particular form, navigate to that form (byselecting the "Create" or "Edit" action in the application) and then use{nav Actions > Show HTTP Parameters} to see full details on which parametersyou can use and how to specify them.You can also use the `template` parameter to copy fields from an existingobject that you have permission to see. Which fields are copied depend on theapplication, but usually content fields (like a name or title) are not copiedwhile other fields (like projects, subscribers, and object states) are.The {nav Show HTTP Parameters} page has a full list of which fields will becopied.You can combine the `template` parameter with other prefilling. The `template`will act first, then prefilling will take effect. This allows you to overwritetemplate values with prefilled values.Some use cases for this include:**Lightweight Integrations**: If you want to give users a way to file tasks froman external application, this is an easy way to get a basic integrationworking. For example, you might have a tool for reviewing error logs inproduction that has a link to "File a Bug" about an error. The link couldprefill the `title`, `body` and `projects` fields with details about the logmessage and a link back into the external tool.**Convenience**: You can create lightweight, ad-hoc links that make takingactions a little easier for users. For example, if you're sending out an emailabout a change you just made to a lot of people, you could include instructionslike "If you run into any issues, assign a task to me with details: ..." andinclude a link which prefills you as the task assignee.**Searchbar Commands**: If you use a searchbar plugin which gives you shortcutcommands, you can write a custom shortcut so a command like "bug ..." canquickly redirect you to a prefilled form.Creating New Forms==================Beyond prefilling forms with HTTP parameters, you can create and save formconfigurations. This is more heavyweight than prefilling and allows you tocustomize, streamline, or structure a workflow more heavily.You must be able to configure an application in order to manage its forms.Form configurations can have special names (like "New Bug Report") andadditional instruction text, and may prefill, lock, hide, and reorder fields.Prefilling and templating still work with custom form configurations, but onlyapply to visible fields.To create a new form configuration, navigate to an existing form via "Create"or "Edit" and choose {nav Actions > View Form Configurations}. This will showyou a list of current configurations.You can also edit existing configurations, including the default configuration.You can use {nav Create Form} from this screen to create a new configuration.After setting some basic information you will be able to lock, hide, andreorder form fields, as well as set defaults.Clicking {nav Use Form} will take you to the permanent URI for this form. Youcan link to this form from elsewhere to take the user directly to yourcustom flow.You can adjust defaults using {nav Change Default Values}. These defaults aresaved with the form, and do not require HTTP parameter prefilling. However,they work in conjunction with prefilling, and you can use prefilling ortemplating to overwrite the defaults for visible fields.If you set a default value for a field and lock or hide the field, the defaultyou set will still be respected and can not be overridden with templatingor prefilling. This allows you to force certain forms to create tasks withspecific field values, like projects or policies.You can also set a view policy for a form. Only users who are able to view theform can use it to create objects.There are some additional options ("Mark as Create Form" and"Mark as Edit Form") which are more complicated and explained in greaterdetail later in this document.Some use cases for this include:**Tailoring Workflows**: If you have certain intake workflows like"New Bug Report" or "New Security Issue", you can create forms for them withmore structure than the default form.You can provide detailed instructions and links to documentation in the"Preamble" for the form configuration. You might use this to remind users aboutreporting guidelines, help them fill out the form correctly, or link to otherresources.You can hide fields that aren't important to simplify the workflow, or reorderfields to emphasize things that are important. For example, you might want tohide the "Priority" field on a bug report form if you'd like all bugs to comein at the default priority before they are triaged.You can set default view and edit policies, and optionally lock or hide thosefields. This allows you to create a form that is locked to certain policysettings.**Simplifying Forms**: If you rarely (or never) use some object fields, you cancreate a simplified form by hiding the fields you don't use regularly, orhide these fields completely from the default form.Changing Creation Defaults=========================You can control which form or forms are presented to users by default whenthey go to create new objects in an application.Using {nav Mark as "Create" Form} from the detail page for a formconfiguration, you can mark a form to appear in the create menu.When a user visits the application, Phorge finds all the formconfigurations that are: - marked as "create" forms; and - visible to the user based on policy configuration; and - enabled.If there is only one such form, Phorge renders a single "Create" button.(If there are zero forms, it renders the button but disables it.)If there are several such forms, Phorge renders a dropdown which allowsthe user to choose between them.You can reorder these forms by returning to the configuration list and using{nav Reorder Create Forms} in the left menu.This logic is also used to select items for the global "Quick Create" menuin the main menu bar.Some use cases for this include:**Simplification**: You can modify the default form to reorder fields, addinstructions, or hide fields you never use.**Multiple Intake Workflows**: If you have multiple distinct intake workflowslike "New Bug Report" and "New Security Issue", you can mark several formsas "Create" forms and users will be given a choice between them when they goto create a task.These flows can provide different instructions and defaults to help usersprovide the desired information correctly.**Basic and Advanced Workflows**: You can create a simplified "Basic" workflowwhich hides or locks some fields, and a separate "Advanced" workflow whichhas all of the fields.If you do this, you can also restrict the visibility policy for the "Advanced"form to experienced users. If you do, newer users will see a button whichtakes them to the basic form, while advanced users will be able to choosebetween the basic and advanced forms.Changing Editing Defaults=========================You can control which form users are taken to when they click "Edit" on anobject detail page.Using {nav Mark as "Edit" Form} from the detail page for a form configuration,you can mark a form as a default edit form.When a user goes to edit an object, they are taken to the first form which is: - marked as an "edit" form; and - visible to them; and - enabled.You can reorder forms by going up one level and using {nav Reorder Edit Forms}in the left menu. This will let you choose which forms have precedence ifa user has access to multiple edit forms.The default edit form also controls which which actions are available inlinein the "Comment" form at the bottom of the detail page, for applications whichsupport comments. If you hide or lock a field, corresponding actions will notbe available.Some use cases for this include:**Simplification**: You can modify the default form to reorder fields, addinstructions, or hide fields you never use.By default, applications tend to have just one form, which is both an edit formand a create form. You can split this into two forms (one edit form and onecreate form) and then simplify the create form without affecting the editform.You might do this if there are some fields you still want access to that younever modify when creating objects. For example, you might always want tocreate tasks with status "Open", and just hide that field from from the createform completely. A separate edit form can still give you access to these fieldsif you want to adjust them later.**Basic and Advanced Workflows**: You can create a basic edit form (with fewerfields available) and an advanced edit form, then restrict access to theadvanced form to experienced users.By ordering the forms as "Advanced", then "Basic", and applying a view policyto the "Advanced" form, you can send experienced users to the advanced formand less experienced users to the basic form.For example, you might use this to hide policy controls or task priorities frominexperienced users.Understanding Policies======================IMPORTANT: Simplifying workflows by restricting access to forms and fields does**not** enforce policy controls for those fields.The configurations described above which simplify workflows are advisory, andare intended to help users complete workflows quickly and correctly. A user whohas very limited access to an application through forms will generally still beable to use other workflows (like Conduit, Herald, Workboards, email, and otherapplications and integrations) to directly or indirectly modify fields.For example, even if you lock a user out of all the forms in an applicationthat have a "Subscribers" field, they can still add subscribers indirectly byusing `@username` mentions.We do not currently plan to change this or introduce enforced, platform-widefield-level policy controls. These form customization features are generallyaimed at helping well-intentioned but inexperienced users complete workflowsquickly and correctly.For more details about policies in general, see @{article:Policies User Guide}.Disabling Form Configurations=============================You can disable a form configuration from the form configuration details screen,by selecting {nav Disable Form}.Disabled forms do not appear in any menus by default, and can not be used tocreate or edit objects.Use Case: Specialized Report Form=================================A project might want to provide a specialized bug report form for a specifictype of issue. For example, if you have an Android application, you might havean internal link in that application for employees to "Report a Bug".A simple way to do this would be to link to the default form and use HTTPparameter prefilling to set a project. You might end up with a link like thisone:```https://phorge.example.com/maniphest/task/edit/?projects=android```A slightly more advanced method is to create a template task, then use it toprefill the form. For example, you might set some projects, subscribers, andcustom field values on the template task. Then have the application link tothe a URI that prefills using the template:```https://phorge.example.com/maniphest/task/edit/?template=123```This is a little easier to use, and lets you update the template later if youwant to change anything about the defaults that the new tasks are createdwith.An even more advanced method is to create a new custom form configuration.You could call this something like "New Android Bug Report". In addition tosetting defaults, you could lock, hide, or reorder fields so that the formonly presents the fields that are relevant to the workflow. You could alsoprovide instructions to help users file good reports.After customizing your form configuration, you'd link to the {nav Use Form}URI, like this:```https://phorge.example.com/maniphest/task/edit/form/123/```You can also combine this with templating or prefilling to further specializethe flow.Use Case: Simple Report Flow============================An open source project might want to give new users a simpler bug report formwith fewer fields and more instructions.To do this, create a custom form and configure it so it has only the relevantfields and includes any instructions. Once it looks good, mark it as a "Create"form.The "Create Task" button should now change into a menu and show both thedefault form and the new simpler form, as well as in the global "Quick Create"menu in the main menu bar.If you prefer the fields appear in a different order, use{nav Reorder Create Forms} to adjust the display order. (You could also renamethe default creation flow to something like "Create Advanced Task" to guideusers toward the best form).Use Case: Basic and Advanced Users==================================An open source project or a company with a mixture of experienced and lessexperienced users might want to give only some users access to adjust advancedfields like "View Policy" and "Edit Policy" when creating tasks.Before configuring things like this, make sure you review "UnderstandingPolicies" above.To do this, first customize four forms: - Basic Create - Advanced Create - Basic Edit - Advanced EditYou can customize these however you'd like.The "Advanced" forms should have more fields, while the "Basic" forms shouldbe simpler. You may want to add additional instructions to the "Basic Create"form.Then: - Mark the two "Create" forms as create forms. - Mark the two "Edit" forms as edit forms. - Limit the visibility of the two "Advanced" forms to only advanced users (for example, "Members of Project: Elite Strike Force"). - Use {nav Reorder Edit Forms} to make sure the "Advanced" edit form is at the top of the list. The first visible form on this list will be used, so this makes sure advanced users see the advanced edit form.Basic users should now only have access to basic fields when creating, editing,and commenting on tasks, while advanced users will retain full access.Use Case: Security Issues=========================If you want to make sure security issues are reported with the correctpolicies, you can create a "New Security Issue" form. On this form, prefill theView and Edit policies and lock or hide them, then lock or hide any additionalfields (like projects or subscribers) that you don't want users to adjust. Youmight use a custom policy like this for both the View and Edit policies:> Allow: Members of Project "Security"> Allow: Task Author> Deny all other usersThis will make it nearly impossible for users to make policy mistakes, and willprevent other users from observing these tasks indirectly through Herald rules.You should review "Understanding Policies" above before pursuing this. Inparticular, note that the author may still be able to leak information aboutthe report like this: - if they have access to a full-power edit form, they can edit the task //after// creating it and open the policies; or - regardless of their edit form access, they can use the Conduit API to change the task policy; or - regardless of any policy controls in Phorge, they can screenshot, print, or forward email about the task to anyone; or - regardless of any technical controls in any software, they can decline to report the issue to you in the first place and sell it on the black market instead.This goals of this workflow are to: - prevent other users from observing security issues improperly through mechanisms like Herald; and - prevent mistakes by well-meaning reporters who are unfamiliar with the software.It is **not** aimed at preventing reporters who are already in possession ofinformation from //intentionally// disclosing that information, since they havemany other channels by which to do this anyway and no software can ever preventit.Use Case: Upstream==================This section describes the upstream configuration circa December 2015. Thecurrent configuration may not be exactly the same as the one described below.We run an open source project with a small core team, a moderate numberof regular contributors, and a large public userbase. Access to the upstreamPhorge instance is open to the public.Although our product is fairly technical, we receive many bug reports andfeature requests which are of very poor quality. Some users also ignore all thedocumentation and warnings and use the upstream instance as a demo/testinstance to click as many buttons as they can.The goals of our configuration are: - Provide highly structured "New Bug Report" and "New Feature Request" workflows which make things as easy as possible to get right, in order to improve the quality of new reports. - Separate the userbase into "basic" and "advanced" users. Give the basic users simpler, more streamlined workflows, to make expectations more clear, improve report quality, and limit collateral damage from testing and fiddling.To these ends, we've configured things like this:**Community Project**: Advanced users are added to a "Community" project, whichgives them more advanced access. Advanced forms are "Visible To: Members ofProject Community".**Basic and Advanced Edit**: We have basic and advanced task edit forms.Members of the community project get access to the advanced one, while otherusers only have access to the basic one.**Bug, Feature and Advanced Create**: We have "New Bug", "New Feature" and"New Advanced Task" creation forms.The advanced form is the standard creation form, and is only accessible tocommunity members.The basic forms have fewer fields, and each form provides tailored instructionswhich point users at relevant documentation to help them provide good reports.The basic versions of these forms also have their "Edit Policy" locked down tomembers of the "Community" project and the task author. This means that usersgenerally can't mess around with other users' reports, but more experiencedusers can still help manage and resolve tasks.