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

[filmaj]

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

• https://slack.dev/bolt-python/concepts/shortcuts/
• maybe also https://slack.dev/bolt-python/concepts/acknowledge ?
• https://slack.dev/bolt-python/concepts/opening-modals
• https://slack.dev/bolt-python/concepts/updating-pushing-views
• https://slack.dev/bolt-python/concepts/view_submissions
• https://slack.dev/bolt-python/concepts/app-home
• maybe https://slack.dev/bolt-python/concepts/options ?
• https://slack.dev/bolt-python/concepts/custom-steps
• https://slack.dev/bolt-python/concepts/context

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]

@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]

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

[github-actions[bot]]

👋 It looks like this issue has been open for 30 days with no activity. We'll mark this as stale for now, and wait 10 days for an update or for further comment before closing this issue out. If you think this issue needs to be prioritized, please comment to get the thread going again! Maintainers also review issues marked as stale on a regular basis and comment or adjust status if the issue needs to be reprioritized.

[github-actions[bot]]

As this issue has been inactive for more than one month, we will be closing it. Thank you to all the participants! If you would like to raise a related issue, please create a new issue which includes your specific details and references this issue number.