[ARCHIVED] Canvas Style Guide - Permanence?

[kevinw]

For those of you who do not know, canvas has an entire style guide full of neat little things you can add to your course. I wish I had found this sooner, so enjoy. 

Now my question is how much of this will still be relevant on a permanent basis? We know that soon the tabs feature will be unavailable, yet that doesn't reflect on the style guide. 

I only ask because I don't want to go through the pain of doing these things to our content only if they are going to be rendered useless in the near future. 

[James]

I don't have a good answer, just some questions.

How do you know that tabs will soon be gone?  Canvas has said that they are deprecating the magic jQuery UI that is undocumented and involves the "enhanceable_content" class. They have also said that they will be working on removing jQuery UI.

I have not seen them say there will be no tabs and that this won't be the markup needed to incorporate them. That said, it won't be jQuery UI that will implement them (at some point in the future) so that part of the documentation will need to change.

I also haven't seen any definitive statement beyond the deprecation of the automatic behavior, removal of jQuery UI, the conversion to WebPack, and the non-exposure of underlying libraries making it necessary to include your own.

But anything in the Style Guide that says "We use jQuery UI" will be changing at some point. That functionality may be replaced, the way it's invoked may change, but most of those things are used by Canvas so there will probably be some way to do them, we just don't what that's going to look like right now.

[kevinw]

I was specifically referencing your post here. 

"What that means for users is that the Canvas Admin will need to add some kind of support in their custom JavaScript for enhanceable content if they want it to keep working."

Anyone considering implementing tabs should be aware that Canvas has announced that they are going to deprecate the jQuery UI magic that does the enhanceable_content accordions, tabs, sortables, draggables, resizables, and dialogues: Deprecated use of magic jQueryUI widget 

Right now, June 2017, it's just accordions, but Canvas has said it's happening to other things as well.

Not all of us who fell into course design know anything about JavaScript. I may be the only one, though I suspect I am not, who is dependent on this kind of documentation from Canvas to add things to our course that "spice it up" or better organize pages or information. 

So my post is more geared at the point "Yeah I can add this stuff now and it will be cool. But what am I going to have to go through later, if and when these things aren't functional anymore" 

[James · Accepted solution]

If I would have known you had seen the other post, I could have saved myself some typing

enhanceable_content is a class that people could apply to their user content and then Canvas would automatically attempt to add some jQuery UI magic to it. That is what is disappearing in the short term (I don't know how short, short is, except that accordions are gone). jQuery UI is still around and if you add unless the local Canvas Admins add some custom JavaScript to their pages to make it happen for their users.

That said, Canvas has not yet removed the jQuery UI accordion widget from production. So, if you were to go to a page that had used the undocumented accordion feature, it would not show up as an accordion. But if you opened a browser console window (F12) and pasted this code in there, then the accordion would magically be there.

$('.enhanceable_content.accordion').accordion();‍

This also still works in the beta instance (at least as of July 6, 2017). I imagine at some point that Canvas will remove the accordion widget from their jQuery UI, but perhaps they won't until they completely remove jQuery UI. From their perspective, the behavior was undocumented and so they are free to change it at any time, but they've been giving us the heads-up for months that it's coming down the line.

There is nothing to keep you from writing your own custom JavaScript that looks for the .enhanceable_content class and acts on it in the way that Canvas previously did. However, that will mean loading jQuery UI at some point or things will stop working.

The other alternative is to find a different, preferably smaller, library that will do the things that you need it to do and load that. I've seen CSS-only solutions for tabs, so it might not even require any JavaScript at all. But that might also mean that you have to change the way that you create the tabs in the first place.

I think what Canvas expects is that each school to decide what items they are going to support and maintain. Then they find out the best way to do it and do it as a customization on their end without relying on undocumented behavior from Canvas to do it. They provide this information to their designers and faculty and have them create pages that way.

In other words, if you want to use enhanced things like accordions, tabs, sortables, etc., then you need to build it.

Obviously, we would all rather have something be done for us rather than having to do it ourselves. We would rather have a well-tested design in place that looks and feels like Canvas than have to come up with our own approach.

From Canvas' perspective, though, what they are removing is an undocumented feature. You weren't relying on what Canvas officially conveyed about the enhanceable_content because they didn't officially communicate anything. What you're talking about is the Style Guide, which may have been a "we have this, why not make it available?" thing rather than an official -- as in the Community Canvas Guides -- communication.

Few people who are freaking out about this are doing what the Style Guide says about tab navigation. What they're doing is using the enhanceable_content class that people in the Community have been pushing as a way to accomplish this. If they were using the Style Guide, they would see that there are two parts to the Tabs. There is the code that goes into the HTML and the code that needs placed into JavaScript.

$("#styleguide-tabs-demo-regular").tabs()‍

That code applies the tabs() through jQuery and it uses the jQueryUI. That's what's going to have to change at some point if people don't load their own jQuery UI or add different jQuery plugin to do tabs. There are a lot of ones to choose from, although jQuery UI made it nice because there was a consistent look and feel to it.

Let's look at the final question:

So my post is more geared at the point "Yeah I can add this stuff now and it will be cool. But what am I going to have to go through later, if and when these things aren't functional anymore"

I think the answer is that if you haven't relied on the enhanceable_content class, then don't start now. Find your own way of adding tabs or sliders or accordions or anything else that you want to add to your website and add it yourself instead of relying on Canvas to do it for you. If you have already started using the enhanceable_content automagic, then start making plans to do something else.

[judy_harmon]

We've just been introduced to Tabs from another course and really like their user friendliness to our students.  This was the first I'd heard that they may not be allowed?  If they're in HTML code, why can't they be used?  I'm going through an entire Student Orientation with tabs.  What will happen to them?  I don't know Java Script but can work my way around the basic of HTML code.

Why would Canvas take tabs away when they are so user friendly?

Thanks!

[dlyons]

The Canvas Styleguide is the styleguide for the Canvas application, not for content created in Canvas. This is why the styleguide is not documented, why changes to it are not always communicated in the release notes, and why some things in the styleguide do not function as expected when creating content. That being said, if you know what you're doing and understand the risks, I've seen some cool content built utilizing the styleguide. Just don't let yourself count on it the way you count on what is in the release notes and the Guides. 

[James]

Thank you,  @dlyons !  

I had long thought that might be the purpose of the style guide and it is great to have a definitive answer. I know some people won't like it, because they're once again relying on undocumented behavior to accomplish things, so I appreciate the added note about understanding the risks.

[kevinw]

If I may ask, what is the distinction between the "Canvas App" and "Content Created in Canvas"? 

[James]

By application, he means the Canvas software. The style guide is a guide for people developing Canvas itself. Most of these people are employees of Instructure, but Canvas is open source and some people host their own instance and develop things, some of which they feed back to Instructure to review and possibly adopt into the core Canvas product.

Content created in Canvas refers to user content: content pages, quizzes, assignments, discussions, files, and anything else that someone puts into Canvas. It can also refer to custom JavaScript or custom CSS that the Canvas Admin adds. People writing user scripts, like much of my code, are essentially providing custom JavaScript that the end-user can decide whether or not to run rather than the Canvas Admin deciding.

External Tools (LTIs) are kind of a thing of their own. They appear to run in Canvas, but they are really running inside an iFrame, which sandboxes them off from the main Canvas instance. Among other things, that means that they don't have access to the stylesheets that Canvas uses unless they load it themselves. They also don't have access to any of the JavaScript libraries that Canvas loads and uses unless they load it themselves. With the switch to webpack earlier this year, Canvas has also tightened up what they expose, so even if the security settings of an iframe didn't block access, Canvas has removed it. That doesn't really affect people who write LTIs much because they have to do this anyway. For those who want it to look and feel like Canvas, they need to include their own CSS rather than relying on Canvas'. For the LTI authors, the Style Guide gave useful information about how Canvas did things, but they wouldn't be able to just go $('my_CSS_selector').tabs(); and have it add tabs to their pages. They would have had to supply the library that used tabs.

Of those, the group freaking out the most right now is the middle group. The people developing the Canvas software are doing things as usual and are able to use the Style Guide. The LTI providers had to write their own stuff anyway and consciously chose whether or not to style it like Canvas. That middle group is the group that believed they had information they could use, and it was information that worked, but being undocumented, it comes with the risk that it might stop working at any point.

There is no officially supported and maintained document for hacking Canvas.

They would rather you go an officially supported route like LTI (that someone other than Canvas maintains), self-host and write your own code (that you maintain), or write your own institutional custom JavaScript (that you maintain).