InstUI: Instructure’s Style Guide 2.0

[aguthrie1]

Since its inception, Canvas has always been open and transparent about our business and our features. We believe in being open. We believe in allowing you to use Canvas the way you want to use Canvas. And branding is one component that we’ve been working hard to improve, specifically relating to the use of the existing style guide and Instructure UI (InstUI), Instructure’s own component library.

Branding Evolution

Web technologies continue to evolve, and over the last three years, we’ve been able to introduce the Theme Editor at the account level, which helps admins create custom templates without the use of custom CSS and JavaScript files, although those file types are still accepted.

Previously, Canvas engineers implemented a style guide to be used for internal engineering teams and ensure consistency throughout the product, hosted as part of each Canvas account (e.g. canvas.instructure.com/styleguide). Over time, we noticed that some of our customers started to leverage that style guide. We know that you enjoy being able to design your own Canvas-theme projects within the Rich Content Editor. Now, with the evolution of additional technology advancements, we’ve discontinued the use of the old style guide in favor of InstUI.

Why InstUI?

In order to use the styleguide, a developer or course designer would copy the HTML markup for a user interface pattern, such as tabs, and paste that markup throughout Canvas. However, HTML is only part that pattern. The style of those tabs is defined with CSS, and the interaction of navigating between tabs is enabled through Javascript. This architecture quickly became difficult to maintain. If we were to make a style enhancement or fix a Javascript bug that necessitated updating that HTML, every instance of those tabs—whether in Canvas, in a custom tool, or in course content—would have to be updated manually or remain broken.

To combat these maintenance challenges, we made the decision to move Canvas front-end development to React, a library developed by Facebook for creating modular user interfaces. React components encapsulate the HTML structure, the styles, and the Javascript together into a reusable, easily maintainable component. A bug fix to a React component propagates to every instance of that component with little to no effort, only needs to be made in one place, and every user immediately benefits.

InstUI, Instructure’s own UI component library, is built using React, which allows our developers to deliver new features more efficiently and makes all of Canvas easier to maintain and innovate. InstUI ensures consistent, accessible experiences throughout Canvas and delivers custom themes made with the Theme Editor to all interactions, just like the style guide intended. With React, those experiences are better tested, better maintained, and more reliable than ever for our users.

InstUI Availability

If you’re interested in using the InstUI components, InstUI is open source and available for you to use in your LTI tools. To get started, visit instructure.design. If you’re starting from scratch, InstUI works great with React boilerplates like Create React App.

We haven’t enabled the use of InstUI in the Rich Content Editor yet; however, other tools are currently available for integrating custom changes. Some options as noted in the community include H5P and other canvas embed tools.

Future Development

In 2019, the InstUI team will begin work to improve documentation and support for third parties.

Additionally, we recognize we don’t have an ideal solution for making changes in the Rich Content Editor. For now, we’re focusing on building a better Rich Content Editor to give you a better experience and give you more controls to design pages the way you want. This project is in the planning stages, and if you want to get more involved, watch for additional details to be posted in Canvas Studio.

If you’ve been using InstUI, let us know your thoughts in our InstUI Community Discussion.

If you’re not using InstUI but have used elements from the style guide in your pages, please let us know in the comments which elements you used and why they were helpful to you. Style guide feedback may be considered for future development.

[atorrey]

I am an instructional designer and our team uses the Style guide for designing pages that we know will work in Canvas without us having to spend a lot of time troubleshooting the code. We do not have a developer on our team, so we have to rely on the code that you have in the style guide. We have used the code for buttons, tables, tabs, and borders extensively. These elements have helped us present information more clearly for the students, especially within discussions and assignments where we don't want students to have to scroll forever. Losing the style guide would mean more time coding or boring pages (if there isn't time to). 

[Shar]

I am also an Instructional Designer who has been using elements from the Style guide to spruce up and organize Canvas pages:

• Buttons
• Borders
• Icons & colors
• Tables
• Enchanceable content - Tabs, Modals
• Element Toggler
• Flexbox grid
• Content-box, pad-box
• Alerts

For us, losing access to these elements within Canvas pages via HTML editor would cripple many of our pages and send us back to Web 1.0 with static, featureless pages.

Thanks in advance for your consideration,
Cheers - Shar

[James]

Deactivated user,

Hi, we met and talked briefly about this at InstructureCon 2018 after the VP's session. I thought about writing a month ago when this first came out, but was bogged down with some other stuff. Now that my good friend ishar-uw has chimed in, I feel like I should say my piece.

The Style Guide was widely misinterpreted by people for uses that it wasn't intended for. I wrote about that here: Canvas Style Guide: CSS Variables. I see this as a continuation of the announced deprecation of jQuery UI that raised a big ruckus in early 2017. To a smaller extent, even the reworking of JavaScript within files from early 2018. Anytime you remove functionality that people have been using, even if it wasn't documented, then people are bothered by it. I'll try to move past that because I accept that you can't keep supporting undocumented things. That's how cruft and crud builds up in the product.

The issue that got people upset then was that people had come to rely on undocumented behaviors (except for documentation that people shared in the Community) that were in Canvas rather than loading their own libraries to accomplish the same task. Why load a separate library and add bloat to the amount of information that has to be downloaded if you can use something that's already there? That loading of the library had to wait until Canvas had loaded and so there was an extra delay, which leads to a bad user-experience. For example, my script that allowed people to reorder the dashboard course cards (until Canvas came up with their own solution in December 2018) had to wait for Canvas to move things around before it could it's thing. So it appeared to users that the cards would jump after they had been displayed. By the way -- that still happens with Canvas' solution.

Instructure came along and said "Hey! We've got this great Inst-UI thing that's really accessible and you should use it." What we talked about at InstructureCon was my fear, which I think you confirmed, that "Oh, by the way, we're not going to expose it to you and if you load a second instance of it, it probably won't play nice with ours do you really shouldn't do that." I'm paraphrasing a little, but hopefully I got the gist right.

Now we're at a place where we want to modify the behavior of Canvas. Even though you don't want us to, historically you've made custom JavaScript available to us so that we can and some people really need to. What we could do in the past was style something as a button and make it look like a Canvas button. If Canvas updated their styling for a button, ours would change to match because we were using your CSS.

LTI authors might have it simpler. You make a link to the CSS available through an LTI variable substitution. By the way, that documentation is now missing and someone filed a ticket on GitHub about it October 11. But all of the variable substitutions used to be there. The way this proposal reads now is that having the CSS from Canvas won't really help anyone because it's all going to be encoded in these React classes. So knowing that something has a .btn class doesn't help people know how to style it. They can monitor Canvas, reverse engineer all the React classes, and hopefully get it right -- as opposed to just using a .btn class like they can now.

For those who need to modify the behavior within Canvas and not as an LTI, it's a bleaker picture.

Take for instance the script I wrote to Sort the Roster. It allows users to click at the top of any column in the roster and sort by that column. Great functionality that should be in Canvas already, but isn't. Different columns have different sorts, so I have to detect what the contents of each column are. In some cases, you've made that easy because there's a class that's been applied to the cells, like .avatar, .roster_user_name, .section, or .admin-links, but in other cases, there is no class to identify things like the Login ID, SIS ID, Role, Last Activity, and Total Activity fields. Some of those may not even be visible to people depending on their permissions. Now consider the Admin Course List, which has been redone with React JS and I have no classes at all or classes like ._16dxlnN and ._1khDq1Q. Tracking down the right selectors to use to add useful links to that page took wonderfully talented people like carroll-ccsd‌ quite a bit of time: Custom JavaScript for Admin/Courses Page 

Canvas may want to take the stance that people shouldn't be modifying the web interface, but there are lots of things with Canvas that people legitimately want to change but don't want to go to hosting their own instance to do it. By the way, what are those people supposed to use to design things if they can't use the Style Guide? It's probably in the documentation somewhere, but you could help enlighten those of us who have been relying on the Style Guide.

Anyway, there is functionality that can really help people, so saying we don't want you to modify the UI is a huge step backwards. I've made some contributions that the end user can choose to apply. Some of them, like the sorting of the dashboard course cards, QuizWiz, and the access report for an entire course have been adopted by institutions, not just end users.

There's a list of much of what I've contributed here: Canvancements - Canvas Enhancements . This helps reduce people's frustration with Canvas' lack of moment on things that don't have a high return on investment, but for some people they waste a lot of time. 

Mostly I've used the buttons: QuizWiz, adding a View All Grades button, assigning intragroup peer reviews, importing a rubric, access report.

I've also used a progress bar for the access report. When I wrote the assigning intragroup peer reviews script, I used the HTML5 progress bar.

If I stop making the case and just list the items from the Style Guide that I've used, either in enhancements or in my classes (I have one elaborate navigation system within a course that is going to break terribly once this is removed).

• Style: colors, buttons, button set, icons, alerts
• Scaffolding: forms, tables
• Components: Item groups, Item groups condensed, modals, tabs (although I removed most of these after the jQuery UI deprecation notice)
• Patterns: header bar, progress bar

What would be nice would be for Canvas to expose React to us for use. That's unlikely because changes we make may interfere with what you're tracking. But still, given that you have this awesome UI that's accessible but we can't use, it would be nice to be able to use it to render our enhancements.

I don't know enough about React to know if that's possible, but the current approach is to add a MutationObserver to see when React changes the DOM and then rewrite our changes on top of that. That's kind of a pain, especially in the world of random class names. That leads to the second request.

The second request would be to continue to use named classes for things. That helps us identify it over some random class name that has no meaning. Please do this even if you don't attach any styling to it. Then, if we want to, we can add our own styling or JavaScript that do what we want it to do when those are encountered.

Of course, the ultimate holiday gift would be to find those things that people use (like buttons and colors and so on) and are not bad for your health (like accordions and possibly tabs) and continue to support those styles. Every extra thing that we have to download takes time and bandwidth. It may not be noticeable with high speed internet, but those initial loads over slow connections can seem excruciatingly long. For example, a slow 3G connection of the dashboard with a full refresh (and no external JS or CSS) took about 36s to load. By the way that might get faster the more you move to React, 25s of it was downloading the vendor JS bundle file and 16 seconds (obviously part of that was concurrent) was spent downloading the dashboard JS bundle. The CSS styling is a much, much smaller part of that -- suggesting that including it for our benefit wouldn't inflict as much penalty as inefficient or wasteful JS. Maybe not sending the internationalization the first time, but loading it in the background could help? Thankfully those files are cached the second time you load them and it only takes about 9s.

[aguthrie1]

Thank you for all of the feedback. The purpose of this post is to let you know the direction Instructure is taking to ensure we can maintain a modern, reliable, updatable architecture for years to come.

More importantly, for our customers, outlining our plans gives you the opportunity to share your insights, your current needs, and your ideas into what we need to consider as we design enhanced tools for course designers to make rich, engaging content for students. 

Rest assured,  @James  and anyone else reading this post: everything you're doing right now will still work. While we are no longer adding new features to the current styleguide, there is currently no schedule to remove it. So please keep this feedback coming so Canvas can continue to meet your high expectations.

Feel free to @ mention me if you have specific questions or ideas. Again, thank you!

[aguthrie1]

I really enjoyed the conversation we had at InstructureCon.

Yes, some of the old ways of inserting elements into Canvas are more difficult and even downright impossible in a future where everything is rendered with React. That's why we need enthusiastic power users like you to help us identify those areas where our architecture decisions may block legitimate use cases.

We're very grateful for the time you took to write this comment. There's a lot to digest here, but rest assured that we're looking at it very closely. More updates to come, I promise!

[venitk]

We're new canvas users and haven't been using buttons and accordion and whatnot because of the warnings that the code could change and break whatever we made using those styles. But we'd really love to use these interactive elements. 

If I were to summarize this post to present to my team, is it that we now can use react to create items like this and they won't break? If so, how?

[aguthrie1]

You can use the Instructure UI React components in LTIs. We do not have a way to use InstUI in the Rich Content Editor at this time. Towards the end of the article, we suggest checking out some community options:

https://community.canvaslms.com/ideas/8844-h5p 

https://community.canvaslms.com/thread/12269-curated-space-for-contenttools-that-can-be-embeded-in-c... 

And if you have some specific uses that the styleguide has made easy for you, please let us know!

[venitk]

Could you give me an example of an LTI that you would use InstUI in? As a new Canvas user, the only LTIs I can think of are things like quizzes.next, publisher integrations, or Kaltura, which would seem to have limited value for accordion or tables (although I could see that occasionally being useful in a quiz). I'm sure I'm missing something...could you fill in the blanks for me? We're definitely looking for ways to jazz up our courses.

Thanks

[James]

 @venitk ,

As a new user, most of this thread doesn't apply. The one take-away may be to warn you not to go down the path of the Canvas Style Guide because it's been deprecated.

The InstUI could be of use if you're writing your own LTI, but not if you're using someone else's LTI. It's for developers, not for end-users.

For instance, we have an LTI during our mandatory student orientation to Canvas that requires them to complete a time management worksheet. I wrote that in PHP because that's what I write most of my forward-facing dynamic web pages in. That was back in 2013 and since then I've learned some JavaScript, so if I was starting out writing the same thing now, I might use ReactJS instead of PHP. If I was doing that, then I certainly could use the InstUI component with that. InstUI is a component for ReactJS, so if you're not using ReactJS, then you won't be able to use InstUI.

[venitk]

Thanks, James, that was VERY helpful. And disappointing, since I’m back to square one with accordions and whatnot. But helpful.

[James]

 @venitk ,

I love your whatnot, so I'll go with it. By whatnot, I mean things that would be called widgets in the jQuery UI interface: accordions, tabs, draggable, sortable, sliders, spinners, progressbars, tooltips, etc. Much of what used to be in the Canvas Style Guide. I do not mean LTIs or other items embedded in an iframe -- that is external to Canvas.

Most whatnot has accessibility issues when not done correctly and it's difficult to do most whatnot correctly from an accessibility perspective. Put the two together and just try to avoid most whatnot. Whatnot can make things look cool to some people, but they can get in the way of learning for others.

Accordions were not popular and Canvas has already deprecated them. Tabs had more of a following and it has been announced that they will go bye-bye, but I don't know that it has happened yet.

Even they have issues for people when people go to print. The recommendation is to have more pages with less content, rather than trying to have fewer pages with more content that is obscured. Students don't want to click on those extra tabs and you have no way of knowing if they did. Of course, you have no way of knowing if they actually consumed the information on any page or just opened the page.

Canvas used to automatically markup some things like accordions and tabs for users if they would add a super-secret CSS class name to their content. As with most secrets, the secret got out out and some people started using it. However, it was not a documented feature and the library that it used was bloated and not accessible. It was not good for Canvas to keep the bloated, inaccessible library in their code when they want to have the best experience they can, so they said they were deprecating that. That was the crux behind the 2017 announced removal of jQuery UI.

The official line is that if you want to support whatnot, you need to do it at the institution level by defining your own code that would do it. This means that you will need to add custom JavaScript and custom CSS and then test things to make sure they don't break. I will say that rarely do things break without Canvas having announced it and in the code I've written over the last couple of years, there have only been a handful of times that something has gone wrong that makes it not work. In most of those cases, it was a quick fix of a CSS selector -- which are going to be harder to find without class names that mean something.

One of my concerns was that if we want to add whatnot to our pages, we need to find an library that provides good accessibility. Canvas says they have a great one called InstUI, but that we won't be able to use it for the purposes of adding whatnot.

And in some ways, that's actually good. Because it keeps people from adding whatnot to their content page and most whatnot probably should not be added to their content pages.

I imagine my case is a little different from most people's. I don't necessarily want to modify the user content with accordions or tabs -- I want to modify the interface itself. There are some functionality my scripts provide that cannot be written in an LTI because there is no API for them, only internal routes from the browser. I need a way to add a button to the interface so people can get access to that and I want my button to look like it's part of Canvas. The Style Guide was a nice place to see what those class names were and what effect they were going to have.

[robotcars]

I tried posting this the other day, but Jive kept truncating my TinyMCE paragraph and then I had to go to a meeting...

Like  @James  I've avoided posting to this thread for awhile, mostly because what I'm reading here doesn't add up.

While we try to avoid using the style guide in our courses, I've just redesigned one of our schools course homepages  to use the built in Bootstrap Grid System, along with 200 lines of custom CSS to make it fun and responsive. Partly to move them away from Accordians! We also use it in many of our UI modifications, just as James does. These common elements are exactly why Mark Otto designed and shared Bootstrap in the first place. Not everyone, especially at our institutions, can produce quality accessible and responsive design patterns consistently. And if it's available I definitely don't want our users downloading an additional library to handle this. A lot of applications are built on Bootstrap, I can understand it's use in Canvas' infancy, and their move to designing their own components now. I think my biggest issue with this is the misdirection that it is somehow something we asked for, but selling it to us as a solution and alternative for the style guide is kinda funky. Because it is absolutely 100% NOT THAT!

InstUI ensures consistent, accessible experiences throughout Canvas and delivers custom themes made with the Theme Editor to all interactions, just like the style guide intended.

To me, this statement implies that I can upload JS and CSS to the Theme Editor and utilize components of InstUI. However, these components are not extended to the Theme Editor. For example, with Global Nav Menu - Custom Tray that I reproduced as a bandaid for some institutions (because they dumped the tray styles for React Tray), I had to use the browsers compiled CSS styles for the Tray Component and copy and paste them to a separate style sheet, because those components styles which are part of Canvas change with each release. Canvas would have to provide human readable, not machine generated styles to make that available in the Theme Editor.

We haven’t enabled the use of InstUI in the Rich Content Editor yet; however, other tools are currently available for integrating custom changes. Some options as noted in the community include H5P and other canvas embed tools.

Everyone has a solution or vendor for bringing better content into Canvas...

I love Canvas, I think everyone knows that, so I hope nobody faults me for saying...

I often feel like we were sold this	they've built this	and we're still waiting for this

For all intents and purposes the RCE is an out of the box installation of TinyMCE, which is perfect for allowing HTML Textarea's to format and accept HTML content. It is not a robust web content editor. You can plug it into any HTML Form.

edit: (I love it when Jive truncates entire paragraphs on submit)

Deactivated user mentions a new RCE, which sounds fantastic and it's definitely needed. However, with the statements about the React components working in the RCE, I'd be cautious if that means the RCE would prevent users from editing HTML. If the InstUI components aren't available as styles in the Theme Editor, and those components are built into the RCE, editing the HTML by some users seems like it would break those components, causing undesirable results. My fear here, and maybe they will address this, is likely what happens with Wordpress Themes. Wordpress provides a basic content editor, but when you install a fancy theme, it usually comes with its own editor. When you edit a page, you are forced to use its theme editor and not the Basic HTML editor. I guess I'd like to know if editing pages and using InstUI components be available at the same time, or would the user/instructor/designer have to chose to design custom elements or get the InstUI/RCE Themes? Would custom pages be able to be modified and styled by our own custom CSS/JS?

I'm having a hard time understanding the trifecta of InstUI, Theme Editor, and InstUI/RCE working in harmony.

If we can't use InstUI components in Global CSS/JS Theme Editor then I have an issue with the statement that InstUI is the next Styleguide. At this point, (for customers) InstUI is just a nice UI for building integrated LTI's.

Which I'm completely happy with. We've been working on architecting our next LTI dashboard using Node and React, and are currently working on incorporating InstUI so that our LTI's have a native feel. The decision to use InstUI still comes down to every line we don't write allows us to focus on our mission. InstUI means not designing our own React Components, styling and testing browser compatibility and makes everything feel symbiotic. We really appreciate Canvas for exposing this.

But if they are gonna jump in here and say This is That, they should provide a better roadmap for how they intend us to transition. I think Canvas needs to provide, support, and document style guides and front end content tools for its users just as it provides really awesome backend tools with the API, Canvas Data, and Live Events.

[tdw]

Hi James,

Full disclosure, I'm not an engineer/designer - I'm just an enthusiast who likes to break things.

That said, your comment about an LTI dev having to reverse engineer a .btn class to figure out how to style it seems a little off. My understanding is that an LTI developer could use (import) INST-UI (a react component library) in their project and it will spit out all the appropriate CSS, JS, and HTML to look exactly like (default) Canvas.  The LTI CSS substitution will then pull in the theme design so the tool can look exactly like the customized Canvas.  The LTI developer doesn't have to know how to style or format everything, they just have to know how to use the react components.

But maybe that's what you were saying, and I misread it

[James]

 @tdw 

That's good news for people who use ReactJS to develop their LTIs. Thanks for explaining.

Let's say I'm writing an LTI not using ReactJS or InstUI because I don't know how or I have a lot of existing code with PHP or some other language (this isn't a hypothetical case). Previously, I could look at the Style Guide and see that by using the .btn class I could make it look like Canvas does. With the deprecation of the style guide, where do I find how to style my class?

Further compounding the issue is that the Style Guide was where those class names and how to use them were defined. If I'm using InstUI, I can apply the Canvas theme. I'm not sure how to invoke a style from that, but that may be because I don't know ReactJS. When I went looking at the InstUI source code to try to figure stuff out, I didn't see anything that helped me, a non-ReactJS user. Since I'm not familiar with that, then I couldn't even manage to wade through the source to find where the code I needed was.

In the Canvas source code, there is some CSS, but the trend I've seen is for more and more to not have a human-readable CSS name applied, but some human-gibberish form. For example, one class is named _16dxlnN. That's not in the Canvas source code and it doesn't appear to be in the InstUI source code either. Through the browser inspector, I find that it adds manipulates the border -- well, it might be for me, I don't know that someone else will get exactly the same class name.

When I look at the bigger picture, I see something like this (line breaks added for human-readability)

<button aria-label="Create new course" type="button" tabindex="0" class="_16dxlnN _2A82x0p _1EYI5q2 _1-Y3qxx _3v81sUu _3PmbyiE" style="margin: 0px; cursor: pointer;" data-ui-testable="Button">
<span class="_1oYJA5q">
<svg name="IconPlus" viewBox="0 0 1920 1920" rotate="0" width="1em" height="1em" aria-hidden="true" role="presentation" focusable="false" class="_1lFiilH _1QNOlOp _27CDWPZ" data-ui-testable="InlineSVG,SVGIcon">
<g role="presentation">
<path d="M903.53 0v903.53H0v112.94h903.53V1920h112.94v-903.53H1920V903.53h-903.53V0z" fill-rule="evenodd" stroke="none" stroke-width="1">
</path>
</g>
</svg>Course
</span>
</button>‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Now I have classes "_16dxlnN _2A82x0p _1EYI5q2 _1-Y3qxx _3v81sUu _3PmbyiE". In the past, there might have been a single class for all that.

Those classes are unusable for me as an LTI developer since I don't use ReactJS. As an LTI developer not using ReactJS, I can get the CSS that Canvas uses. But if the CSS that Canvas uses is all done through the ReactJS and doesn't contain static class names, what good is it?

[mike_bamford]

Long time LMS admin, first time poster. Fully understand both sides of the equation here, as there are quite a few useful pieces of code within the styleguide, but administratively "supporting unsupported functionality" always ends poorly.

That being said, we are heavily using the Canvas Flexbox Grid code to create accessible, orderly and responsive landing pages in our courses. Not having to write, test, break, fix, etc. loads of extra CSS in order for this to work was very helpful and would be sorely missed if fully depreciated. Sounds like we still have an undefined length runway to continue using it at least, correct?

Our use case for Canvas is far from the norm, so I understand that 'hacks' or some level of customization will almost always be necessary. Thanks to the helpful Canvas Community for documenting so many of these, as it has made my job that much easier! Hopefully, the product management and development teams at Instructure fully understand this need, which will allow them to continue being responsive and thoughtful with future improvements / changes. 

[cgaudreau]

Deactivated user‌, thank you for sharing insight into the design process. My team and I have been muddling through some of the Style Guide components, but are still looking for in-house solutions to some of our commonly used UI elements. It was reassuring to read in some of the comments that old style guide usage will not be depreciated!

Redesigning legacy courses to meet accessibility guidelines is an ongoing focus for me as a new ID, and this library looks like it could provide a huge boon to course design elements.

I love the idea of streamlining iconography and toggles (accordions?), but don't know where to start with React - even the directions on instructure.design are a bit vague for someone with minimal knowledge of coding, and I have no clue how to start with Git.

Looking forward to more documentation coming later this year.

[james_trueman]

I am a mere pleb in comparison to the above respected commenters - please forgive any inaccuracies that emerge as a result.

What I am concerned about is the apparent conflict we have - a) we are told that Canvas is open source (perhaps a different matter - but aligned to transparent and available to the end user), so we can 'tweak' the platform to our own specifications, and as a customer, b) we are frequently warned that Instructure has finite resources to deliver feature requests - which seems to lead to bottleneck delivery of limited solutions (and which circles back to a). 

My understanding is that the style guide has been adopted so much because the vanilla offering of Canvas just doesn't do what end users need - it's too basic, and the platform kills blacklisted HTML entered via the RCE (HTML page) - thus limiting what can be introduced. Whilst the Canvas Style Guide was designed for developers rather than instructors / academics / content developers to use on their pages, it seems end users were frustrated by the lack of functionality, and business demands meant they couldn't wait for Instructure to catch up. So they ended up using the Style Guide to deliver what should have been possible in the first place (I take on board the accessibility issues that are presented by some of these).

But the move with InstUI seems to say (in a far more robust way than the Style Guide did), that there is more wizzy stuff that can be done in Canvas, but you people aren't allowed to do it (unless you're building an LTI - which I don't think is what many developers are doing and probably beyond most 'end users').  It seems the exact opposite of 'open' and pushes people toward the already buckling process of feature requests?

[d00386959]

I use the grid layout a lot.  No seriously, the grid columns were a game changer for me.

I also use buttons, icons, tabs, tables, and popovers, 

[kflowers]

I'm the same as  @james_trueman ‌ - only a newbie when it comes to a lot of this. However, I've now worked in two institutions where the grid layout specifically, but also the ability to add those "little extras" such as buttons, icons, popovers has been a turning point from slapping text and videos on a page into formatted experiences. While definitely not as flexible as one would like and requires some skill in tweaking HTML, it's all we have to work with, in the RCE. Especially when the administration of a large institution doesn't allow just anyone in the university to upload to the Theme Editor. 

And while I know at this point in time it's not going anywhere... I'm worried that one day it will just happen and we won't have a way to clean up the mess that remains.

Any time you search Google for resources on Canvas, numerous institutions are using the style guide to provide formatted training, resources or support pages. These may not be updated frequently and therefore, they may not even know that this is all going to change on them. Picture me talking a few deep breaths here. 

[DeletedUser]

As an assistant at a university who is responsible for managing the Canvas pages of the faculty that I support, my main resources for styling in Canvas are my own HTML/CSS knowledge and the classes exposed to us via the styleguide and Canvas CSS. Because the CSS we can use in the RCE is limited (and has to be all inline for me, because the style tag is stripped out), the styleguide classes/CSS bring a lot of additional functionality and take away the need to code some CSS myself. I could do more if I were able to be left to my own devices in designing the pages, in which case I'd move from designing them in Canvas entirely and embed them from elsewhere, but alas, I have some faculty who like being to press the Edit button and make a (minor) change like adding a reading or uploading some slides.

I will never have admin access or really anything beyond the lowliest of permissions because that's how universities roll. The ID team at my institution at least seems limited in capability, resources, and vision. I mean, the main ID at my school basically handed another assistant a copy of one of the pages I built to help her organize her content, which I don't mind, happy to help, but that's kind of where we're at with our ID support. We have faculty and assistants who know NOTHING about creating a visually appeasing Canvas page and our ID team provides NOTHING (no widgets, LTIs,  custom CSS and Javascript, or other cool things other universities seem to do). They don't train assistants on how to organize content or best practices or anything, so...yeah. When I tell you many of our courses are barebones or have homepages full of tables, believe it. Note this is partly because our ID team seems to think the Pages section is ideal for organizing content, to the point that the default template has Pages activated and Modules deactivated, and they also admitted they essentially don't know how Modules work or uses for them, which is just...::sigh::

This state of affairs saddens me and since I have some knowledge to alleviate it a bit, I do what I can. In terms of styleguide elements I use, these are the ones I use:

• Element Toggler: This is a big one and the one I'd miss the most if we lost access. I currently use it a lot in one course for vocabulary definitions, both in a "glossary" style page, but also as modal style popups. The enhanceable_content modals/dialog are limited in customization, so I create my own using this functionality. As an aside, the turn into dialog option that is supposed to go hand in with the element toggler does not work properly in the RCE because the modal code it generates gets added to the bottom of the page, outside of the user_content area. So it only triggers once because on the subsequent triggers, it's outside the area that the toggler code will look. If this didn't happen, it'd make use the element toggler to create modals even easier! Of course, we aren't to be using it anyway I suppose, so I can't really call it a bug and apparently it will disappear, but just thought I'd mention it.
• The Grid: The aspect I use most often, honestly. It's a must for easily creating columns and organizing content without having to use a table!
• Buttons: Button looking buttons and links acting as buttons.

But most of my usage actually comes from aping the CSS classes applied to many elements. Things like "box-shadow", "border-round", and "ui-widget-overlay" (because CSS attributes changing border-radius, adding box-shadows, and changing opacity are not allowed in the RCE). Or like the "page-title" class, which I use to hide the default page title our institution sticks there, and then use negative margins to cover it up with my own. I also use the font icons.

[robotcars]

My post above has received more helpfuls and likes than I think any of my other content... which feels weird because my other content is much nicer and more helpful. The Bob Ross RCE joke felt dirty to me, but it's been on my mind for years as I've struggled to empower teachers and designers to get more content into Canvas in an environment (the web) that is powered by access and tinkering and against the argument that teachers aren't designers. Canvas provides a very simple content solution and some basic tools, and yet it's users need someone/something that will show them how to paint something beautiful without being a pro. At the same time, the pro's need to have access to design globally for their institution. Those tools should to be hosted natively in Canvas, if that's not Bootstrap, the solution should be Bootstrap-esque. Bootstrap, btw is 2 files.

I'd like Canvas to provide a tiered and ever gracious approach to keeping development and design open to all levels of users, not just UI components that make development easier for their engineers, who I'm always willing to applaud and thank for their fantastic work. It's often hard enough for institutions to have someone who can make these changes when they really need them, let's not make it harder by making Canvas a programmer's only playground.

• A robust, easy to use content editor, that allows everyone to paint happy clouds or at least happy little accidents, without having to know responsive web design or concepts like progressive enhancement and graceful degradation... or hiring someone who does
• The users (students, instructors, designers, developers, admins) who want to modify the UI with Tamper Monkey or Theme Editor, should be able to access DOM elements via id and class selectors
• There should be a developer style guide, including buttons, modals, alerts, trays, sidebars?, etc – as well as a designer style guide, to access and utilize grid layouts, accessible tabs, and other interactive components that can be used, within the RCE and custom DOM through Theme Editor uploads.
• InstructureUI making these elements usable via LTI
• Provide source maps in test and production
• and documentation to boot

The human readable CSS class names debate kind of took off this weekend. Here's some highlights from my Twitter feed. A primary argument being, that it allows the web to continue to be open, anyone can learn how to make a web page by accessing and easily understanding what's in View Source or Developer Tools.  If Canvas is open, then allowing developers, institutions, instructional designers, instructors, and students the ability to modify and alter it should remain open. Please keep Canvas open.

@DHH... is the creator of Ruby on Rails, which is one of the many languages Instructure uses to write Canvas.

Paying tribute to the web with View Source - Signal v. Noise 

DHH on Twitter: "Amen. Same for me with both CSS and JavaScript. This is a learning path worth fight...

 

Sindre Sorhus on Twitter: "I learned web development in the early days (long before GitHub) with the...

Abdul Jaleel on Twitter: "@dhh This is exactly why we ♥️ you for being opinionated!   … " 

And Heydon Pickering, I've shared his work here before, Add Tooltips to Images and Text 

@heydon@mastodon.social on Twitter: "Web development isn't just for professional web developers. A w... 

I'm not sure what's on the Canvas roadmap, so apologies if I've jumped the gun, just working with what's in the OP, and what we've seen trending from Canvas, and the web.

[James]

I agree with much (most?) of what you wrote, carroll-ccsd. I'm not sure that Canvas sees it that way.

Let me put on my magical, mystical, psychic hat. It's what I use in the classroom when I introduce a theorem. I have the students follow the conditions and the hat tells them what they see without looking at their papers. It has a nearly 100% accuracy rate. It's the eventual reality of what the hat sees that worries me.

If your software isn't going to use something (Bootstrap), why should they be forced to include it? The same goes with jQuery. It's included right now because there is legacy code that uses it, but if Canvas migrates to more modern libraries, why should they be forced to continue to force it to be downloaded? Is it really Canvas' place to push users into a third-party solution that they don't use themselves?

And yes, that's a loaded question because they have integrations and do it all the time. But if I want to use React, why should I be forced to download jQuery or Bootstrap? Whatever they deliver, they have to make sure that it works with Canvas and doesn't cause problems. If you're not using a library, and the library you are using maintains a virtual DOM that is predicated on items having IDs that manipulating the DOM could break, why would you want to do that?

As for a developer's guide, if your components are invoked through a ReactJS library and not through CSS, the end-game would probably be to remove that CSS. If there's no CSS that users can utilize, and widgets aren't reactionary (scan the DOM looking for elements with certain classes), but they're implemented through the React components, then what good would it do to give people a list of CSS classes that they can apply to things? If you're not using them yourselves, then you have to continue to support them, which means keeping old, untested code around. That potentially defeats some of the efficiency and security they're striving to obtain, but it definitely means downloading extra code that you're not using, which is wasteful.

Canvas wants to use ReactJS to deliver their content and it doesn't play well with other libraries. People can't use ReactJS themselves within the web interface. Manipulating the DOM directly might break the React. Including human-friendly CSS names serves no purpose to Canvas directly, they only encourage users to do things that Canvas doesn't want them to do in the first place.

So, what does the magical, mystical, psychic hat foretell for people wanting to change Canvas? It's stuff we've heard before: Mene, mene, tekel [upharsin].

Loosely translated (with my comments): Your days (of freedom) have been numbered and you've been found wanting (more from Canvas). It's going to get even harder to accomplish anything that requires manipulating the web interface. That's a shame as not everything can be done through an LTI and some of the calls that are necessary to accomplish things aren't available through the API, so you need to be inside the browser to make them.

[robotcars]

You know...

if you ever decide not to have a realistic photo :smileysilly: on your profile, please use Merlin...

...you provide enough magical, mystical mentorship to own it.

All good points.

I don't want to force them to include a library they don't want to use, I'm hoping they will make their own, expose it, and provide documentation for us to access, much like the API docs and current style guide. If InstUI is Styleguide 2.0, then it would be nice if some/all of those elements are available to us with in the Theme Editor Uploads. Just wish listing here.

It's sad if our days of modifying the UI are limited, Canvas begs for so many bandaids and end user patches, because it cannot solve every scenario. Yet, delivering something close to a community of developers allows that open source feedback that helps drive improvements. Maybe they'd prefer if we write code and submit pull requests? But then I'm trying to implement my 'edge case' into every other instance.

Instructure seems to do really well at providing the tools for developing with the API, Canvas Data, Live Events, and GraphQL... I guess I'm just hopeful they will provide a similarly robust front end solution.

I have a couple hours to tinker tonight... now I'm flipping a coin between:

Syllabus Without Assignments: #comment-123257

Getting SQS message to SQL Database 

[James]

If I had a couple of hours to tinker, I would get some sleep. Alas, neither one seems in the forecast any time soon.

[James]

carroll-ccsd,

I didn't see this one coming when I wrote the other. 

As of Feb 4, the Tampermonkey update on Chrome is now issuing a warning.

When you look at the Tampermonkey 4.8 release notes for Chrome, it has the following announcement with a couple of links with more information.

The Chrome development team is currently planning changes that will disable Tampermonkey's ability to execute foreign code. Instead, all userscripts would have to become standalone Chrome extensions.

[MattHanes]

Well...this is unfortunate considering how useful these scripts are.

[James]

I don't know how much of it is like this discussion about InstUI 2.0 and they're actually going to remove it and how much of it is just speculation and initial over-reaction. I spent way more hours than I had last night reading through the Google forums and decided to delete everything else I had written in this post and just let it stand with what the Tampermonkey guy said. For the time being, it may mean switching to another browser if you need to run those. But historically as Chrome goes, Firefox soon follows. Chromium is seeking comments and there are some good use cases out there -- mostly related to how these extensions using some of these things improve security, privacy, and privacy.

I would love to say that it won't affect Canvas much if people put things into their global custom JavaScript, but I have seen some people talk about intercepting calls before they're made and then waiting for those to return -- that kind of stuff is what they're talking about blocking.

If you can't run userscripts at all, then it will make it more difficult to test things.

[floresr]

Does anyone have instructions on how to put these icons on a canvas page?

[cgaudreau]

 @floresr ‌, you can use the icon code found at Canvas Style Guide and substitute out the SVG text for the icon you chose from icon library.

Hope this helps!

[floresr]

thank you,

that was helpful.

Ricardo 

[tom_gibbons]

Oh, thank the stars that it's not being pulled. I had to come to the style guide page to find a class for the first time in a while, and saw that the page was deprecated. I'm also in the process of putting together a conference presentation for something that relies heavily on the style guide to function. So I was a little panicky for a hot second. 

[danielcktan]

Our school serves students with Special Needs (Autism).  To ensure that the Online Learning Environment on Canvas is autism-friendly, our e-Learning Team is putting in efforts to ensure that the learning interface is consistent and easy to understand by our students with autism.

When we adopt Canvas, we know that we need extensive customisation to meet our students' learning needs. As much as possible, we import 3rd party CSS (Bootstrap3, Fontawesome 4) and Javascript to the customise CSS and Javascript section of the Theme Editor. We tried to rely less on Enhance Content, which will soon be deprecated.

However, we have to use the following UI components from the Style Guide as these require javascript behaviours which we cannot add to the RCE.

• Accordions
• Tabs
• Modal Popups

We will be interested to be updated on InstUI 2.0 development as any new developments on InstUI may impact the UI of our courses and we will need to update the codings on the course pages.

To better explain our situation, the following are some examples of the UI components from the Style Guide that we have implemented on our course pages:

Accordions - To organise contents into chunks to order the flow of reading without distractions

Tabs - To organise small amount of contents into categories for easy consumption at one time.

Modal Popups - To provide additional information that are good to know and not critical to the learning.

[monica_nahas]

Hi!  I was reading up on this today because I received a question from a staff member regarding the Canvas Style Guide.  She was trying to design checkboxes on a Canvas page.  The code she found in the Style Guide is no longer working once the page is saved.  I read, somewhere, in this long thread that the style guide elements have not been taken away yet, but are there some of these pieces of code that no longer work on Canvas pages?  I know we are encouraged not to use the Style Guide for design, but I know that many people still do.  Thanks for any support!

[James]

 @monica_nahas ,

She is likely experiencing the Canvas HTML Whitelist.  It's a list of items that are allowed in user created content. Forms and any JavaScript are not allowed.

The original (now deprecated) style guide is for developers, not end users, so some of the stuff there never worked for regular users, but some did, which is why people found it confusing. What you're seeing most people comment on is about losing the stuff that did work. The New Style Guide 2.0 is not intended for content creators, either, it's still for the software developers.

One option to get checkboxes is to create them in a separate document that is hosted elsewhere and then embed that page in an iframe in Canvas.

[danielcktan]

 @monica_nahas ‌

You can try using H5P to create contents that require checkboxes and embed the H5P activities on canvas page using iFrame code.

H5P has free option (H5P – Create and Share Rich HTML5 Content and Applications ), Paid Subscription that integrates with Canvas (H5P as a Service ). You can also host your own H5P by installing Wordpress and H5P pluggin.

[kflowers]

We only have access to the free version at this point in time, and sadly it isn't responsive. And knowing how to resize while keeping the ratio messes with my head.

I do love a good H5P, but sadly doesn't help with a number of the design elements that people are using the Style guide for. 

[danielcktan]

Hi  @kflowers ‌

Agree that free version of H5P has its limitations. As far as I know, most of H5P's activities are responsive.

For our organisation, we take a step further by implementing CSS to ensure the iFrames used on our course pages are responsive. To allow more flexibility and access to more features, we host our own H5P. Hosting your own H5P tools by setting up Wordpress and H5P plugins will allow more flexibility and access to all H5P tools. You may wish to check with your organisation to see if this arrangement is possible.

[benjamin_rodrig]

How about Flex Grid? Will we still be able to utilize that in the RCE? Fingers are crossed that the answer is yes.

[Shar]

Hello, It's May 11, 2019 and the modals aka enhanceable_content dialog are no longer working.

The text that would have been in the modal (popup window) is just displayed on the page following the button the launch the modal.

I can't even begin to recollect all the places I used these popup boxes. Oh man, did I miss a warning some place that modals were going away?

Alas - Shar

[James]

ishar-uw,

They made an announcement before April 2017 about the deprecation of the jQuery UI and enhanceable content warning that it was coming, but no definite time table had been set. I haven't seen anything recently. The only one I remember seeing a notice for was the accordion and that was a while ago. I don't see "enhanceable", "modal", or "dialog" when I search the release notes for today. 

I don't have any modals to test that use enhanceable_content, but the ones I invoke using the information in the old Style Guide still works (I create my own dialog in the rubric importer script) and it uses the jQuery UI .dialog() method, which means it's still likely in the code. Our tabs that use enhanceable_content are still working, but dialogs are probably in the lesser-used category like accordions.

I'm 99% sure you've done this, but you did clear the cache and force a page reload or try a different browser, didn't you? Dialogs may be gone, but sometimes things act wonky over the weekend of a new release.

[Shar]

First, Thank-you for still being awake  @James !

I tried it on 2 different browsers, 2 different log-ins. At first I thought it was just a glitch on the page I was on, because once I went it and edited the page, saved, the functionality was restored.  But when I refresh the page, it's still broken.

I want to cry cry cry... But I'm going to wait until Monday to freak out because technically I shouldn't be working on a weekend and I don't want my team to know I'm burning weekend oil.

Next, tell me(us) more about these other dialog boxes. Are they just in your theme (custom CSS), or are they user-browser only Tampermonkey-enabled?

I'm writing a Q&A post in the Instructional designers group now too. But yeah, I keep up on the release notes and didn't see anything about modals being next. When accordions were done, they warned us! Let's just hope this is a weekend release temporary glitch.

I greatly appreciate you answering, my calm is starting to return.
Happy Mothers Day Eve,
Cheers - Shar

Edited to include sample code for folks to try. Line breaks added for readability.

<p>Want to know <a id="secretlink" class="btn btn-small" href="#secret">
a lil secret</a>?</p>
<div id="secret" class="enhanceable_content dialog" title="A lil secret">
This is a simple popup box.
</div>‍‍‍‍‍

[James]

When you look at the source code, the handling of dialog() within the enhanceable_content block are still there and that portion of the code was last changed 2 years ago when they took out accordions. It may very well be a glitch or something unrelated causing the problem. Is there anything other than the error message to the browser's developer tools console about the deprecation that jumps out?

If it turns out that it's not a glitch, then you may be able to quickly recover by it adding the code that Ryan Shaw contributed to your custom global JavaScript. That should work until they remove jQuery UI completely or the portion that does the dialogs. The long-term fix is for each college to decide which of those features they want to use and support and add the code that will display it. The purpose of this thread on Inst-UI was Canvas telling us they have a much better way to do it, probably not realizing the biggest (most vocal) concern people have are from people that used the old Style Guide in a way it wasn't intended and is unsupported. The enhanceble_content is a semi-related issue of having it automatically applied.

I wrote a really lengthy explanation of things back in July 2017 in Can I create an accordion outline in Canvas . It mentions how the release notes said the accordion was getting dropped and includes a link to Ryan's code:  GitHub - ryankshaw/widgetize-canvas-lms-user-content: A drop-in replacement for the functionality in...  That's not a long term solution, though, because eventually the jQuery UI widgets will disappear and then it will stop working.

[James]

Thanks for the example so I could test. Here's what it looks like for me when I click on "a lil secret". It works in both Firefox and Chrome (after clearing my cache) and in production and beta.

[Shar]

Replying to myself,

Seems it's just my org's instance that is breaking the modal. <org>.instructure.com

Free for Teacher is fine, and the University with their custom branded Canvas is fine too. canvas.<university>.edu

Ok, so maybe some updates are still being pushed to different instances. I'll chill for a moment and finish up my little work and worry later.

Cheers - Shar

Code to try in your Canvas. Line-breaks added for readability.

<p>Want to know <a id="link3" class="btn btn-small" href="#secret">
a lil secret</a>?</p>
<div id="secret" class="enhanceable_content dialog" title="A lil secret">
This is a simple popup box.</div>‍‍‍‍

[danielcktan]

Hi ishar-uw‌,

We are using the following solution for Modal Popup on our Canvas instance that do not depend on the deprecated JQuery UI approach: https://community.canvaslms.com/groups/designers/blog/2017/09/05/modalsdialogs-without-enchanceable-... 

You may wish to check out the above approach for long term usage. You will need to add your own custom CSS for the modal popup into your Theme CSS for styling and presentation purposes.

[Shar]

Thank-you Thank-you thank-you Daniel Tan!!!

This variation of the modals is just about perfect --- Cannot keyboard navigate to the modal link text using tab. But hey It's a step in the direction that I will need to go.

Again great many thanks and appreciation and shout-out to Andie Davis for contributing that blog post!

Cheers - Shar

[thomas_claeys]

Hi all!

Anyone developing something like Emble by RMIT? -> https://www.youtube.com/watch?v=iPJC-F3FLfM

We are looking for a React-based LTI tool to easily add InstUI to our pages. Even though the 'old' way of adding regular HTML and CSS seems to work (for now ...), we would love to design our courses in a more sufficient and future proof way . Curious about what's cooking! 

Best

Thomas

[DeletedUser]

You're welcome, though I do have to warn to use with caution. If you in any way have the ability to edit your Institutions css/js in any way, that'd be a far better way to go. 

Truthfully, the method does use jQuery UI, it just does not use the .enhanceable_content helper that Canvas will invoke. It instead relies on the manipulation of the Element Toggler that you can find in the styleguide to trigger a modal that is then styled using the same css classes that Canvas uses. Whenever Canvas gets around to not just killing the .enhanceable_content feature, but also no longer loading jQueryUI into the library at all, this method will hit the graveyard too. Or sooner, if Canvas decides to pop-in and delete the script with the element toggler code. It also will not work in the mobile app AT ALL, so if your students are primarily mobile-app dependent, it may not be worth it. We just advise students to use the mobile web version because there are just too many sacrifices in using the mobile app in general I find. 

[DeletedUser]

I know that the styleguide was deprecated, but was the navigation purposely broken too? The header is stuck on Components and you're unable to click on Style, Scaffold, or Patterns though all of the items do at least appear to be listed.

[DeletedUser]

Daniel,

If your team has the ability to edit your instances javascript, you could actually get the modals working WAY easier than using all the HTML I put up there. Like you could add, 

<p><a class="element_toggler btn" aria-controls="demo_modal">Show Modal</a></p>
<div title="Modal Title here!" id="demo_modal" style="display: none;" 
data-turn-into-dialog='{"width":800,"modal":true}'>
Whatever gets put in here becomes modal content!!!
<div class="button-container"><a class="btn dialog_closer">Close Modal</a></div>
</div>
</p>‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

But you would have to make 2 small edits to a couple of files...or make a copy of them, and then edit them. I don't know exactly how updates from Canvas and adding your own JS work together in Canvas since I've never seen the admin side of it.