After a bunch of edits, one would like to check the result before making it live. Although there is some tricks one can use to publicly preview a page without making it visible (by setting a difficult long permalink like /secret/2et8rtr8bf38fnsfmfuvkjba/my-secret-page ), it is best to have a live preview so we don't even wait for build time :)
For this reason, Troglio comes with a special button in Trello cards. After a little setup we will detail here, one will be able to pre-visualize the page related to the selected card within a popup.
Ok there are two steps for previews to work: define a base URL (usually the domain of your final website), and re-route live data in your templates. So there are basically two different actors playing here: usually the writer defines the base URL, and the developer adapts routing logic in the back-end. So if you fit this kind of organization, do not forget to call your developer or writer for each of you to comply with their own part :)
So, let's start easy: the base URL (for writers and/or site owners)
There should not be much to explain here: Troglio needs to know where is your final app/website located at. So for this very website our base URL for previews is simply https://troglio.com. From this base URL, Troglio will append each cards path and navigate to it to preview the relevant page. Fair enough ?! Simple.
To setup your base URL, just open a card and click the preview button. If nothing has been setup yet, a popup will prompt you for setting it. Just input your URL like https://yourdomain.com.
Now the crazy part (for developers)
When a user clicks the preview button, Troglio will compute the data into formatted JSON pages exactly the same way one receives after clicking the Publish ! button. However, instead of sending these data to a back-end, instead we navigate to the page URL (according to permalinks rules etc...) and we try to pass the data as arguments to the iFrame the page sits in.
You might have understood it already, the idea is that you should intercept these arguments and shortcut existing routes and template data to replace them with fresh preview data.
It is a fairly complicated concept so let's re-phrase it again in another fashion to get a second understanding: when a user clicks the preview button, Troglio will open the relevant page as an iFrame and present it to the user. However, if we do nothing, the user will simply see the published page content that is live on the web. So we need to take out this still published content, and replace it with the ones Troglio provides as arguments of the iFrame instead. This way, the user will see fresh data like if it was actually published. Makes sense ?!
We just need to replace published content with preview content when we are in preview mode
Decomposing this sentence, there are two parts to care about: replace content, and be aware of the preview mode.
When your site is in an iFrame, there is a high chance for it to be opened from Trello's preview. This could then be a trigger for you to actually listen for arguments and swap content with preview data.
Then Trello provides an SDK to easily intercept arguments we named pages (all cards except those with a kind of settings) and config (the __config card). The idea is then to load this SDK on-the-fly and get the data. See an actual implementation example using react.js HERE:
componentWillMount () {
/* IF THE APPLICATION IS OPENED IN AN IFRAME */
if (typeof window !== "undefined" && this.isCrossOriginFrame() ) {
const scriptjs = require("scriptjs")
/* LOAD TRELLO SDK */
scriptjs('https://p.trellocdn.com/power-up.min.js', () => {
var t = TrelloPowerUp.iframe();
/* IF TRELLO IS SUPPLYING NEW PREVIEW DATA */
if(t.args[0].context !== undefined){
/* GET LIVE PAGE'S DATA: an array of pages data ( including paths to generate routes on-the-go ) */
const pages = t.arg('pages')
/* GET LIVE CONFIG'S DATA: an object with the __config card properties */
const config = t.arg('config')
/* DO WHATEVER FROM THE STATE */
this.setState({dynamicRoutes: pages, config: config, bypassRoutes: true})
}
})
}
}In the above example written in react.js, the idea is exactly as explained: first we check if the application is opened in an iFrame, If it is, we probably are in the context of Trello so we load the Trello SDK. Once loaded, we have access to iFrame arguments using var t = TrelloPowerUp.iframe(); and we can test if we are actually getting something from Trello using t.args[0].context !== undefined. If something comes up, we are definitely within Trello, so we can collect our preview data using t.arg("pages") and t.arg("config"). And there you go, you should have sufficient data to do whatever you want. In our example, we put data into the state() of our react component. But for any other frameworks, one should just implement relevant logic to fill templates with preview data.
We are now working on more frameworks examples to help getting started.