Display Block / Card
Overview
Some of the concepts in Responsive UI have followed us over from prior component libraries and older technologies. Some of these have been around for quite some time, and as such, have names that we gave them way back when, before more common names came to be used for them.
One of these is the display block component. This type of element is typically called a card in the industry, but because we have such a long history of calling it display block, we’ve opted to keep using the old name to avoid (at least some) confusion and breaking changes.
We do only use display blocks within one very specific content — as the top-level containers in a view — so in that respect their usage is more focused and restricted than typical card usage.
Display blocks (a.k.a. cards) are the top-level visual containers for the content in your views. Each display block has an optional title, with its content displayed below that.
You can include multiple display blocks in a view. This is a good way to partition sections of data within a function view. You can lay out multiple display blocks in a view using either responsive layout or fixed layout.
Set a title for the display block if you’re displaying more than one in a view. You can omit the title if there is only one display block in the view and its purpose is explained by the function title.
You can optionally specify a subtitle that displays at the top-right of the display block. This text should be short since it doesn’t wrap.
If you have buttons or other elements that apply only to the data within one specific display block, you can optionally include a toolbar within that display block. You can display the toolbar either below the display block title or to the right of the title. You can’t display both a display block subtitle and a right-aligned display block toolbar, since they occupy the same location. In that case, either display the toolbar below the display block title or include the subtitle text as another element within the right-aligned display block toolbar,
If your view content is relatively simple and only has one section for the user to focus on, you do not have to use a display block in your view.
- A view without display blocks will use the primary content background color to maximize readability.
- A view with at least one display block will use a different background color to visually contrast with the display blocks in the view.
Development
Web component development
Component reference
rui-display-block
Display blocks are the top-level visual containers for the content in your views, nested within the function view. Your view may include one or more display blocks.
| Name | Type | Default | Description |
|---|---|---|---|
| titleText | string | '' | Optional title displayed at top-left of the display block |
| subtitleText | string | '' | Optional subtitle displayed at the top-right of the display block. You should not use a subtitle without a title. |
| collapseDirection | string | '' | Optional enum that allows users to collapse/expand the display block. Options are “left”, “right” and “up”. |
| isCollapsed | boolean | false | Setting this property to true will hide the display block on view load. |
| isBusy | boolean | false | Displays a busy indicator within the display block when set to true. Set this to true if the data within the display block is currently being loaded, false otherwise. |
| busyText | string | '' | Optional text displayed below the spinning busy indicator when isBusy is true. |
| isFullHeight | boolean | false | By default, display blocks are auto height, meaning they take their height from their content. Set isFullHeight to a value of true when you need the display block to take 100% of its parent’s height, such as in a match height scenario. |
Implementation
Begin by importing the rui-layout module into your application.
// import into app.module
import '@jkhy/responsive-ui-wc/components/rui-layout/rui-layout-imports';
Use the rui-display-block tag to present a display block. Nest the display block content within the opening and closing rui-display-block tags.
Below is a basic example for a display block:
<rui-display-block titleText="Customer Info" [isBusy]="loadingCustomerInfo" busyText="Loading customer information">
<!-- Display block content goes here -->
</rui-display-block>
Responsive vs Fixed Layout
Use Responsive Layout to get the default layout, where the elements in each view shift, flow, or change size or visibility to fit the available width. The view height is left unaltered, with a single vertical scrollbar used to access anything below or above the visible viewport.
You can also use Fixed Layout if you would like to keep all display blocks visible in the viewport at the same time.
Collapsing and expanding display blocks
Display blocks can collapse to the left, to the right, and up.
A collapsed display block only displays its header — with the display block title and an embedded collapse/expand button — while hiding the display block toolbar and content.
- The user collapses an expanded display block by pressing the embedded collapse button, which the display block presents when you set up collapse behavior.
- The user expands a collapsed display block by pressing anywhere in the collapsed display block.
Collapse behavior can be set up by assigning a value of “left”, “right”, or “up” to the collapseDirection property. To make display block display initially collapsed, bind the isCollapsed property to a value of true.
<rui-display-block titleText="Customer Info" isCollapsed="true" collapseDirection="left">
...
</rui-display-block>
Using rui-match-height to match heights for display blocks in the same visual row
If you have more than one display block in the same visual row and you’re not using fixed layout, it can be helpful to use the rui-match-height CSS class to match all of their heights. The rui-match-height CSS class uses flexbox layout to split the width evenly between all display blocks in the row, keeping their heights matching. At mobile size, the display blocks automatically drop into a vertically scrolling list.
Note that this approach is not compatible with the responsive layout grid. Also, this approach only works with single display blocks contained within the same row; more complex layouts will not work with this.
In the HTML, add the “rui-match-height” CSS class to a div that contains multiple display blocks whose heights you want to match.
<div class="rui-match-height">
<rui-display-block></rui-display-block>
<rui-display-block></rui-display-block>
</div>
Angular wrapper development
Wrapper reference
jha-display-block
Display blocks are the top-level visual containers for the content in your views, nested within the function view. Your view may include one or more display blocks.
| Name | Type | Default | Description |
|---|---|---|---|
| jhaTitle | string | '' | Optional title displayed at top-left of the display block |
| jhaSubtitle | string | '' | Optional subtitle displayed at the top-right of the display block. You should not use a subtitle without a title. |
| jhaCollapseDirection | string | '' | Optional enum that allows users to collapse/expand the display block. Options are “Left”, “Right” and “Up”. |
| jhaIsCollapsed | boolean | false | Setting this property to true will hide the display block on view load. |
| jhaIsBusy | boolean | false | Displays a busy indicator within the display block when set to true. Set this to true if the data within the display block is currently being loaded, false otherwise. |
| jhaBusyText | string | '' | Optional text displayed below the spinning busy indicator when jhaIsBusy is true. |
Implementation
Begin by importing the JhaLayoutModule module into your application.
// import into app.module
import { JhaLayoutModule } from '@jkhy/responsive-ui-angular/jha-layout';
@NgModule({
imports: [
...
JhaLayoutModule,
...
]
})
export class AppModule(){}
Use the jha-display-block tag to present a display block. Nest the display block content within the opening and closing jha-display-block tags.
Below is a basic example for a display block:
<jha-display-block jhaTitle="Customer Info" [jhaIsBusy]="loadingCustomerInfo" jhaBusyText="Loading customer information">
<!-- Display block content goes here -->
</jha-display-block>
Responsive vs Fixed Layout
Use Responsive Layout to get the default layout, where the elements in each view shift, flow, or change size or visibility to fit the available width. The view height is left unaltered, with a single vertical scrollbar used to access anything below or above the visible viewport.
You can also use Fixed Layout if you would like to keep all display blocks visible in the viewport at the same time.
Collapsing and expanding display blocks
Display blocks can collapse to the left, to the right, and up.
A collapsed display block only displays its header — with the display block title and an embedded collapse/expand button — while hiding the display block toolbar and content.
- The user collapses an expanded display block by pressing the embedded collapse button, which the display block presents when you set up collapse behavior.
- The user expands a collapsed display block by pressing anywhere in the collapsed display block.
Collapse behavior can be set up by assigning a value of “Left”, “Right”, or “Up” to the jhaCollapseDirection property. To make display block display initially collapsed, bind the isCollapsed property to a value of true.
<jha-display-block jhaTitle="Related Info" [jhaIsCollapsed]="true" [jhaCollapseDirection]="relatedInfoCollapseDirection">
...
</jha-display-block>
Using jha-match-height to match heights for display blocks in the same visual row
If you have more than one display block in the same visual row and you’re not using fixed layout, it can be helpful to use the jha-match-height CSS class to match all of their heights. The jha-match-height CSS class uses flexbox layout to split the width evenly between all display blocks in the row, keeping their heights matching. At mobile size, the display blocks automatically drop into a vertically scrolling list.
Note that this approach is not compatible with the responsive layout grid. Also, this approach only works with single display blocks contained within the same row; more complex layouts will not work with this.
In the HTML, add the “jha-match-height” CSS class to a div that contains multiple display blocks whose heights you want to match.
<div class="jha-match-height">
<jha-display-block></jha-display-block>
<jha-display-block></jha-display-block>
</div>
Design
Figma design
| Dev Component | Design Component Name |
|---|---|
| Display block | RUI / Layout / Display Block |
| Display block subtitle | Add text and apply the “JHA / Text / Display Block Subtitle” character style. Add text, then apply rui/regular as the Text Style and rui-pacific/content-subtitle as the Color Style. |
Double-click the display block title until it becomes selected, then type in an appropriate title. Enter a single space if you need to blank out the display block title.
Display blocks should be separated from each other by 10 pixels of space.
Content within a display block should be 22 pixels from the edge of the display block.
Adobe XD design
- Sample App - Display Block
| Dev Component | Design Component Name |
|---|---|
| Display block | JHA / Layout / Display Block |
| Display block subtitle | Add text and apply the “JHA / Text / Display Block Subtitle” character style. |
It can be helpful to lock the display block component while you drag other components onto it.
Double-click the display block title until it becomes selected, then type in an appropriate title. Enter a single space if you need to blank out the display block title.
Display blocks should be separated from each other by 10 pixels of space.
Content within a display block should be 22 pixels from the edge of the display block.