Theming Design and Workflow Considerations

Owned by Matthew Drayer
Last updated: Apr 03, 2023 by Brian Smith
4 min read

Reference Documentation:

Background

  • Comprehensive theming shipped with Cypress release of edx-platform

Current State

Questions:

QuestionAnswer
Andy Armstrong (Deactivated): I'm finding it difficult to understand how multiple themes will be configured in production. It seems that they all have to live under a single directory in order to be processed. Is this correct? Andy Armstrong (Deactivated), at the present time the theming feature expects theme assets to be located in a single directory. However this could certainly be enhanced to support a list of directories (ie, a simple registry pattern), or to even walk the entire directory tree during installation (or startup) to determine locations of themes.
Andy Armstrong (Deactivated): Since they aren't committed into edx-platform this way, how will they get into a single directory? Andy Armstrong (Deactivated), the current plan is to modify the provisioning script that currently pulls assets from the edx-microsites code repository to also pull theme assets from a new edx-themes code repository.
Andy Armstrong (Deactivated): Are we imagining a separate installation phase that copies themes into directories? Andy Armstrong (Deactivated), I'm not sure if it's so much a separate phase as much as an enhancement of the existing microsites provisioning workflow.
Andy Armstrong (Deactivated): Has someone from devops reviewed the configuration details?Andy Armstrong (Deactivated), not yet, this is the next step in the process for the current project.
Felipe Montoya: I see some work has been done to support the wiki after removing the SITE_ID, after that change is done, will the templates that use django_templates instead of MAKO also work?Felipe Montoya, I will check with Saleem Latif about this – I don't see any reason why the template engine would matter but it would be good to have confirmation on this.
Felipe Montoya: In this same like, is there a specific plan to bring more support of the sites framework? If I may ask... what is the end purpose of that?Felipe Montoya, as per the discussion taking place on edx-code, the overall goal is to add support for Django Sites to the edx-platform project. In addition, as part of PR 11613, we will be adding new SiteConfiguration and SiteTheme models to enable easier administration of multiple experiences on the platform. Ultimately we will be transitioning the existing microsites functionality, including configuration overrides, into this new framework.
Felipe Montoya: Since the Comprehensive theme is liked to the site, it means that won't work for microsites using the filebased backend right?Felipe Montoya, I think as part of the work to transition microsites we should look at ways of supporting the filebased backend for microsite/theme configuration – I envision a series of configuration fall-backs where first the site's database configuration is checked, and then a file-based configuration, and then ultimately the default platform configuration would be used.
Felipe Montoya: I could not make the assets work despite testing them on devstack and aws configurations or trying collecstatics directly. Any particular configuration that is required? Felipe Montoya, there have been some updates to PR 11613 since you asked this question – perhaps give it another try and if still no success we can work with Saleem Latif to resolve the issue.
Felipe Montoya: Also, are the assets going to be prefixed by the theme name in any way?Felipe Montoya, in order for theme assets to properly override default assets I think the current implementation expects them to be named the same. So no prefixing of asset names with theme names is currently planned. Let us know if this is going to create a problem and we can revisit.
Andy Armstrong (Deactivated): How will stage and production builds automatically pick up the edx.org theme? Andy Armstrong (Deactivated), the edx.org theme is currently provided with the core edx-platform code project, so the configuration setup will be the main thing to address. Essentially we will just need the proper Site, SiteConfiguration, and SiteTheme entries available in the database so the proper theme is applied for the stage/prod host.
Andy Armstrong (Deactivated): Do the configuration scripts need to be updated to explicitly pass the theme root directory? Andy Armstrong (Deactivated), each Site entry will be linked to a corresponding SiteConfiguration and SiteTheme entry, so we should not need to modify the configuration scripts themselves in order to select and serve the proper theme for a given Site.
Andy Armstrong (Deactivated) (ARCH-13): How to support installing themes as pluginsAndy Armstrong (Deactivated), this is definitely something we should consider as an overall Comprehensive Theming enhancement. I agree that using Stevedore is a worthy investigation.
Andy Armstrong (Deactivated) (ARCH-13): How the edX Pattern Library can be consumed and overridden by themesAndy Armstrong (Deactivated), I think that themes should be able to reference the edX Pattern Library the same way they reference any other stylesheets and scripts – by including the proper references in their header templates. As far as overrides go, we can discuss the best way to support that as part of a follow-on to the current effort.
Andy Armstrong (Deactivated) (ARCH-13): How to support theming with multi-tenancyAndy Armstrong (Deactivated), the multi-tenant aspect of theming should be addressed through the addition of the Site, SiteConfiguration, and SiteTheme models, as well as the merge of the microsites feature into the theming subsystem.
Andy Armstrong (Deactivated) (ARCH-13): How all IDAs can implement comprehensive theming, not just edx-platformAndy Armstrong (Deactivated), we might accomplish this by moving the theming implementation out of edx-platform and into a standalone project/library which could be referenced by any IDA. In addition, the introduction of a separate edx-themes project should also result in applicability across multiple services. I believe there is another team at edX currently exploring the extraction of the theming logic into its own repository.
Andy Armstrong (Deactivated) (ARCH-13): How to support theming in iframes (particularly for LTI, but also for David Ormsbee's new remote blockAndy Armstrong (Deactivated), I don't have an answer for this one at this point – I think it's certainly worth investigating, however I consider it out of scope for our current effort.