Merge pull request #225 from wrabit/test_app_subdirectories

Allow `templates` in project root

Author: wrabit

dev/example_project/example_project/templates/cotton/button.html

@@ -0,0 +1 @@
+button!

dev/example_project/templates/cotton/app2/sub.html

@@ -0,0 +1 @@
+i'm sub in project root

dev/example_project/templates/cotton/project_root.html

@@ -0,0 +1 @@
+I'm from project roo templates!

django_cotton/cotton_loader.py

@@ -2,6 +2,7 @@
 import os
 from functools import lru_cache
 
+from django.conf import settings
 from django.template.loaders.base import Loader as BaseLoader
 from django.core.exceptions import SuspiciousFileOperation
 from django.template import TemplateDoesNotExist, Origin
@@ -50,14 +51,20 @@ def _get_template_string(self, template_name):
 
     @lru_cache(maxsize=None)
     def get_dirs(self):
-        """This works like the file loader with APP_DIRS = True."""
+        """Retrieves possible locations of cotton directory"""
         dirs = list(self.dirs or self.engine.dirs)
 
+        # Include any included installed app directories, e.g. project/app1/templates
         for app_config in apps.get_app_configs():
             template_dir = os.path.join(app_config.path, "templates")
             if os.path.isdir(template_dir):
                 dirs.append(template_dir)
 
+        # Check project root templates, e.g. project/templates
+        root_template_dir = os.path.join(settings.BASE_DIR, "templates")
+        if os.path.isdir(root_template_dir):
+            dirs.append(root_template_dir)
+
         return dirs
 
     def reset(self):

django_cotton/tests/test_basic.py

@@ -203,3 +203,21 @@ def test_hyphen_naming_convention(self):
         rendered = get_rendered(html)
 
         self.assertTrue("I have a hyphenated component name" in rendered)
+
+    def test_multiple_app_subdirectory_access(self):
+        self.create_template(
+            "cotton/app_dir.html",
+            "I'm from app templates!",
+        )
+
+        html = """
+            <c-app-dir />
+            <c-project-root />
+            <c-app2.sub />
+        """
+
+        rendered = get_rendered(html)
+
+        self.assertTrue("I'm from app templates!" in rendered)
+        self.assertTrue("I'm from project roo templates!" in rendered)
+        self.assertTrue("i'm sub in project root" in rendered)

docs/docs_project/docs_project/templates/quickstart.html

@@ -2,6 +2,7 @@
     <c-slot name="page_index">
         <c-index-link><a href="#install" class="no-underline">Install Cotton</a></c-index-link>
         <c-index-link><a href="#create-a-component" class="no-underline">Create a component</a></c-index-link>
+        <c-index-link><a href="#templates-location" class="no-underline">Templates location</a></c-index-link>
         <c-index-link><a href="#include-a-component" class="no-underline">Include a component</a></c-index-link>
         <c-index-link><a href="#usage" class="no-underline">Usage</a></c-index-link>
         <c-index-sublink><a href="#basics" class="no-underline text-opacity-70">Basics</a></c-index-sublink>
@@ -18,17 +19,17 @@ <h2>Install cotton</h2>
 
     <p>Then update your settings.py:</p>
 
-    <h3>Automatic configuration:</h3>
+    <h3>For automatic configuration:</h3>
 
     <c-snippet language="python" label="settings.py">{% cotton_verbatim %}{% verbatim %}
 INSTALLED_APPS = [
     'django_cotton',
 ]
     {% endverbatim %}{% endcotton_verbatim %}</c-snippet>
 
-    <p>This will automatically handle the settings.py adding the required loader and templatetags.</p>
+    <p>This will attempt to automatically handle the settings.py by adding the required loader and templatetags.</p>
 
-    <h3>Customised configuration</h3>
+    <h3>For custom configuration</h3>
 
     <p>If your project requires any non-default loaders or you do not wish Cotton to manage your settings, you should instead provide `django_cotton.apps.SimpleAppConfig` in your INSTALLED_APPS:</p>
 
@@ -72,6 +73,18 @@ <h2>{{ title }}</h2>
 </div>
     {% endverbatim %}{% endcotton_verbatim %}</c-snippet>
 
+    <c-hr id="templates-location" />
+
+    <h2>Templates location</h2>
+
+    <p>Cotton supports 2 common approaches regarding the location of the <code>templates</code> directory:</p>
+
+    <c-ul>
+        <li><strong>App level</strong> - You can place your cotton folder in any of your installed app folders, like: <div><code>[project]/[app]/templates/cotton/row.html</code></div></li>
+        <li><strong>Project root</strong> - You can place your cotton folder in a project level templates directory, like: <div><code>[project]/templates/cotton/row.html</code></div></li>
+    </c-ul>
+
+    <p>Any style will allow you to include your component the same way: <code>{{ '<c-row />'|force_escape }}</code></p>
 
     <c-hr id="include-a-component" />
 
@@ -111,7 +124,8 @@ <h2 id="usage">Usage</h2>
 
     <h3 id="basics">Basics</h3>
     <c-ul>
-        <li>Cotton components should be placed in the <c-highlight>templates/cotton</c-highlight> folder (unless you have set COTTON_DIR).</li>
+        <li>Cotton components should be placed in the <c-highlight>templates/cotton</c-highlight> folder ('cotton' directory is <a href="{% url 'configuration' %}">configurable</a> using COTTON_DIR).</li>
+        <li>The <code>templates</code> folder can be located in either an app-level or top-level project root folder.</li>
     </c-ul>
 
     <h3 id="naming">Naming</h3>