mirrors/django-cotton
1
0
Fork 0
mirror of https://github.com/wrabit/django-cotton.git synced 2025-08-04 15:18:20 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

added docs for index.html pattern

Browse source
This commit is contained in:
Will Abbott 2025-03-02 13:28:37 +00:00
parent 44c8360b3e
commit 3274cfb28a
7 changed files with 88 additions and 39 deletions
Download patch file Download diff file Expand all files Collapse all files

2
docs/docs_project/docs_project/templates/components.html
View file

@ -365,7 +365,7 @@ context = { 'today': Weather.objects.get(...) }
<a href="{% url 'quickstart' %}">Quickstart</a>
</c-slot>
<c-slot name="next">
<a href="{% url 'layouts' %}">Layouts</a>
<a href="{% url 'usage-patterns' %}">Usage Patterns</a>
</c-slot>
</c-navigation>

3
docs/docs_project/docs_project/templates/cotton/sidebar.html
View file

@ -8,6 +8,9 @@
<c-sidebar-link url="{% url 'components' %}">
Components
</c-sidebar-link>
<c-sidebar-link url="{% url 'usage-patterns' %}">
Usage Patterns
</c-sidebar-link>
</ul>
</c-sidebar-block>
<c-sidebar-block>

2
docs/docs_project/docs_project/templates/form_fields.html
View file

@ -140,7 +140,7 @@
<c-navigation>
<c-slot name="prev">
<a href="{% url 'components' %}">Components</a>
<a href="{% url 'usage-patterns' %}">Usage Patterns</a>
</c-slot>
<c-slot name="next">
<a href="{% url 'alpine-js' %}">Tabs with Alpine.js</a>

34
docs/docs_project/docs_project/templates/quickstart.html
View file

@ -4,11 +4,6 @@
<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>
<c-index-sublink><a href="#naming" class="no-underline">Naming</a></c-index-sublink>
<c-index-sublink><a href="#subfolders" class="no-underline">Subfolders</a></c-index-sublink>
<c-index-sublink><a href="#tag-style" class="no-underline">Tag Style</a></c-index-sublink>
</c-slot>
<h1 id="install">Quickstart</h1>
@ -121,35 +116,6 @@ def dashboard_view(request):
</c-slot>
</c-snippet>
<c-hr />
<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 ('cotton' path is <a href="{% url 'configuration' %}">configurable</a> using <code>COTTON_DIR</code>).</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>
<p>Cotton uses the following naming conventions:</p>
<c-ul>
<li>Component file names by default are in snake_case: <c-highlight>my_component.html</c-highlight> (kebab-case filenames can be enabled, see <a href="{% url 'configuration' %}">configuration</a>)</li>
<li>and are included using kebab-case: <code>{{ "<c-my-component />"|force_escape }}</code></li>
</c-ul>
<h3 id="subfolders">Subfolders</h3>
<c-ul>
<li>Components in subfolders can be defined using dot notation</li>
<li>A component in <c-highlight>sidebar/menu/link.html</c-highlight> would be included as <code>{{ "<c-sidebar.menu.link />"|force_escape }}</code></li>
</c-ul>
<h3 id="tag-style">Tag Style</h3>
<c-ul>
<li>Components can either be self-closing <code>{{ "<c-my-component />"|force_escape }}</code> or have a closing tag <code>{{ "<c-my-component></c-my-component>"|force_escape }}</code></li>
</c-ul>
<c-navigation>
<c-slot name="prev">
<a href="{% url 'home' %}">Home</a>

79
docs/docs_project/docs_project/templates/usage_patterns.html Normal file
View file

@ -0,0 +1,79 @@
<c-layouts.with-sidebar>
<h1 id="components">Usage Patterns</h1>
<c-slot name="page_index">
<c-index-link><a href="#components" class="no-underline">Components</a></c-index-link>
<c-index-sublink><a href="#basics" class="no-underline text-opacity-70">Basics</a></c-index-sublink>
<c-index-sublink><a href="#naming" class="no-underline">Naming</a></c-index-sublink>
<c-index-sublink><a href="#subfolders" class="no-underline">Subfolders</a></c-index-sublink>
<c-index-sublink><a href="#index" class="no-underline">index.html</a></c-index-sublink>
<c-index-sublink><a href="#tag-style" class="no-underline">Tag Style</a></c-index-sublink>
</c-slot>
<h3 id="basics">Basics</h3>
<c-ul>
<li>Cotton components should be placed in the <c-highlight>templates/cotton</c-highlight> folder ('cotton' path is <a href="{% url 'configuration' %}">configurable</a> using <code>COTTON_DIR</code>).</li>
<li>The <code>templates</code> folder can be located in either an app-level or top-level project root folder.</li>
</c-ul>
<c-hr />
<h3 id="naming">Naming</h3>
<p>Cotton uses the following naming conventions:</p>
<c-ul>
<li>By default, component file names are in snake_case (<c-highlight>my_component.html</c-highlight>).
<li>kebab-case filenames (<c-highlight>my-component.html</c-highlight>) can be enabled with <code>COTTON_SNAKE_CASED_NAMES = False</code> see <a href="{% url 'configuration' %}">configuration</a>.</li>
<li>Components are included in templates using kebab-case name of the component: <code>{{ "<c-my-component />"|force_escape }}</code></li>
</c-ul>
<c-hr />
<h3 id="subfolders">Subfolders</h3>
<c-ul>
<li>Components in subfolders can be called using dot notation to represent folder levels.</li>
<li>A component in <c-highlight>sidebar/menu/link.html</c-highlight> would be included with <code>{{ "<c-sidebar.menu.link />"|force_escape }}</code></li>
</c-ul>
<c-hr />
<h3 id="index">The index.html component</h3>
<p>When your component has sub-components, you can define the default component of a folder by adding an <code>index.html</code>. This helps to keep your project structure tidy and reduce additional code in the template.</p>
<c-snippet label="Project structure">
{% cotton_verbatim %}{% verbatim %}
templates/
├── cotton/
│ ├── card/
│ │ ├── index.html
│ │ ├── header.html
{% endverbatim %}{% endcotton_verbatim %}
</c-snippet>
<c-snippet label="Usage">
{% cotton_verbatim %}{% verbatim %}
<c-card>
<c-card.header>...</c-card.header>
</c-card>
{% endverbatim %}{% endcotton_verbatim %}
</c-snippet>
<c-hr />
<h3 id="tag-style">Tag Style</h3>
<c-ul>
<li>Components can either be self-closing <code>{{ "<c-my-component />"|force_escape }}</code> or have a closing tag <code>{{ "<c-my-component></c-my-component>"|force_escape }}</code></li>
</c-ul>
<c-navigation>
<c-slot name="prev">
<a href="{% url 'components' %}">Components</a>
</c-slot>
<c-slot name="next">
<a href="{% url 'form-fields' %}">Form Inputs</a>
</c-slot>
</c-navigation>
</c-layouts.with-sidebar>

5
docs/docs_project/docs_project/urls.py
View file

@ -10,8 +10,9 @@ urlpatterns = [
name="home",
),
path("docs/quickstart", views.build_view("quickstart"), name="quickstart"),
path("docs/installation", views.build_view("installation"), name="installation"),
path("docs/usage", views.build_view("usage"), name="usage"),
path(
"docs/usage-patterns", views.build_view("usage_patterns"), name="usage-patterns"
),
# Features
path("docs/components", views.build_view("components"), name="components"),
path("docs/slots", views.build_view("slots"), name="slots"),