mirror of
https://github.com/wrabit/django-cotton.git
synced 2025-08-04 15:18:20 +00:00
moved to code blocks, added single cvars statement
This commit is contained in:
Will Abbott
parent
4933154d99
commit
6d223e5d1f
6 changed files with 62 additions and 33 deletions
|
|
@ -19,7 +19,7 @@
|
|||
|
||||
<h2>1. The basic building block: {% verbatim %}{{ slot }}{% endverbatim %}</h2>
|
||||
|
||||
<p>The <c-highlight>{% verbatim %}{{ slot }}{% endverbatim %}</c-highlight> variable captures all content passed between a component's opening and closing tags.</p>
|
||||
<p>The <code>{% verbatim %}{{ slot }}{% endverbatim %}</code> variable captures all content passed between a component's opening and closing tags.</p>
|
||||
|
||||
<c-snippet label="cotton/box.html">{% cotton_verbatim %}{% verbatim %}
|
||||
<div class="box">
|
||||
|
|
@ -62,7 +62,7 @@
|
|||
|
||||
<h2 id="named-slots">3. Using Named Slots</h2>
|
||||
|
||||
<p>If we want to pass HTML instead of just a string (or another data type) into a component, we can pass them as <c-highlight>named slots</c-highlight> with the <c-highlight>{{ '<c-slot name="...">...</c-slot>'|force_escape }}</c-highlight> syntax.</p>
|
||||
<p>If we want to pass HTML instead of just a string (or another data type) into a component, we can pass them as <c-highlight>named slots</c-highlight> with the <code>{{ '<c-slot name="...">...</c-slot>'|force_escape }}</code> syntax.</p>
|
||||
|
||||
<p>So as with normal attributes, you reference the slot content like normal variables, as in:</p>
|
||||
|
||||
|
|
@ -204,18 +204,17 @@ context = { 'today': Weather.objects.get(...) }
|
|||
{% endcotton_verbatim %}{% endverbatim %}
|
||||
</c-snippet>
|
||||
|
||||
|
||||
<c-hr />
|
||||
|
||||
<h2 id="vars">6. <c-highlight>{{ '<c-vars />'|force_escape }}</c-highlight>: Defining Local Variables</h2>
|
||||
<h2 id="vars">6. Defining Local Variables with <code>{{ '<c-vars />'|force_escape }}</code></h2>
|
||||
|
||||
<p>{{ '<c-vars />'|force_escape }} gives components local state and default behavior, making them more self-sufficient and reducing the need for repetitive attribute declarations and maintaining UI state in the backend.</p>
|
||||
<p>The <code>{{ '<c-vars />'|force_escape }}</code> tag simplifies component design by allowing local variable definition, reducing the need for repetitive attribute declarations and maintaining backend state.</p>
|
||||
|
||||
<p>Vars are defined using a <c-highlight>{{ '<c-vars />'|force_escape }}</c-highlight> tag at the top of a component file. It can either contain key="value" pairs or just standalone keys (keep reading to understand why).</p>
|
||||
<p>Place a single <code>{{ '<c-vars />'|force_escape }}</code> at the top of a component to set key-value pairs that provide a default configuration.</p>
|
||||
|
||||
<h3 id="default-attributes">Use {{ '<c-vars />'|force_escape }} to set attribute defaults</h3>
|
||||
<h3 id="default-attributes">Example: Setting Default Attributes</h3>
|
||||
|
||||
<p>You may design a component that will often have a default behaviour and rarely needs overriding. In this case, you may opt to give a default value to your component.</p>
|
||||
<p>In components with common defaults, <code>{{ '<c-vars />'|force_escape }}</code> can pre-define attributes that rarely need overriding.</p>
|
||||
|
||||
<c-snippet label="cotton/alert.html">{% cotton_verbatim %}{% verbatim %}
|
||||
<c-vars type="success" />
|
||||
|
|
@ -236,9 +235,9 @@ context = { 'today': Weather.objects.get(...) }
|
|||
</c-slot>
|
||||
</c-snippet>
|
||||
|
||||
<h3 id="excluded">{{ '<c-vars />'|force_escape }} are excluded from {% verbatim %}{{ attrs }}{% endverbatim %}</h3>
|
||||
<h3 id="excluded"><code>{{ '<c-vars />'|force_escape }}</code> are excluded from <code>{% verbatim %}{{ attrs }}{% endverbatim %}</code></h3>
|
||||
|
||||
<p>Keys defined in {{ '<c-vars />'|force_escape }} will not be included in {% verbatim %}{{ attrs }}{% endverbatim %}. This is useful when some of the properties you pass down to a component are for configuration purposes only and not intended as attributes.</p>
|
||||
<p>Keys in {{ '<c-vars />'|force_escape }} are omitted from {{ attrs }}, making them ideal for configuration attributes that shouldn't appear in HTML attributes.</p>
|
||||
|
||||
<c-snippet label="cotton/input_group.html">{% cotton_verbatim %}{% verbatim %}
|
||||
<c-vars label errors />
|
||||
|
|
@ -272,8 +271,7 @@ context = { 'today': Weather.objects.get(...) }
|
|||
</c-slot>
|
||||
</c-snippet>
|
||||
|
||||
<c-note>Specifying an attribute as a 'var' will remove the item from {% verbatim %}{{ attrs }}{% endverbatim %}. It can also be a single key without a default value, this is when you know a particular attribute should not end up in {% verbatim %}{{ attrs }}{% endverbatim %}, whether it's defined in a parent or not.</c-note>
|
||||
|
||||
<p>By specifying <code>label</code> and <code>errors</code> keys in <code>{{ '<c-vars />'|force_escape }}</code>, these attributes won’t be included in <code>{% verbatim %}{{ attrs }}{% endverbatim %}</code>, allowing you to control attributes that are designed for component configuration and those intended as attributes.</p>
|
||||
|
||||
<c-hr />
|
||||
|
||||
|
|
@ -294,7 +292,7 @@ context = { 'today': Weather.objects.get(...) }
|
|||
<c-input name="telephone" required />
|
||||
{% endcotton_verbatim %}{% endverbatim %}
|
||||
<c-slot name="preview">
|
||||
<input type="text" autocomplete="off" class="border px-2 py-1 shadow rounded" name="telephone" placeholder="Telephone" /> <span class="text-red-500 text-3xl">*</span>
|
||||
<input type="text" autocomplete="off" class="border px-2 py-1 shadow rounded" name="telephone" placeholder="Telephone" /> <span class="text-red-500 text-2xl">*</span>
|
||||
</c-slot>
|
||||
</c-snippet>
|
||||
|
||||
|
|
@ -302,7 +300,7 @@ context = { 'today': Weather.objects.get(...) }
|
|||
|
||||
<h2 id="dynamic-components">8. Dynamic Components</h2>
|
||||
|
||||
<p>There can be times where components need to be included dynamically. For these cases we can reach for a special <c-highlight>{{ '<c-component>'|force_escape }}</c-highlight> tag with an <c-highlight>is</c-highlight> attribute:</p>
|
||||
<p>There can be times where components need to be included dynamically. For these cases we can reach for a special <code>{{ '<c-component>'|force_escape }}</code> tag with an <code>is</code> attribute:</p>
|
||||
|
||||
<c-snippet label="cotton/icon_list.html">{% cotton_verbatim %}{% verbatim %}
|
||||
{% for icon in icons %}
|
||||
|
|
@ -310,7 +308,7 @@ context = { 'today': Weather.objects.get(...) }
|
|||
{% endfor %}
|
||||
{% endcotton_verbatim %}{% endverbatim %}</c-snippet>
|
||||
|
||||
<p>The <c-highlight>is</c-highlight> attribute is similar to other attributes so we have a number of possibilities to define it:</p>
|
||||
<p>The <code>is</code> attribute is similar to other attributes so we have a number of possibilities to define it:</p>
|
||||
|
||||
<c-snippet label="cotton/icon_list.html">{% cotton_verbatim %}{% verbatim %}
|
||||
<!-- as variable -->
|
||||
|
|
@ -322,22 +320,23 @@ context = { 'today': Weather.objects.get(...) }
|
|||
|
||||
<c-hr />
|
||||
|
||||
<h2 id="context-isolation">9. Extras</h2>
|
||||
<h2 id="context-isolation">9. Context Isolation with `only`</h2>
|
||||
|
||||
<p>Similar to Django's <c-highlight>{% verbatim %}{% include %}{% endverbatim %}</c-highlight> tag you can add an "<c-highlight>only</c-highlight>" attribute which will prevent the component from inheriting the parent's context.</p>
|
||||
<p>Similar to Django's <code>{% verbatim %}{% include %}{% endverbatim %}</code> tag you can add an "<code>only</code>" attribute which will prevent the component from inheriting the parent's context.</p>
|
||||
|
||||
<c-hr />
|
||||
|
||||
<h2 id="summary">Summary of Concepts</h2>
|
||||
<ul>
|
||||
<li><c-highlight>{% verbatim %}{{ slot }}{% endverbatim %}</c-highlight> - Default content injection.</li>
|
||||
<li><code>{% verbatim %}{{ slot }}{% endverbatim %}</code> - Default content injection.</li>
|
||||
<li><c-highlight>Attributes</c-highlight> - Simple, straightforward customization.</li>
|
||||
<li><c-highlight>Named Slots</c-highlight> - Provide HTML or template partial as a variable in the component.</li>
|
||||
<li><c-highlight>`:` Dynamic Attributes</c-highlight> - Pass variables and other data types other than strings.</li>
|
||||
<li><c-highlight>{% verbatim %}{{ attrs }}{% endverbatim %}</c-highlight> - Prints attributes as HTML attributes.</li>
|
||||
<li><c-highlight>{{ '<c-vars />'|force_escape }}</c-highlight> - Set default values and other component state.</li>
|
||||
<li><c-highlight>Boolean attributes</c-highlight> - Attributes without values are passed down as `:bool = True`</li>
|
||||
<li><c-highlight>{{ '<c-component is=".." />'|force_escape }}</c-highlight> - Dynamically insert a component where the name is generated by a variable or template expression</li>
|
||||
<li><c-highlight><code>:</code> Dynamic Attributes</c-highlight> - Pass variables and other data types other than strings.</li>
|
||||
<li><code>{% verbatim %}{{ attrs }}{% endverbatim %}</code> - Prints attributes as HTML attributes.</li>
|
||||
<li><code>{{ '<c-vars />'|force_escape }}</code> - Set default values and other component state.</li>
|
||||
<li><c-highlight>Boolean attributes</c-highlight> - Attributes without values are passed down as <code>True</code></li>
|
||||
<li><c-highlight>Dynamic Components</c-highlight> - Insert a component where the name is generated by a variable or template expression: <code>{{ '<c-component :is="my_variable" />'|force_escape }}</code>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1 +1 @@
|
|||
<li class="py-0.5 pl-1 ml-5 list-disc marker:text-teal-600 text-[15px] text-[#1a384a] dark:text-gray-400">{{ slot }}</li>
|
||||
<li class="py-0.5 pl-1 ml-5 list-disc marker:text-teal-600 text-[#1a384a] dark:text-gray-400">{{ slot }}</li>
|
||||
|
|
@ -4,15 +4,45 @@
|
|||
<c-sidebar />
|
||||
</div>
|
||||
<div class="overflow-auto flex-1 pb-10">
|
||||
<div class="max-w-[760px] mx-auto px-0 pt-3 md:pt-0 md:px-5 py-0 prose !text-[16.5px] prose-a:text-teal-600 prose-h2:text-3xl prose-h3:text-2xl prose-headings:text-[#1a384a] text-[#1a384a] dark:text-white dark:text-opacity-70 prose-headings:font-semibold dark:prose-headings:text-white">
|
||||
<div class="
|
||||
max-w-[760px]
|
||||
mx-auto
|
||||
px-0
|
||||
pt-3
|
||||
md:pt-0
|
||||
md:px-5
|
||||
py-0
|
||||
!text-[16.5px]
|
||||
text-[#1a384a]
|
||||
|
||||
prose
|
||||
prose-a:text-teal-600
|
||||
prose-h2:text-3xl
|
||||
prose-h3:text-2xl
|
||||
prose-headings:text-[#1a384a]
|
||||
prose-headings:font-semibold
|
||||
prose-code:before:content-none
|
||||
prose-code:after:content-none
|
||||
prose-code:bg-yellow-900/10
|
||||
prose-code:rounded
|
||||
prose-code:px-1
|
||||
prose-code:inline-block
|
||||
prose-code:my-0
|
||||
|
||||
dark:text-white
|
||||
dark:text-opacity-70
|
||||
dark:prose-headings:text-white
|
||||
dark:prose-code:bg-gray-800
|
||||
dark:prose-code:text-gray-300/80
|
||||
">
|
||||
{{ slot }}
|
||||
</div>
|
||||
</div>
|
||||
<div class="relative h-full pl-10 border-opacity-10 hidden lg:block">
|
||||
<div class="relative h-full pl-10 border-opacity-10 hidden lg:block text-[15px]">
|
||||
{% if page_index %}
|
||||
<div class="sticky top-[68px] pt-0 pb-10">
|
||||
<c-sidebar-heading>On this page</c-sidebar-heading>
|
||||
<ul class="ml-0 pl-0 mt-4">
|
||||
<ul class="ml-0 pl-0 mt-4 ">
|
||||
{{ page_index }}
|
||||
</ul>
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -64,9 +64,9 @@
|
|||
localStorage.theme = this.dark ? 'dark' : 'light'
|
||||
}
|
||||
}">
|
||||
<c-icons.sun class="size-8 text-yellow-900 opacity-60 dark:text-gray-100" stroke-width="1.5" />
|
||||
<c-icons.sun class="size-8 text-yellow-900/40 dark:text-gray-100" stroke-width="1.5" />
|
||||
</a>
|
||||
<a href="https://github.com/wrabit/django-cotton" target="_blank" class="text-yellow-900 opacity-60 dark:text-gray-100 flex items-center space-x-2">
|
||||
<a href="https://github.com/wrabit/django-cotton" target="_blank" class="text-yellow-900/40 dark:text-gray-100 flex items-center space-x-2">
|
||||
<c-icons.github class="size-7" />
|
||||
</a>
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -41,7 +41,7 @@
|
|||
|
||||
<h2 id="type">Change the input type</h2>
|
||||
|
||||
<p>You will probably need more than just a text input in your project. So let's declare an attribute `text` in <c-highlight>{{ '<c-vars />'|force_escape }}</c-highlight>. Adding it as a var will allow us to set "text" as the default. Additionally, it will be excluded from <c-highlight>{% verbatim %}{{ attrs }}{% endverbatim %}</c-highlight>:</p>
|
||||
<p>You will probably need more than just a text input in your project. So let's declare an attribute `text` in <code>{{ '<c-vars />'|force_escape }}</code>. Adding it as a var will allow us to set "text" as the default. Additionally, it will be excluded from <code>{% verbatim %}{{ attrs }}{% endverbatim %}</code>:</p>
|
||||
|
||||
<c-snippet label="cotton/input.html">{% cotton_verbatim %}{% verbatim %}
|
||||
<c-vars type="text" />
|
||||
|
|
|
|||
|
|
@ -118,19 +118,19 @@ def dashboard_view(request):
|
|||
<p>Cotton uses the following naming conventions:</p>
|
||||
<c-ul>
|
||||
<li>Component file names are in snake_case: <c-highlight>my_component.html</c-highlight></li>
|
||||
<li>but are called using kebab-case: <c-highlight>{{ "<c-my-component />"|force_escape }}</c-highlight></li>
|
||||
<li>but are called 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 <c-highlight>{{ "<c-sidebar.menu.link />"|force_escape }}</c-highlight></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 <c-highlight>{{ "<c-my-component />"|force_escape }}</c-highlight> or have a closing tag <c-highlight>{{ "<c-my-component></c-my-component>"|force_escape }}</c-highlight></li>
|
||||
<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>
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue