diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/data-list/data-list.md b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/data-list/data-list.md index 5fdfc26c84..dc7d3fe626 100644 --- a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/data-list/data-list.md +++ b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/data-list/data-list.md @@ -5,13 +5,13 @@ related: ['Table'] --- ## Elements -The elements mentioned below are similar for a data list with compact or default spacing. This example shows a data list with compact spacing. +The elements mentioned below are similar for a data list with compact or default spacing. This example shows a data list with compact spacing. [Learn more about spacing options here.](#spacing) example of elements on a data list 1. **[Toolbar](/components/toolbar/design-guidelines):** Sits above the list and contains controls for manipulating list data. Common actions include filtering, sorting, and pagination. 2. **[Bulk selection](/patterns/bulk-selection):** When present, selects all items in a table. If pagination is being used, this will only select items on the current page. See [bulk selection](/patterns/bulk-selection) for more information. -3. **Global actions:** Actions that apply to all selected items. +3. **Global actions:** Actions that apply to all selected items. Also includes actions that directly impact the table, regardless of selection, such as "Create", "Edit row item", "Delete row item", and "Export table", for example. For more guidance, [see the actions pattern.](/patterns/actions) 4. **Row:** Row height may be variable and sizes to the content. Rows in a data list may take any supported layout. 5. **Expand:** Expands this row. 6. **Select checkbox:** Selects this row. @@ -27,27 +27,34 @@ Think of each row in a data list as a container for some formatted content. In P * **[Split](/layouts/split):** Distributes content evenly with a main content area in the center. * **[Flex](/layouts/flex):** Enables more customization control over the alignment and spacing options provided in the other layouts. -PatternFly offers 2 components for displaying large data sets: data lists and [tables](/components/table/design-guidelines). While they satisfy similar use cases, choosing the correct component to use in your design will be dependent on the type of data you need to display. +Data list toolbars should only contain actions that directly impact the data list. Any actions that are related to the overall page and its context (or impact the general page but not the data list directly) should be placed outside of the data list, at the top right of the page at the header level. This may include actions that edit the page header, actions that launch related windows, and so on. Data lists can also appear in primary-detail views. Visit the [primary-detail guidelines](/patterns/primary-detail/design-guidelines) to learn more about the functionality. ### When to use a data list vs. a table +PatternFly offers 2 components for displaying large data sets: data lists and [tables](/components/table/design-guidelines). While they satisfy similar use cases, choosing the correct component to use in your design will be dependent on the type of data you need to display. + **Use a data list when**: * The information you want to display is not easily structured into a tabular format. * Content displayed varies between rows and you want a more flexible layout. * You plan to embed rich content like a chart or an image into a row. -**Use a table when**: +**Use a [table](/components/table) when**: * The information you want to display is easily structured into a tabular format. * The clarity of your content would benefit from well defined columns and headings. +### When to use a data list vs. a card +Instead of a data list, you may choose to use [card views](/components/card/design-guidelines#card-views). Card views and data lists have similar properties, but information in a card view is chunked into a grid of individual cards. + +In choosing between a data list and a card view, consider the type of data that will be displayed and the format that best suits that data. If you cannot easily fit all of the data that needs to be displayed into a card, a data list might be a better solution. + ## Variations -PatterFly supports 2 main types of data lists: +PatternFly supports 2 main types of data lists: 1. **[Compact data list](#compact-spacing):** Use when you want to show as much data per page as possible. 2. **[Default data list](#default-spacing):** Use when you don’t have to minimize paging. -See [when to use compact vs. default spacing](#when-to-use-a-data-list-vs.-a-table)for more information about the styling and usage. +See [when to use compact vs. default spacing](#when-to-use-a-data-list-vs.-a-table) for more information about the styling and usage. Compact and default data list @@ -60,19 +67,21 @@ Every data list can be extended with these functionalities: * **[Draggable data list rows](#draggable-data-list-rows)** ### Selectable data list -The selectable data list provides checkboxes that enable users to select one or more rows in the list. Users may then act on those selections using options in the [toolbar](/components/toolbar/design-guidelines). +The selectable data list provides checkboxes that enable users to select 1 or more rows in the list. Users may then act on those selections using options in the [toolbar](/components/toolbar/design-guidelines). example of selectable data list 1. **[Bulk selection](/patterns/bulk-selection):** When present, selects all items in a table. If pagination is being used, this will only select items on the current page. See [bulk selection](/patterns/bulk-selection) for more information. 2. **Checkbox:** Enables a user to select a row. -3. **Global actions:** Actions that can be applied to **all** selected items. If actions in the data list are restricted to a single row or object, keep the actions at the individual row level, instead of in the toolbar. +3. **Global actions:** Actions that can be applied to all selected items. Also includes actions that directly impact the table, regardless of selection, such as "Create", "Edit row item", "Delete row item", and "Export table", for example. For more guidance, [see the actions pattern.](/patterns/actions) + - If actions in the data list are restricted to a single row or object, keep the actions at the individual row level, instead of in the toolbar. #### When to use -* **Use an actionable data list** when you need to enable a user to select and act on multiple items in the list. +* You need to enable a user to select and act on multiple items in the list. -* **Don't use an actionable data list** when users can not take any actions on data list items/rows. +#### When not to use +* Users cannot take any actions on data list items/rows. ### Clickable data list The clickable data list can be used when data lists need to provide additional information while keeping the row information available via a primary-detail drawer. This can be done by clicking on the row itself. @@ -108,7 +117,7 @@ Draggable data list rows can be added to any data list and allow you to customiz example of draggable data list -1. **Drag icon:** To indicate a row is draggable, use the fa-grip icon. Use grip-vertical to indicate the ability to move a vertically-oriented component via drag and drop. Use grip-horizontal to move a horizontally-oriented component via drag and drop. For example, if you are selecting items to be dragged from two parallel lists. +1. **Drag icon:** To indicate a row is draggable, use the fa-grip icon. Use grip-vertical to indicate the ability to move a vertically-oriented component via drag and drop. Use grip-horizontal to move a horizontally-oriented component via drag and drop. For example, if you are selecting items to be dragged from 2 parallel lists. 2. **Dragged row:** When dragging a row, it becomes slightly less opaque and floats above the static rows to indicate that it is the one moving. example of draggable data list @@ -126,7 +135,7 @@ Whether to use a data list with compact or default spacing is up to you and your A data list may sometimes need to be compact to make more rows visible at a time. The more rows you can see, the less you need to use [pagination](/components/pagination/design-guidelines). Compact spacing is recommended for data with a simple structure. See an example below. **Use compact spacing when:** -* You need to show as much data as possible on one page. +* You need to show as much data as possible on 1 page. * You need to show data in a small space, like in a modal or wizard. * You need to minimize paging. * Readability is a secondary concern. @@ -134,15 +143,15 @@ A data list may sometimes need to be compact to make more rows visible at a time Example of compact spacing data list **Example:** -* You can see more data on one page. +* You can see more data on 1 page. * You have a good overview about the structure of data. -* The structure of data is simple, informative and have less visual elements. +* The structure of data is simple, informative and has less visual elements. ### Default spacing A data list may sometimes need more space for rich graphical data. See an example below. **Use default spacing when:** -* You don’t have to display a lot of data on one page. +* You don’t have to display a lot of data on 1 page. * You use many visual indicators that are placed in columns, such as icons or charts. * You don't have to minimize paging. * Readability is a primary concern. @@ -150,9 +159,6 @@ A data list may sometimes need more space for rich graphical data. See an exampl Example of default spacing data list **Example:** -* You can see less data on one page. +* You can see less data on 1 page. * You will need a pagination to see more rows. -* Data structure includes many visual elements. - -## Alternative solutions -Alternative to a data list include [tables](/components/table/design-guidelines) or [card views](/components/card/design-guidelines#card-views). Card views and data lists have similar properties, but information in a card view is chunked into a grid of individual cards. In choosing between a data list and a card view, consider the type of data that will be displayed and the format that best suits that data. If you cannot easily fit all of the data that needs to be displayed into a card, a data list might be a better solution. +* Data structure includes many visual elements. \ No newline at end of file diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/table/img/page-action.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/table/img/page-action.png new file mode 100644 index 0000000000..3e3cb9132c Binary files /dev/null and b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/table/img/page-action.png differ diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/table/table.md b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/table/table.md index da6aa208da..86f7b3c434 100644 --- a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/table/table.md +++ b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/table/table.md @@ -9,11 +9,11 @@ The elements mentioned below are similar for a table with compact or default spa example of table and the elements -1. **[Toolbar](/components/toolbar/design-guidelines):** Sits above the table and contains controls for manipulating table data. Common actions include filtering, sorting, and pagination. +1. **[Toolbar](/components/toolbar/design-guidelines):** Sits above the table and contains controls for manipulating table data. Common actions include filtering, sorting, and pagination. 2. **[Bulk selection](/patterns/bulk-selection):** When present, selects all items in a table. If pagination is being used, this will only select items on the current page. See [bulk selection](/patterns/bulk-selection) for more information. -3. **Global actions:** Actions that apply to all selected items. +3. **Global actions:** Actions that apply to all selected items. Also includes actions that directly impact the table, regardless of selection, such as "Create", "Edit row item", "Delete row item", and "Export table", for example. For more guidance, [see the actions pattern](/patterns/actions). 4. **Expansion:** Expand all the rows in the table. -5. **Column headers:** Should align with the content they contain. If the user is able to sort on a column, the first click on the header will sort the content of the table on the content in that column. Subsequent clicks will toggle the direction of the sort. Table data can only be sorted on one column at a time. See [sorting by columns](#sorting-by-columns) for more information on the sort component. +5. **Column headers:** Should align with the content they contain. If the user is able to sort on a column, the first click on the header will sort the content of the table on the content in that column. Subsequent clicks will toggle the direction of the sort. Table data can only be sorted on 1 column at a time. [Read about sorting by columns](#sorting-by-columns) for more information on the sort component. 6. **Inline actions:** Actions that apply only to the current row/item. 7. **Select checkbox:** Selects this row. 8. **Expanded panel:** Expanded table row content. @@ -22,6 +22,10 @@ The elements mentioned below are similar for a table with compact or default spa ## Usage When using tables you need to consider the structure of the data you want to display and organize that information into columns. Columns will typically have column headers. Every row within a table must have a consistent format. If the table row includes actions, they should always be placed in the rightmost column(s). +Table toolbars should only contain actions that directly impact the table. Any actions that are related to the overall page and its context (or impact the general page but not the table directly) should be placed outside of the table, at the top right of the page at the header level. This may include actions that edit the page header, actions that launch related windows, and so on. + +![UI screen with action button placed outside of the table.](./img/page-action.png) + PatternFly offers 2 components for displaying large data sets: [data lists](/components/data-list/design-guidelines) and tables. While they satisfy similar use cases, choosing the correct component to use in your design will be dependent on the type of data you need to display. Tables can also appear in primary-detail views. Visit the [primary-detail guidelines](/patterns/primary-detail/design-guidelines) to learn more about the functionality. @@ -43,7 +47,7 @@ In this example, a table is positioned in the body of a page in a card. ### Showing more information in a table cell -To show more information in a table cell than can fit in the row field, you may truncate the list and use a label to indicate that there are more items to view. This label should be gray and indicate the number of items left to view (example: "3 more"). It is recommended to show at least one item before hiding the rest of the items. +To show more information in a table cell than can fit in the row field, you may truncate the list and use a label to indicate that there are more items to view. This label should be gray and indicate the number of items left to view (example: "3 more"). It is recommended to show at least 1 item before hiding the rest of the items. Clicking on the label would open up a popover or modal depending on the number of items: @@ -104,20 +108,21 @@ Every table can be extended with these functionalities: * It would not make sense to combine all of this information into a single, simple expansion. ### Actionable table -The actionable table provides checkboxes or radio buttons that enable users to select one or more rows in a table. Users may then act on those selections using options in the [toolbar](/components/toolbar/design-guidelines),. +The actionable table provides checkboxes or radio buttons that enable users to select 1 or more rows in a table. Users may then act on those selections using options in the [toolbar](/components/toolbar/design-guidelines). example of actionable table 1. **[Bulk selection](/patterns/bulk-selection):** When present, selects all items in a table with checkboxes. If pagination is being used, this will only select items on the current page. See [bulk selection](/patterns/bulk-selection) for more information. 2. **Checkbox**: Enables a user to select a row. Use when multiple rows can be selected at the same time. -3. **Radio button**: Enables a user to select a single row at a time. Use when only one row can be selected at a time. -3. **Global actions:** Actions that can be applied to **all** selected items. If actions in the table are restricted to a single row or object, keep the actions at the row kebab level, instead of in the toolbar. +3. **Radio button**: Enables a user to select a single row at a time. Use when only 1 row can be selected at a time. +3. **Global actions:** Actions that can be applied to all selected items or the entire table. If actions in the table are restricted to a single row or object, keep the actions at the row kebab level, instead of in the toolbar. #### When to use -* You need to enable a user to select one or more items in the table, for example to make selections in a wizard, or to carry out actions in a full page table. +* Users need to be able to select 1 or more items in the table. For example, in order to make selections in a wizard. +* Users need to carry out actions in a full page table. #### When not to use -* Users can not take any actions on table items/rows. +* Users cannot take any actions on table items/rows. ### Comparison table @@ -168,12 +173,12 @@ Sorting by columns is possible for any table variation. Enabling the component w The default sort order for a table should support the primary use case for the application. All columns in a table do not require sort functionality. That is, you can disable the header sort function on some columns and enable it on others. #### Example -If a table contains these two attributes: (System Name | Last Sync) you may want to show the most recently synced system at the top of the table (in other words, it is the default sort column), because a primary use case for this table is verifying that you have successfully connected or troubleshot the system’s connection to Cloud Services. +If a table contains these 2 attributes: (System Name | Last Sync) you may want to show the most recently synced system at the top of the table (in other words, it is the default sort column), because a primary use case for this table is verifying that you have successfully connected or troubleshot the system’s connection to Cloud Services. -If a table contains these three attributes: (System Name | Last Sync | Severity) you may want to show the system with the highest Severity because that is the system the user should tend to first. +If a table contains these 3 attributes: (System Name | Last Sync | Severity) you may want to show the system with the highest Severity because that is the system the user should tend to first. ### Table with favoriting -Adding the ability to favorite is possible for any table variation. Users can set their favorites by clicking the star icon in the favorites row. By default, the star is grey; when an item is favorited, the star becomes yellow. Clicking the star again will unfavorite the item. When an item is favorited or unfavorited, it does not move in the list unless sorting is on. +Adding the ability to favorite is possible for any table variation. Users can set their favorites by clicking the star icon in the favorites row. By default, the star is gray; when an item is favorited, the star becomes yellow. Clicking the star again will unfavorite the item. When an item is favorited or unfavorited, it does not move in the list unless sorting is on. Table with favoriting @@ -203,13 +208,13 @@ A table may sometimes need to be compact to make more rows visible at a time. Th **Example:** * You can see more data on 1 page. * You have a good overview about the structure of data. -* The structure of data is simple, informative and have less visual elements. +* The structure of data is simple, informative, and has less visual elements. #### Default spacing A table may sometimes need more space for rich graphical data. See an example below. **Use default spacing when:** -* You don’t have to display a lot of data on one page. +* You don’t have to display a lot of data on 1 page. * You use many visual indicators that are placed in columns, such as icons or charts. * You don't have to minimize paging. * Readability is a primary concern. @@ -217,14 +222,11 @@ A table may sometimes need more space for rich graphical data. See an example be Default spacing **Example:** -* You can see less data on one page. +* You can see less data on 1 page. * You will need a pagination to see more rows. * Data structure includes many visual elements. ## Tables on mobile The PatternFly table is designed to be fully responsive. When columns no longer fit within the width of the viewport, columns are stacked so that data in each row is displayed as sets of attribute-value pairs. -Mobile data table - - - +Mobile data table \ No newline at end of file diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/toolbar/toolbar.md b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/toolbar/toolbar.md index 26b4a4c4d9..09087135eb 100644 --- a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/toolbar/toolbar.md +++ b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/toolbar/toolbar.md @@ -118,7 +118,7 @@ To save space, you may represent some actions as icons. Use an icon group to pro **Custom toolbar** custom toolbar layout -The Toolbar component is extremely flexible and you can create custom toolbar layouts by working with items, groups, and spacers. Here, a custom toolbar with three labeled filters is created by paring a text label and a Select component. Items are spaced by 16px by default but here the spacing to the right of each Select filter has been modified to 24px to help better group each filter with its related label. +The toolbar component is extremely flexible and you can create custom toolbar layouts by working with items, groups, and spacers. Here, a custom toolbar with three labeled filters is created by pairing a text label and a select component. Items are spaced by 16px by default but here the spacing to the right of each select filter has been modified to 24px to help better group each filter with its related label. ### The toolbar on mobile @@ -131,11 +131,11 @@ The following is an example of a complex toolbar optimized for mobile. toolbar with filters and actions hidden on mobile -Here, the search filter and filter group containing three drop-down filters are placed in a toggle group that collapsed when the screen shrinks to mobile size. The two action buttons are part of an overflow menu that collapses to a single kabob menu. The bulk selector and sort icon button are implemented as toolbar items that remain visible at all breakpoints. +Here, the search filter and filter group containing three drop-down filters are placed in a toggle group that collapses when the screen shrinks to mobile size. The two action buttons are part of an overflow menu that collapses to a single kabob menu. The bulk selector and sort icon button are implemented as toolbar items that remain visible at all breakpoints. ## Placement -The toolbar should live as close to possible to the content it controls. For a card view or similar views, the toolbar should be placed inside of the page header. This arrangement is also recommended if the user may switch between views (e.g. view as cards or as a list). You may optionally apply the `pf-m-sticky-top` modifier to the header section to create a sticky toolbar and prevent it from scrolling off the page. +The toolbar should live as close as possible to the content it controls. For a card view or similar views, the toolbar should be placed inside of the page header. This arrangement is also recommended if the user may switch between views (e.g. view as cards or as a list). You may optionally apply the `pf-m-sticky-top` modifier to the header section to create a sticky toolbar and prevent it from scrolling off the page. ![toolbar in page header](./img/toolbar-layout-cardview.png) diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/patterns/card-view/card-view.md b/packages/documentation-site/patternfly-docs/content/design-guidelines/patterns/card-view/card-view.md index 31f32121fc..e671b79da4 100644 --- a/packages/documentation-site/patternfly-docs/content/design-guidelines/patterns/card-view/card-view.md +++ b/packages/documentation-site/patternfly-docs/content/design-guidelines/patterns/card-view/card-view.md @@ -55,10 +55,15 @@ If multiple actions can be performed on a single card, place those actions in a example of cards with multiple inline actions in a kebab #### Global actions -If an action can be performed globally on multiple cards, or if it leads to multiple pieces of content at the same time, place the action in a toolbar above the card view. In the top-right corner of your card, add a checkbox so that users can select one or more items. + +A global action is any action that applies to multiple cards that a user selects or actions that directly impact the card view as a whole (such as "Create", "Edit row item", "Delete row item", and "Export table", for example.) + +Place global actions in a toolbar above the card view. In the top-right corner of your cards, add a checkbox so that users can select one or more items. example of card view with global action toolbar +Any actions that are related to the overall page and its context (or impact the general page but not the card view directly) should be placed outside of the card view, at the top right of the page at the header level. This may include actions that edit the page header, actions that launch related windows, and so on. + #### Action card You may use an extra-small empty state inside a card to present users with another way to add more cards to the existing card view. We recommend using this feature **in addition to** a primary button in the toolbar, to ensure that the user is still able to perform the action from any page of the card view. Place the action card where a new card will be added, most likely as the very first or last card in the card view.