create_list_screen

Required. The id of the form this screen belongs to.

Required. The name of the screen.

Optional. 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. Leave it out and the handle is made from the screen’s title, which is usually what you want.

Optional. 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. If you leave this out, the list starts out with the form’s own default columns, which on most forms is just the element that identifies an entry, so it is usually worth naming the columns you want. 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.Omit it (or provide an empty array) for a screen that shows every entry the user has permission to see. 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. 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. 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).Buttons you do not mention get sensible default labels, which means most of them will be present. For any that you do not want, set them to an empty string. 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. Custom buttons to put on the screen. A custom button appears on every row of the list and changes values in that row’s entry when clicked - the usual reason to add one is to let a user alter an entry with a single click, without having to open it and edit it. For example, update a status, approve something, etc 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. 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. Defaults to every view. 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.

Optional. Which view each group of users starts out on. Defaults to all_entries for Registered Users, however a given user will only ever see the entries that their permissions on the form allow. Set user permissions with the set_form_permissions tool. 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. 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. 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. Show the count at the bottom of the list, eg: ‘Showing entries 1 to 10 of 55’. Default is true.

Optional. 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. 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. 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. Show the ‘Working’ message while the page reloads. Default is true.

Optional. 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. 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. 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. 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".