Why is Tutor documenting tutor-indigo theming when it does not work?

Site Operators Tutor Help
1

Hi,
I am trying to figure out how theming works with OpenEdX and Tutor.

I have been mislead in following

which simply does not work.

The changes to this theme only apply to pages that are under the direct LMS_HOST url, i.e. edx.<domain>, NOT to any of the apps.edx.<domain> pages, which are the vast majority of pages. I figured that by adding a prefix to the Powered by text in the footer. The prefix only appears on the “courses” page and the wiki pages, not the learner-dashboard (that redirects to apps.edx.<domain>, nor any of the courses page, nor the studio, nor anything else relevant!

How do I modify the theme for apps.edx.<domain> pages ?

2

In other words, if I change

/tutor/.local/share/tutor/env/build/openedx/themes/indigocq/lms/templates/footer.html

it instantly changes the footer on the pages that are under edx.<domain>. What do I need to do for the changes to affect pages that are under apps.edx.<domain> ?

3

@tutor-maintainers any advice?

4

This question is documented here: GitHub - overhangio/tutor-indigo: An elegant, customizable theme for Open edX
and here: GitHub - overhangio/tutor-mfe: This plugin makes it possible to easily add micro frontend (MFE) applications on top of an Open edX platform that runs with Tutor.

5

Mmm, ok, but then why is this not what’s documented in the Tutor doc ?

Also, how does one go ahead and test the changes without rebuilding the images ? Building the images takes ~20-30 minutes. This is not good for developing.

With tutor-indigo, we can simply mount the theme directory, make the changes and refresh the page and the effect of the changes are seen instantaneously. Also, it is quite obvious through tutor-indigo what the files are. With the npm branding stuff, the templates are not in the repository, it seems only a few of the images and the css files are.

6

Also, the examples in here and here contradict eachother

The first one states:

hooks.Filters.ENV_PATCHES.add_item((
            "mfe-dockerfile-post-npm-install",
            """
RUN npm install '@edx/brand@npm:custom-brand-package'
RUN npm install '@edx/brand@git+https://github.com/username/brand-openedx.git#custom-branch'
""",
        ))

while the second one states

hooks.Filters.ENV_PATCHES.add_item(
    (
        "mfe-dockerfile-post-npm-install",
        """
RUN npm install '@edx/brand@git+https://github.com/edx/brand-edx.org.git'
"""
    )
)

This is confusing. Do I need RUN npm install '@edx/brand@npm:custom-brand-package' ? or do I need RUN npm install '@edx/brand@git+https://github.com/username/brand-openedx.git#custom-branch' ? or both ? or RUN npm install '@edx/brand@git+https://github.com/edx/brand-edx.org.git' ? Is it brand-openedx.git ? or brand-edx.git ? This raises more questions than it gives answers.

7

Multiple reasons:

  1. Tutor core and tutor-indigo and tutor-mfe are different things.
  2. Different people take care of these different things.
  3. The documentation is imperfect.

I’m not myself an expert in MFE/Indigo theming, so it’s difficult for me to give you good advice other than “read the docs”. If you feel like this documentation should be centralized in the core Tutor docs, then we would be more than happy to discuss this. Would you like to open a pull request? The docs are in the /docs directory of the tutor repo.

I believe this is an intrinsic limitation of MFEs and tutor-mfe for production builds. But you should not have to rebuild the image when running tutor dev commands. Just install the branding package on the host, with npm install ..., and then bind-mount the MFE repository with tutor mounts add .... Unless I’m mistaken, the node_modules/ directory will also be bind-mounted. But I suggest you only try this out after you get everything to work.

All these commands are examples of the same thing. You should replace “edx/brand”, “brand-edx”, “username”, etc. with your own package name and GitHub repository.

Again, it’s quite possible that these instructions could be improved. If you have suggestions, I encourage you to open pull requests in the corresponding repositories.

8

That’s unfortunate. We run a development platform in a cloud VM with “tutor local”. As far as I understand, “tutor dev” only allows localhost, i.e. not exposed to the internet. That would mean that it’s very difficult to properly develop without it being installed on one’s local computer.