improve related documents (#6939)

Author: escattone

kitsune/sumo/static/sumo/js/wiki_search.js

@@ -7,7 +7,7 @@ import nunjucksEnv from "sumo/js/nunjucks"; // has to be loaded after templates
 
 document.addEventListener("DOMContentLoaded", function() {
   const locale = document.documentElement.lang;
-  const search = new Search(`/${locale}/search`, { w: 1, format: 'json' });
+  const search = new Search("/api/1/kb/", { locales: `en-US,${locale}`, categories: "10,20,30,40,50" });
 
   const relatedDocsList = document.getElementById('related-docs-list');
   const searchInput = document.getElementById('search-related');
@@ -34,6 +34,9 @@ document.addEventListener("DOMContentLoaded", function() {
     closeAfterSelect: true,
     maxItems: null, // Allow multiple selections
     plugins: {
+      clear_button: {
+        title: "Clear All",
+      },
       remove_button: {
         title: 'Remove this document'
       }
@@ -48,24 +51,9 @@ document.addEventListener("DOMContentLoaded", function() {
           return callback();
         }
 
-        const formattedResults = data.results
-          .filter(result => result.type === 'document')
-          .map(item => {
-            let id = item.id;
-            if (!id && item.url) {
-              const match = item.url.match(/\/(\d+)\//);
-              if (match) {
-                id = match[1];
-              }
-            }
-            return {
-              id: id,
-              title: item.title,
-              url: item.url
-            };
-          })
-          .filter(item => item.id)
-          .filter(item => !currentDocId || String(item.id) !== String(currentDocId));
+        const formattedResults = data.results.filter(
+          item => !currentDocId || String(item.id) !== String(currentDocId)
+        );
 
         callback(formattedResults);
       });
@@ -110,13 +98,13 @@ document.addEventListener("DOMContentLoaded", function() {
     if (emptyMessage) {
       emptyMessage.remove();
     }
-    
+
     preSelectedOptions.forEach(option => {
       const docData = {
         id: option.value,
         title: option.textContent
       };
-      
+
       // Add the option to TomSelect's options and selected items
       tomSelect.addOption(docData);
       tomSelect.addItem(option.value, true); // true = silent, don't trigger events

kitsune/sumo/static/sumo/scss/components/_wiki.scss

@@ -1317,4 +1317,24 @@ article {
   >h1:before {
     transform: rotate(0);
   }
-}
+}
+
+// Styling for the tom-select clear_button plugin.
+.ts-wrapper.multi.plugin-clear_button .ts-control > .clear-button {
+  opacity: 100%;
+  width: 1rem;
+  height: 1rem;
+  font-size: 1rem;
+  display: inline-flex;
+  justify-content: center;
+  align-items: center;
+  padding-bottom: 8px;
+  text-shadow: 0 1px 0 rgba(0, 51, 83, 30%);
+  border-radius: 3px;
+  background-image: linear-gradient(to bottom, #1da7ee, #178ee9) !important;
+  box-shadow: 0 1px 0 rgba(0, 0, 0, 20%),inset 0 1px rgba(255, 255, 255, 3%);
+
+  &:hover {
+    background-image: linear-gradient(to bottom, #008fd8, #0075cf) !important;
+  }
+}

kitsune/wiki/api.py

@@ -13,7 +13,7 @@
 class DocumentShortSerializer(serializers.ModelSerializer):
     class Meta:
         model = Document
-        fields = ("title", "slug")
+        fields = ("id", "title", "slug")
 
 
 class DocumentDetailSerializer(DocumentShortSerializer):
@@ -37,19 +37,31 @@ class DocumentList(LocaleNegotiationMixin, generics.ListAPIView):
     serializer_class = DocumentShortSerializer
 
     def get_queryset(self):
-        queryset = Document.objects.visible(
-            self.request.user, category__in=settings.IA_DEFAULT_CATEGORIES
-        )
+        locales = self.request.query_params.get("locales")
+        if locales:
+            # Multiple locales are separated by commas.
+            locales = locales.replace(",", " ").split()
+        elif locale := normalize_language(self.get_locale()):
+            locales = [locale]
+
+        categories = self.request.query_params.get("categories")
+        if categories:
+            # Multiple categories are separated by commas.
+            categories = categories.replace(",", " ").split()
+        else:
+            categories = settings.IA_DEFAULT_CATEGORIES
 
-        locale = normalize_language(self.get_locale())
         product = self.request.query_params.get("product")
         topic = self.request.query_params.get("topic")
         is_template = bool(self.request.query_params.get("is_template", False))
         is_archived = bool(self.request.query_params.get("is_archived", False))
         is_redirect = bool(self.request.query_params.get("is_redirect", False))
+        title_query = self.request.query_params.get("q")
 
-        if locale is not None:
-            queryset = queryset.filter(locale=locale)
+        queryset = Document.objects.visible(self.request.user, category__in=categories)
+
+        if locales:
+            queryset = queryset.filter(locale__in=locales)
 
         if product is not None:
             if locale == settings.WIKI_DEFAULT_LANGUAGE:
@@ -76,6 +88,9 @@ def get_queryset(self):
         else:
             queryset = queryset.filter(~redirect_filter)
 
+        if title_query:
+            queryset = queryset.filter(title__icontains=title_query)
+
         return queryset
 
 

kitsune/wiki/forms.py

@@ -3,13 +3,19 @@
 from django import forms
 from django.conf import settings
 from django.contrib.auth.models import Group
+from django.db.models.functions import Coalesce
 from django.template.defaultfilters import slugify
 from django.utils.translation import gettext_lazy as _lazy
 from django.utils.translation import ngettext_lazy as _nlazy
 
 from kitsune.products.models import Product, Topic
 from kitsune.sumo.form_fields import MultiUsernameField, MultiUsernameFilterField
-from kitsune.wiki.config import CATEGORIES, SIGNIFICANCES
+from kitsune.wiki.config import (
+    CANNED_RESPONSES_CATEGORY,
+    CATEGORIES,
+    SIGNIFICANCES,
+    TEMPLATES_CATEGORY,
+)
 from kitsune.wiki.content_managers import ManualContentManager
 from kitsune.wiki.models import MAX_REVISION_COMMENT_LENGTH, Document, DraftRevision, Revision
 from kitsune.wiki.tasks import add_short_links
@@ -63,6 +69,9 @@
 )
 PRODUCT_REQUIRED = _lazy("Please select at least one product.")
 TOPIC_REQUIRED = _lazy("Please select at least one topic.")
+RELATED_DOCUMENTS_DISALLOWED = _lazy(
+    "Related documents are not allowed for Templates and Canned Responses."
+)
 
 
 class DocumentForm(forms.ModelForm):
@@ -135,8 +144,11 @@ class DocumentForm(forms.ModelForm):
         widget=ProductsWidget(),
     )
 
-    related_documents = forms.MultipleChoiceField(
-        label=_lazy("Related documents:"), required=False, widget=RelatedDocumentsWidget()
+    related_documents = forms.ModelMultipleChoiceField(
+        required=False,
+        queryset=Document.objects.none(),
+        label=_lazy("Related documents:"),
+        widget=RelatedDocumentsWidget(),
     )
 
     locale = forms.CharField(widget=forms.HiddenInput())
@@ -154,10 +166,28 @@ def clean_slug(self):
             raise forms.ValidationError(SLUG_INVALID)
         return slug
 
+    def clean_related_documents(self):
+        """Replace any children with their parent documents."""
+        related_docs = self.cleaned_data.get("related_documents", Document.objects.none())
+
+        # In the form, we'll show the translations of the related documents if they exist
+        # (see kitsune.wiki.views.get_visible_related_documents), but we always store
+        # related documents as parents.
+        return Document.objects.filter(
+            id__in=related_docs.annotate(
+                root_id=Coalesce("parent_id", "id"),
+            ).values_list("root_id", flat=True)
+        ).distinct()
+
     def clean(self):
         cdata = super().clean()
         locale = cdata.get("locale")
 
+        if cdata.get("related_documents") and (
+            int(cdata.get("category", 0)) in (TEMPLATES_CATEGORY, CANNED_RESPONSES_CATEGORY)
+        ):
+            raise forms.ValidationError(RELATED_DOCUMENTS_DISALLOWED)
+
         # Products are required for en-US
         product_ids = set(map(int, cdata.get("products", [])))
         if locale == settings.WIKI_DEFAULT_LANGUAGE and (not product_ids or len(product_ids) < 1):
@@ -229,6 +259,7 @@ def __init__(self, *args, **kwargs):
         can_archive = kwargs.pop("can_archive", False)
         can_edit_needs_change = kwargs.pop("can_edit_needs_change", False)
         initial_title = kwargs.pop("initial_title", "")
+        locale = kwargs.pop("locale", None)
 
         super().__init__(*args, **kwargs)
 
@@ -244,8 +275,13 @@ def __init__(self, *args, **kwargs):
         products_field = self.fields["products"]
         products_field.choices = Product.active.values_list("id", "title")
 
+        # Set up the queryset for the related documents field.
         related_documents_field = self.fields["related_documents"]
-        related_documents_field.choices = Document.objects.values_list("id", "title")
+        queryset = Document.objects.filter(is_template=False)
+        locales = [settings.WIKI_DEFAULT_LANGUAGE]
+        if locale and (locale != settings.WIKI_DEFAULT_LANGUAGE):
+            locales.append(locale)
+        related_documents_field.queryset = queryset.filter(locale__in=locales)
 
         # If user hasn't permission to frob is_archived, remove the field. This
         # causes save() to skip it as well.

kitsune/wiki/jinja2/wiki/document.html

@@ -124,7 +124,7 @@
     </section>
 
     {% if not document.is_switching_devices_document %}
-      {{ related_documents(document) }}
+      {{ related_documents(related_docs) }}
     {% endif %}
 
   </section>

kitsune/wiki/jinja2/wiki/edit_metadata.html

@@ -47,6 +47,7 @@ <h1 class="sumo-page-heading">{{ _('<em>Editing Metadata For:</em><br>{title}')|
             {% endif %}
               {% for field in document_form.visible_fields() if
                 (field.name != 'restrict_to_groups') and (field.name != 'is_localizable' or not document.translations.exists()) %}
+                {% if (field.name != 'related_documents') or document.allows_related_documents %}
                 <div class="field has-large-textarea">
                   {{ field|label_with_help }}
                   {% if field.name in ['products', 'topics'] %}
@@ -57,6 +58,7 @@ <h1 class="sumo-page-heading">{{ _('<em>Editing Metadata For:</em><br>{title}')|
                   {% endif %}
                   {{ field }}
                 </div>
+                {% endif %}
               {% endfor %}
             {% if document.translations.exists() %}
               {{ document_form.is_localizable.as_hidden()|safe }}

kitsune/wiki/jinja2/wiki/includes/document_macros.html

@@ -418,35 +418,32 @@ <h4 class="document-vote--heading">{{ header }}</h4>
   {% endif %}
 {%- endmacro %}
 
-{% macro related_documents(document) %}
-  {% if document.related_documents.count() > 0 %}
-    {% set docs = document.related_documents.all() %}
+{% macro related_documents(related_docs) %}
+  {% if related_docs %}
     <section id="related-documents" class="sumo-page-section wiki-related-documents">
       <div class="text-center">
         <h2 class="sumo-page-subheading">{{ _('Related Articles') }}</h2>
       </div>
       <div class="sumo-card-grid">
         <div class="scroll-wrap">
-          {% for related in docs %}
-            {% if related.is_unrestricted_for(user) %}
-              <div class="card card--article">
-                  <img class="card--icon-sm" src="{{ webpack_static('protocol/img/icons/reader-mode.svg') }}" alt="todo: title" />
-                  <div class="card--details">
-                    <h3 class="card--title">
-                      <a class="expand-this-link" href="{{ url('wiki.document', related.slug) }}"
-                        data-event-name="link_click"
-                        data-event-parameters='{"link_name": "related.kb-article"}'>
-                        {{ related.title }}
-                      </a>
-                    </h3>
-                    <div class="card--desc">
-                      <p>
-                      {{ related.html|striptags|truncate(length=150) }}
-                      </p>
-                    </div>
+          {% for related in related_docs %}
+            <div class="card card--article">
+                <img class="card--icon-sm" src="{{ webpack_static('protocol/img/icons/reader-mode.svg') }}" alt="todo: title" />
+                <div class="card--details">
+                  <h3 class="card--title">
+                    <a class="expand-this-link" href="{{ url('wiki.document', related.slug) }}"
+                      data-event-name="link_click"
+                      data-event-parameters='{"link_name": "related.kb-article"}'>
+                      {{ related.title }}
+                    </a>
+                  </h3>
+                  <div class="card--desc">
+                    <p>
+                    {{ related.html|striptags|truncate(length=150) }}
+                    </p>
                   </div>
-              </div>
-            {% endif %}
+                </div>
+            </div>
           {% endfor %}
         </div>
       </div>

kitsune/wiki/jinja2/wiki/includes/related_docs_widget.html

@@ -1,12 +1,12 @@
 <select id="search-related" class="tom-select-related-docs" placeholder="{{ _('Search for documents...') }}">
-  {% if related_documents.count() %}
-    {% for doc in related_documents.all() %}
+  {% if related_documents %}
+    {% for doc in related_documents %}
       <option value="{{ doc.pk }}" selected>{{ doc.title }}</option>
     {% endfor %}
   {% endif %}
 </select>
 <div id="related-docs-list">
-  {% if not related_documents.count() %}
+  {% if not related_documents %}
     <div class="empty-message">{{ _('No related documents.') }}</div>
   {% endif %}
 </div>

kitsune/wiki/models.py

@@ -797,6 +797,10 @@ def is_linked_in_product(self):
             locale__in=("", self.locale), target__contains=f"kb/{self.slug}"
         ).exists()
 
+    @property
+    def allows_related_documents(self):
+        return self.category not in [TEMPLATES_CATEGORY, CANNED_RESPONSES_CATEGORY]
+
 
 class AbstractRevision(models.Model):
     # **%(class)s** is being used because it will allow  a unique reverse name for the field