X

The Oracle APEX blog is your source for APEX news, technical tips and strategic direction

A Simple Guide to the New Cards Region in APEX 20.2

Chaitanya Koratamaddi
Senior Principal Product Manager, Oracle APEX | Database Tools

Cards regions in your application are useful for presenting a variety of information in small blocks. In releases prior to Oracle APEX 20.2, Cards implementation is a classic report region with the layout controlled by the cards report template. This implementation doesn't offer much of a flexibility to customize. 

Oracle APEX 20.2 introduced a new Cards native report region type. The new Cards region is a lightweight report region, declaratively supporting easy customization of card UI, including the layout, appearance, icon, badge, media, and actions.

The following are some of the main differences between the Cards implementation in releases prior to APEX 20.2 and the new Cards native report region type in APEX 20.2:

  • In releases prior to APEX 20.2, since the card layout is controlled through cards report template, it requires column aliases to map card's title and body. Therefore, the data source for Cards is always a SQL query with specific column aliases as required by the report template. Starting APEX 20.2, this restriction is no longer applicable. You can now declare any of the region data sources: Table or SQL Query, REST Enabled SQL, and REST Data Source. 
  • The declarative creation of Cards pages in releases prior to APEX 20.2 is only through the Create Application wizard. And, if you want to create a Cards region, you have to first create a Classic Report and then edit the region to select the cards report template.  But now, starting APEX 20.2, both the Create Application and the Create Page wizards support the creation of Cards pages. Now, Page Designer allows you to declaratively add a Cards region to your page. You can simply drag the Cards region from the Layout > Regions and drop in the Layout. The Cards region is added if Faceted Search page gets added from a Create Page or Create Application wizard with Cards result type.
  • Because the Cards implementation uses the Classic Report region in releases prior to APEX 20.2, all the rendering is through server-side. But, the new Cards region in APEX 20.2 uses the client-side rendering and therefore much lighter and faster in rendering.
  • In releases prior to APEX 20.2, it is not that easy to customize for example, to change the layout and appearance of the card. You have to modify the card report template and use HMTL and CSS to implement the changes. In APEX 20.2, Page Designer allows  you to do customization completely declaratively, quickly, and easily.

The new Cards region in APEX 20.2 can be displayed in three styles: with icons or initials, images as part of the body or as the background, to enhance each card presentation and you can completely control the layout. Actions can be added to each card's image, title, subtitle, as new buttons or even using the entire card to enhance user experience. Use cards to embed and share media sourced from BLOB column, URL or video in iFrame.

Prerequisites

  • You can try out the examples in any Oracle APEX 20.2 instance. You can also sign up for a free workspace on the customer evaluation instance apex.oracle.com.
  • The first example discussed in the Embedding and Displaying Media section uses DEMO_PRODUCT_INFO table and therefore you should have the Sample Database App installed in your workspace.
  • To perform the steps in the second example discussed in the Embedding and Displaying Media section, you need  The Movie Database API key.

Super- Easy Customization of Cards

In this section, you learn how new Cards report region type provides you with the ultimate control and flexibility over the user interface.

From within the Create Application wizard, you create two different Cards pages and an interactive report with form. First, you add a Cards page on the EMP table. Next, you add a faceted search page and select Cards result type in the wizard. The form that is created along with the interactive report is used to link to the Cards pages.

Starting Oracle APEX 20.2, Universal Theme supports a new Redwood Light theme style, available via Theme Roller. For any of your existing apps to uptake the latest version of Universal Theme and this new theme style, you need to refresh the Universal Theme. In this example, you simply switch to the Redwood Light Theme style using Theme Roller.

This example shows you how to create actions to link from a Cards page. You also learn how to define conditional actions.

1. Creating an Application with Cards Pages

Perform the following steps:

  1. Log in to your workspace and click App Builder. Then, click Create.
     
  2. Click New Application.
     
  3. Enter a name for your application. For example, enter Cards Demo App. Then, click Add Page.
     
  4. In the Add Page dialog, click Cards.
     
  5. In the Add Cards Page dialog, enter a name for Page Name. In this example, enter Cards
     
  6. Select EMP for Table or View and accept the default Grid layout. The wizard automatically picks up the Title Column and the Body Column using APEX data dictionary cache.
     
  7. Select ENAME for Icon Initials Column and DEPTNO for Badge Column. Then, click Add Page.


     
  8. Click Add Page again and select Faceted Search page type.
     
  9. In the Add Faceted Search Page dialog enter Faceted Search with Cards for Page Name and then select Cards.


     
  10. Repeat steps 6 and 7 above.


     
  11. Click Add Page again and select Interactive Report page type.
     
  12. In the Add Report Page dialog enter Interactive Report for Page Name. 
     
  13. Select EMP for Table or View and then select the Include Form checkbox.
     
  14. Click Add Page and then click Create Application.
     
  15. Click Run Application. Enter your workspace username and password and click Sign In.
     
  16. Now apply the Redwood Light Theme Style to your app. In the Developer Toolbar, click Theme Roller. Select Redwood Light for Style.


     
  17. Click Set as Current. Click OK and close the Theme Roller dialog.
     
  18. Your application is now refreshed with the Redwood Light theme style.

 

2. Customizing the Card UI

Now that you have the Cards pages available in your app, in this section, you can customize the UI by editing the attributes in Page Designer. In APEX 20.2, you will no longer see the Attributes and Printing sub-nodes in the tree , instead you simply select the region, and then the Attributes and Printing (if appropriate) tabs will appear in the Property Editor next to the region's main properties.

Card Title, Subtitle, Body, Secondary Body, and Media include an Advanced Formatting option which enables flexible customization with HTML expressions. Including HTML expressions, all free form text attributes, such as CSS Classes, Icon or Image Description, or Badge Label, support column substitutions through standard substitution string syntax (for example, &ENAME.)

  1. Click Cards. Notice that each card in the example displays title, initials, body and badge. In the Developer Toolbar, click Edit Page 2.


     
  2. In Page Designer, under Rendering, select the Cards region. In this example, select Cards. Notice the Region and Attributes tabs in the Property Editor.
    Under Region tab, notice that the region type is Cards. Under Region > Appearance, notice the new Cards Container template. This template includes different options that allow to control the card styles, is a new addition to the Universal Theme in APEX 20.2. Therefore, for your old apps to uptake the Cards Container template, you must refresh the Universal Theme. 
     
  3. Click the Attributes tab. You can define the mapping of the card under Attributes. You can declaratively specify Title, Subtitle, Body, Secondary Body, Icon and Badge, Media, and more. In the example, the Icon Source is the Initials value of the ENAME column value. You can also change the position of the icon in the card header by selecting the values for Icon Position: Top, Start, and End.
    Entering Icon Description or Badge Label provides better accessibility for your application. In this example, you want to specify the label for the badge to describe the badge value. Enter Department for Badge Value.


     
  4. Click Save and Run Page
     
  5. You don't see the badge label for the cards yet. This is controlled by the style defined in the Cards Container template.
    In the Developer Toolbar, click Quick Edit and then click the Wrench icon in the right upper corner.


     
  6. In the Live Template Options dialog, for Style, select Style C and review how the cards are displayed.
    Then, select Style B and click Save.


     
  7. The badge label is displayed now. In the left navigation menu, click Faceted Search with Cards.


     
  8. Notice that facets along with the cards region are displayed. Starting APEX 20.2, facets display bar and pie charts of facet value counts.  In releases prior to APEX 20.2, facet controls work along with only the classic report region. Starting APEX 20.2, they work with the new native Cards report region type as well.
    In the Developer Toolbar, click Edit Page 3.


     
  9. Under Rendering, select Search Results. In the Property Editor, under Regions, notice that the region type is Cards.


     
  10. Navigate to your application running environment and in the left navigation menu, select Cards.
     
  11. Unlike the other report regions, Cards region doesn't have a header rendered. Developers might want to define a message when the report doesn't return any data. In the Developer Toolbar, click Edit Page 2.
     
  12. Under Rendering, select Cards.
    In the Property Editor, under Region > Where Clause, specify a where condition for the report to not return any data. Enter 1=0 and then click Save and Run Page
     
  13. You now see a No data found message. You can customize this to display a meaningful message. In the Developer Toolbar, click Edit Page 2.


     
  14. Under Rendering, select Cards and then In the Property Editor, click Attributes.
    Under Messages, click the Code Editor icon for When No Data Found. As you enter a message, notice that the No Data Found Icon field is displayed.  In this example, enter No Employees Found and click OK.


     
  15. The No Data Found Icon field is displayed. Click the List of Values icon, and search for Warning. Select fa-warning Font APEX icon and then click Save and Run Page.


     
  16. The custom message along with the icon is now displayed.


     
  17. Navigate to Page Designer and then in the Property Editor, remove the condition defined under Region > Where Clause as in step 12 above.
    Then, click Save and Run Page. The report is now displayed again.


3. Defining Actions to Link From Cards

A Cards page displays a subset of information and then can include links to more detail. In releases prior to APEX 20.2, you can include functionality to link only from the card title. This is achieved by modifying the SQL query and using the APEX_PAGE.GET_URL API. Now, the native Cards report region type allows you to create different types of actions that link from cards. You can create actions to link from full card, card title, card subtitle, media, or buttons. You can also add multiple buttons within each of the cards.

In this example, you want to ensure that a link from the full card navigates to the form dialog page that was created in the Creating an Application with Cards Pages section.
 

  1. In Page Designer, under Rendering > Cards, select Actions, right-click and select Create Action.
     
  2. In the Property Editor, select Full Card for Type and then click No Link Defined.


     
  3. In the Link Builder - Target dialog, select / enter the following and then click OK.
    • Page: Form dialog page number. In this example, select 5
    • Set Items > Name: P5_EMPNO
    • Value: EMPNO
    • Clear Cache: 5
       
  4. The link target is set now. Click Save and Run Page
     
  5. Notice that a full card is a clickable link now. Click any of the cards to view the form dialog page. Close the dialog.


     
  6. Navigate to Page Designer. Now you want to convert the Full Card action to the Title action type. Under Rendering select Full Card action.
    In the Property Editor, select Title for Type and then click Save and Run Page.
     
  7. Notice that the full card is not a link anymore. Hover over the title column for each of the cards and notice that the card title is a link now. 
    Click the title for any card to view the form dialog page. Close the dialog.


     
  8. Next, you want to create a conditional action in the Cards region. Navigate to Page Designer. Under Rendering, select Cards > Actions.
    Right-click Actions and select Create Action.
     
  9. Accept the default Button for Type and enter Edit for Label.
     
  10. You can specify where the button should be positioned on the card. For Layout > Position, accept the default Primary. Click No Link Defined.


     
  11. In the Link Builder - Target dialog, select / enter the following and then click OK.
    • Page: Form dialog page number. In this example, select 5
    • Set Items > Name: P5_EMPNO
    • Value: EMPNO
    • Clear Cache: 5
       
  12. The link target is set now. Click Save
     
  13. You can also define the appearance of the button. Under Appearance, select Text with Icon for Display Type and then for Icon, pick up the fa-edit Font APEX icon.
    Turn on the Hot switch.


     
  14. You can specify a condition type that must be met in order for this Cards component to be rendered or processed. Since we refer to Columns in the condition, we must specify For Each Row in order for the condition to be evaluated for each card. 
    In this example, for Server-side Condition, select / enter the following and then click Save and Run Page.
    • Type: Item = Value
    • Item: JOB
    • Value: SALESMAN
    • Execute Condition: For Each Row

     
  15. Notice that the title is still a clickable link and the Edit button appears only on those cards that meet the condition JOB = SALESMAN.


     

On top of column row condition, actions conditionally can be defined using authorization schemes or build options as well.  You can define multiple actions of the same type. However, only button actions are rendered multiple times. For all other action types, the first TRUE display condition gets rendered, and the rest are ignored.

Embedding and Displaying Media

The new Cards report region type allows you to embed and share media sourced from a BLOB column, URL, or video in iFrame. The first example in this section shows Cards region using  a BLOB column as the media source. Web Source Modules are now renamed as REST Data Sources. In the second example, the report source for the Cards region is a REST Data Source (formerly Web Source Module). This example shows how to use an image URL as the media source. 

Using a BLOB Column as a Media Source

Fiirst, you create a Cards page on a table that has a BLOB column. Then,  you choose this BLOB column as the media source.

  1. Now you can also create a Cards page from the Create Page wizard. Navigate to Page Designer. Click the Create icon and then select Page.


     
  2. Select Report and then select Cards.
     
  3. Enter Products for Page Name and click Next.
     
  4. For Navigation Preference, select Create a new navigation menu entry and click Next.
     
  5. The DEMO_PRODUCT_INFO table from the Sample Database App includes a BLOB column. In this example, for Report Source > Table / View Name, select DEMO_PRODUCT_INFO and click Next.

  6. Accept the default Grid layout, and the default selections for Title Column and Body Column.
    Select PRODUCT_NAME for Icon Initials Column, and Category for Badge Column.
    Click Create.


     
  7. In Page Designer, under Rendering, select Products. In the Property Editor, click Attributes.
     
  8. Under Media, select BLOB Column for Source and select PRODUCT_IMAGE for BLOB Column.


     
  9. For BLOB Attributes > Last Updated Column, select IMAGE_LAST_UPDATE. Note that when you use a BLOB column for the media source and if you define the Last Updated Column, then APEX renders ETag. That is, the image gets cached in the browser and the next time when the  page is rendered, the image is fetched from the cache but not from the server.
     
  10. In order for APEX to get the image for each card, defining the primary key column is required. If the region is set to display scroll pagination, the primary key is also used to avoid displaying duplicate rows.
    For Card > Primary Key Column 1, select PRODUCT_ID and then click Save and Run Page.
     
  11. Notice that the cards now display media.


     

Using an URL as a Media Source

In this example, first you create a REST Data Source to fetch data using The Movie DB API. This REST API queries the movies database and fetches movies data. In your application, you create a Cards page using this REST Data Source as a report source. Your Cards region then uses an image URL to embed and display poster media.


1. Creating a REST Data Source


Perform the following steps:

  1. Navigate to your application shared components. Under Data Sources, click REST Data Sources.
     
  2. Click Create. In the Create REST Data Source wizard, select / enter the following:
    • Create REST Data Source method: From Scratch
    • Name: Movies DB
    • Endpoint URL:  https://api.themoviedb.org/3/list/10
       
  3. Turn on the Authentication Required switch and select URL Query String for Authentication Type.
    Enter the name of the URL Query String parameter. In this example, enter api_key.
    Enter the secret (value) for the URL Query String parameter. In this example, enter your The Movie DB API key. 
     
  4. Click Discover and then click Create REST Data Source.
     
  5. Click the REST Data Source name. In this example, click Movies DB.


     
  6. Click the Parameters tab and then click Add Parameter.
     
  7. Enter language for Name and en-US for Value. Click Add Parameter.


2. Creating a Cards Page


Perform the following steps:

  1. Navigate to your application home page and then click Create Page.
     
  2. Select Report and then select Cards.
     
  3. Enter Movies for Page Name and click Next.
     
  4. Select Create a new navigation menu entry for Navigation Preference and click Next.
     
  5. For Data Source, select REST Data Source and then select the one that you just created. In this example, select MOVES DB. Click Next.


     
  6. Unlike when you choose Local Table as the data source, notice that the Title  Column and the Body Column are not pre-selected when you choose REST Data Source as the data source.
    Select the following and click Create:
     
    • Title Column: TITLE
    • Body Column: OVERVIEW
    • Icon Initials Column: TITLE
    • Badge Column: RELEASE_DATE

  7. The Cards page is now created. In Page Designer, under Rendering, select MOVIES.
     

3. Embedding and Displaying Images Sourced from an URL


Perform the following steps:

  1. In the Property Editor, click Attributes and then navigate to Media.
     
  2. Select Image URL for Source.
     
  3. For  URL, enter https://image.tmdb.org/t/p/w500/&POSTER_PATH. .
    Click Save and Run Page.
    The URL https://image.tmdb.org/t/p/w500/&POSTER_PATH. fetches the movies' posters using the POSTER_PATH column values. It includes column substitution string &POSTER_PATH.


     
  4. Movies cards with the poster media embedded are displayed. Notice that the Scroll pagination is the default when you create a Cards region.


     
  5. In Page Designer, under Attributes, navigate to Pagination.
    Select Page for Type and  enter 4 for Cards Per Page. Click Save and Run Page.
     
  6. Notice the Cards page now displays traditional (Page type) pagination.

 

Summary

Oracle APEX 20.2 introduced a new Cards report region type. The new Cards component provides developers with the ultimate control and flexibility over the user interface. Developers can very easily customize every aspect of the card UI, including the layout, appearance, icon, badge, media, and actions. As Cards usually provide entry to more detailed information, you can include a number of actions as button or links declaratively. In your workspace, install the Sample Reporting sample app to see an example of the new Cards region. Visit the Cards page on the Universal Theme Sample App to see Cards in action. 

 

Join the discussion

Comments ( 2 )
  • Badri Narayanan Saturday, October 24, 2020
    This is awesome..
  • Haitham Alshami Wednesday, November 25, 2020
    Thanks so much for this short guide, which is full of great information.
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.