Implement a three column theme

[sjmueller]

Three column layouts are all the rage. It started with the stripe api, then readme.io and others followed suit. Apiary.io is currently the only 3 column layout renderer for api blueprint spec, but it is a cloud solution that is more complicated than it needs to be. Stripe has it nailed, and aglio needs a copycat theme to take it to the next level.

Now that aglio vnext is out, shouldn't a theme like this be more approachable to build?

[danielgtaylor]

I've been planning something like this for a long time but haven't had the time to implement it yet. It could definitely be done either as a new layout in the default theme or with a new theme engine. Ideas and mockups are definitely welcome 😄

[m-baumgartner]

This would be a perfect! 👍

[danielgtaylor]

@sjmueller @m-baumgartner I've been working on something for this over the past few days. What do you guys think of this?

It's kind of a mashup of Stripe, ReadMe.io and Apiary. In the future the MSON attribute descriptions will go under the URI parameters and the right column can have raw, cURL, Node.js, Python, etc examples which could be selected similar to how things work on Stripe's documentation.

View and play with the live demo and please give me some feedback on what you think. 🚀

[m-baumgartner]

That looks awesome already !
MSON attributes will really help you're right.
Regarding cURL, Node, Python (ruby?) examples :

• Is there some way to generate those snippets dynamically ?
• Do you think about language-related syntax coloration ?

Great work, i'm looking forward to use this !

[danielgtaylor]

@m-baumgartner this is now released with olio-theme-1.3.0 so please give it a try and let me know what you think! Be sure to try out the new streak color scheme, which you can see a demo of in the project README.

Is there some way to generate those snippets dynamically ?

Yes. Some libraries exist, though we may need to write our own depending on the features we deem necessary. I'd prefer to use a library if possible.

Do you think about language-related syntax coloration ?

This should already work with the Highlight.js functionality in the themes.

The code snippets feature will have to come at a later date, because I spent most of the week on the three column layout. Hope to find some more time to work on this soon! For now I'd love to get feedback and work out any major kinks with the three column layout before adding more features.

[sjmueller]

@danielgtaylor this is very impressive! Well done. I think there are a few tweaks to make the theme a bit more modern, which I illustrate here:

• changed the the menu action icons to be more explicit, with sharper corners
• removed right padding on menu action icons
• horizontal rule to separate resources changed from gradient to solid, spanning entire width
• sharpened border-radius around endpoint container

[robbinjanssen]

Great work @danielgtaylor, love it! I suppose the attributes rendering will happen inside the GET 'boxes'.

Quick question, looks like the --no-theme-condense is no longer working for this template? Correct?

[m-baumgartner]

@danielgtaylor Looks great with my blueprint. Only 2 notes :

• The "API Endpoint" title on the top of the right panel, can we hide it?
• The horizontal scrollbar is shown no matter how I resize my browser window. (tested on chorme 46 and safari 9).

[danielgtaylor]

this is very impressive! Well done. I think there are a few tweaks to make the theme a bit more modern, which I illustrate here

@sjmueller Thanks! I will try to apply some of these changes soon.

I suppose the attributes rendering will happen inside the GET 'boxes'.
Quick question, looks like the --no-theme-condense is no longer working for this template? Correct?

@robbinjanssen the attributes rendering will happen inside the action boxes. There's an interesting case where attributes can be defined per request but I think it can be handled in a similar way. Turning off condensing of the nav items still works and the option is called --no-theme-condense-nav. See --help for all the official option names (excludes the secret ones for backward compatibility with Aglio 1.x).

The "API Endpoint" title on the top of the right panel, can we hide it?

@m-baumgartner I can make this an option. I was trying to keep the area from looking too empty, but I'm not sure what else to put there. Maybe in the future auth information could go there, but it's hard to say.

The horizontal scrollbar is shown no matter how I resize my browser window. (tested on chorme 46 and safari 9).

I see this as well and need to debug it. I'm also seeing some strange behavior after hovering over titles, where instead of the anchor disappearing the title disappears. I'm not sure if this is a bug in Chrome or some other issue.

I'll leave this ticket open for a little while in case anyone else has any more feedback. Thanks for all the help!

[robbinjanssen]

@danielgtaylor when I use that option, some of my menu items still get collapsed. Might be related to #130, but atm this is not a problem. Can't wait for the attributes rendering to happen, especially in this theme! 👍 If I have the time i'd love to contribute, since we're planning on using aglio for our apidocs!

Maybe create a new milestone where we target 3 or 4 major issues and prepare for a 'stable' release? As things keep changing and breaking now and then?

[danielgtaylor]

@robbinjanssen please look at #130, which has a discussion on disabling the auto-collapsing of navigation groups. The nav condensing is about turning list items with a single sublist item into just a single item in the navigation.

Okay, I'm considering this issue completed for now, since the three column theme is out and has had several of the bigger issues fixed. Please file separate bugs if you'd like to see other issues addressed!