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

574 lines
No EOL
22 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>Getting Started &#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 = 'getting_started';</script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="User Guide" href="user_guide/index.html" />
<link rel="prev" title="Installation" href="installation.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 current active">
<a class="nav-link nav-internal" href="#">
Getting Started
</a>
</li>
<li class="nav-item">
<a class="nav-link nav-internal" href="user_guide/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 current active">
<a class="nav-link nav-internal" href="#">
Getting Started
</a>
</li>
<li class="nav-item">
<a class="nav-link nav-internal" href="user_guide/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"></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 active" aria-current="page">Getting Started</li>
</ul>
</nav>
</div>
</div>
</div>
</div>
<div id="searchbox"></div>
<article class="bd-article">
<section id="getting-started">
<h1>Getting Started<a class="headerlink" href="#getting-started" title="Link to this heading">#</a></h1>
<p>You can use Django Categories in two ways:</p>
<ol class="arabic">
<li><p>As storage for one tree of categories, using 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:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Top</span> <span class="n">Category</span> <span class="mi">1</span>
<span class="n">Subcategory</span> <span class="mi">1</span><span class="o">-</span><span class="mi">1</span>
<span class="n">Subcategory</span> <span class="mi">1</span><span class="o">-</span><span class="mi">2</span>
<span class="n">subcategory</span> <span class="mi">1</span><span class="o">-</span><span class="mi">2</span><span class="o">-</span><span class="mi">1</span>
<span class="n">Top</span> <span class="n">Category</span> <span class="mi">2</span>
<span class="n">Subcategory</span> <span class="mi">2</span><span class="o">-</span><span class="mi">1</span>
</pre></div>
</div>
</li>
<li><p>As the basis for several custom categories (see <a class="reference internal" href="user_guide/custom_categories.html#creating-custom-categories"><span class="std std-ref">Creating Custom Categories</span></a>), e.g. a <strong>MusicGenre</strong> model</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">MusicGenre</span> <span class="mi">1</span>
<span class="n">MusicSubGenre</span> <span class="mi">1</span><span class="o">-</span><span class="mi">1</span>
<span class="n">MusicSubGenre</span> <span class="mi">1</span><span class="o">-</span><span class="mi">2</span>
<span class="n">MusicSubGenre</span> <span class="mi">1</span><span class="o">-</span><span class="mi">2</span><span class="o">-</span><span class="mi">1</span>
<span class="n">MusicGenre</span> <span class="mi">2</span>
<span class="n">MusicSubGenre</span> <span class="mi">2</span><span class="o">-</span><span class="mi">1</span>
</pre></div>
</div>
<p>and a <strong>Subject</strong> model</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Subject</span> <span class="mi">1</span>
<span class="n">Discipline</span> <span class="mi">1</span><span class="o">-</span><span class="mi">1</span>
<span class="n">Discipline</span> <span class="mi">1</span><span class="o">-</span><span class="mi">2</span>
<span class="n">SubDiscipline</span> <span class="mi">1</span><span class="o">-</span><span class="mi">2</span><span class="o">-</span><span class="mi">1</span>
<span class="n">Subject</span> <span class="mi">2</span>
<span class="n">Discipline</span> <span class="mi">2</span><span class="o">-</span><span class="mi">1</span>
</pre></div>
</div>
</li>
</ol>
<section id="connecting-your-model-with-django-categories">
<h2>Connecting your model with Django-Categories<a class="headerlink" href="#connecting-your-model-with-django-categories" title="Link to this heading">#</a></h2>
<p>There are two ways to add Category fields to an application. If you are in control of the code (it’s your application) or you are willing to take control of the code (fork someone else’s app) you can make a <a class="reference internal" href="#hard-coded-connection"><span class="std std-ref">Hard Coded Connection</span></a>.</p>
<p>For 3rd-party apps or even your own apps that you don’t wish to add Django-Categories as a dependency, you can configure a <a class="reference internal" href="#lazy-connection"><span class="std std-ref">Lazy Connection</span></a>.</p>
<section id="hard-coded-connection">
<span id="id1"></span><h3>Hard Coded Connection<a class="headerlink" href="#hard-coded-connection" title="Link to this heading">#</a></h3>
<p>Hard coded connections are done in the exact same way you handle any other foreign key or many-to-many relations to a model.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.db</span> <span class="kn">import</span> <span class="n">models</span>
<span class="k">class</span> <span class="nc">MyModel</span><span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">Model</span><span class="p">):</span>
<span class="n">name</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">100</span><span class="p">)</span>
<span class="n">category</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">ForeignKey</span><span class="p">(</span><span class="s1">&#39;categories.Category&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>Don’t forget to add the field or fields to your <code class="docutils literal notranslate"><span class="pre">ModelAdmin</span></code> class as well.</p>
</section>
<section id="lazy-connection">
<span id="id2"></span><h3>Lazy Connection<a class="headerlink" href="#lazy-connection" title="Link to this heading">#</a></h3>
<p>Lazy connections are done through configuring Django Categories in the project’s <code class="docutils literal notranslate"><span class="pre">settings.py</span></code> file. When the project starts up, the configured fields are dynamically added to the configured models and admin.</p>
<p>If you do this before you have created the database (before you ran <code class="docutils literal notranslate"><span class="pre">manage.py</span> <span class="pre">syncdb</span></code>), the fields will also be in the tables. If you do this after you have already created all the tables, you can run <code class="docutils literal notranslate"><span class="pre">manage.py</span> <span class="pre">add_category_fields</span></code> to create the fields (this requires Django South to be installed).</p>
<p>You add a many-to-one or many-to-many relationship with Django Categories using the <a class="reference internal" href="reference/settings.html#fk-registry"><span class="std std-ref">FK_REGISTRY</span></a> and <a class="reference internal" href="reference/settings.html#m2m-registry"><span class="std std-ref">M2M_REGISTRY</span></a> settings respectively. For more information see <a class="reference internal" href="user_guide/registering_models.html#registering-models"><span class="std std-ref">Registering Models</span></a>.</p>
</section>
</section>
</section>
</article>
<footer class="prev-next-footer">
<div class="prev-next-area">
<a class="left-prev"
href="installation.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">Installation</p>
</div>
</a>
<a class="right-next"
href="user_guide/index.html"
title="next page">
<div class="prev-next-info">
<p class="prev-next-subtitle">next</p>
<p class="prev-next-title">User Guide</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="#connecting-your-model-with-django-categories">Connecting your model with Django-Categories</a><ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#hard-coded-connection">Hard Coded Connection</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#lazy-connection">Lazy Connection</a></li>
</ul>
</li>
</ul>
</nav></div>
<div class="sidebar-secondary-item">
<div class="tocsection sourcelink">
<a href="_sources/getting_started.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