From 2cdc59f8564ae4e8f617803ffb005662b61ad71b Mon Sep 17 00:00:00 2001
From: Wesley B <62723358+wesleyboar@users.noreply.github.com>
Date: Thu, 25 Jan 2024 10:29:07 -0600
Subject: [PATCH] feat(example): improve example app, add upgrade doc (#177)
* feat(example): core-cms v3.11.3
* chore: move e-mail settings to same spot
* chore: move all images to /img, no child dirs
* test: remove elasticsearch.yml (core-cms has it)
* chore: set TACC_CORE_STYLES_VERSION = 2
So new projects use v2!
Migrated projects, they need to be checking every setting.
* feat(example): core cms v3.12.0-beta.3
* chore: try to clean up diff
* chore: extra new line (for consistency)
* feat!: install custom app (FAIL)
Breaking Change: Fails with error.
```
django.core.exceptions.ImproperlyConfigured: Cannot import 'custom_example'. Check that 'apps.custom_example.apps.CustomExampleConfig.name' is correct.
```
* fix: upgrade for Core-CMS v3.12 (i.e. Django 3.2)
* feat: new upgrade path to Core-CMS v3.12
* docs(port-project): small improvements
* docs(upgrade-project): add "Rename Project"
And make some small fixes.
* docs(upgrade-project): refactor "Rename Project"
* docs(develop-project): apps are moved
* docs(upgrade-project): drop extra STATICFILES_DIRS
* chore: whtiespace tweak
* refactor(example-cms): undo unnecessary changes
* docs(upgrade-project): add "Move Images"
And make minor fixes.
* docs(upgrade-project): move aliases to bottom
---
README.md | 6 ++
docs/upgrade-project.md | 85 ++++++++++++++++++
example_cms/docker-compose.dev.yml | 1 -
example_cms/elasticsearch.yml | 14 ---
example_cms/src/apps/custom_example/apps.py | 5 --
.../custom_example/custom_example.html | 4 -
.../__init__.py | 0
example_cms/src/apps/example_app/apps.py | 5 ++
.../static/example_app/css/example_app.css | 3 +
.../templates/example_app/index.html | 13 +++
.../{custom_example => example_app}/urls.py | 3 +-
.../{custom_example => example_app}/views.py | 2 +-
.../src/taccsite_cms/custom_app_settings.py | 2 +-
.../src/taccsite_cms/settings_custom.py | 14 ++-
example_cms/src/taccsite_cms/urls_custom.py | 4 +-
.../img/{favicons => }/favicon.ico | Bin
.../img/{org_logos => }/portal.png | Bin
17 files changed, 131 insertions(+), 30 deletions(-)
create mode 100644 docs/upgrade-project.md
delete mode 100644 example_cms/elasticsearch.yml
delete mode 100644 example_cms/src/apps/custom_example/apps.py
delete mode 100644 example_cms/src/apps/custom_example/templates/custom_example/custom_example.html
rename example_cms/src/apps/{custom_example => example_app}/__init__.py (100%)
create mode 100644 example_cms/src/apps/example_app/apps.py
create mode 100644 example_cms/src/apps/example_app/static/example_app/css/example_app.css
create mode 100644 example_cms/src/apps/example_app/templates/example_app/index.html
rename example_cms/src/apps/{custom_example => example_app}/urls.py (81%)
rename example_cms/src/apps/{custom_example => example_app}/views.py (74%)
rename example_cms/src/taccsite_custom/example_cms/static/example_cms/img/{favicons => }/favicon.ico (100%)
rename example_cms/src/taccsite_custom/example_cms/static/example_cms/img/{org_logos => }/portal.png (100%)
diff --git a/README.md b/README.md
index 1062f739..a303e126 100644
--- a/README.md
+++ b/README.md
@@ -14,6 +14,7 @@ Extensions of the [Core CMS] project
- [Build Project](#build-project)
- [Deploy Project](#deploy-project)
- [Port Project](#port-project)
+- [Upgrade Project](#upgrade-project)
## Related Repositories
@@ -161,6 +162,10 @@ Follow "Core-CMS-Custom" section of [How To Build & Deploy][Deploy Project].
To port a project from [Core CMS Resources], read [Port Project].
+## Upgrade Project
+
+To upgrade components of an existing project (e.g. [Core CMS]), read [Upgrade Project].
+
[Core Portal Deployments]: https://github.com/TACC/Core-Portal-Deployments
@@ -176,6 +181,7 @@ To port a project from [Core CMS Resources], read [Port Project].
[Deploy Project]: https://tacc-main.atlassian.net/wiki/x/2AVv
[Port Project]: ./docs/port-project.md
+[Upgrade Project]: ./docs/upgrade-project.md
[Django CMS User Guide]: https://tacc-main.atlassian.net/wiki/x/phdv
[Upgrade Project]: https://github.com/TACC/Core-CMS/blob/main/docs/upgrade-project.md
diff --git a/docs/upgrade-project.md b/docs/upgrade-project.md
new file mode 100644
index 00000000..2258a090
--- /dev/null
+++ b/docs/upgrade-project.md
@@ -0,0 +1,85 @@
+# Upgrade Project
+
+## Table of Contents
+
+- [Core-CMS v3.11 to v3.12](#core-cms-v311-to-v312)
+ 1. [Rename Project](#rename-project)
+ 2. [Update Settings](#update-settings)
+ 3. [Move Images](#move-images)
+
+## [Core CMS] v3.11 to v3.12
+
+### Rename Project
+
+Verify project name is compatible with Django 3.2.
+
+1. If your project directory name has dashes, rename it to use underscores, i.e.
+
+ | | root |
+ | - | - |
+ | from | `custom-project-dir` |
+ | to | `custom_project_dir` |
+
+ | | `taccsite_custom` |
+ | - | - |
+ | from | `taccsite_custom/custom-project-dir` |
+ | to | `taccsite_custom/custom_project_dir` |
+
+ | |`taccsite_cms/static` |
+ | - | - |
+ | from | `taccsite_cms/static/custom-project-dir` |
+ | to | `taccsite_cms/static/custom_project_dir` |
+
+ > **Important**
+ > A valid Python application uses underscores.
+
+2. Rename **all** references to the previous directory names.
+
+3. Identify, support and deprecate old CMS template paths.
+
+ Follow [Port Project: Old CMS Template paths](./port-project.md#old-cms-template-paths).
+
+ > **Important**
+ > Failure to do this can crash an entire page.
+
+4. In `taccsite_cms/custom_app_settings.py`, remove project from `STATICFILES_DIRS`, i.e.
+
+ | | change |
+ | - | - |
+ | from | `STATICFILES_DIRS = ('taccsite_custom/custom_project_dir', ...)` |
+ | to | `STATICFILES_DIRS = (...)` |
+
+ > **Note**
+ > [Core CMS] already defines the `static` directory for each project.
+
+### Update Settings
+
+Remove unnecessary settings.
+
+1. In `taccsite_cms/custom_app_settings.py`, remove apps from `STATICFILES_DIRS`, i.e.
+
+ | | change |
+ | - | - |
+ | from | `STATICFILES_DIRS = ('apps/custom_example', ...)` |
+ | to | `STATICFILES_DIRS = (...)` |
+
+ > **Note**
+ > Django automatically identifies the `static` directory for each app.
+
+### Move Images
+
+Verify project name is compatible with Django 3.2.
+
+1. Remove any subdirectories of your project's static `img` directory, i.e.
+
+ | | root |
+ | - | - |
+ | from | `taccsite_custom/static/custom_project_dir/img/*/...` |
+ | to | `taccsite_custom/static/custom_project_dir/img/...` |
+
+2. Rename **all** references to the previous image paths e.g.
+ - in `settings_custom.py`
+
+
+
+[Core CMS]: https://github.com/TACC/Core-CMS
diff --git a/example_cms/docker-compose.dev.yml b/example_cms/docker-compose.dev.yml
index 2aeb7843..5663fe54 100644
--- a/example_cms/docker-compose.dev.yml
+++ b/example_cms/docker-compose.dev.yml
@@ -40,7 +40,6 @@ services:
- ES_HEAP_SIZE:1g
- discovery.type=single-node
volumes:
- - ./elasticsearch.yml:/usr/share/elasticsearch/config/elasticsearch.yml
- core_cms_es_data:/usr/share/elasticsearch/data
container_name: core_cms_elasticsearch
ports:
diff --git a/example_cms/elasticsearch.yml b/example_cms/elasticsearch.yml
deleted file mode 100644
index 55847499..00000000
--- a/example_cms/elasticsearch.yml
+++ /dev/null
@@ -1,14 +0,0 @@
-#Use this to configure elasticsearch
-#More info: https://www.elastic.co/guide/en/elasticsearch/reference/current/settings.html
-#
-cluster.name: es-dev
-network.host: 0.0.0.0
-#network.publish_host: hostname
-node.name: es01
-#minimum_master_nodes need to be explicitly set when bound on a public IP
-# set to 1 to allow single node clusters
-# Details: https://github.com/elastic/elasticsearch/pull/17288
-discovery.zen.minimum_master_nodes: 1
-#More info about memory_lock: https://www.elastic.co/guide/en/elasticsearch/reference/current/setup-configuration-memory.html
-bootstrap.memory_lock: true
-xpack.security.enabled: false
\ No newline at end of file
diff --git a/example_cms/src/apps/custom_example/apps.py b/example_cms/src/apps/custom_example/apps.py
deleted file mode 100644
index 672181cf..00000000
--- a/example_cms/src/apps/custom_example/apps.py
+++ /dev/null
@@ -1,5 +0,0 @@
-from django.apps import AppConfig
-
-
-class CustomExampleConfig(AppConfig):
- name = 'custom_example'
diff --git a/example_cms/src/apps/custom_example/templates/custom_example/custom_example.html b/example_cms/src/apps/custom_example/templates/custom_example/custom_example.html
deleted file mode 100644
index 93902fc3..00000000
--- a/example_cms/src/apps/custom_example/templates/custom_example/custom_example.html
+++ /dev/null
@@ -1,4 +0,0 @@
-{% extends "base.html" %}
-{% block content %}
-This page will contain custom content.
-{%endblock %}
diff --git a/example_cms/src/apps/custom_example/__init__.py b/example_cms/src/apps/example_app/__init__.py
similarity index 100%
rename from example_cms/src/apps/custom_example/__init__.py
rename to example_cms/src/apps/example_app/__init__.py
diff --git a/example_cms/src/apps/example_app/apps.py b/example_cms/src/apps/example_app/apps.py
new file mode 100644
index 00000000..1016a269
--- /dev/null
+++ b/example_cms/src/apps/example_app/apps.py
@@ -0,0 +1,5 @@
+from django.apps import AppConfig
+
+
+class ExampleAppConfig(AppConfig):
+ name = 'apps.example_app'
diff --git a/example_cms/src/apps/example_app/static/example_app/css/example_app.css b/example_cms/src/apps/example_app/static/example_app/css/example_app.css
new file mode 100644
index 00000000..dda2cdf8
--- /dev/null
+++ b/example_cms/src/apps/example_app/static/example_app/css/example_app.css
@@ -0,0 +1,3 @@
+h1 {
+ color: green;
+}
diff --git a/example_cms/src/apps/example_app/templates/example_app/index.html b/example_cms/src/apps/example_app/templates/example_app/index.html
new file mode 100644
index 00000000..1d46c708
--- /dev/null
+++ b/example_cms/src/apps/example_app/templates/example_app/index.html
@@ -0,0 +1,13 @@
+{% extends "base.html" %}
+{% load static sekizai_tags %}
+
+{% block content %}
+
+{% addtoblock "css" %}
+
+{% endaddtoblock %}
+
+Example App
+Example application content.
+
+{% endblock %}
diff --git a/example_cms/src/apps/custom_example/urls.py b/example_cms/src/apps/example_app/urls.py
similarity index 81%
rename from example_cms/src/apps/custom_example/urls.py
rename to example_cms/src/apps/example_app/urls.py
index d38dbd09..d3a292c9 100644
--- a/example_cms/src/apps/custom_example/urls.py
+++ b/example_cms/src/apps/example_app/urls.py
@@ -1,7 +1,8 @@
from django.urls import re_path
from .views import AddedView
-app_name = 'custom_example'
+
+app_name = 'example_app'
urlpatterns = [
re_path('', AddedView, name='index'),
]
diff --git a/example_cms/src/apps/custom_example/views.py b/example_cms/src/apps/example_app/views.py
similarity index 74%
rename from example_cms/src/apps/custom_example/views.py
rename to example_cms/src/apps/example_app/views.py
index 985d9732..4e1e16ec 100644
--- a/example_cms/src/apps/custom_example/views.py
+++ b/example_cms/src/apps/example_app/views.py
@@ -5,5 +5,5 @@
def AddedView(request):
- template = loader.get_template('custom_example/custom_example.html')
+ template = loader.get_template('example_app/index.html')
return HttpResponse(template.render({}, request))
diff --git a/example_cms/src/taccsite_cms/custom_app_settings.py b/example_cms/src/taccsite_cms/custom_app_settings.py
index a1a905ca..f194c465 100644
--- a/example_cms/src/taccsite_cms/custom_app_settings.py
+++ b/example_cms/src/taccsite_cms/custom_app_settings.py
@@ -1,3 +1,3 @@
-CUSTOM_APPS = []
+CUSTOM_APPS = ['apps.example_app']
CUSTOM_MIDDLEWARE = []
STATICFILES_DIRS = ()
diff --git a/example_cms/src/taccsite_cms/settings_custom.py b/example_cms/src/taccsite_cms/settings_custom.py
index 5c6fff21..9154b792 100644
--- a/example_cms/src/taccsite_cms/settings_custom.py
+++ b/example_cms/src/taccsite_cms/settings_custom.py
@@ -29,7 +29,7 @@
#
# _CUSTOM_BRANDING = [
# "example",
-# "example_cms/img/org_logos/example-logo.png",
+# "example_cms/img/some-logo.png",
# "",
# "https://example.com",
# "_blank",
@@ -46,7 +46,7 @@
LOGO = [
"example",
- "example_cms/img/org_logos/portal.png",
+ "example_cms/img/portal.png",
"",
"/",
"_self",
@@ -55,6 +55,10 @@
"True"
]
+FAVICON = {
+ "img_file_src": "example_cms/img/favicon.ico"
+}
+
########################
# TACC: PORTAL
########################
@@ -62,3 +66,9 @@
# INCLUDES_CORE_PORTAL = False
# INCLUDES_PORTAL_NAV = False
# INCLUDES_SEARCH_BAR = False
+
+########################
+# TACC: CORE STYLES
+########################
+
+TACC_CORE_STYLES_VERSION = 2
diff --git a/example_cms/src/taccsite_cms/urls_custom.py b/example_cms/src/taccsite_cms/urls_custom.py
index 03805aef..96f4dd39 100644
--- a/example_cms/src/taccsite_cms/urls_custom.py
+++ b/example_cms/src/taccsite_cms/urls_custom.py
@@ -1,3 +1,5 @@
from django.urls import path, include
-custom_urls = []
+custom_urls = [
+ path('example_app/', include('apps.example_app.urls', namespace='example_app')),
+]
diff --git a/example_cms/src/taccsite_custom/example_cms/static/example_cms/img/favicons/favicon.ico b/example_cms/src/taccsite_custom/example_cms/static/example_cms/img/favicon.ico
similarity index 100%
rename from example_cms/src/taccsite_custom/example_cms/static/example_cms/img/favicons/favicon.ico
rename to example_cms/src/taccsite_custom/example_cms/static/example_cms/img/favicon.ico
diff --git a/example_cms/src/taccsite_custom/example_cms/static/example_cms/img/org_logos/portal.png b/example_cms/src/taccsite_custom/example_cms/static/example_cms/img/portal.png
similarity index 100%
rename from example_cms/src/taccsite_custom/example_cms/static/example_cms/img/org_logos/portal.png
rename to example_cms/src/taccsite_custom/example_cms/static/example_cms/img/portal.png