October 17, 2019
Open edX 2017: The Evolution of Open edX Theming

Open edX 2017: The Evolution of Open edX Theming


Hello, everyone, this talk is about the theming
capabilities built in to Open edX. We will look at both past and present technologies that allow
us to theme our instances. So my name is Matjaz Gregoric and
I’m a software developer at OpenCraft. First, what is theming? The basic function of theming is
changing how your site looks and feels. You are usually, most often, only concerned with theming the end-user
facing parts of the system. For example, for
edX that would be the LMS. But sometimes you may also want to
theme the backend, like the edX studio. Theming allows you to change colors,
images, text and it also lets you modify the layout. A simple layout modification would be
injecting some links into the header or the footer and the more complex layout modification
would completely shuffle things around. Either by injecting some
complex CSS rules for just by changing
the structure of your HTML. And why would you want to theme your site? The most common motivation is branding. Most often,
when you install a new Open edX instance, you will want to use your own company’s
logo instead of the stock Open edX one. And you may also want to
change the default edX blue to some color from your
company’s own color palette. If you have existing corporate sites, you may want to make the LMS look similar
to the corporate sites, so that when users move from one system to another,
the experience is more consistent. Or you may just want to make your site
look different from the competition. Another reason is theming for
legal reasons. In this case, you are not concerned
about the looks, but about the content. For example,
the theming system in Open edX lets you change the text on the terms of
service and honor code pages. And it also lets you replace
the different copyright notice in the footer with your own text if
the default doesn’t work for you. Finally, theming lets you
do functional changes. For example, you can add custom
links into the header or the footer. Or you can replace the login button
with a link to a third-party single sign-on solution. And another common reason to theme your
site is to make it more responsive. So that it works better on mobile devices. The default Open edX team
has been improving this responsiveness area a bit, but
it’s still far from perfect. Now, we look how the theming
system in Open edX came to be. Before there was any officially support
system built in, the only way to theme your site was to fork the edX
repository and make changes in that. That’s very nice because it
lets you change anything but it’s a maintenance nightmare. Open EdX moves really fast and
every time you upgrade to a new release, you will have to rebase your changes,
you will run into lots of code conflicts and
basically have a very bad time. So forking is not a viable solution for
theming. And team at Stanford were very much
aware of that, so before they launched their edX site they had to come
up with a solution for theming. And that’s how the first theming
system built into Open EdX came to be. It was contributed in GitHub
full request number 57. And it has since been known as
the Stanford Theming system. It will let you override
static content such as images, templates, Django or micro templates. And it would let you add
custom static pages. Stanford developed a sample
theme that they put on GitHub. And the common workflow when you were
developing a new theme was that you would form this repository and
make your changes and develop your consistency on
top of the Stanford Theme. This is what
the Stanford Theme looks like. The nice thing about Stanford Theming was
that it was the first officially supported theming system that was build into edX. It would let you override any static
file and any Django or micro template. It also had SASS support built in. So when you issued the favor
comments to generate your assets, it would build your SASS together
with the SASS in the edX platform. And the most common modifications
were easy to make but more complex things were trickier. Stanford theming had some issues,
one of them was not being able to override
arbitrary sass files. And while overriding arbitrary files is
usually not a great idea, it sometimes the simplest solution that doesn’t
involve copying large amounts of CSS. Stanford theming had no support for
Studio. It was LMS only. And because the Stanford was a bit
in a hurry to rush their site, so the implementation was
a bit hackish in some areas. Like there were areas in
the code where it would say, if using Stanford theming inject
this content, otherwise inject this. Stanford theming was single theme for
instance only. And this was a problem for
the Solutions team. Team which had a task to build
multitenancy into Open EdX. And they had to add some
limited support for theming so that each microsite could
be themed differently. And so they’d develop their
own system which was known as the microsite theming system. It would let you add custom
additional CSS per microsite. It would let you override certain images. And it would also let you override
templates, all of these for a microsite. The obvious advantage of microsite theming
was that it supported multitenancy. So, If you looked at the site from one domain it looked different than
if you looked at it from another domain. But it could only override specific
images and it had no SASS support. Both microsite theming and
Stanford theming coexisted for a while, but
you could not use them at the same time. You had to pick one or the other. So if you need that multitenancy you would
typically go with microsite teaming, and if not,
you would probably use Stanford. And that’s how we come to
comprehensive theming, which merges this multitenancy with
the basic approach of Stanford theming. Comprehensive theming was
first released in dogwood and has seen some significant
improvements in eucalyptus. It is similar to Stanford theming, but it’s more consistent and
the implementation is much cleaner. And like we said,
it supports multitenancy. In addition to the LMS,
it also supports Studio and ecommerce. It lets you override any static file and
any Django or macro template, just like Stanford. But it also lets you override
any SASS file or partial. This is nice because it makes, hopefully,
aspects of theming static files, templates, and SASS very consistent. Now while I was preparing for this talk, I found this repository on
the edX Github account. It contains a sample theme for
the LMS and ecommerce. And it seems to serve a similar purpose as
the sample stanford theme we saw before. But I don’t remember ever
seeing it publicly announced, so I’m not sure what
this [INAUDIBLE] it is. But it looks like this, as you can see,
there are areas where you’re supposed to replace the before content with your own. Let’s look at some examples. This is a very simple thing, it changes
the logo, the color of the button, the background image on the home page and
that’s about it. This one is similar, custom logo,
custom colors, images, but not much else. This one is similar again, except that
the background of the header is dark, which means that you also have
to change the color of the text. Cuz otherwise it’s not very
visible on dark background. And we found that that’s currently not
as simple to do as it could have been. And I’ll talk about this a bit more later. Now this theme wasn’t built by OpenCraft,
but I included it here because it looks nice. And I think it was built on
the sample theme that we saw earlier, because the structure of
the header looks very similar. And this is an example of a theme that doesn’t look anything like
the default edX theme. Now that you’ve learned what comprehensive
theming can do, let’s talk about some best practices that we try to
stick to at OpenCraft. The first one is just to try
to keep your theme small. The smaller the theme is, the easier
it will be to upgrade to a new release. The second thing is always prefer
CSS changes over template overrides. Because we found that template
overrides are the worst, templates change all the time. And every time you upgrade to a new
release, you have to go through each template, figure out what has changed
upstream, merge your changes back. And it takes a long time, and
I’m sure nobody enjoys doing that. That said, you should still try to
keep CSS small, cuz even if you have huge amounts of CSS, that still tends
to break the layout when you upgrade. But at least it only breaks the look,
it will not start producing server errors. And it’s usually easier to debug and fix. Next thing is to try to use the built
in SASS variables if possible. There are quite a lot of SASS variables
already built into edX platform, some work better than the others. But you should try it first and
if it works, just stick to it. Cuz it’s less likely to
break when you upgrade. And there are some potential
improvements that I think would make theming easier, especially
from the maintenance perspective. The first is the ability to override named
blocks in Django or macro templates. Currently, you cannot override
a single block from a template. You have to copy the whole thing and
then maintain it through releases. And one example would be
changing the log in button in the header with a link to
a third party SSO solution. Now, the log in button is neatly wrapped
in this “navigation_sign_in” block. But unfortunately, there’s no
way to override just this block. You have to copy the entire template. And solutions for this problem exist,
there’s a Django package for Django overextends that lets
you override and extend the override template at the same time,
which is basically what we need here. And I actually think that this is
built into Django 1.9 out of the box. Unfortunately, simply upgrading to Django
1.9 won’t solve themes for edX platform. Because, first of all, we use we don’t
use a lot of standard Django templates. And second,
we also use dynamic template lookups. So there will probably have to be
some custom coding [INAUDIBLE]. And once we have the ability
to override specific blocks, we should try to use more of them. It’s still not a good idea
to go overriding blocks all over the place, but it’s still
better than overriding entire templates. The other thing I mentioned a bit earlier
is improving with built-in SASS variables. There are There are already
a lot of variables, but not all of them work consistently. Some don’t work at all,
some are over even later below in the default Open edX style sheet. So when you try to change
the color of some buttons, for example, you have to copy the CSS and to replace the hard coded
colors with your desired value. And another example I mentioned earlier
is changing just the color of the text in the header. Cuz we have very nice SASS variables that allow you to change the background
color of the header or the footer. You set onto your desired color and
it just works, but there’s nothing like that for
the color of the text. So if you’re changing the color to dark, you have to do a lot of extra
work just to change the text. In conclusion, we have seen that
comprehensive theming has evolved from quick and dirty solutions into
a pretty decent theming system. It has come a long way, but there are still areas where it
could use some improvement. And being able to override
chunks of templates would be one of the most
important upgrades, I believe. And until we have that and
also after we have that, please try to keep template
overrides to a minimum. Now, with open craft, we’ll be closely
following further development of theming. I hope we will be able to
contribute some of our own ideas, both in terms of feedback and code. And I would like to welcome
the community to do the same. So we can discuss these things on
the mailing list and on Slack. And that’s all for me. Thank you very much, and,>>[APPLAUSE]>>We have time for questions or comments, suggestions. Yes, please?>>First of all, thank you for
your presentation. It was really informative. At Techrock we still use
the Stanford theming. But I would like to know a little
bit more about the blocks and overrides that are available with
the new comprehensive theming. So, you mentioned that the template
blocks are not yet available, right? Template blocks overwrite, so you still have to-
>>Yes.>>Okay, so
what about the SASS overwrites? How this has have been developed? So I haven’t looked really well into
the documentation, but I would like to, So I would like to hear from you about
how many overrides are possible, I mean, are there any
missing SASS overrides that-?>>SASS variables.>>No, not just variables, I mean SASS-
>>Overriding->>For the specific class, can I override the specific
class in the SASS?>>You can override the specific class,
yes. But you can add your custom CSS to
the bottom of the default styles, then you can-
>>No, can I replace the complete partial? Is that supported?>>You can replace a complete partial,
yes.>>So I remove the edX. Not just like patching it until I-
>>Yeah, it works very similar
to template overwrites. If you give it the same name as in edX
platform and put it in the same place, it will use your version instead of the-
>>Okay, so, and that was not supported in
the Stanford theming, right? Yeah, right, that was not
supported in the Stanford, yes.>>Thank you.>>That’s just a SASS feature,
that’s not with edX.>>Yeah, so at Stanford, so we’re actually
in the process right now of switching over from Stanford theming, putting that to
rest and switching over to comp theming. And one of the things that’s held
us up was the use of blocks. We leveraged those Mako blocks a lot. What we’ve actually found that
allowed us to essentially make that a non-issue is instead of using
blocks, just moving those into fragments. So instead of defining a Mako block,
simply moving that into a partial HTML file, and
then we can override that at will. Have you guys looked into doing that?>>No, not really, cuz then,
I would have to see the code. I’m not really sure how that’s-
>>So literally, instead of having a Mako block and
then overriding that, you just move the contents of
that block into an HTML file.>>Yeah, but-
>>So then you can shadow it
just like anything else.>>That would need to happen in
the edX platform repository.>>Sure, but I mean, that’s the follow up. That then allows us to then to
completely move away from this. And I think that’s
the overarching thing that needs, the followup work for
the edX platform to be changed, is then moving specific blocks or
specific areas into separate files instead of having these
massive aggregate template files.>>That could work, but
we would end up with a massive amount of templates if we put each
chunk into a separate template. So it’s an interesting solution, but
I would prefer to see template overrides.>>Sure.>>Hi, Julio, also from Stanford. And actually,
I’m the one that created pull request 57. But so,
>>[LAUGH]>>So we actually have a couple things that we’re currently doing now. So what you can do is in Mako and Django,
you can inherit a file and then you don’t actually change anything, except redefine
the same block that you want to override. And that gives you block overriding. So you say, inherit main, cuz if you look
at the other things, they inherit main and then they make changes, but don’t actually replace any of
the content on main like the rest of it.>>Do you still need the content
in the overwritten file, right?>>The overwritten file
needs to have the block. So if it has a name block,
you can say inherit from that template and then you redefine the block. And it just swaps out the block and
leaves the rest as it is. So you can do that. That does exist and
it does work, we do that. Another one, is you can put optional
includes in your templates on platform. And with the comp theming, what that does is any theme that has
this template defined, it’ll take it. And if it doesn’t, it just ignores it. And on platform, it’s just an injection, which means it’s very low risk for
conflicts. And even if there are, you know you want
that, so it’s an easy conflict to resolve. So that’s another one to consider for
those kinds of situations. And then, yeah, in the CSS,
you covered that, so,>>Yeah, thank you very much for both the comments and for
creating pull request number 57.>>[LAUGH] But
I think you’re talking about overriding, [INAUDIBLE] you were talking about the.>>Override just a specific section
of an included block, right?>>Yes.
>>Yeah, so it’s a little bit different. Whereas Julio, you’re talking about being
able to include another block instead.>>No, I said two things
>>Right.>>So both things are possible right now.>>Overriding just part
of the template though?>>Yes.
>>I mean, part of the block template?>>Yes.
>>Hm, okay. [LAUGH]
>>[LAUGH]>>[INAUDIBLE]>>Yeah, I have a question So, many of the things that conversations
around themes centers around making minimal changes to avoid future conflict. It seems like we have this artificial
yoke around our necks, right? Is there any plan to fix
down a more permanent basis? And I’ve had a number of
conversations already. You don’t have this theming conflict or
major issues as much as it is in edX? As it is in something like WordPress. You can easily flip out themes in and
out without having problems, right? And you can define your templatesyou
can do everything else without having these major conflicts.>>Right.
>>So is there any intention to go towards, this is not
something that doesn’t exist. It’s already out there. And the question now is, is there any
plans to adopt something like that versus having this yoke on your
neck always saying, hey, just make minimal changes
because of future conflicts. And just make these little changes and
avoid the conflicts.>>Yes, I think everyone would
like to see a better solution but it’s a difficult problem and
we are working towards it. This morning,
we’ve had a interesting discussion and we decided on some future steps. So I’m sure we will see improvements, I’m
just not sure how fast these will come.>>The short answer is yes,
and it’s going to be more of a revolution
[INAUDIBLE] evolution.>>So I think the future direction
is much more toward react jxs based. So encapsulated components with css
encapsulation that don’t leak out. I mean, the problem with edX platform is
much, much more complex than something like a WordPress, which essentially is a
CMS, which generates a static site, right? So I think just by nature of
it is much harder to solve. As far as global theming, I think
the way that we’re thinking of moving forward is using the bootstrap framework,
bootstrap four, so we just punt that problem to bootstrap. So, you don’t end up with variable
that gets overridden down the path or gets hardcoded. So the exact problem that
you’re talking about like header background versus header text. That’s all stuff that bootstrap solves,
so we don’t have to solve that problem, or we solve the problem and that addresses
exactly block element overwrites. There’s no such thing as a block,
your entire page is a component made of components,
made of components, made of components. So at the smallest atomic
level of a component if you wanna swap that component out,
go to town cuz that’s your problem. Or if you want to change I think in your
example it was like a navigation specific?>>Yes.
>>Like, navigation within a specific part, right? In that case, you just say okay, I have a navigation component that’s
made up of these sub-components. Well, I wanna keep some of
the sub-components and inject my own, then I’ll just make a new navigation
parent that takes existing components, add my own component, remove other
components, do whatever you want. They’re just markup at the end of the day. Of course, new components you
have to create that new tag, or new custom component. But yeah, I think we have
a good way of separating out even at the presentation layers,
styling from the HTML. And then you know, you have a whole other layer for
behavior that then you can mix and match. That’s kind of the long term thing. It’s a long ways from now, but that is
the direction that we’re looking at. But like I said,
that would be much more of a revolution. So it a complete has nothing
to do with this basically. [LAUGH]
>>But I think in a previous conversation
the move towards bootstrap, I think there’s on roadmap here
in the next resource partially.>>Partially, it’ll be in whatever -b3 is.>>Okay, so.>>But that’s a very small step. [INAUDIBLE]
[LAUGH]>>Any other questions?>>You talked about SASS
partials overwrite.>>Yes.>>And to be honest I’ve done
the SASS files override and the SASS partials, but
with the partials sometimes it breaks, and it doesn’t exactly put
under like you want it to be. Sometimes there’s some other partial or
some other file on the edX platform that is overriding
the partial that you are overriding. And you end up with
an override hell on the->>Yeah, I can imagine. I did not run into this particular problem but-
>>Yeah.>>Yeah, so with that, I think you just have to be really cognizant
of the build pipeline and make sure your stuff comes later
than any of the edX stuff. And again that is something with the new
system we’re gonna simplify much more. There’s Jango’s not gonna be involved
[LAUGH] in the asset pipeline stuff or the new stuff anymore. It’s all gonna be node based which
is a lot more clear what’s going on. And it’s much more
declarative rather than, I think Jango Compressor
is what we use right now. So yeah, it’ll be much more of an
open-source community standard rather than this rat’s nest of stuff that Jango’s
not well suited to deal with.>>Yeah, so I think one thing that I
feel like we’re missing from this, so, we were focusing a lot on the styling,
and the look and the feel. But how do you guys
handle your custom data, custom logic that needs pass through? It’s one thing to say,
don’t fork the template. Don’t fork the CSS, but
when you need to pass additional context, how much work do you do with that,
and then what are your thoughts there?>>Well, if we have to do it,
we try to upstream our changes.>>Right.
>>So and I get it, right? Cuz this has come up in
a couple of the talks though.>>Yes.
>>But the reality is that’s just not possible for everyone. There are legitimate features that people
build that are put behind feature flags. And then, the response from edX is,
we still don’t want it though. And so, I think this again,
this is where the idea, that balance between the idealism and
practicality of it is. So I have some ideas, if you wanna
talk about it later, let me know.>>Okay.>>My short response to that
would be use Jango’s facility. I mean, it sounds like potentially the
cleanest way is to just have your own sub URL scheme, right? And you direct to that sub URL, and
that’s its own self contained Jango app, which still allows you to import stuff
from Jango LMS, or wherever that you want. And then you create your own views. You control your own templates. You can even control your own
asset pipeline, or whatever for that, from that URL path down is yours. That’s, I guess, off the cuff. That’s kind of my, I’m just trying to
think of the most Jango way of doing it. [LAUGH]
>>It still doesn’t quite solve it, cuz it really is, when you wanna change it’s one
thing if you’re building something new. Sure, you’ll put it on a new URL,
separate as much as you can. But that still doesn’t address
what happens when you’re trying to change something that exists. That’s the unsolved problem.>>Okay, so Thank you very much.>>[APPLAUSE]

1 thought on “Open edX 2017: The Evolution of Open edX Theming

Leave a Reply

Your email address will not be published. Required fields are marked *