GH-93: Article List Styles

taccsite_cms/contrib/_docs/how-to-conditionally-render-child-plugins.md

@@ -0,0 +1,11 @@
+# How to Conditionally Render Child Plugins
+
+```handlebars
+    {% for plugin_instance in instance.child_plugin_instances %}
+      {% if plugin_instance.plugin_type == 'LinkPlugin' %}
+        <a href="{{ link }}" <!-- ... -->>
+          <!-- ... -->
+        </a>
+      {% endif %}
+    {% endfor %}
+```

taccsite_cms/contrib/_docs/how-to-extend-django-cms-plugin.md

@@ -0,0 +1,66 @@
+# How To Extend a `djangocms-___` Plugin
+
+These example codes extend the [`djangocms-link` plugin](https://github.com/django-cms/djangocms-link/tree/3.0.0/djangocms_link).
+
+`.../models.py`:
+
+```python
+from djangocms_link.models import AbstractLink
+
+class Taccsite______(AbstractLink):
+    """
+    Components > "Article List" Model
+    https://confluence.tacc.utexas.edu/x/OIAjCQ
+    """
+    # ___ = ___
+
+    class Meta:
+        abstract = False
+```
+
+`.../cms_plugins.py`:
+
+```python
+from djangocms_link.cms_plugins import LinkPlugin
+
+from .models import ______Preview
+
+class ______Plugin(LinkPlugin):
+    module = 'TACC Site'
+    model = Taccsite______
+    name = _('______')
+    render_template = 'static_article_preview.html'
+    def get_render_template(self, context, instance, placeholder):
+        return self.render_template
+
+    fieldsets = [
+        (_('Link'), {
+            'fields': (
+                ('external_link', 'internal_link'),
+                ('anchor', 'target'),
+            )
+        }),
+    ]
+
+    # Render
+    def render(self, context, instance, placeholder):
+        context = super().render(context, instance, placeholder)
+        request = context['request']
+
+        context.update({
+            'link_url': instance.get_link(),
+            'link_text': instance.name,
+            'link_target': instance.target
+        })
+        return context
+```
+
+`.../templates/______.py`:
+
+```handlebars
+
+<a class="______" href="{{ link_url }}"
+  {% if link_target %}target="{{ link_target }}"{% endif %}>
+  <span>{{ link_text }}
+</a>
+```

taccsite_cms/contrib/_docs/how-to-handle-non-nullable-default-value.md

@@ -0,0 +1,62 @@
+# How to Handle "Non-Nullable" "Default Value"
+
+## Sample Error
+
+```text
+You are trying to add a non-nullable field '...'
+to choice without a default; we can't do that
+(the database needs something to populate existing rows).
+Please select a fix:
+ 1) Provide a one-off default now (will be set on all existing rows)
+ 2) Quit, and let me add a default in models.py
+Select an option:
+```
+
+## Explanations
+
+- (blog post) [What do you do when 'makemigrations' is telling you About your Lack of Default Value](https://chrisbartos.com/articles/what-do-you-do-when-makemigrations-is-telling-you-about-your-lack-of-default-value/)
+- (video) [You are trying to add a non-nullable field ' ' to ' ' without a default; we can't do that](https://www.youtube.com/watch?v=NgaTUEijQSQ)
+
+## Solutions
+
+### For `cmsplugin_ptr`
+
+1. ☑ Select option 1), then see:
+    - [Follow-Up Error](#follow-up-error)
+    - [Notes ▸ `cmsplugin_ptr`](#cmsplugin_ptr)
+
+### For Other Fields
+
+1. ⚠ Select option 1) and hope for the best.
+2. ☑ Select option 2) and provide a sensible default (_not_ `None` a.k.a. null).
+3. ⚠ (blog post) (hack) [Add A Migration For A Non-Null Foreignkey Field In Django](https://jaketrent.com/post/add-migration-nonnull-foreignkey-field-django)
+
+## Follow-Up Error
+
+If you allowed Null to be set as default, then you may have this new error:
+
+```text
+django.db.utils.IntegrityError: column "..." contains null values
+```
+
+Solutions:
+
+1. [delete _relevant_ migration files and rebuild migrations](https://stackoverflow.com/a/37244199/11817077)
+2. [delete _all_ migration files and rebuild migrations](https://stackoverflow.com/a/37242930/11817077)
+
+## Notes
+
+### `cmsplugin_ptr`
+
+  If the field is `cmsplugin_ptr` then know that
+
+  - [it is a database relationship field managed automatically by Django](https://github.com/nephila/djangocms-blog/issues/316#issuecomment-242292787),
+  - you may see it in workarounds for other plugins ([source a](https://github.com/django-cms/djangocms-link/blob/3.0.0/djangocms_link/models.py#L125), [source b](https://github.com/django-cms/djangocms-picture/blob/3.0.0/djangocms_picture/models.py#L208)),
+  - you should __not__ add or overwrite it unless you know what you are doing.
+
+  _W. Bomar learned everything in the intitial version of this document after trying to overwrite `cmsplugin_ptr` while extending its model from [source a](https://github.com/django-cms/djangocms-link/blob/3.0.0/djangocms_link/models.py#L125). His solution was [delete _all_ migration files and rebuild migrations](https://stackoverflow.com/a/37242930/11817077)._
+
+## Appendix
+
+- [Django CMS ▸ How to create Plugins ▸ Handling Relations](https://docs.django-cms.org/en/release-3.7.x/how_to/custom_plugins.html#handling-relations)
+- [[BUG] Plugins with models that don't directly inherit from CMSPlugin or an abstract model cannot be copied](https://github.com/django-cms/django-cms/issues/6987)

taccsite_cms/contrib/_docs/how-to-override-validation-error-from-parent-model.md

@@ -0,0 +1,67 @@
+# How To Override `ValidationError()` from Parent Model
+
+Intercept Error(s):
+
+```python
+from django.core.exceptions import ValidationError
+
+from djangocms_Xxx.models import AbstractXxx
+
+from taccsite_cms.contrib.helpers import (
+    get_indices_that_start_with
+)
+
+class OurModelThatUsesXxx(AbstractXxx):
+    # Validate
+    def clean(self):
+        # Bypass irrelevant parent validation
+        try:
+            super().clean()
+        except ValidationError as err:
+            # Intercept single-field errors
+            if hasattr(err, 'error_list'):
+                for i in range(len(err.error_list)):
+                  # SEE: "Find Error(s)"
+                  # ...
+                    # Skip error
+                    del err.error_list[i]
+                    # Replace error
+                    # SEE: https://docs.djangoproject.com/en/2.2/ref/forms/validation/#raising-validationerror
+
+            # Intercept multi-field errors
+            if hasattr(err, 'error_dict'):
+                for field, errors in err.message_dict.items():
+                    # SEE: "Find Error(s)"
+                    # ...
+                        # Skip error
+                        del err.error_dict[field]
+                        # Replace error
+                        # SEE: https://docs.djangoproject.com/en/2.2/ref/forms/validation/#raising-validationerror
+
+            # NOTE: The conditional `pass` is only to skip multi-field errors;
+            #       single-field error skipping is unaffected by this logic;
+            #       so it seems safe to always include this logic block
+            if len(err.messages) == 0:
+                pass
+            else:
+                raise err
+```
+
+Handle Error(s):
+
+```python
+# SEE: "Find Error(s)"
+# ...
+
+                    # Catch known static error
+                    if 'Known static error string' in error:
+                        # ...
+
+                    # Catch known dynamic error
+                    indices_to_catch = get_indices_that_start_with(
+                        'Known dynamic error string that starts with same text',
+                        errors
+                    )
+                    for i in indices_to_catch:
+                        # ...
+```

taccsite_cms/contrib/_docs/taccsite_static_article.md

@@ -0,0 +1,66 @@
+# Static Article Plugins
+
+## Intention
+
+Support static addition of news articles that originate from a Core news site.
+
+A [dynamic solution that pulls form the Core news site](https://github.com/TACC/Core-CMS/issues/69) is preferable.
+
+But this is not available due to constrainst of architecture, time, or ability.
+
+## Architecture
+
+### (Currently) Add Image via Child Plugin Instead of Via Fields
+
+Instead, the image fields should be in the plugin, __not__ via a child plugin, but a solution has not yet been implemented.
+
+#### Hope for the Future
+
+The `AbstractLink` model was successfully extended.
+
+See:
+    - [./how-to-extend-django-cms-plugin.md](./how-to-extend-django-cms-plugin.md)
+    - [../taccsite_static_article_preview](../taccsite_static_article_preview)
+    - [../taccsite_static_article_list](../taccsite_static_article_list)
+
+#### Failed Attempt
+
+1. Build model so it extends `AbstractPicture` from `djangocms-picture`.
+2. Tweak model to sweep bugs under the rug.
+3. Quit when he was unable to resolve the error,
+    `TaccsiteStaticNewsArticlePreview has no field named 'cmsplugin_ptr_id'`
+    upon saving a plugin instance.
+4. Learn:
+    - [one should not try to reduce `AbstractPicture`](https://stackoverflow.com/a/3674714/11817077)
+    - [one should not subclass a subclass of `CMSPlugin`](https://github.com/django-cms/django-cms/blob/3.7.4/cms/models/pluginmodel.py#L104)
+
+#### Abandoned Code
+
+```python
+from djangocms_picture.models import AbstractPicture
+
+# To allow user to not set image
+# FAQ: Emptying the clean() method avoids picture validation
+# SEE: https://github.com/django-cms/djangocms-picture/blob/3.0.0/djangocms_picture/models.py#L278
+def skip_image_validation():
+    pass
+
+class TaccsiteStaticNewsArticlePreview(AbstractPicture):
+    #
+    # …
+    #
+
+    # Remove error-prone attribute from parent class
+    # FAQ: Avoid error when running `makemigrations`:
+    #      "You are trying to add a non-nullable field 'cmsplugin_ptr' […]"
+    # SEE: https://github.com/django-cms/djangocms-picture/blob/3.0.0/djangocms_picture/models.py#L212
+    # SEE: https://github.com/django-cms/djangocms-picture/blob/3.0.0/djangocms_picture/models.py#L234
+    cmsplugin_ptr = None
+
+    class Meta:
+        abstract = False
+
+    # Validate
+    def clean(self):
+        skip_image_validation()
+```

taccsite_cms/contrib/bootstrap4_djangocms_link/cms_plugins.py

@@ -1,4 +1,4 @@
-# Reregister unregistered LinkPlugin without uninstalling Bootstrap4's
+# Re-register unregistered LinkPlugin without uninstalling Bootstrap4's
 # FAQ: A Bootstrap link is undesirable but may be used by migrated legacy sites
 # TODO: Drop try/except & load non-standard plugin set for migrated legacy sites
 # FAQ: If we can import both plugins, then re-register LinkPlugin
@@ -18,7 +18,7 @@
 
     # SEE: https://github.com/django-cms/djangocms-link/issues/163
     plugin_pool.register_plugin(LinkPlugin)
-# CAVEAT: If import statement fails for reason other than Bootstrap presence,
+# CAVEAT: If import statement fails for reason other than Bootstrap absence,
 #         then that failure, and the failure of this plugin, is silent
 except ImportError:
     pass

taccsite_cms/contrib/bootstrap4_djangocms_picture/cms_plugins.py

@@ -1,5 +1,6 @@
-# Reregister unregistered PicturePlugin without uninstalling Bootstrap4's
+# Re-register unregistered PicturePlugin without uninstalling Bootstrap4's
 # FAQ: A Bootstrap picture has superfluous options that are not always desirable
+# TODO: Drop try/except & load non-standard plugin set for migrated legacy sites
 # FAQ: If we can import both plugins, then re-register PicturePlugin
 #      (because Bootstrap4Picture unregistered PicturePlugin)
 try: