< Jewel Components list

Jewel Card


Available since version 0.9.4.

Class Extends
org.apache.royale.jewel.Card org.apache.royale.jewel.VContainer

Note: This component is currently only available for JavaScript.


The Jewel Card class is a Container for content like text or images that supports optional parts like title and action (mostly buttons) zones.

Card is a vertical container with a default “panel” styling that extends the features already provided by VContainer.

It can be used alone or with other complementary components listed below:

Component Description
CardHeader a container to hold drawer header content (i.e: a title, image icon logo, or header actions)
CardTitle a title label to use in the Card or inside the drawer header with specific styling
CardPrimaryContent a container to hold card main content
CardExpandedContent a container for content that need to remove all paddings and gaps with the surrounding Card
CardActions a footer container to hold actions like buttons, icons or navigation

Example of use

In MXML declare a Card like this:

Simple Card

This is the most basic Jewel card that can be declared. Elements are laid out vertically and with a default gap predefined in Jewel Theme.

    <j:CardTitle text="Jewel Simple Card"/>

    <j:Label text="This is the content"/>

    <j:Button text="Action" emphasis="primary"/>

Card with optional components

For advanced card layouts the next example shows how to use optional Card components.

First, we add a CardHeader with two BarSection components to separate the header content. In the left section we add the CardTitleand in the right one we add an IconButton (that provides an action. In the example we describe the action as “Assign new data”).

Next, we have a CardPrimaryContent with the main content; in this case, some text description and a ComboBox component. Those elements are laid out vertically with some gap between them.

Finally a CardActions with two BarSections (similar to card header). In the left we have a Label and in the right a NumericStepper.

			<j:CardTitle text="Object Collection" className="secondary-normal"/>
		<j:BarSection itemsHorizontalAlign="itemsRight">
			<j:IconButton unboxed="true" click="assignNewData(avengersComboBox)">
					<js:MaterialIcon text="{MaterialIconType.SETTINGS_BACKUP_RESTORE}" />
					<j:ToolTip toolTip="Assign new data"/>
		<j:Label multiline="true">
			<j:html><![CDATA[<p>This <b>ComboBox</b> is using an object collection as <i>dataProvider</i>. Use <i>labelField</i> to indicate the object property to use as label. A <b>ComboBoxTextPrompt</b> bead is used to show a prompt message.</p>]]></j:html>
		<j:ComboBox localId="avengersComboBox" labelField="label" dataProvider="{listModel.avengers}">
				<j:ComboBoxTextPrompt prompt="Avengers Team..."/>
	<j:CardActions itemsVerticalAlign="itemsCenter">
			<j:Label localId="avengersComboBoxResult" html="{describeItem(avengersComboBox.selectedItem)}"/>
		<j:BarSection gap="3" itemsHorizontalAlign="itemsRight">
			<j:Label text="Select Index: "/>
			<j:NumericStepper valueChange="avengersComboBox.selectedIndex = event.target.value" minimum="0" maximum="8"/>

In ActionScript we can do the same in the following way. In this case we declare just the Card and a Label inside the card to keep it simple:

var card:Card = new Card();
// add a label to the Card
var label:Label = new Label();
label.text = "Some text";
// add the Container to the parent

where parent is the container where the control will be added.

Relevant Properties and Methods

Check the Reference of org.apache.royale.jewel.Card for a more detailed list of properties and methods.


PROPERTY Type Description
currentState String The name of the current state.
itemsExpand Boolean Make items resize to the fill all container space.
itemsHorizontalAlign String Distribute all items horizontaly. Possible values are: itemsLeft, itemsCenter, itemsRight, itemsSpaceBetween, itemsSpaceAround
itemsVerticalAlign String Distribute all items verticaly. Possible values are: itemsSameHeight, itemsCenter, itemsTop, itemsBottom
gap Number Assigns variable gap in steps predefined in Jewel CSS.
numElements int The number of element children that can be laid out.
mxmlContent Array The array of childs for this group. Is the DefaultProperty.
states Array The array of view states. These should be instances of org.apache.royale.states.State
strandChildren IParent An object to access the immediate children of the strand.
variableRowHeight Boolean Specifies whether layout elements are allocated their preferred height.


Method Parameters Description
addElement c(IChild), dispatchEvent(Boolean=true) Add a component to the parent.
addElementAt c(IChild), index(int), dispatchEvent(Boolean=true) Add a component to the parent at the specified index.
getElementIndex c(IChild) Gets the index of this subcomponent.
getElementAt index(int) Get a component from the parent at specified index.
removeElement c(IChild), dispatchEvent(Boolean=true) Remove a component from the parent.

Relevant Events

The most important event is initComplete, which indicates that initialization of the card is complete.

It is needed when some action coded in a callback function needs to be triggered when the card is ready to use after initialization.

You can attach callback listeners to the initComplete event in MXML as follows:

<j:Card initComplete="initCompleteHandler(event)"/>

the initComplete event will use the initCompleteHandler callback function you provide in ActionScript:

        private function initCompleteHandler(event:Event):void {
            trace("Card is ready!");

When the container is initialized the message “Card is ready!” appears in the console log.

In ActionScript we can add an event handler this way:

var c:Card = new Card();
c.addEventListener('initComplete', initCompleteHandler);

Relevant Beads

Bead Type Implementation Description
ContainerView org.apache.royale.core.IBeadView This is the default view bead.
VerticalLayout org.apache.royale.core.IBeadLayout This is the default layout bead.
Viewport org.apache.royale.core.IViewport Define the area that display content.

Optional Beads

Bead Type Implementation Description
ContainerDataBinding org.apache.royale.binding.DataBindingBase Provide binding capabilities to the container.

Common Beads

Jewel Card can use any of the layout beads available in the Jewel library. Also you can check Related controls section to see some preconfigured containers with specific layouts.

More examples

Other useful Jewel containers components are: