Arches for HERs docx/ directory needs to be overwritable from project

[samuelscandrett]

In Arches for HERs, if you wish to customise Consultation letter templates (and/or the content going into letters), the files in the docx/ directory need to be replaced and the file_template.py needs to be updated with the new information.

These currently cannot be created in the project by creating a file_template.py in views/. Similarly, you cannot create a docx/ directory in the project to manage letter templates.

This means, to customise Cons in AfHER, you are required to clone the app repo to make customisations - a problematic solution that opens you up to conflicts and overall difficult management.

[CWDamm-Kint]

I think we can address this by importing the project version of file_template.py within the project version of urls.py.

from .views.file_template import FileTemplateView

urlpatterns = [
   re_path(r'^filetemplate', FileTemplateView.as_view(), name='filetemplate'),

   path("", include("arches.urls")),
   path("", include("arches_her.urls")),
] + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

Requests to /filetemplate will then be directed to the project view, before the app or core arches urls are imported.

[samuelscandrett]

I feel like there should be a more clean and general way of overwriting any files in the arches_her app with files in the project, similar to how a project can overwrite any file in core Arches by creating a file with the same name and path.

Though my example in the issue is regarding file_template.py and the docx directory, this should be possible with any file in AfHER, for example if a project needed to extend any of the bng files.

I'll change the title of the issue to reflect it as more general.

[samuelscandrett]

After speaking with @CWDamm-Kint I can confirm that .py files are not able to be overwritten in the project, and I was confusing this with overwriting .htm and .js files which are presumably picked up by webpack.

The method of overwriting the AfHER file_template.py suggested by @CWDamm-Kint should be sufficient.

The issue of the docx/ directory and files within is still important.
I wonder whether we should include DOCX_DIR in settings.py for AfHER, and this can be overwritten in the project. If not specified in the project, AfHER will fall back to its own settings.

[CWDamm-Kint]

For reference, this is the current code in file_template. Could we update it to try looking for a docx folder in the project before looking in HER_ROOT as the fallback option?

template_path = os.path.join(site.getsitepackages()[0], "arches_her", "docx", template_name)
        if not os.path.exists(template_path):
            template_path = os.path.join(settings.HER_ROOT, "docx", template_name)

[samuelscandrett]

HER_ROOT is used for developing with Arches for HERs, but not when installing via pip.

An idea would be that DOCX_DIR set in settings.py could use site-packages or HER_ROOT, or an entirely custom path.
e.g.

# default
DOCX_DIR = os.path.join(site.getsitepackages()[0], "arches_her", "docx")
# if developing
DOCX_DIR = os.path.join(settings.HER_ROOT, "docx")
# if docx directory is elsewhere
DOCX_DIR = "/home/arches_user/project/project/docx"

With an approach like the above, the default can be to look in the venv, but any fallback options can be customised.

Going further, we might also want to support external paths such as S3.

[samuelscandrett]

@aj-he, what are your thoughts on this?

[aj-he]

@samuelscandrett @CWDamm-Kint - I would agree that you would almost always want to use you own letters and therefore be able to add your own.

If be interested to know if the things you changed in the file-template.py are also things people would want to have the option of changing?

Looking at your solution above, could you please consider the contents of the PR linked below, which highlights that the use of site.getsitepackages()[0] can cause Windows Server users issues? I can see that this is in out of the box file-template.py file already. I'd appreciate it is you could incorporate this?

https://github.com/archesproject/arches/pull/11952/files