Hướng dẫn viết Custom Power-up cho Trello sử dụng Laravel

camnh

Mar 9, 2022 • 9 min read

Phiên bản Laravel đang sử dụng là 9.x, sử dụng Laravel Valet để tạo https. Https là yêu cầu bắt buộc để implement 1 power-ups trong Trello

1. Tạo extension trong Trello

Để tiến hành viết Trello extensions, nhiệm vụ đầu tiên là phải tạo trello extension trước. Truy cập Trello extension qua trang: https://trello.com/power-ups/admin và ấn nút Thêm mới.

Điền các thông tin cần thiết với Trello extension, chú ý với Iframe connector thì phải lựa chọn đường link với giao thức https. Đây cũng chính là entry point cho power-up.

Phần cài đặt https và domain thì các team tự tùy chỉnh. Ở hình trên thì domain đang sử dụng là localhost. Iframe này đóng vai trò là cổng chuyển tiếp giữa các power-up với nhau

*Cài đặt https trên domain powerup.test (cấu hình trong /etc/hosts)*

Sau khi cài đặt 1 project Laravel từ đầu, bước tiếp theo đến cấu hình powerups và các capabilities để chạy

Phần basic information và icon thì serve ảnh dưới dạng https có kích thước là 144 * 144 px

2. Kích hoạt capabilities trong Trello

Các capabilities trong Trello cho phép mình thêm các tính năng mà các powerup cần có. Ví dụ như Show Authorization thì cần login và xác thực người dùng trước khi đăng nhập vào board, card button để tạo ra button làm nhiệm vụ cho card cụ thể (Thêm log, thêm bug note, …)

Chú ý dùng capabilities nào thì kích hoạt capabilities ấy lên. Click vào Learn more… để xem chi tiết capabilities đó là gì và giao diện ra sao

Trong trường hợp có nhiều người làm thì có thể thêm vào collaborator

Phần API key có thể lấy ở đây: https://trello.com/app-key . Đồng thời thêm phần origin để cho phép các domain sau khi authorization xong thì return về domain này

*Cho phép Powerup.test được truy cập sử dụng API*

Phần Privacy và Compliance cũng cần thêm API key vào, cho phép trello thu thập data bằng cách chọn Yes ở trên

*Cho phép Trello truy cập API key và Trello data gathering*

Sau đó ấn Save để kết thúc việc Setup Powerups

3. Tích hợp Powerups vào Board

Để tích hợp Powerups vào Board, chọn Powerups ở menu top và tìm kiếm Powerups vừa tạo

Trong trường hợp không tìm thấy Powerups đồng nghĩa với việc chọn sai Workspace visibility khi tạo mới Powerup ở phần 1. Nếu tạo sai workspace thì phải tạo lại Powerup từ đầu.

4. Phát triển chức năng Powerups

Mở routes/web.php, đây chính là trang chủ powerups để nạp capabilities vào đó. Routes web này được dùng để điều hướng path sang các controller hoặc operation tương ứng

File Welcome.blade.php: View ứng với path / ở trên

Xây dựng layouts/app.blade.php, layouts này dùng để dẫn link đến Trello Powerup cdn, các hàm hỗ trợ cho Trello cũng sử dụng method từ cdn này.

File client.js là file chứa capabilities mà đã được tick trong powerups installation phần 2, được để trong thư mục public

Ở phần này tốt nhất nên chia project thành các modules, mỗi modules là 1 package trong Laravel do mỗi module trong Powerups sẽ khác nhau về capabilities. Nói cách khác, mỗi powerups là một package trong Laravel.

Kết quả khi chạy powerups

*Estimate Size button ứng với 'card-buttons' được tạo ở trên*

Card button là capabilities của Trello Powerups

5. Tạo migration

Để lưu dữ liệu trong Laravel, sử dụng migration và chỉnh sửa .env theo bài toán đặt ra. Phần này là cơ bản của Laravel nên sẽ không cần giải thích ở đây

Sử dụng Trello Powerup card-back-section. Copy trong phần Learn more của Trello capabilities tại https://developer.atlassian.com/cloud/trello/power-ups/capabilities/card-back-section/.

*Card back section với route là /categories*

Chú ý ở đây đang sử dụng t.signUrl(‘./categories’). Phải dùng chấm đằng trước nếu không sẽ không nhận
Chú ý với route: /categories như trong t.signUrl() thì tương ứng có route /categories trong routes/web.php

*/categories ứng với Controller và action tương ứng*

Hay nói cách khác, Trello hiểu khi load phần card-back-section ra thì nội dung là iframe được lấy từ route /categories trong routes/web.php

Phần view categories.index tương ứng

Kết quả đạt được là thông tin của category: camnh được hiển thị trên màn hình

Để sử dụng modal trong Trello thì cần sử dụng jquery và custom js như sau

*Thêm jquery và yield scripts tương ứng để viết custom scripts*

Cập nhật lại index.blade.php

Trong này link “Create new” được thêm mới, đồng thời do bên client.js có sử dụng t.signUrl(), nên các UI functions của Trello cũng sử dụng được biến t thông qua window.TrelloPowerUp.iframe()

Mục đích là khi ấn vào link thì mở ra một modal box của Trello để làm việc. Các UI functions có thể được tra cứu tại link này https://developer.atlassian.com/cloud/trello/power-ups/ui-functions/

Tương tự như lúc trước, url được nhận là /categories/create,vì thế cần cập nhật /categories/create trong routes/web.php.

Create action trong CategoryController.php

Kết quả

*Modal create category khi ấn nút Create New*

Để xử lí ở trang này, sử dụng ajax request và tiến hành gọi t.closeModal() để đóng modal

Sửa và xóa cũng tương tự

Sau khi đóng modal, nhiệm vụ tiếp theo là refresh lại card-back-section sau khi thêm mới để không cần tải lại trang. Để xử lí vấn đề này thì dùng real-time, ví dụ như Pusher.

6. Xác thực người dùng

Làm sao để biết ai là người tạo hoạt động trên powerup trên Trello là ai ?

Để xác thực người dùng trong Trello thì sử dụng capabilities show-authorization, authorization-status và on-enable

Với on-enable: Khi người dùng tiến hành cài đặt power-ups thành công thì ngay lập tức hiển thị ra modal, popup tùy theo use case. Trường hợp này thích hợp khi người dùng cài đặt power-up xong thì sẽ tiến hành hiển thị box cho người dùng authorize ngay lập tức.

Phần tạo routes và controller để load view ko cần đề cập tới vì giống phần trên. Code authorization tham khảo ở đây: https://developer.atlassian.com/cloud/trello/power-ups/client-library/t-authorize/

Thông tin về REST API client tham khảo ở đây: https://developer.atlassian.com/cloud/trello/power-ups/rest-api-client/

Trong trường hợp người dùng lỡ nhấn nút X để đóng modal, Trello cũng cung cấp capabilities show-authorization và authorization-status để xác thực người dùng. Code tương tự như trên

Chi tiết code authorization có thể xem ở đây: https://developer.atlassian.com/cloud/trello/power-ups/client-library/t-authorize/

Phần return_url là sau khi grant quyền xong thì sẽ redirect sang đây, điều quan trọng trong này là để có thể set được token (dòng 27) khi được resolve thành công thì cần 1 trong 2 phương thức sau ở trang return_url

Gọi authorize(token)
Gọi localStorage.setItem(‘token’, token)

Hàm authorize được gọi hoặc localStorage được gọi nếu không hỗ trợ window.opener

Trong client.js, để không hiển thị Authorize User trong menu Settings nữa thì cần kiểm tra xem token đã set hay chưa. Ở đây t.get() là hàm để lấy giá trị trong t.set() ở trên phần Authorization 2 ảnh trên tại dòng 27

*Check token: nếu đã xác thực thì hiển thị "Remove personal settings" như ở dưới*

Xem thêm tại: https://developer.atlassian.com/cloud/trello/power-ups/capabilities/authorization-status/

Power ups chuyển sang trạng thái "Remove personal settings"

Remove personal settings ở menu item khi authorization status là true

7. Lấy thông tin board, card, user

Sau khi lấy thông tin token, để lấy thông tin board, card và user hiện tại thì sử dụng một số hàm ultilities như sau

Figure 26: Lấy thông tin user hiện tại và card hiện tại

Xem thêm các hàm tham khảo có sẵn tại: https://developer.atlassian.com/cloud/trello/power-ups/client-library/accessing-trello-data/

Trong trường hợp muốn chỉnh sửa thông tin card (CRUD), board (CRUD), … có thể xem ở đây: https://developer.atlassian.com/cloud/trello/rest/api-group-actions/

Lưu ý là cần cung cấp cả key và access token trên url để lấy thông tin, ví dụ như sau

*Lấy thông tin chi tiết card bao gồm key và token*

Token được lấy ở trong phần authorization còn key ở đây là API key cũng được lấy ở phần Trello APP Key: https://trello.com/app-key