{"_id":"59e143dd35da0300261212e0","project":"5746675a5aa03c0e00fce9bc","version":{"_id":"5746675a5aa03c0e00fce9bf","__v":8,"project":"5746675a5aa03c0e00fce9bc","createdAt":"2016-05-26T03:02:50.849Z","releaseDate":"2016-05-26T03:02:50.849Z","categories":["5746675a5aa03c0e00fce9c0","574899e7e8c6a420000b7314","57489c11d929e919006ed4ae","57489c82d929e919006ed4b1","57489ce91b345d0e004e5231","5748a82e1b345d0e004e5256","59ce5c88e8c105001a4bedd7","59f96cd129b4d600246c2899"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"category":{"_id":"59ce5c88e8c105001a4bedd7","project":"5746675a5aa03c0e00fce9bc","version":"5746675a5aa03c0e00fce9bf","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2017-09-29T14:45:28.177Z","from_sync":false,"order":1,"slug":"blockspring-scripts","title":"Blockspring Scripts"},"user":"545988354f86a50800f9cce4","__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-10-13T22:53:17.238Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":5,"body":"Let's learn how to give your script a front-end. In this case it's a sidebar form.\n[block:api-header]\n{\n  \"title\": \"Usecase: Count Cards by Assignee\"\n}\n[/block]\nMost apps don't have a good way to generate quick reports. In this tutorial, we'll write a script that gives a front-end to our count cards function. Specifically, we'll enter a member's email and see how many cards they've been assigned.\n\n## Build our sidebar form\nFirst thing is first - let's write a function that opens a sidebar in Trello, with a preliminary form.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"import trello_app\\n\\ndef card_report():\\n    # build form\\n    return {\\n        \\\"_type\\\": \\\"form\\\",\\n        \\\"_title\\\": \\\"Card Report\\\",\\n        \\\"_inputs\\\": [{\\n            \\\"name\\\": \\\"username\\\",\\n            \\\"type\\\": \\\"text\\\"\\n        }],\\n        \\\"_on_submit\\\": \\\"count_cards_\\\"\\n    }\\n\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\nNow go back to Trello, and run the `card_report` App Button.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/a4d8184-sidebar.gif\",\n        \"sidebar.gif\",\n        797,\n        605,\n        \"#dbdada\"\n      ],\n      \"border\": true\n    }\n  ]\n}\n[/block]\nClicking the App Button opens a sidebar with the form you specified in your script. Let's dig into the script itself.\n\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"def card_report():\\n    # build form\\n    return {\\n      \\t### _type tells us what type of UI to open. So far the only option is form.\\n        \\\"_type\\\": \\\"form\\\",\\n      \\n      \\t### _title sets the title of the form sidebar.\\n        \\\"_title\\\": \\\"Card Report\\\",\\n      \\n      \\t### _inputs determines what types of inputs to generate for your form. The name will be pased into your code and shown as a label. The type can be text or textarea for now.\\n        \\\"_inputs\\\": [{\\n            \\\"name\\\": \\\"username\\\",\\n            \\\"type\\\": \\\"text\\\"\\n        }],\\n      \\n      \\t### _on_submit determines what function in your script to call when they submit the form.\\n        \\\"_on_submit\\\": \\\"count_cards_\\\"\\n    }\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\nSo by editing that configuration, we can generate our own custom forms.\n[block:api-header]\n{\n  \"title\": \"When We Submit...\"\n}\n[/block]\nYou may have noticed we set `count_cards_` to be the function to call when the user submits our form. Let's create our count cards function.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"import trello_app\\n\\ndef count_cards_():\\n    # get member from form by username\\n    username = trello_app.get_request().get(\\\"username\\\")\\n    board = trello_app.get_current_board()\\n    member = next((x for x in board.get_members() if x.get_field(\\\"username\\\") == username), None)\\n\\n    # catch error if not a real member\\n    if not(member):\\n        return \\\"Could not find %s\\\" % username\\n\\n    # count cards\\n    cards = board.get_cards(filter=\\\"open\\\")\\n    member_cards = list(filter(lambda x: member.get_field(\\\"id\\\") in x.get_field(\\\"idMembers\\\"), cards))\\n    return \\\"%s open cards for %s\\\" % (len(member_cards), username)\\n\\ndef card_report():\\n    # build form\\n    return {\\n        \\\"_type\\\": \\\"form\\\",\\n        \\\"_title\\\": \\\"Card Report\\\",\\n        \\\"_inputs\\\": [{\\n            \\\"name\\\": \\\"username\\\",\\n            \\\"type\\\": \\\"text\\\"\\n        }],\\n        \\\"_on_submit\\\": \\\"count_cards_\\\"\\n    }\\n\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\nThe most important concept to this function is `.get_request()`. This lets you retrieve the form response as a dictionary/hash. Since we named the form input `username`, that's the variable we'll pull out of get_request().\n\nThe rest of the function is fairly intuitive. Given the member, it counts their boards and returns a text response. Let's see the sidebar form in action.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/393088e-complete_sidebar.gif\",\n        \"complete_sidebar.gif\",\n        1118,\n        634,\n        \"#dbdbdb\"\n      ],\n      \"border\": true\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Need Help?\"\n}\n[/block]\nIf you run into any issues, or what to chat with others, [connect to the Blockspring community](https://blockspring-help.readme.io/docs/getting-help) right from the Scripts editor.","excerpt":"","slug":"tutorial-sidebars-ui","type":"basic","title":"Tutorial: Sidebar Form"}

Tutorial: Sidebar Form


Let's learn how to give your script a front-end. In this case it's a sidebar form. [block:api-header] { "title": "Usecase: Count Cards by Assignee" } [/block] Most apps don't have a good way to generate quick reports. In this tutorial, we'll write a script that gives a front-end to our count cards function. Specifically, we'll enter a member's email and see how many cards they've been assigned. ## Build our sidebar form First thing is first - let's write a function that opens a sidebar in Trello, with a preliminary form. [block:code] { "codes": [ { "code": "import trello_app\n\ndef card_report():\n # build form\n return {\n \"_type\": \"form\",\n \"_title\": \"Card Report\",\n \"_inputs\": [{\n \"name\": \"username\",\n \"type\": \"text\"\n }],\n \"_on_submit\": \"count_cards_\"\n }\n", "language": "python" } ] } [/block] Now go back to Trello, and run the `card_report` App Button. [block:image] { "images": [ { "image": [ "https://files.readme.io/a4d8184-sidebar.gif", "sidebar.gif", 797, 605, "#dbdada" ], "border": true } ] } [/block] Clicking the App Button opens a sidebar with the form you specified in your script. Let's dig into the script itself. [block:code] { "codes": [ { "code": "def card_report():\n # build form\n return {\n \t### _type tells us what type of UI to open. So far the only option is form.\n \"_type\": \"form\",\n \n \t### _title sets the title of the form sidebar.\n \"_title\": \"Card Report\",\n \n \t### _inputs determines what types of inputs to generate for your form. The name will be pased into your code and shown as a label. The type can be text or textarea for now.\n \"_inputs\": [{\n \"name\": \"username\",\n \"type\": \"text\"\n }],\n \n \t### _on_submit determines what function in your script to call when they submit the form.\n \"_on_submit\": \"count_cards_\"\n }", "language": "python" } ] } [/block] So by editing that configuration, we can generate our own custom forms. [block:api-header] { "title": "When We Submit..." } [/block] You may have noticed we set `count_cards_` to be the function to call when the user submits our form. Let's create our count cards function. [block:code] { "codes": [ { "code": "import trello_app\n\ndef count_cards_():\n # get member from form by username\n username = trello_app.get_request().get(\"username\")\n board = trello_app.get_current_board()\n member = next((x for x in board.get_members() if x.get_field(\"username\") == username), None)\n\n # catch error if not a real member\n if not(member):\n return \"Could not find %s\" % username\n\n # count cards\n cards = board.get_cards(filter=\"open\")\n member_cards = list(filter(lambda x: member.get_field(\"id\") in x.get_field(\"idMembers\"), cards))\n return \"%s open cards for %s\" % (len(member_cards), username)\n\ndef card_report():\n # build form\n return {\n \"_type\": \"form\",\n \"_title\": \"Card Report\",\n \"_inputs\": [{\n \"name\": \"username\",\n \"type\": \"text\"\n }],\n \"_on_submit\": \"count_cards_\"\n }\n", "language": "python" } ] } [/block] The most important concept to this function is `.get_request()`. This lets you retrieve the form response as a dictionary/hash. Since we named the form input `username`, that's the variable we'll pull out of get_request(). The rest of the function is fairly intuitive. Given the member, it counts their boards and returns a text response. Let's see the sidebar form in action. [block:image] { "images": [ { "image": [ "https://files.readme.io/393088e-complete_sidebar.gif", "complete_sidebar.gif", 1118, 634, "#dbdbdb" ], "border": true } ] } [/block] [block:api-header] { "title": "Need Help?" } [/block] If you run into any issues, or what to chat with others, [connect to the Blockspring community](https://blockspring-help.readme.io/docs/getting-help) right from the Scripts editor.