Hopiu/django-categories
1
0
Fork 0
mirror of https://github.com/jazzband/django-categories.git synced 2026-03-27 19:50:24 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
django-categories/user_guide/usage.html
PetrDlouhy c3b07a4851 deploy: 3db5f8ae40
2024-05-22 09:20:42 +00:00

609 lines
No EOL
26 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html lang="en" data-content_root="../" >
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Using categories in templates &#8212; Django Categories 2.0.0 documentation</title>
<script data-cfasync="false">
document.documentElement.dataset.mode = localStorage.getItem("mode") || "";
document.documentElement.dataset.theme = localStorage.getItem("theme") || "light";
</script>
<!-- Loaded before other Sphinx assets -->
<link href="../_static/styles/theme.css?digest=8d27b9dea8ad943066ae" rel="stylesheet" />
<link href="../_static/styles/bootstrap.css?digest=8d27b9dea8ad943066ae" rel="stylesheet" />
<link href="../_static/styles/pydata-sphinx-theme.css?digest=8d27b9dea8ad943066ae" rel="stylesheet" />
<link href="../_static/vendor/fontawesome/6.5.1/css/all.min.css?digest=8d27b9dea8ad943066ae" rel="stylesheet" />
<link rel="preload" as="font" type="font/woff2" crossorigin href="../_static/vendor/fontawesome/6.5.1/webfonts/fa-solid-900.woff2" />
<link rel="preload" as="font" type="font/woff2" crossorigin href="../_static/vendor/fontawesome/6.5.1/webfonts/fa-brands-400.woff2" />
<link rel="preload" as="font" type="font/woff2" crossorigin href="../_static/vendor/fontawesome/6.5.1/webfonts/fa-regular-400.woff2" />
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../_static/css/custom.css?v=ea07567a" />
<!-- Pre-loaded scripts that we'll load fully later -->
<link rel="preload" as="script" href="../_static/scripts/bootstrap.js?digest=8d27b9dea8ad943066ae" />
<link rel="preload" as="script" href="../_static/scripts/pydata-sphinx-theme.js?digest=8d27b9dea8ad943066ae" />
<script src="../_static/vendor/fontawesome/6.5.1/js/all.min.js?digest=8d27b9dea8ad943066ae"></script>
<script src="../_static/documentation_options.js?v=51b770b3"></script>
<script src="../_static/doctools.js?v=9a2dae69"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<script>DOCUMENTATION_OPTIONS.pagename = 'user_guide/usage';</script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Registering Models" href="registering_models.html" />
<link rel="prev" title="User Guide" href="index.html" />
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<meta name="docsearch:language" content="en"/>
</head>
<body data-bs-spy="scroll" data-bs-target=".bd-toc-nav" data-offset="180" data-bs-root-margin="0px 0px -60%" data-default-mode="">
<a id="pst-skip-link" class="skip-link" href="#main-content">Skip to main content</a>
<div id="pst-scroll-pixel-helper"></div>
<button type="button" class="btn rounded-pill" id="pst-back-to-top">
<i class="fa-solid fa-arrow-up"></i>
Back to top
</button>
<input type="checkbox"
class="sidebar-toggle"
name="__primary"
id="__primary"/>
<label class="overlay overlay-primary" for="__primary"></label>
<input type="checkbox"
class="sidebar-toggle"
name="__secondary"
id="__secondary"/>
<label class="overlay overlay-secondary" for="__secondary"></label>
<div class="search-button__wrapper">
<div class="search-button__overlay"></div>
<div class="search-button__search-container">
<form class="bd-search d-flex align-items-center"
action="../search.html"
method="get">
<i class="fa-solid fa-magnifying-glass"></i>
<input type="search"
class="form-control"
name="q"
id="search-input"
placeholder="Search the docs ..."
aria-label="Search the docs ..."
autocomplete="off"
autocorrect="off"
autocapitalize="off"
spellcheck="false"/>
<span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd>K</kbd></span>
</form></div>
</div>
<header class="bd-header navbar navbar-expand-lg bd-navbar">
<div class="bd-header__inner bd-page-width">
<label class="sidebar-toggle primary-toggle" for="__primary">
<span class="fa-solid fa-bars"></span>
</label>
<div class="col-lg-3 navbar-header-items__start">
<div class="navbar-item">
<a class="navbar-brand logo" href="../index.html">
<p class="title logo__title">Django Categories 2.0.0 documentation</p>
</a></div>
</div>
<div class="col-lg-9 navbar-header-items">
<div class="me-auto navbar-header-items__center">
<div class="navbar-item">
<nav class="navbar-nav">
<ul class="bd-navbar-elements navbar-nav">
<li class="nav-item">
<a class="nav-link nav-internal" href="../installation.html">
Installation
</a>
</li>
<li class="nav-item">
<a class="nav-link nav-internal" href="../getting_started.html">
Getting Started
</a>
</li>
<li class="nav-item current active">
<a class="nav-link nav-internal" href="index.html">
User Guide
</a>
</li>
<li class="nav-item">
<a class="nav-link nav-internal" href="../reference/index.html">
Reference
</a>
</li>
<li class="nav-item">
<a class="nav-link nav-internal" href="../api/index.html">
API
</a>
</li>
<li class="nav-item dropdown">
<button class="btn dropdown-toggle nav-item" type="button" data-bs-toggle="dropdown" aria-expanded="false" aria-controls="pst-nav-more-links">
More
</button>
<ul id="pst-nav-more-links" class="dropdown-menu">
<li class="nav-item">
<a class="nav-link dropdown-item nav-internal" href="../changelog.html">
Changelog
</a>
</li>
</ul>
</li>
</ul>
</nav></div>
</div>
<div class="navbar-header-items__end">
<div class="navbar-item navbar-persistent--container">
<script>
document.write(`
<button class="btn navbar-btn search-button-field search-button__button" title="Search" aria-label="Search" data-bs-placement="bottom" data-bs-toggle="tooltip">
<i class="fa-solid fa-magnifying-glass"></i>
<span class="search-button__default-text">Search</span>
<span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd class="kbd-shortcut__modifier">K</kbd></span>
</button>
`);
</script>
</div>
<div class="navbar-item">
<script>
document.write(`
<button class="btn btn-sm navbar-btn theme-switch-button" title="light/dark" aria-label="light/dark" data-bs-placement="bottom" data-bs-toggle="tooltip">
<span class="theme-switch nav-link" data-mode="light"><i class="fa-solid fa-sun fa-lg"></i></span>
<span class="theme-switch nav-link" data-mode="dark"><i class="fa-solid fa-moon fa-lg"></i></span>
<span class="theme-switch nav-link" data-mode="auto"><i class="fa-solid fa-circle-half-stroke fa-lg"></i></span>
</button>
`);
</script></div>
</div>
</div>
<div class="navbar-persistent--mobile">
<script>
document.write(`
<button class="btn navbar-btn search-button-field search-button__button" title="Search" aria-label="Search" data-bs-placement="bottom" data-bs-toggle="tooltip">
<i class="fa-solid fa-magnifying-glass"></i>
<span class="search-button__default-text">Search</span>
<span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd class="kbd-shortcut__modifier">K</kbd></span>
</button>
`);
</script>
</div>
<label class="sidebar-toggle secondary-toggle" for="__secondary" tabindex="0">
<span class="fa-solid fa-outdent"></span>
</label>
</div>
</header>
<div class="bd-container">
<div class="bd-container__inner bd-page-width">
<div class="bd-sidebar-primary bd-sidebar">
<div class="sidebar-header-items sidebar-primary__section">
<div class="sidebar-header-items__center">
<div class="navbar-item">
<nav class="navbar-nav">
<ul class="bd-navbar-elements navbar-nav">
<li class="nav-item">
<a class="nav-link nav-internal" href="../installation.html">
Installation
</a>
</li>
<li class="nav-item">
<a class="nav-link nav-internal" href="../getting_started.html">
Getting Started
</a>
</li>
<li class="nav-item current active">
<a class="nav-link nav-internal" href="index.html">
User Guide
</a>
</li>
<li class="nav-item">
<a class="nav-link nav-internal" href="../reference/index.html">
Reference
</a>
</li>
<li class="nav-item">
<a class="nav-link nav-internal" href="../api/index.html">
API
</a>
</li>
<li class="nav-item dropdown">
<button class="btn dropdown-toggle nav-item" type="button" data-bs-toggle="dropdown" aria-expanded="false" aria-controls="pst-nav-more-links-2">
More
</button>
<ul id="pst-nav-more-links-2" class="dropdown-menu">
<li class="nav-item">
<a class="nav-link dropdown-item nav-internal" href="../changelog.html">
Changelog
</a>
</li>
</ul>
</li>
</ul>
</nav></div>
</div>
<div class="sidebar-header-items__end">
<div class="navbar-item">
<script>
document.write(`
<button class="btn btn-sm navbar-btn theme-switch-button" title="light/dark" aria-label="light/dark" data-bs-placement="bottom" data-bs-toggle="tooltip">
<span class="theme-switch nav-link" data-mode="light"><i class="fa-solid fa-sun fa-lg"></i></span>
<span class="theme-switch nav-link" data-mode="dark"><i class="fa-solid fa-moon fa-lg"></i></span>
<span class="theme-switch nav-link" data-mode="auto"><i class="fa-solid fa-circle-half-stroke fa-lg"></i></span>
</button>
`);
</script></div>
</div>
</div>
<div class="sidebar-primary-items__start sidebar-primary__section">
<div class="sidebar-primary-item">
<nav class="bd-docs-nav bd-links"
aria-label="Section Navigation">
<p class="bd-links__title" role="heading" aria-level="1">Section Navigation</p>
<div class="bd-toc-item navbar-nav"><ul class="current nav bd-sidenav">
<li class="toctree-l1 current active"><a class="current reference internal" href="#">Using categories in templates</a></li>
<li class="toctree-l1"><a class="reference internal" href="registering_models.html">Registering Models</a></li>
<li class="toctree-l1"><a class="reference internal" href="adding_the_fields.html">Adding the fields to the database</a></li>
<li class="toctree-l1"><a class="reference internal" href="admin_settings.html">Adding the fields to the Admin</a></li>
<li class="toctree-l1"><a class="reference internal" href="custom_categories.html">Creating Custom Categories</a></li>
</ul>
</div>
</nav></div>
</div>
<div class="sidebar-primary-items__end sidebar-primary__section">
</div>
<div id="rtd-footer-container"></div>
</div>
<main id="main-content" class="bd-main">
<div class="bd-content">
<div class="bd-article-container">
<div class="bd-header-article">
<div class="header-article-items header-article__inner">
<div class="header-article-items__start">
<div class="header-article-item">
<nav aria-label="Breadcrumb">
<ul class="bd-breadcrumbs">
<li class="breadcrumb-item breadcrumb-home">
<a href="../index.html" class="nav-link" aria-label="Home">
<i class="fa-solid fa-home"></i>
</a>
</li>
<li class="breadcrumb-item"><a href="index.html" class="nav-link">User Guide</a></li>
<li class="breadcrumb-item active" aria-current="page">Using...</li>
</ul>
</nav>
</div>
</div>
</div>
</div>
<div id="searchbox"></div>
<article class="bd-article">
<section id="using-categories-in-templates">
<h1>Using categories in templates<a class="headerlink" href="#using-categories-in-templates" title="Link to this heading">#</a></h1>
<section id="getting-all-items-within-a-category">
<h2>Getting all items within a category<a class="headerlink" href="#getting-all-items-within-a-category" title="Link to this heading">#</a></h2>
<p>The <a class="reference internal" href="../reference/models.html#Category" title="Category"><code class="xref py py-class docutils literal notranslate"><span class="pre">Category</span></code></a> model automatically gets <a class="reference external" href="https://docs.djangoproject.com/en/1.3/topics/db/queries/#following-relationships-backward">reverse relationships</a> with all other models related to it.</p>
<p>This allows you access to the related objects from the template without altering any views. For example, if you only had <code class="docutils literal notranslate"><span class="pre">Entry</span></code> models related to <a class="reference internal" href="../reference/models.html#Category" title="Category"><code class="xref py py-class docutils literal notranslate"><span class="pre">Category</span></code></a>, your <code class="docutils literal notranslate"><span class="pre">categories/category_detail.html</span></code> template could look like</p>
<div class="highlight-django notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="cp">{%</span> <span class="k">extends</span> <span class="s1">&#39;categories/base.html&#39;</span> <span class="cp">%}</span>
<span class="linenos"> 2</span><span class="cp">{%</span> <span class="k">block</span> <span class="nv">content</span> <span class="cp">%}</span>
<span class="linenos"> 3</span><span class="x">&lt;h1&gt;</span><span class="cp">{{</span> <span class="nv">category</span> <span class="cp">}}</span><span class="x">&lt;/h1&gt;</span>
<span class="linenos"> 4</span><span class="cp">{%</span> <span class="k">if</span> <span class="nv">category.parent</span> <span class="cp">%}</span>
<span class="linenos"> 5</span><span class="x"> &lt;h2&gt;Go up to </span>
<span class="linenos"> 6</span><span class="x"> &lt;a href=&quot;</span><span class="cp">{{</span> <span class="nv">category.parent.get_absolute_url</span> <span class="cp">}}</span><span class="x">&quot;&gt;</span>
<span class="linenos"> 7</span><span class="x"> </span><span class="cp">{{</span> <span class="nv">category.parent</span> <span class="cp">}}</span>
<span class="linenos"> 8</span><span class="x"> &lt;/a&gt;&lt;/h2&gt;</span>
<span class="linenos"> 9</span><span class="cp">{%</span> <span class="k">endif</span> <span class="cp">%}</span>
<span class="linenos">10</span><span class="cp">{%</span> <span class="k">if</span> <span class="nv">category.description</span> <span class="cp">%}</span><span class="x">&lt;p&gt;</span><span class="cp">{{</span> <span class="nv">category.description</span> <span class="cp">}}</span><span class="x">&lt;/p&gt;</span><span class="cp">{%</span> <span class="k">endif</span> <span class="cp">%}</span>
<span class="linenos">11</span><span class="cp">{%</span> <span class="k">if</span> <span class="nv">category.children.count</span> <span class="cp">%}</span>
<span class="linenos">12</span><span class="x"> &lt;h2&gt;Subcategories&lt;/h2&gt;</span>
<span class="linenos">13</span><span class="x"> &lt;ul&gt;</span>
<span class="linenos">14</span><span class="x"> </span><span class="cp">{%</span> <span class="k">for</span> <span class="nv">child</span> <span class="k">in</span> <span class="nv">category.children.all</span> <span class="cp">%}</span>
<span class="linenos">15</span><span class="x"> &lt;li&gt;&lt;a href=&quot;</span><span class="cp">{{</span> <span class="nv">child.get_absolute_url</span> <span class="cp">}}</span><span class="x">&quot;&gt;</span><span class="cp">{{</span> <span class="nv">child</span> <span class="cp">}}</span><span class="x">&lt;/a&gt;&lt;/li&gt;</span>
<span class="linenos">16</span><span class="x"> </span><span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span>
<span class="linenos">17</span><span class="x"> &lt;/ul&gt;</span>
<span class="linenos">18</span><span class="cp">{%</span> <span class="k">endif</span> <span class="cp">%}</span>
<span class="linenos">19</span><span class="x">&lt;h2&gt;Entries&lt;/h2&gt;</span>
<span class="linenos">20</span><span class="cp">{%</span> <span class="k">if</span> <span class="nv">category.entries_set.all</span> <span class="cp">%}</span>
<span class="linenos">21</span><span class="x"> </span><span class="cp">{%</span> <span class="k">for</span> <span class="nv">entry</span> <span class="k">in</span> <span class="nv">category.entries_set.all</span> <span class="cp">%}</span>
<span class="linenos">22</span><span class="x"> &lt;p&gt;&lt;a href=&quot;</span><span class="cp">{{</span> <span class="nv">entry.get_absolute_url</span> <span class="cp">}}</span><span class="x">&quot;&gt;</span><span class="cp">{{</span> <span class="nv">entry.headline</span> <span class="cp">}}</span><span class="x">&lt;/a&gt;&lt;/p&gt;</span>
<span class="linenos">23</span><span class="x"> </span><span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span>
<span class="linenos">24</span><span class="cp">{%</span> <span class="k">else</span> <span class="cp">%}</span>
<span class="linenos">25</span><span class="x"> &lt;p&gt;&lt;em&gt;No entries for </span><span class="cp">{{</span> <span class="nv">category</span> <span class="cp">}}</span><span class="x">&lt;/em&gt;&lt;/p&gt;</span>
<span class="linenos">26</span><span class="cp">{%</span> <span class="k">endif</span> <span class="cp">%}</span>
<span class="linenos">27</span>
<span class="linenos">28</span><span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>If you have <code class="docutils literal notranslate"><span class="pre">related_name</span></code> parameters to the configuration (see <a class="reference internal" href="registering_models.html#registering-models"><span class="std std-ref">Registering Models</span></a>), then you would use <code class="docutils literal notranslate"><span class="pre">category.related_name.all</span></code> instead of <code class="docutils literal notranslate"><span class="pre">category.relatedmodel_set.all</span></code>.</p>
</section>
<section id="template-tags">
<h2>Template Tags<a class="headerlink" href="#template-tags" title="Link to this heading">#</a></h2>
<p>To use the template tags:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span><span class="o">%</span> <span class="kn">import</span> <span class="nn">category_tags</span> <span class="o">%</span><span class="p">}</span>
</pre></div>
</div>
<section id="tree-info">
<h3><code class="docutils literal notranslate"><span class="pre">tree_info</span></code><a class="headerlink" href="#tree-info" title="Link to this heading">#</a></h3>
<p>Given a list of categories, iterates over the list, generating
two-tuples of the current tree item and a <code class="docutils literal notranslate"><span class="pre">dict</span></code> containing
information about the tree structure around the item, with the following
keys:</p>
<blockquote>
<div><dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">'new_level'</span></code></dt><dd><p><code class="docutils literal notranslate"><span class="pre">True</span></code> if the current item is the start of a new level in
the tree, <code class="docutils literal notranslate"><span class="pre">False</span></code> otherwise.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">'closed_levels'</span></code></dt><dd><p>A list of levels which end after the current item. This will
be an empty list if the next item’s level is the same as or
greater than the level of the current item.</p>
</dd>
</dl>
</div></blockquote>
<p>An optional argument can be provided to specify extra details about the
structure which should appear in the <code class="docutils literal notranslate"><span class="pre">dict</span></code>. This should be a
comma-separated list of feature names. The valid feature names are:</p>
<blockquote>
<div><dl>
<dt>ancestors</dt><dd><p>Adds a list of unicode representations of the ancestors of the
current node, in descending order (root node first, immediate
parent last), under the key <code class="docutils literal notranslate"><span class="pre">'ancestors'</span></code>.</p>
<p>For example: given the sample tree below, the contents of the list
which would be available under the <code class="docutils literal notranslate"><span class="pre">'ancestors'</span></code> key are given
on the right:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Books</span> <span class="o">-&gt;</span> <span class="p">[]</span>
<span class="n">Sci</span><span class="o">-</span><span class="n">fi</span> <span class="o">-&gt;</span> <span class="p">[</span><span class="sa">u</span><span class="s1">&#39;Books&#39;</span><span class="p">]</span>
<span class="n">Dystopian</span> <span class="n">Futures</span> <span class="o">-&gt;</span> <span class="p">[</span><span class="sa">u</span><span class="s1">&#39;Books&#39;</span><span class="p">,</span> <span class="sa">u</span><span class="s1">&#39;Sci-fi&#39;</span><span class="p">]</span>
</pre></div>
</div>
</dd>
</dl>
</div></blockquote>
</section>
</section>
</section>
</article>
<footer class="prev-next-footer">
<div class="prev-next-area">
<a class="left-prev"
href="index.html"
title="previous page">
<i class="fa-solid fa-angle-left"></i>
<div class="prev-next-info">
<p class="prev-next-subtitle">previous</p>
<p class="prev-next-title">User Guide</p>
</div>
</a>
<a class="right-next"
href="registering_models.html"
title="next page">
<div class="prev-next-info">
<p class="prev-next-subtitle">next</p>
<p class="prev-next-title">Registering Models</p>
</div>
<i class="fa-solid fa-angle-right"></i>
</a>
</div>
</footer>
</div>
<div class="bd-sidebar-secondary bd-toc"><div class="sidebar-secondary-items sidebar-secondary__inner">
<div class="sidebar-secondary-item">
<div
id="pst-page-navigation-heading-2"
class="page-toc tocsection onthispage">
<i class="fa-solid fa-list"></i> On this page
</div>
<nav class="bd-toc-nav page-toc" aria-labelledby="pst-page-navigation-heading-2">
<ul class="visible nav section-nav flex-column">
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#getting-all-items-within-a-category">Getting all items within a category</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#template-tags">Template Tags</a><ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#tree-info"><code class="docutils literal notranslate"><span class="pre">tree_info</span></code></a></li>
</ul>
</li>
</ul>
</nav></div>
<div class="sidebar-secondary-item">
<div class="tocsection sourcelink">
<a href="../_sources/user_guide/usage.rst.txt">
<i class="fa-solid fa-file-lines"></i> Show Source
</a>
</div>
</div>
</div></div>
</div>
<footer class="bd-footer-content">
</footer>
</main>
</div>
</div>
<!-- Scripts loaded after <body> so the DOM is not blocked -->
<script src="../_static/scripts/bootstrap.js?digest=8d27b9dea8ad943066ae"></script>
<script src="../_static/scripts/pydata-sphinx-theme.js?digest=8d27b9dea8ad943066ae"></script>
<footer class="bd-footer">
<div class="bd-footer__inner bd-page-width">
<div class="footer-items__start">
<div class="footer-item">
<p class="copyright">
© Copyright 2010-2024, Corey Oordt.
<br/>
</p>
</div>
<div class="footer-item">
<p class="sphinx-version">
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 7.3.7.
<br/>
</p>
</div>
</div>
<div class="footer-items__end">
<div class="footer-item">
<p class="theme-version">
Built with the <a href="https://pydata-sphinx-theme.readthedocs.io/en/stable/index.html">PyData Sphinx Theme</a> 0.15.2.
</p></div>
</div>
</div>
</footer>
</body>
</html>
Reference in a new issue View git blame Copy permalink