docs: Consider using the bolt-python Block Kit wrapper classes instead of JSON

filmaj commented 2 weeks ago

A developer on the Community Workspace noted that some of our docs use example Block Kit JSON payloads, while bolt-py provides helper wrapper classes for modeling Block Kit that may provide a better authoring experience.

Example here: https://slack.dev/bolt-python/concepts/shortcuts/ is:

@app.shortcut("open_modal")
def open_modal(ack, shortcut, client):
    # Acknowledge the shortcut request
    ack()
    # Call the views_open method using the built-in WebClient
    client.views_open(
        trigger_id=shortcut["trigger_id"],
        # A simple view payload for a modal
        view={
            "type": "modal",
            "title": {"type": "plain_text", "text": "My App"},
            "close": {"type": "plain_text", "text": "Close"},
            "blocks": [ ... ]
        }
    )

but perhaps that could be replaced with:

View(
    type="modal",
    callback_id="modal-id",
    title=PlainTextObject(text="My App"),
    close=PlainTextObject(text="Close"),
    blocks=[ ... ]
)

The page URLs

Requirements

Please read the Contributing guidelines and Code of Conduct before creating this issue or pull request. By submitting, you are agreeing to those rules.

seratch commented 2 weeks ago

@filmaj Thanks for creating this issue.

I personally don't think we should replace it. Having the dict data structure can still be beneficial as it's easier to convert JSON data in Block Kit Builder into dict objects. If the documents only encourage the class-based ones, first-time developers could be confused by the difference between the api.slack.com documents and the bolt-python docs. If we add equivalent ones using classes rather than replacing the current ones, it might be helpful for developers who prefer using classes.

The only exception is bolt-java. Java doesn't provide a handy way to describe Map (dict in Python; objects in JS) data structures, unlike TS and Python. Thus, it's straightforward to ask developers to use classes and their factories and/or Kotlin DSLs.

filmaj commented 2 weeks ago

Ah yes good point @seratch ! Perhaps our documents in Bolt-Python should provide examples in both dict data structure style as well as the slack sdk models? Not sure. I think it's something to discuss with our colleagues in devrel education cc @lukegalbraithrussell

slackapi / bolt-python

docs: Consider using the bolt-python Block Kit wrapper classes instead of JSON #1139

The page URLs

Requirements