Support explicit column width in pixels

[dclaux]

Implementation status

• JavaScript
• UWP ([UWP] Support explicit column width in pixels #1392)
• .NET ([.NET] Support explicit column width in pixels #1662)
• iOS ([iOS] Support explicit column width in pixels #1664)
• Android ([Android] Support explicit column width in pixels #1663)
• Documentation

Problem

Achieving table-like layouts with Adaptive is hard because one has to use several ColumnSets on top of each other and there are only two ways to ensure that all columns in all those set have the same widths:

• Use weights
• Use auto and make sure the content always has the same width. That is easy enough with images, but very hard (near impossible) with text

Solution

Allow columns to have an explicit width, expressed in pixels. Essentially, make it possible in an easy and straightforward way to do what is already possible with a column containing an explicitly sized invisible image, which card authors will do to achieve the results they want.

Property	Type	Description
Column.width	string	Defines the width of the column in pixels. Width can be either a number or a string. To specify a width in pixels, set the unit px. eg: "width": "50px".

Example use:

{
	"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
	"type": "AdaptiveCard",
	"version": "1.0",
	"body": [
		{
		    "type": "ColumnSet",
		    "columns": [
		        {
		            "width": "50px",
		            "items": [
		                {
		                    "type": "Image",
		                    "url": "http://3.bp.blogspot.com/-Xo0EuTNYNQg/UEI1zqGDUTI/AAAAAAAAAYE/PLYx5H4J4-k/s1600/smiley+face+super+happy.jpg",
		                    "size": "stretch"
		                }
		            ]
		        },
		        {
		            "width": "stretch",
		            "verticalContentAlignment": "center",
		            "items": [
		                {
		                    "type": "TextBlock",
		                    "text": "This card has two ColumnSets on top of each other. In each, the left column is explicitly sized to be 50 pixels wide.",
		                    "wrap": true
		                }
		            ]
		        }
		    ]
		},
		{
		    "type": "ColumnSet",
		    "columns": [
		        {
		            "width": "50px"
		        },
		        {
		            "width": "stretch",
		            "verticalContentAlignment": "center",
		            "items": [
		                {
		                    "type": "TextBlock",
		                    "text": "In this second ColumnSet, columns align perfectly even though there is nothing in the left column.",
		                    "wrap": true
		                }
		            ]
		        }
		    ]
		}
	]
}

As rendered:

[khouzam]

Hey David,

Since Width is already a string couldn't we use that string with a differentiator to specify the width in pixels? It would save on the ambiguity when both width and pixelWidth are specified.

How do we handle?

{
	"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
	"type": "AdaptiveCard",
	"version": "1.0",
	"body": [
		{
		    "type": "ColumnSet",
		    "columns": [
		        {
		            "pixelWidth": 50,
                            "width": 50
                        },
		        {
		            "width": "stretch"
                        }

Why not do what HTML does and have 50px mean that the units are pixels?

Thoughts?

[dclaux]

The reason I went with pixelWidth is we also need explicit image sizes in pixels. But Image doesn't have a width nor a height property and I didn't want to overload the size property so it supports syntax line "50px*50px" which I think is horrible. A cleaner approach IMO was to introduce a width and a height property on Image, and given that the only accepted unit would be pixels I went for pixelWidth and pixelHeight. And therefore, I opted for pixelWidth for Column as well for consistency.

Overall it seems to me that introducing explicit properties for pixel sizes is cleaner. The rule would be that pixelWidth wins over width (same on Image).

Thoughts?

[khouzam]

David,

Thanks for the explanation, with the image scenario, I completely agree that overloading size and having to parse a string to extract both the width and the height would be horrible.

But pixelWidth and pixelHeight start becoming restrictive if we want to introduce new measures and units in the future.

If we keep the names generic width and height for images, we could take pixels initially and have the initial version only accept pixels with the px unit specified in the string, but keeping the possibility in the future of accepting other units or ways of specifying the width and the height without introducing more properties.

The rule would still apply that width and height take precedence over the size parameter for images.

[dclaux]

I used the names pixelWidth and pixelHeight so as to be able to type them as number and be explicit as to what unit they were expressed in.

What you suggest is definitely an option. However it requires that we make these properties strings instead of numbers. I would prefer using actual numbers when possible, it makes payload validation and schema-based IntelliSense easier. Also note that the "width" property in Column can be expressed as a number, representing a weight. I'd say it would be a bit weird to let authors specify a weight as a number but pixels as a string.

Typically, if we used "width" and "height" as string, it would likely be so we support values like "*" for stretch, "auto" for automatic, "150px" for explicit pixels. Both "*" and "auto" are already handled via the "size" property. So if we used "width" and "height" as strings IMO it would really only be in order to maybe support additional units in the future, such as "mm", "in", "em" or whatnot, and I am really not sure we would ever need to go there.

All that said, I am open. If there is a consensus around "width" and "height" as strings, I can live with it.

[matthidinger]

My opinion for future-proofing would be either (in order of preference):

1. Use type string with a syntax of <number><unit>. E.g., 50px or 2*
   This seems aligned with what all other UI platforms have done to my knowledge.

2. Use type object with named properties for the value, and the unit

{
  "type": "Image",
  "width": { 
     "value": 50,
     "unit": "px"
  }
}

[dclaux]

The question is, do we actually need to future proof this? This page lists supported units in CSS; I do not imagine we'd ever want to support any of them aside from % (e.g. our weight sizing for Column) and explicit pixels...

[dclaux]

BTW we might want to make a quick decision here, as I believe pixelWidth/pixelHeight is already in the process of being implemented in either the Android or iOS SDK (or both) and if we go with that for image then we should do the same for Column IMO.
Edit: it's in the UWP renderer: #1373

[khouzam]

I would rather keep Width and Height and have them as strings for future proofing even if we don't make use of other units.

[dclaux]

I can live with that. That said going with this approach on Column will introduce some inconsistency given that Column.width can be expressed as a number to represent a weight.

[jwoo-msft]

I have one question regarding to relative width; i.e. width without unit (e.g. "px"). in a columnset with both explicit and relative width, how relative width should be handled? For example, column 1 has "50px" and column 2 has "5". Should we consider explicit width in determining the width for relative widths?

[dclaux]

Any column that requests an explicit width in pixels gets what it asked for. All other columns (weight, auto or stretch) share the remaining space.

[paulcam206]

Documentation is done and in the mahiding/site1.1 branch.