README.md

Widget Post Message Definitions

Overview

This project defines and generates the Post Message handling code for our various Widget SDKs. The documentation for Post Messages and their payloads can be found here.

Generating source code

Running the generators

After you install the version of Ruby specified in .ruby-version , you can run the following command to execute all generators:

./bin/run

Using the generated code

The generated output should be grouped by language (and perhaps use case). For example, the generated TypeScript source can be found in the packages/typescript directory. These packages can then be imported into the corresponding SDK or library using the appropriate import method. Using TypeScript again as an example, this package is released to npm where it can then be imported as an npm package in any downstream library.

Adding or modifying a Post Message definition

Open lib/post_message_definition.yml and make the required modifications. Note that this file is grouped into various sections with post_messages being where all Post Messages are defined. Definitions should be kept in their corresponding namespace (either widget, entity, or generic).

Adding or modifying a template

Source code is generated by defining a template class. This template class is where the ERB template and any auxiliary methods live.

class Template::TypescriptDocumentation < Template::Base
  HEADER = <<-EOS
    |<!-- AUTO GENERATED, DO NOT EDIT -->
  EOS

  CONTENT = <<-EOS
    |# Callback Documentation
    |
    |<%- post_message_definitions.each do |post_message| -%>
    |## <%= post_message %>
    |
    |<%- post_message.properties.each do |property, rhs| -%>
    |- <%= property -%>
    |<%- end -%>
    |<%- end -%>
  EOS
end

When adding a new template, create a class in the lib/template directory using the <language>_<thing>.rb (eg, typescript_source.rb, or typescript_documentation.rb) naming convention and extend Template::Base. Then import and save the output to the appropriate file in the corresponding package. For example:

Template::TypescriptDocumentation.save("packages/typescript/docs/generated.md",
                                       post_message_definitions: post_message_definitions)

Development

Refer to CONTRIBUTING.md for details.

---