AdaptiveCard.render() return undefined criteria

[antpowell]

The render method on the AdaptiveCard class returns HTMLElement | undefined, under what criteria would the method return undefined. Asking because currently I can pass in a random string and it would render an element with no children but I would expect it to fail or return undefined.

[paulcam206]

@dclaux - care to chime in here?

[dclaux]

AdaptiveCard.render() itself will not return undefined. But AdaptiveCard extends CardElement like all other elements, and the render() method is declared on CardElement. Some elements return undefined when rendered simply because there is nothing to render, like is the case for a ColumnSet without any column.

Passing in a random string to AdaptiveCard.parse() will result in nothing being parsed, and thus you will end up with an empty card (an AdaptiveCard instance with an empty body). When rendered, you get a DOM element for the card itself and nothing else. To avoid rendering an "invalid" card, you can:

• Pass an explicit SerializationContext instance to the parse() method. When parse returns, you can check the serialization context's eventCount property and getEventAt(index) method to determine if any error was emitted
• Check that the card's body isn't empty with getItemCount()

[antpowell]

Thanks this helps a lot. My thought process was to use the empty AdaptiveCard instance as a test itself with AdaptiveCard.render().children.length === 0 but I think the context you added will def help me come up with a better way.

[antpowell]

Could you point me to the docs on SerializationContext? Checking adaptivecards.io and I can't seem to find it.

[dclaux]

In general you should rely on the object model rather than the generated DOM. The SDK might change the way it generates the DOM in the future, and if it does your code might break if it relies on the DOM. The OM however is a contract and we will continue to honor it.

As for SerializationContext, unfortunately there is no good documentation at this time. If you're coding with TypeScript and using our typings, you should be guided by IntelliSense. Otherwise, the best it to look at the available APIs here. However, again there are currently no explanations as to what those APIs do, so you will have to guess (and I can answer questions if necessary)

The short story though is you just need to do this:

let card = new AdaptiveCard();
let serializationContext = new SerializationContext();
card.parse(payload, serializationContext);

for (let i = 0; i < serializationContext.eventCount; i++) {
  let e = serializationContext.getEventAt(i);

  switch (e.event) {
    case ValidationEvent.DuplicateId:
      if (e.source && e.source instanceof Input) {
        // You probably want to fail completely in this case, duplicate Ids on inputs is never good
      }
      break;
    case ...
      // Handle other cases
      // You can also take a shortcut and not render the moment there is at least one validation event
  }
}

The list of events at this time is defined as follows:

export enum ValidationEvent {
    Hint,
    ActionTypeNotAllowed,
    CollectionCantBeEmpty,
    Deprecated,
    ElementTypeNotAllowed,
    InteractivityNotAllowed,
    InvalidPropertyValue,
    MissingCardType,
    PropertyCantBeNull,
    TooManyActions,
    UnknownActionType,
    UnknownElementType,
    UnsupportedCardVersion,
    DuplicateId,
    UnsupportedProperty,
    RequiredInputsShouldHaveLabel,
    RequiredInputsShouldHaveErrorMessage,
    Other
}

[antpowell]

This is amazing thanks! Great starting point, if I need any additional help I'll be sure to reach back out.