Set up pattern library (#10808)

* Install django-pattern-librray

* Enabled pattern-library, and tweaked template path so it works. Added monkey patch for some custom tags. Though individual templates still show errors in pattern library. This only affects pattern-library functionalities but not the normal website.

* Added new base template for Pattern library

* Added pattern library base template for rendering fragments.

* Add some yaml for pattern library. Also tweaked settings to tidy up pattern library nav.

* Linting

* Updated inline code comment for Django Pattern Library.

---------

Co-authored-by: Jhonatan Lopes <jhonatan.dapontelopes@gmail.com>
Co-authored-by: Mavis Ou <mmmavis@users.noreply.github.com>

dev-requirements.in

@@ -1,4 +1,5 @@
 -c requirements.txt
+django-pattern-library
 black
 coveralls
 django-debug-toolbar

dev-requirements.txt

@@ -46,8 +46,11 @@ django==3.2.20
     # via
     #   -c requirements.txt
     #   django-debug-toolbar
+    #   django-pattern-library
 django-debug-toolbar==4.1.0
     # via -r dev-requirements.in
+django-pattern-library==1.0.0
+    # via -r dev-requirements.in
 djhtml==1.5.2
     # via -r dev-requirements.in
 djlint==1.19.16
@@ -75,6 +78,8 @@ idna==3.3
     #   -c requirements.txt
     #   requests
     #   urllib3
+importlib-metadata==6.7.0
+    # via markdown
 iniconfig==2.0.0
     # via pytest
 isort==5.12.0
@@ -139,7 +144,9 @@ pytz==2021.3
     #   -c requirements.txt
     #   django
 pyyaml==6.0
-    # via djlint
+    # via
+    #   django-pattern-library
+    #   djlint
 regex==2022.10.31
     # via djlint
 requests==2.31.0
@@ -191,3 +198,5 @@ urllib3-secure-extra==0.1.0
     # via
     #   -c requirements.txt
     #   urllib3
+zipp==3.15.0
+    # via importlib-metadata

network-api/networkapi/project_styleguide/templatetags/localization.py

@@ -0,0 +1,14 @@
+from pattern_library.monkey_utils import override_tag
+
+from networkapi.wagtailpages.templatetags.localization import register
+
+# Override the localization tags with a fake implementation to return dummy URLs.
+# The fake implementation will only be used when viewing the pattern library.
+# See https://torchbox.github.io/django-pattern-library/guides/overriding-template-tags/
+#
+# These tags are used in a large number of pages, and their output does
+# not affect appearance. Overriding them centrally here is a convenient way
+# to avoid having to override the tags in each individual YAML file.
+override_tag(register, name="get_unlocalized_url", default_html="/dummy")
+override_tag(register, name="relocalized_url", default_html="/en/dummy")
+override_tag(register, name="localizedroutablepageurl", default_html="/en/routed-dummy")

network-api/networkapi/project_styleguide/templatetags/wagtailmetadatatags.py

@@ -0,0 +1,8 @@
+from pattern_library.monkey_utils import override_tag
+from wagtailmetadata.templatetags.wagtailmetadata_tags import register
+
+override_tag(
+    register,
+    name="meta_tags",
+    default_html='<title>Example title</title><meta name="description" content="Example description">',
+)

network-api/networkapi/settings.py

@@ -87,6 +87,7 @@ env = environ.Env(
     XSS_PROTECTION=bool,
     SCOUT_KEY=(str, ""),
     WAGTAILADMIN_BASE_URL=(str, ""),
+    PATTERN_LIBRARY_ENABLED=(bool, False),
 )
 
 # Read in the environment
@@ -185,6 +186,10 @@ USE_S3 = env("USE_S3")
 # Detect if Django is running normally, or in test mode through "manage.py test"
 TESTING = "test" in sys.argv or "pytest" in sys.argv
 
+# Django Pattern Library
+# Do not enable for production!
+PATTERN_LIBRARY_ENABLED = env("PATTERN_LIBRARY_ENABLED")
+
 INSTALLED_APPS = list(
     filter(
         None,
@@ -257,6 +262,8 @@ INSTALLED_APPS = list(
             "networkapi.wagtailpages",
             "networkapi.mozfest",
             "networkapi.donate",
+            "pattern_library" if PATTERN_LIBRARY_ENABLED else None,
+            "networkapi.project_styleguide",
         ],
     )
 )
@@ -360,6 +367,7 @@ TEMPLATES = [
                 "settings_value": "networkapi.utility.templatetags.settings_value",
                 "wagtailcustom_tags": "networkapi.wagtailcustomization.templatetags.wagtailcustom_tags",
             },
+            "builtins": ["pattern_library.loader_tags"],
         },
     },
 ]
@@ -722,3 +730,36 @@ if DEBUG:
         "127.0.0.1",
         "10.0.2.2",
     ]
+
+# Django Pattern Library
+# https://torchbox.github.io/django-pattern-library/
+#
+# Pattern library isn’t intended for production usage, and hasn’t received
+# extensive security scrutiny. Don't enable it on production.
+#
+# PATTERN_LIBRARY_ENABLED is set to True in docker-compose.yml for local development.
+# For pattern library to work with CSP, you also need to add the following to your .env file:
+#    PATTERN_LIBRARY_ENABLED=1
+#    X_FRAME_OPTIONS=SAMEORIGIN
+#    CSP_FRAME_ANCESTORS="'self'"
+PATTERN_LIBRARY_ENABLED = env("PATTERN_LIBRARY_ENABLED", default=False)
+PATTERN_LIBRARY = {
+    # Groups of templates for the pattern library navigation. The keys
+    # are the group titles and the values are lists of template name prefixes that will
+    # be searched to populate the groups.
+    "SECTIONS": (
+        # Add additional sections here. This will appear as the left-hand nav in /pattern-library/
+        # e.g. ("Component name", ["path_to/component_name"]),
+        ("Pages", ["pages"]),
+        ("Fragments", ["fragments"]),
+        ("Wagtailpages", ["wagtailpages"]),
+    ),
+    # Configure which files to detect as templates.
+    "TEMPLATE_SUFFIX": ".html",
+    # Set which template components should be rendered inside of,
+    # so they may use page-level component dependencies like CSS.
+    "PATTERN_BASE_TEMPLATE_NAME": "pattern_library_base.html",
+    # Any template in BASE_TEMPLATE_NAMES or any template that extends a template in
+    # BASE_TEMPLATE_NAMES is a "page" and will be rendered as-is without being wrapped.
+    "BASE_TEMPLATE_NAMES": ["pages/base.html"],
+}

network-api/networkapi/templates/fragments/custom_hero_guts.html

@@ -1,5 +1,8 @@
 {% load static i18n wagtailimages_tags homepage_tags %}
-{% get_page_authors page as authors %}
+{# Pattern library has problems with this tag, so we exclude it from pattern library rendering. #}
+{% if not is_pattern_library %}
+    {% get_page_authors page as authors %}
+{% endif %}
 
 
 

network-api/networkapi/templates/fragments/custom_hero_guts.yaml

@@ -0,0 +1,36 @@
+context:
+  page:
+    title: Example page title
+    subtitle: Example page subtitle
+    secondary_subtitle: Example page secondary subtitle
+    hero_image:
+      raw:
+        url: 'https://via.placeholder.com/1920x1080'
+        alt: Example alt text
+    authors:
+      count: 2
+      all:
+        - author:
+            name: Cynthia Williams
+        - author:
+            name: Justin Sanders
+  is_publication_article: true
+  self:
+    breadcrumb_list:
+      - entry:
+        localized:
+          title: Example one
+          url: '#'
+      - entry:
+        localized:
+          title: Example two
+          url: '#'
+  download_file:
+    url: '#'
+    file_size: 104
+  authors:
+    raw:
+      - name: Cynthia Williams
+        slug: cythiawilliams
+      - name: Justin Sanders
+        slug: justinsanders

network-api/networkapi/templates/fragments/publication_hero.html

@@ -1,6 +1,9 @@
 {% load i18n homepage_tags %}
 
-{% get_page_authors page as authors %}
+{# Pattern library has problems with this tag, so we exclude it from pattern library rendering. #}
+{% if not is_pattern_library %}
+    {% get_page_authors page as authors %}
+{% endif %}
 
 <div
     class="publication-hero-container tw-relative tw-bg-gradient-to-b tw-from-gray-60 tw-to-gray-80 {% if size == "small" %} small tw-pt-56 tw-pb-72 {% else %} tw-pt-72 tw-pb-96 {% endif %}"

network-api/networkapi/templates/fragments/publication_hero.yaml

@@ -0,0 +1,36 @@
+context:
+  page:
+    title: Example page title
+    subtitle: Example page subtitle
+    secondary_subtitle: Example page secondary subtitle
+    hero_image:
+      raw:
+        url: 'https://via.placeholder.com/1920x1080'
+        alt: Example alt text
+    authors:
+      count: 2
+      all:
+        - author:
+            name: Cynthia Williams
+        - author:
+            name: Justin Sanders
+  is_publication_article: true
+  self:
+    breadcrumb_list:
+      - entry:
+        localized:
+          title: Example one
+          url: '#'
+      - entry:
+        localized:
+          title: Example two
+          url: '#'
+  download_file:
+    url: '#'
+    file_size: 104
+  authors:
+    raw:
+      - name: Cynthia Williams
+        slug: cythiawilliams
+      - name: Justin Sanders
+        slug: justinsanders

network-api/networkapi/templates/fragments/responsive_screen_wide_image.html

@@ -10,17 +10,19 @@
     xlarge: "1200px",
     "2xl": "1400px",
   {% endcomment %}
-    {% image image_object width-576 as img_576 %}
-    {% image image_object width-1152 as img_576_2x %}
-    {% image image_object width-768 as img_768 %}
-    {% image image_object width-1536 as img_768_2x %}
-    {% image image_object width-992 as img_992 %}
-    {% image image_object width-1984 as img_992_2x %}
-    {% image image_object width-1200 as img_1200 %}
-    {% image image_object width-2400 as img_1200_2x %}
-    {% image image_object width-1400 as img_1400 %}
-    {% image image_object width-2800 as img_1400_2x %}
-    {% image image_object original as img_original %}
+    {% if not is_pattern_library %}
+        {% image image_object width-576 as img_576 %}
+        {% image image_object width-1152 as img_576_2x %}
+        {% image image_object width-768 as img_768 %}
+        {% image image_object width-1536 as img_768_2x %}
+        {% image image_object width-992 as img_992 %}
+        {% image image_object width-1984 as img_992_2x %}
+        {% image image_object width-1200 as img_1200 %}
+        {% image image_object width-2400 as img_1200_2x %}
+        {% image image_object width-1400 as img_1400 %}
+        {% image image_object width-2800 as img_1400_2x %}
+        {% image image_object original as img_original %}
+    {% endif %}
     <source
         media="(max-width: 576px)"
         srcset="{{ img_576.url }}, {{ img_576_2x.url }} 2x"

network-api/networkapi/templates/fragments/responsive_screen_wide_image.yaml

@@ -0,0 +1,23 @@
+context:
+  img_576:
+    url: 'https://via.placeholder.com/576x324'
+  img_576_2x:
+    url: 'https://via.placeholder.com/1152x648'
+  img_768:
+    url: 'https://via.placeholder.com/768x432'
+  img_768_2x:
+    url: 'https://via.placeholder.com/1536x864'
+  img_992:
+    url: 'https://via.placeholder.com/992x558'
+  img_992_2x:
+    url: 'https://via.placeholder.com/1984x1116'
+  img_1200:
+    url: 'https://via.placeholder.com/1200x675'
+  img_1200_2x:
+    url: 'https://via.placeholder.com/2400x1350'
+  img_1400:
+    url: 'https://via.placeholder.com/1400x788'
+  img_1400_2x:
+    url: 'https://via.placeholder.com/2800x1575'
+  img_original:
+    url: 'https://via.placeholder.com/1920x1080'

network-api/networkapi/templates/pages/article_page.yaml

@@ -0,0 +1,13 @@
+context:
+  page:
+    hero_layout: static
+    article_file: #
+    is_publication_article: True
+    authors:
+      count: 2
+      all:
+        - author:
+            name: Cynthia Williams
+        - author:
+            name: Justin Sanders
+    show_side_share_buttons: True

network-api/networkapi/templates/pattern_library_base.html

@@ -0,0 +1,47 @@
+{% load wagtailmetadata_tags i18n localization settings_value wagtailuserbar static mofo_common %}
+
+{% get_current_language as lang_code %}
+
+<!DOCTYPE html>
+<html lang="{{ lang_code }}" class="{% block html_class %}{% endblock %}">
+    <head>
+        <meta charset="utf-8">
+        <title>
+            {% block page_title %}
+                {% environment_prefix %}
+                {% trans "Mozilla Foundation" %} - {% if page.specifics.seo_title %}{{ page.specifics.seo_title }}{% else %}{{ page.title }}{% endif %}
+            {% endblock %}
+        </title>
+
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+
+        {% block stylesheets %}
+            <link rel="stylesheet" href="{% static "_css/main.compiled.css" %}">
+            {% if debug %}<link rel="stylesheet" href="{% static "_css/tailwind.compiled.css" %}">{% endif %}
+
+            <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Nunito+Sans:400,300,700,300i,800,900,400i">
+            <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Zilla+Slab:300,400,500,600,700,300i,400i,600i">
+        {% endblock %}
+    </head>
+    <body class="{% block bodyclass %}{% endblock %}" id="view-{% block body_id %}{% endblock %}">
+        {% block body_wrapped %}
+            <div class="wrapper">
+                {% block content_wrapped %}
+                    <main role="main">
+                        {% block content %}
+                            {# This is only used when viewing pattern library via /pattern-library. #}
+                            {{ pattern_library_rendered_pattern }}
+                        {% endblock %}
+                    </main>
+                {% endblock content_wrapped %}
+            </div>
+        {% endblock %}
+
+        {% block script_bundle %}
+            <script src="{% url "javascript-catalog" %}"></script>
+            <script src="{% static "_js/main.compiled.js" %}"></script>
+        {% endblock %}
+
+        {% block extra_scripts %}{% endblock %}
+    </body>
+</html>

network-api/networkapi/urls.py

@@ -1,3 +1,4 @@
+from django.apps import apps
 from django.conf import settings
 from django.conf.urls.i18n import i18n_patterns
 from django.conf.urls.static import static
@@ -155,6 +156,12 @@ if settings.DEBUG:
 if settings.DEBUG_TOOLBAR_ENABLED:
     urlpatterns += (path("__debug__/", include("debug_toolbar.urls")),)
 
+# Styleguide
+if settings.PATTERN_LIBRARY_ENABLED and apps.is_installed("pattern_library"):
+    urlpatterns += [
+        path("pattern-library/", include("pattern_library.urls")),
+    ]
+
 urlpatterns += [path("sitemap.xml", sitemap_index)]
 
 # Use a custom 404 handler so that we can serve distinct 404

network-api/networkapi/wagtailpages/templates/wagtailpages/blocks/rich_text_block.yaml

@@ -0,0 +1,2 @@
+context:
+  value: Else health character policy television now. Style could affect eye. Bank me morning scientist provide value. Leave physical stock role summer. Off represent first worry explain chance. Defense address carry opportunity I machine according.

pyproject.toml

@@ -102,6 +102,7 @@ ignore="H017"
 "network-api/networkapi/templates/partials/banner.html" = "H006,H025,T003"
 "network-api/networkapi/templates/partials/footer.html" = "H006,H008,T002,T003"
 "network-api/networkapi/templates/partials/primary_nav.html" = "D018,H014,H025,T002,T003"
+"network-api/networkapi/templates/pattern_library_base.html" = "H030,H031,T003"
 "network-api/networkapi/templates/reviewapp-help.html" = "D018,T003"
 "network-api/networkapi/wagtailcustomization/templates/wagtailadmin/404.html" = "D018,H014,T003"
 "network-api/networkapi/wagtailcustomization/templates/wagtailadmin/account/account.html" = "T003"