update_list_screen

Required. The id of the list screen to update.

Optional. A new name for the screen.

Optional. Left unchanged if omitted. A short name for this screen, unique across every screen in the system. Spaces and hyphens become underscores, anything else that is not a letter, number or underscore is stripped, and capitals are lowered. If the name you ask for is already in use by another screen, it is adjusted until it is unique. Changing it breaks anything that refers to the screen by the old handle.

Optional. Left unchanged if omitted. When anonymous visitors can reach this screen, require them to enter a passcode that they will have received prior, in order to open a particular entry. On by default. Turning it off means anyone with the link can open the entry, so only do it for truly public access situations. The Anonymous Users group (group 3) will also need permission for the form, use the set_form_permissions tool to do that.

Optional. Make this the default list screen. When a menu item or URL leads to the form without naming a screen, and the user has permission to interact with multiple entries in the form, Formulize will default to showing this screen. Setting true replaces whatever list screen held the position before - a form only has one default list screen at a time. If you are updating, setting false will remove the default ‘.list.’ screen, but only if this screen is currently the one holding it; on any other screen false does nothing, so it cannot displace a different screen by accident.

Optional. The columns of the list, in the order they appear. Columns can be from this screen’s form, and also any form directly connected to this screen’s form. Providing this property will REPLACE the screen’s current columns, so include every column you want the screen to have, not just the new ones. Omit it to leave the columns as they are. Users can change which columns they see (with the change_columns button) and save their own views; these columns are what the screen starts out with. Each column may also carry a Quicksearch control and a starting sort direction.

Optional. Conditions that permanently restrict which entries this screen can ever show. Unlike a search, the user cannot see or undo them, and they apply to every view on the screen, so they are the way to make a screen that is only ever about a subset of the entries (eg: only this year’s orders, or only the records assigned to the person looking at the screen). This setting applies only to this screen; users may be able to access other screens that show more entries. Conversely, permissions set with the set_form_permissions tool apply system wide.Providing this REPLACES the screen’s current filters; provide an empty array ([]) to remove them all so the screen can show every entry the user has permission to see. Omit it to leave them unchanged. Each condition has an element, an operator, a value, and a ‘type’ flag of ‘match-all’ (combined with AND) or ‘match-one-or-more’ (combined with OR). Conditions can reference elements in this form or in connected forms. Do not use foreign keys as values for linked elements; use the readable value, which this tool understands automatically. Use “{BLANK}” to match blank values, and dynamic values such as {TODAY}, {TODAY+7}, {NOW} and {USER} (the user looking at the screen).

Optional. Left unchanged if omitted. How many entries appear on each page of the list. Use 0 to put every entry on one page, which is only sensible for lists that will always be short. The default is 10.

Optional. Left unchanged if omitted. Which form screen opens when a user clicks through to an individual entry. The default is the default form screen for this form. Use a specific screen id to set this to a different form screen, on this form or on a connected form. Use the string ‘default’ to reset to the default.

Optional. The buttons on the screen, and the text on them. To turn off a button, set its text to an empty string (buttons with no text do not appear).Only the buttons you include are changed; the rest keep their current labels. A button only ever appears for users whose permissions allow the action behind it. For example, if can include the Delete Entries button, and it will only show up on the screen for users who have permission to delete entries. Use the set_form_permissions tool to update permissions for users.

Starts a new entry (or opens the user’s own entry, on a form where each user has only one). Default is “Add <the form’s singular name>”. Set an empty string to remove this button from the screen.

Starts a new entry, and reloads the form blank after saving, so another new entry can be created. Useful for forms where people make more than one entry at once often. This button is off by default. Suggested text would be “Add <the form’s plural name>”. Set an empty string to remove this button from the screen.

Starts a new entry on behalf of another user. Only ever shown to users who have permission to do that, and no permission to create entries of their own. Set an empty string to remove this button from the screen.

Duplicates the entries the user has checked off. Set an empty string to remove this button from the screen.

Deletes the entries the user has checked off. Set an empty string to remove this button from the screen.

Changes who owns the entries the user has checked off. This alters the groups the entries are associated with, and so may change who can see the entries. Set an empty string to remove this button from the screen.

Checks off every entry visible on the current page of the list. Set an empty string to remove this button from the screen.

Unchecks every entry visible on the current page of the list. Set an empty string to remove this button from the screen.

Opens the interface for choosing which columns the list shows. Set an empty string to remove this button from the screen.

Opens the interface for totals, averages and other calculations on the columns. Set an empty string to remove this button from the screen.

Exports all entries matching the current search terms and visibility scope to a csv file. Only includes the currently selected columns. Set an empty string to remove this button from the screen.

Exports the results of the calculations to a file. Set an empty string to remove this button from the screen.

Opens the import interface for creating entries from a csv file. Set an empty string to remove this button from the screen.

Opens the interface where users can choose when to be notified of new or updated or deleted entries. A User with the set_notifications_for_others permission can configure notifications that will go to other users besides themself. Set an empty string to remove this button from the screen.

Saves the current columns, searches, sorting, and visibility scope as a view that can be returned to later. Users with the publish_reports permission can publish views to their groups. Users with the publish_globalscope permission can publish views to anyone Set an empty string to remove this button from the screen.

Puts the list back to it’s initial state, clearing any changes the user might have made to the searches, column choices, sorting order, or visibility scope. Set an empty string to remove this button from the screen.

Deletes the saved view the user is currently looking at. Users can always delete their own saved views. Users with delete_other_reports permission can delete views published by others. Set an empty string to remove this button from the screen.

Optional. Changes to this screen’s custom buttons. Only include the buttons you want to change, add or delete - buttons you do not mention are left alone. Target one by button_id, or omit button_id to add a new one. These tools only configure the in-row kind of button. There are other kinds of custom buttons in Formulize that can have other effects, but they must be set in the administration interface. A button on this screen that does one of those things cannot be changed here and will be left exactly as it is.

Optional. Left unchanged if omitted. The text that introduces the visibility scope options interface. The default text is “Showing:” The basic options are ‘Entries by me’, ‘Entries by my groups’, ‘Entries by all users’. In addition, there is an option for users to select an arbitrary set of groups (from among the groups they are a member of). If the user has access to any saved views, they will be selectable in this interface as well. Set an empty string to turn off the interface.

Optional. Which views the visibility scope interface offers. Providing this REPLACES the current list. Omit it to leave it unchanged. Use [‘every_view’] for no restriction. The three standard views are their_own_entries, their_groups_entries and all_entries. Regardless of this setting, what a given user actually sees will always depend on their permissions. Set user permissions with the set_form_permissions tool. Any other values here will be the ids of published saved views on this form.

Optional. Which view each group of users starts out on. Providing this REPLACES the current settings, so include every group you want a setting for. Omit it to leave them unchanged. All users are members of Registered Users (group 2). If there are default_view values specified for multiple groups, a user who is a member of more than one will get the view that comes first in the array. Use list_groups to find group ids.

Optional. Left unchanged if omitted. Show a heading at the top of each column. Default is true. Headings are also what users click to sort the list, so turning them off removes the ability to sort.

Optional. Left unchanged if omitted. Whether the Quicksearch boxes appear under the column headings: ‘shown’ (the default) puts them on screen; ‘hidden’ keeps them out of the way until the user clicks to open them; ‘off’ removes them.

Optional. Left unchanged if omitted. Show the count at the bottom of the list, eg: ‘Showing entries 1 to 10 of 55’. Default is true.

Optional. Left unchanged if omitted. Show the ‘Hide repeating data’ switch, which lets users blank out values that repeat from the row above. Default is true. This is useful if the list will include a lot of the same values over and over, and then the user can flip the switch to isolate the relevant data.

Optional. Left unchanged if omitted. Whether a checkbox appears beside each entry, so users can select entries to act on: ‘based_on_delete_permission’ (the default) shows one only where the user can delete the entry; ‘all_entries’ shows one on every entry, which is what you want when the workflow might involve users doing something other than deleting entries; ‘none’ removes the checkboxes for everyone, regardless of permission.

Optional. Left unchanged if omitted. The icon at the left of each entry that opens the full entry: ‘pen’ suggests editing, ‘magnifying_glass’ suggests looking, and ‘none’ results in no icon, which means users have no way to open an entry from this screen.

Optional. Left unchanged if omitted. Show the ‘Working’ message while the page reloads. Default is true.

Optional. Left unchanged if omitted. Truncate the text shown in any cell to this many characters, so one long value cannot stretch the list. Use 0 for no limit. New screens use 255.

Optional. The columns whose values are shown as editable form inputs right in the list, instead of as text, so users can change many entries without opening them. Providing this REPLACES the current set; provide an empty array ([]) for none. Omit it to leave it unchanged. Specify elements by handle or id. This setting does not cause the element to appear in the screen, do that with the columns property. A column that is not initially in the screen, will appear in an editable form if the user changes columns to include it.

Optional. Left unchanged if omitted. When should the values in editable columns turn into inputs: ‘immediately’ (the default) makes all values editable as soon as the list loads; ‘pen’ or ‘magnifying_glass’ makes each cell editable only after the user clicks the icon on it.

Optional. Left unchanged if omitted. The text on the button below the list that saves changes the user made in the editable columns. Only relevant when editable_columns is in use, and editable_columns_show_option is set to ‘immediately’ (otherwise each cell has its own save button). Default is "Save".