diff --git a/user-guide/requirements.in b/user-guide/requirements.in index 210d535..e9a124a 100644 --- a/user-guide/requirements.in +++ b/user-guide/requirements.in @@ -13,3 +13,4 @@ django~=4.2 git+https://github.com/django-cms/django-cms@release/4.1.x codespell pip-tools +docstrfmt diff --git a/user-guide/requirements.txt b/user-guide/requirements.txt index e20e6a7..7420c80 100644 --- a/user-guide/requirements.txt +++ b/user-guide/requirements.txt @@ -1,34 +1,39 @@ # -# This file is autogenerated by pip-compile with python 3.10 -# To update, run: +# This file is autogenerated by pip-compile with Python 3.12 +# by the following command: # -# pip-compile +# pip-compile --output-file=requirements.txt requirements.in # -alabaster==0.7.12 +alabaster==0.7.13 # via sphinx -asgiref==3.5.2 +asgiref==3.7.2 # via django -babel==2.11.0 +babel==2.14.0 # via sphinx -beautifulsoup4==4.11.1 +beautifulsoup4==4.12.2 # via furo -build==0.9.0 +black==23.12.1 + # via docstrfmt +build==1.0.3 # via pip-tools -certifi==2022.12.7 +certifi==2023.11.17 # via requests -charset-normalizer==2.1.1 +charset-normalizer==3.3.2 # via requests -click==8.1.3 - # via pip-tools -codespell==2.2.2 +click==8.1.7 + # via + # black + # docstrfmt + # pip-tools +codespell==2.2.6 # via -r requirements.in colorama==0.4.6 # via sphinx-autobuild -coverage==6.5.0 +coverage==7.4.0 # via -r requirements.in -datetime==4.7 +datetime==5.4 # via -r requirements.in -django==3.2.16 +django==4.2.8 # via # -r requirements.in # django-classy-tags @@ -36,109 +41,140 @@ django==3.2.16 # django-formtools # django-sekizai # django-treebeard -django-classy-tags==3.0.1 + # djangocms-admin-style +django-classy-tags==4.1.0 # via # django-cms # django-sekizai -django-cms @ git+https://github.com/django-cms/django-cms@develop-4 +django-cms @ git+https://github.com/django-cms/django-cms@release/4.1.x # via -r requirements.in -django-formtools==2.4 +django-formtools==2.5.1 # via django-cms -django-sekizai==3.0.1 +django-sekizai==4.1.0 # via django-cms -django-treebeard==4.5.1 +django-treebeard==4.7 # via django-cms -djangocms-admin-style==3.2.0 +djangocms-admin-style==3.2.6 # via django-cms -docutils==0.19 - # via sphinx -furo==2022.12.7 +docstrfmt==1.6.1 # via -r requirements.in -idna==3.4 +docutils==0.20.1 + # via + # docstrfmt + # sphinx +furo==2023.9.10 + # via -r requirements.in +idna==3.6 # via requests imagesize==1.4.1 # via sphinx jinja2==3.1.2 # via sphinx +libcst==1.1.0 + # via docstrfmt livereload==2.6.3 # via sphinx-autobuild -markupsafe==2.1.1 +markupsafe==2.1.3 # via # -r requirements.in # jinja2 -packaging==21.3 +mypy-extensions==1.0.0 + # via + # black + # typing-inspect +packaging==23.2 # via + # black # build # django-cms # sphinx -pep517==0.13.0 - # via build -pip-tools==6.9.0 +pathspec==0.12.1 + # via black +pip-tools==7.3.0 # via -r requirements.in +platformdirs==4.1.0 + # via + # black + # docstrfmt pyenchant==3.2.2 # via # -r requirements.in # sphinxcontrib-spelling -pygments==2.13.0 +pygments==2.17.2 # via # -r requirements.in # furo # sphinx -pyparsing==3.0.9 - # via packaging -pytz==2022.6 - # via - # babel - # datetime - # django -requests==2.28.1 +pyproject-hooks==1.0.0 + # via build +pytz==2023.3.post1 + # via datetime +pyyaml==6.0.1 + # via libcst +requests==2.31.0 # via sphinx six==1.16.0 # via livereload snowballstemmer==2.2.0 # via sphinx -soupsieve==2.3.2.post1 +soupsieve==2.5 # via beautifulsoup4 -sphinx==5.3.0 +sphinx==7.2.6 # via # -r requirements.in + # docstrfmt # furo # sphinx-autobuild # sphinx-basic-ng # sphinx-copybutton + # sphinxcontrib-applehelp + # sphinxcontrib-devhelp + # sphinxcontrib-htmlhelp + # sphinxcontrib-qthelp + # sphinxcontrib-serializinghtml # sphinxcontrib-spelling # sphinxext-opengraph sphinx-autobuild==2021.3.14 # via -r requirements.in -sphinx-basic-ng==1.0.0b1 +sphinx-basic-ng==1.0.0b2 # via furo -sphinx-copybutton==0.5.1 +sphinx-copybutton==0.5.2 # via -r requirements.in -sphinxcontrib-applehelp==1.0.2 +sphinxcontrib-applehelp==1.0.7 # via sphinx -sphinxcontrib-devhelp==1.0.2 +sphinxcontrib-devhelp==1.0.5 # via sphinx -sphinxcontrib-htmlhelp==2.0.0 +sphinxcontrib-htmlhelp==2.0.4 # via sphinx sphinxcontrib-jsmath==1.0.1 # via sphinx -sphinxcontrib-qthelp==1.0.3 +sphinxcontrib-qthelp==1.0.6 # via sphinx -sphinxcontrib-serializinghtml==1.1.5 +sphinxcontrib-serializinghtml==1.1.9 # via sphinx -sphinxcontrib-spelling==7.6.2 +sphinxcontrib-spelling==8.0.0 # via -r requirements.in -sphinxext-opengraph==0.7.5 +sphinxext-opengraph==0.9.1 # via -r requirements.in -sqlparse==0.4.3 +sqlparse==0.4.4 # via django -tornado==6.2 +tabulate==0.9.0 + # via docstrfmt +toml==0.10.2 + # via docstrfmt +tornado==6.4 # via livereload -urllib3==1.26.12 +typing-extensions==4.9.0 + # via + # libcst + # typing-inspect +typing-inspect==0.9.0 + # via libcst +urllib3==2.1.0 # via requests -wheel==0.38.3 +wheel==0.42.0 # via pip-tools -zope-interface==5.5.1 +zope-interface==6.1 # via datetime # The following packages are considered to be unsafe in a requirements file: diff --git a/user-guide/source/alias-note.rst b/user-guide/source/alias-note.include similarity index 100% rename from user-guide/source/alias-note.rst rename to user-guide/source/alias-note.include diff --git a/user-guide/source/explanation/aliases.rst b/user-guide/source/explanation/aliases.rst index 7f6b7c7..02d0289 100644 --- a/user-guide/source/explanation/aliases.rst +++ b/user-guide/source/explanation/aliases.rst @@ -1,21 +1,30 @@ Aliases -####### +======= -.. include:: ../alias-note.rst +.. include:: ../alias-note.include - -In Django CMS, the Alias plugin is a powerful tool that enables content editors to display in as many places as they like without duplicating it. Essentially, it creates a reference or link to content that resides in a separate place - called an "Alias". +In Django CMS, the Alias plugin is a powerful tool that enables content editors to +display in as many places as they like without duplicating it. Essentially, it creates a +reference or link to content that resides in a separate place - called an "Alias". Key aspects of the Alias plugin include: -1. **Content Replication:** Rather than copying content, the alias content is referenced either in a page template or by using the Alias plugin. - -2. **Cross-Page Content Sharing:** It facilitates sharing content across different pages within the site. For instance, if there's a section that needs to appear in multiple places but should have consistent content, the aliases can be employed to achieve this. - -3. **Maintaining Consistency:** Using aliases ensures consistency in content across various parts of the website. If the original content gets updated, all aliases referencing it will reflect those changes instantly. - -4. **Saves Effort and Reduces Errors:** Instead of manually replicating content across multiple pages (which could lead to discrepancies or errors), the Alias plugin streamlines the process and reduces the chance of inconsistencies. - -5. **Ease of Management:** Content editors can manage content in one place while displaying it in multiple locations, making it easier to maintain and update information without having to navigate through numerous pages. - -In essence, aliases in Django CMS serves as a smart reference system, allowing content editors to reuse existing content across the site while maintaining consistency and efficiency in content management. +1. **Content Replication:** Rather than copying content, the alias content is referenced + either in a page template or by using the Alias plugin. +2. **Cross-Page Content Sharing:** It facilitates sharing content across different pages + within the site. For instance, if there's a section that needs to appear in multiple + places but should have consistent content, the aliases can be employed to achieve + this. +3. **Maintaining Consistency:** Using aliases ensures consistency in content across + various parts of the website. If the original content gets updated, all aliases + referencing it will reflect those changes instantly. +4. **Saves Effort and Reduces Errors:** Instead of manually replicating content across + multiple pages (which could lead to discrepancies or errors), the Alias plugin + streamlines the process and reduces the chance of inconsistencies. +5. **Ease of Management:** Content editors can manage content in one place while + displaying it in multiple locations, making it easier to maintain and update + information without having to navigate through numerous pages. + +In essence, aliases in Django CMS serves as a smart reference system, allowing content +editors to reuse existing content across the site while maintaining consistency and +efficiency in content management. diff --git a/user-guide/source/explanation/index.rst b/user-guide/source/explanation/index.rst index 1d38408..f017e85 100644 --- a/user-guide/source/explanation/index.rst +++ b/user-guide/source/explanation/index.rst @@ -1,12 +1,12 @@ .. _user-explanation: -######## Concepts -######## +======== .. include:: ../contribute-note.include -django CMS uses some specific concepts. This section explains those concepts from a content editor perspective. +django CMS uses some specific concepts. This section explains those concepts from a +content editor perspective. .. toctree:: :maxdepth: 1 @@ -14,7 +14,6 @@ django CMS uses some specific concepts. This section explains those concepts fro placeholders plugins publishing - version-locking aliases structure-content-modes touch diff --git a/user-guide/source/explanation/placeholders.rst b/user-guide/source/explanation/placeholders.rst index b5b8746..c386294 100644 --- a/user-guide/source/explanation/placeholders.rst +++ b/user-guide/source/explanation/placeholders.rst @@ -1,12 +1,29 @@ Placeholders -############ +============ -In Django CMS, placeholders are special markers within templates that define regions where content can be edited and managed by content editors. These placeholders act as slots or containers within a template where various types of content can be added, modified, and rearranged through django CMS' frontend editor and its structure board. +In Django CMS, placeholders are special markers within templates that define regions +where content can be edited and managed by content editors. These placeholders act as +slots or containers within a template where various types of content can be added, +modified, and rearranged through django CMS' frontend editor and its structure board. Here's how placeholders work: -1. **Defined Areas in a page:** Designers identify specific areas within their HTML templates where content can be dynamically inserted. Editors can access these defined placeholders and add or edit content directly through the user-friendly frontend editing interface without needing to touch the underlying code. Pages can be rendered using different templates. -2. **Content Manipulation:** Editors interact with placeholders to add various types of content elements or plugins (such as text, images, videos, forms, etc.) to these designated areas. They can modify existing content, rearrange elements, or remove content as needed. -3. **Flexibility and Customization:** Django CMS allows for the creation of custom plugins that can be inserted into placeholders. These plugins offer a wide range of functionalities and content types, giving content editors the flexibility to create diverse and engaging web pages without requiring developer intervention for each content update. +1. **Defined Areas in a page:** Designers identify specific areas within their HTML + templates where content can be dynamically inserted. Editors can access these defined + placeholders and add or edit content directly through the user-friendly frontend + editing interface without needing to touch the underlying code. Pages can be rendered + using different templates. +2. **Content Manipulation:** Editors interact with placeholders to add various types of + content elements or plugins (such as text, images, videos, forms, etc.) to these + designated areas. They can modify existing content, rearrange elements, or remove + content as needed. +3. **Flexibility and Customization:** Django CMS allows for the creation of custom + plugins that can be inserted into placeholders. These plugins offer a wide range of + functionalities and content types, giving content editors the flexibility to create + diverse and engaging web pages without requiring developer intervention for each + content update. -Ultimately, placeholders in Django CMS facilitate a clear separation between the presentation layer (templates) and the content, enabling content editors to manage and update website content easily without needing extensive technical knowledge or modifying the underlying code. +Ultimately, placeholders in Django CMS facilitate a clear separation between the +presentation layer (templates) and the content, enabling content editors to manage and +update website content easily without needing extensive technical knowledge or modifying +the underlying code. diff --git a/user-guide/source/explanation/plugins.rst b/user-guide/source/explanation/plugins.rst index 968e59d..64461ec 100644 --- a/user-guide/source/explanation/plugins.rst +++ b/user-guide/source/explanation/plugins.rst @@ -1,14 +1,30 @@ Plugins -####### +======= -Django CMS plugins are modular components that represent content. In Django CMS, content components are organized into placeholders within templates. These placeholders can be filled with various plugins to add diverse content components. +Django CMS plugins are modular components that represent content. In Django CMS, content +components are organized into placeholders within templates. These placeholders can be +filled with various plugins to add diverse content components. -Django CMS plugins offer content editors an intuitive way to manage and enrich the content of web pages without needing technical expertise or diving into code. Here's how they benefit content editors: +Django CMS plugins offer content editors an intuitive way to manage and enrich the +content of web pages without needing technical expertise or diving into code. Here's how +they benefit content editors: -1. **Ease of Use:** Content editors can work inside the frontend editor and use the structure board, where they can see available placeholders on a page. They can easily add, edit, or remove content elements (plugins) within these placeholders using a simple drag-and-drop interface or form-based interactions. +1. **Ease of Use:** Content editors can work inside the frontend editor and use the + structure board, where they can see available placeholders on a page. They can easily + add, edit, or remove content elements (plugins) within these placeholders using a + simple drag-and-drop interface or form-based interactions. +2. **Content Variety:** Plugins provide a wide range of content types that can be + inserted into placeholders, such as text, images, videos, galleries, sliders, forms, + maps, and more. This variety enables editors to create rich and diverse web pages + without relying on developers for every content update. +3. **Customization:** While there's a set of default plugins available, each + installation has its own set of plugins activated and might also use custom plugins + tailored to specific needs. These custom plugins can encapsulate complex + functionalities or unique design elements that content editors might require for + their content. Those custom plugins are not within the scope of this user guide. -2. **Content Variety:** Plugins provide a wide range of content types that can be inserted into placeholders, such as text, images, videos, galleries, sliders, forms, maps, and more. This variety enables editors to create rich and diverse web pages without relying on developers for every content update. - -3. **Customization:** While there's a set of default plugins available, each installation has its own set of plugins activated and might also use custom plugins tailored to specific needs. These custom plugins can encapsulate complex functionalities or unique design elements that content editors might require for their content. Those custom plugins are not within the scope of this user guide. - -In essence, Django CMS plugins empower content editors to manage and present content effectively, providing them with the tools to create engaging and dynamic web experiences without needing to delve into the technical intricacies of web development. These plugins empower editors to create and manage content without needing to write code or modify templates each time they want to add specific elements to a webpage. +In essence, Django CMS plugins empower content editors to manage and present content +effectively, providing them with the tools to create engaging and dynamic web +experiences without needing to delve into the technical intricacies of web development. +These plugins empower editors to create and manage content without needing to write code +or modify templates each time they want to add specific elements to a webpage. diff --git a/user-guide/source/explanation/publishing.rst b/user-guide/source/explanation/publishing.rst index 00bcba6..bd6dfba 100644 --- a/user-guide/source/explanation/publishing.rst +++ b/user-guide/source/explanation/publishing.rst @@ -1,5 +1,67 @@ Publishing -########## +========== .. include:: ../versioning-note.include +In Django CMS, publishing and versioning are crucial aspects for editors managing +content. Here's a breakdown of how they work: + +Publishing +---------- + +Publishing refers to making content available to website visitors. In Django CMS, you +typically create or edit content using a **draft**, which means the unfinished content +or changes are not immediately visible to the public. Editors can work on content +privately until it's ready for publication. + +This is the typical workflow: + +1. **Create Draft:** Editors create or modify content only in a draft version within the + CMS admin interface. +2. **Preview:** They can preview how the content will appear on the live site before + publishing. +3. **Publish:** When ready, editors can publish the changes to make them visible on the + live website for visitors to see. + +Published content cannot be changed any more. To make additional changes, create a start +over the process and create a new draft based on the published version. + +Managing versions +----------------- + +Versions in Django CMS keep track of changes made to content over time. This feature +allows editors to revert to earlier versions of content if needed and view the history +of modifications: + +1. **Version History:** Django CMS maintains a history of all changes made to a + particular piece of content. +2. **Compare Versions:** Editors can compare different versions of content to see what + changes were made between each iteration. +3. **Rollback:** If necessary, editors can revert to a previous version of the content, + effectively undoing recent changes. + +These functionalities empower editors to manage content effectively, ensuring quality +and control over what gets published on the live site while maintaining a history of +changes for reference or restoration purposes. + +.. figure:: ../tutorial/images/08-version-states.png + :alt: Version states and the editing process + + This diagram summarizes the possible states and the actions which create a change in + the state of a version. + +Locked versions +--------------- + +.. note:: + + This feature is not enabled in all installations of django CMS. See `django CMS + Versioning documentation + `_ + for more information. + +Version locking in Django CMS is a feature that automatically locks each draft version +of a content item to prevent unintended modifications or edits. A locked draft can only +be changed by the person who created the draft. This functionality is particularly +useful when you want to ensure that not two editors make changes to a specific content, +ensuring changes do not interfere with each other. diff --git a/user-guide/source/explanation/structure-content-modes.rst b/user-guide/source/explanation/structure-content-modes.rst index aca9f91..92b8601 100644 --- a/user-guide/source/explanation/structure-content-modes.rst +++ b/user-guide/source/explanation/structure-content-modes.rst @@ -1,10 +1,11 @@ -########################### Structure and content modes -########################### +=========================== -In Django CMS, the concepts of "structure" and "content" modes refer to different aspects of managing and arranging the plugins when editing a page (or other content). +In Django CMS, the concepts of "structure" and "content" modes refer to different +aspects of managing and arranging the plugins when editing a page (or other content). -You can toggle between structure and content mode by clicking the button on the far right of the toolbar. +You can toggle between structure and content mode by clicking the button on the far +right of the toolbar. .. image:: ../tutorial/images/07-structure-toggle.jpg :scale: 50 @@ -12,18 +13,27 @@ You can toggle between structure and content mode by clicking the button on the 1. **Structure Mode:** - - **Purpose:** Structure mode is primarily concerned with the arrangement and organization of the different plugins within placeholders. - - - **Functionality:** In structure mode, you can define the overall layout of your pages by creating plugins (regions within a template where content can be placed) and arranging these plugins within the placeholders of your page. - - - **Usage:** This mode is used for setting up the basic plugin structure of a page, determining where various types of content (text, images, videos, etc.) are placed within the layout. + - **Purpose:** Structure mode is primarily concerned with the arrangement and + organization of the different plugins within placeholders. + - **Functionality:** In structure mode, you can define the overall layout of your + pages by creating plugins (regions within a template where content can be placed) + and arranging these plugins within the placeholders of your page. + - **Usage:** This mode is used for setting up the basic plugin structure of a page, + determining where various types of content (text, images, videos, etc.) are placed + within the layout. 2. **Content Mode:** - - **Purpose:** Content mode focuses on the actual content that fills the placeholders created in structure mode. - - - **Functionality:** When in content mode, you can add, edit, and manage the specific plugins by double-clicking. This includes text, images, videos, widgets, and any other content types supported by Django CMS. - - - **Usage:** Content mode is used for changing or populating the placeholders with actual content. Users typically work in content mode when they want to add or modify text, images, or any other elements on the pages. - -In summary, structure mode deals with the layout and arrangement of placeholders on a page, while content mode involves filling those placeholders with actual content. These modes work together to provide a structured yet flexible way of managing the overall structure and content of a website within Django CMS. + - **Purpose:** Content mode focuses on the actual content that fills the placeholders + created in structure mode. + - **Functionality:** When in content mode, you can add, edit, and manage the specific + plugins by double-clicking. This includes text, images, videos, widgets, and any + other content types supported by Django CMS. + - **Usage:** Content mode is used for changing or populating the placeholders with + actual content. Users typically work in content mode when they want to add or + modify text, images, or any other elements on the pages. + +In summary, structure mode deals with the layout and arrangement of placeholders on a +page, while content mode involves filling those placeholders with actual content. These +modes work together to provide a structured yet flexible way of managing the overall +structure and content of a website within Django CMS. diff --git a/user-guide/source/explanation/touch.rst b/user-guide/source/explanation/touch.rst index 5931ce7..7264605 100644 --- a/user-guide/source/explanation/touch.rst +++ b/user-guide/source/explanation/touch.rst @@ -1,118 +1,106 @@ .. _touch: -########################################## Using touch-screen devices with django CMS -########################################## - +========================================== .. important:: - These notes about touch interface support apply only to the **django CMS admin and editing - interfaces**. The visitor-facing published site is **wholly independent** of this, and the - responsibility of the site developer. - + These notes about touch interface support apply only to the **django CMS admin and + editing interfaces**. The visitor-facing published site is **wholly independent** of + this, and the responsibility of the site developer. -******* General -******* +------- -django CMS has made extensive use of double-click functionality, which lacks an exact equivalent in -touch-screen interfaces. The touch interface will interpret taps and touches in an intelligent way. +django CMS has made extensive use of double-click functionality, which lacks an exact +equivalent in touch-screen interfaces. The touch interface will interpret taps and +touches in an intelligent way. -Depending on the context, a tap will be interpreted to mean *open for editing* (that is, the -equivalent of a double-click), or to mean *select* (the equivalent of a single click), according to -what makes sense in that context. +Depending on the context, a tap will be interpreted to mean *open for editing* (that is, +the equivalent of a double-click), or to mean *select* (the equivalent of a single +click), according to what makes sense in that context. -Similarly, in some contexts similar interactions may *drag* objects, or may *scroll* them, -depending on what makes most sense. Sometimes, the two behaviours will be present in the same view, -for example in the page list, where certain areas are draggable (for page re-ordering) while other -parts of the page can be used for scrolling. +Similarly, in some contexts similar interactions may *drag* objects, or may *scroll* +them, depending on what makes most sense. Sometimes, the two behaviours will be present +in the same view, for example in the page list, where certain areas are draggable (for +page re-ordering) while other parts of the page can be used for scrolling. -In general, the chosen behaviour is reasonable for a particular object, context or portion of the -screen, and in practice is quicker and easier to apprehend simply by using it than it is to explain. +In general, the chosen behaviour is reasonable for a particular object, context or +portion of the screen, and in practice is quicker and easier to apprehend simply by +using it than it is to explain. Pop-up help text will refer to clicking or tapping depending on the device being used. -Be aware that some hover-related user hints are simply not available to touch interface users. - +Be aware that some hover-related user hints are simply not available to touch interface +users. .. _device-support: -************** Device support -************** +-------------- -Smaller devices such as most phones are too small to be adequately usable. For example, your Apple -Watch is sadly unlikely to provide a very good django CMS editing experience. +Smaller devices such as most phones are too small to be adequately usable. For example, +your Apple Watch is sadly unlikely to provide a very good django CMS editing experience. Older devices will often lack the performance to support a usefully responsive frontend editing/administration interface. -The following devices are known to work well, so newer devices and more powerful models should also -be suitable: +The following devices are known to work well, so newer devices and more powerful models +should also be suitable: -* iOS: Apple iPad Air 1, Mini 4 -* Android: Sony Xperia Z2 Tablet, Samsung Galaxy Tab 4 -* Windows 10: Microsoft Surface +- iOS: Apple iPad Air 1, Mini 4 +- Android: Sony Xperia Z2 Tablet, Samsung Galaxy Tab 4 +- Windows 10: Microsoft Surface We welcome feedback about specific devices. - -******************** Your site's frontend -******************** - -django CMS's toolbar and frontend editing architecture rely on good practices in your own frontend -code. To work well with django CMS's responsive management framework, your own site should be -friendly towards multiple devices. +-------------------- -Whether you use your own frontend code or a framework such as Bootstrap 3 or Foundation, be aware -that problems in your CSS or markup can affect django CMS editing modes, and this will become -especially apparent to users of mobile/hand-held devices. +django CMS's toolbar and frontend editing architecture rely on good practices in your +own frontend code. To work well with django CMS's responsive management framework, your +own site should be friendly towards multiple devices. +Whether you use your own frontend code or a framework such as Bootstrap 3 or Foundation, +be aware that problems in your CSS or markup can affect django CMS editing modes, and +this will become especially apparent to users of mobile/hand-held devices. -************ Known issues -************ +------------ General issues --------------- +~~~~~~~~~~~~~~ -* Editing links that lack sufficient padding is currently difficult or impossible using +- Editing links that lack sufficient padding is currently difficult or impossible using touch-screens. - -* Similarly, other areas of a page where the visible content is composed entirely of links with - minimal padding around them can be difficult or impossible to open for editing by tapping. This - can affect the navigation menu (double-clicking on the navigation menu opens the page list). - -* Adding links is known to be problematic on some Android devices, because of the behaviour of the - keyboard. - -* On some devices, managing django CMS in the browser's *private* (also known as *incognito*) - mode can have significant performance implications. - - This is because local storage is not available in this mode, and user state must be stored in a - Django session, which is much less efficient. +- Similarly, other areas of a page where the visible content is composed entirely of + links with minimal padding around them can be difficult or impossible to open for + editing by tapping. This can affect the navigation menu (double-clicking on the + navigation menu opens the page list). +- Adding links is known to be problematic on some Android devices, because of the + behaviour of the keyboard. +- On some devices, managing django CMS in the browser's *private* (also known as + *incognito*) mode can have significant performance implications. + + This is because local storage is not available in this mode, and user state must be + stored in a Django session, which is much less efficient. This is an unusual use case, and should not affect many users. - CKEditor issues ---------------- - -* Scrolling on narrow devices, especially when opening the keyboard inside the CKEditor, does not - always work ideally - sometimes the keyboard can appear in the wrong place on-screen. - -* Sometimes the CKEditor moves unexpectedly on-screen in use. - -* Sometimes in Safari on iOS devices, a rendering bug will apparently truncate or reposition - portions of the toolbar when the CKEditor is opened - even though sections may appear to missing - or moved, they can still be activated by touching the part of the screen where they should have - been found. +~~~~~~~~~~~~~~~ +- Scrolling on narrow devices, especially when opening the keyboard inside the CKEditor, + does not always work ideally - sometimes the keyboard can appear in the wrong place + on-screen. +- Sometimes the CKEditor moves unexpectedly on-screen in use. +- Sometimes in Safari on iOS devices, a rendering bug will apparently truncate or + reposition portions of the toolbar when the CKEditor is opened - even though sections + may appear to missing or moved, they can still be activated by touching the part of + the screen where they should have been found. Django Admin issues -------------------- +~~~~~~~~~~~~~~~~~~~ -* In the page tree, the first touch on the page opens the keyboard which may be undesirable. This - happens because Django automatically focuses the search form input. +- In the page tree, the first touch on the page opens the keyboard which may be + undesirable. This happens because Django automatically focuses the search form input. diff --git a/user-guide/source/explanation/version-locking.rst b/user-guide/source/explanation/version-locking.rst deleted file mode 100644 index dd343a1..0000000 --- a/user-guide/source/explanation/version-locking.rst +++ /dev/null @@ -1,4 +0,0 @@ -Locking versions -################ - -.. include:: ../versioning-note.include diff --git a/user-guide/source/how-to/index.rst b/user-guide/source/how-to/index.rst index 79ede3d..71c7a3c 100644 --- a/user-guide/source/how-to/index.rst +++ b/user-guide/source/how-to/index.rst @@ -1,14 +1,12 @@ .. _user-how-to: -############# How-to-guides -############# +============= .. include:: ../contribute-note.include Use our guides to learn how to do a specific task in the CMS. - .. toctree:: :maxdepth: 1 diff --git a/user-guide/source/how-to/media-files.rst b/user-guide/source/how-to/media-files.rst index 2872879..173caed 100644 --- a/user-guide/source/how-to/media-files.rst +++ b/user-guide/source/how-to/media-files.rst @@ -1,17 +1,25 @@ Managing media files -#################### +==================== -In Django CMS, managing media files such as images, videos, documents, etc., is often handled using a popular Django package called "django-filer." This package integrates seamlessly with Django CMS to handle file management efficiently. Here's a step-by-step guide on managing media files in Django CMS using django-filer: +In Django CMS, managing media files such as images, videos, documents, etc., is often +handled using a popular Django package called "django-filer." This package integrates +seamlessly with Django CMS to handle file management efficiently. Here's a step-by-step +guide on managing media files in Django CMS using django-filer: -1. **Accessing Filer in Django CMS Admin:** - Once installed, you can access the django-filer functionalities through the Django CMS admin interface. +1. **Accessing Filer in Django CMS Admin:** Once installed, you can access the + django-filer functionalities through the Django CMS admin interface. +2. **Uploading Files:** Content editors can navigate to the Filer section within the CMS + admin to upload new files (images, documents, videos, etc.). They can create folders, + upload files, and organize them within the file manager provided by django-filer. +3. **Inserting Files into Content:** When editing content in Django CMS, content editors + can easily insert files (images, documents) stored in django-filer using plugins or + specific placeholders designed to handle media elements. For instance, they might use + a "File" or "Image" plugin that allows them to select files from the django-filer + library and place them within the content area. +4. **File Management:** Django-filer provides features for renaming, deleting, moving, + and organizing files and folders within the file manager interface, ensuring a + well-structured and manageable collection of media files. -2. **Uploading Files:** - Content editors can navigate to the Filer section within the CMS admin to upload new files (images, documents, videos, etc.). They can create folders, upload files, and organize them within the file manager provided by django-filer. - -3. **Inserting Files into Content:** - When editing content in Django CMS, content editors can easily insert files (images, documents) stored in django-filer using plugins or specific placeholders designed to handle media elements. For instance, they might use a "File" or "Image" plugin that allows them to select files from the django-filer library and place them within the content area. -4. **File Management:** - Django-filer provides features for renaming, deleting, moving, and organizing files and folders within the file manager interface, ensuring a well-structured and manageable collection of media files. - -By using django-filer, content editors can easily manage media files directly within the CMS interface, simplifying the process of adding and organizing various types of content elements throughout the website. +By using django-filer, content editors can easily manage media files directly within the +CMS interface, simplifying the process of adding and organizing various types of content +elements throughout the website. diff --git a/user-guide/source/how-to/pages.rst b/user-guide/source/how-to/pages.rst index c9cbfe3..442a4f9 100644 --- a/user-guide/source/how-to/pages.rst +++ b/user-guide/source/how-to/pages.rst @@ -1,45 +1,58 @@ Managing pages -############## +============== -Managing pages in Django CMS involves creating, organizing, and editing the structure and content of your website. Here's a step-by-step guide: - -1. **Accessing the Page Admin Interface:** - Select "Pages..." in the page menu of the toolbar. +Managing pages in Django CMS involves creating, organizing, and editing the structure +and content of your website. Here's a step-by-step guide: +1. **Accessing the Page Admin Interface:** Select "Pages..." in the page menu of the + toolbar. 2. **Creating a New Page:** - * Click on "Add Page" to create a new page. - * Enter the page title, select the page type (if applicable), and define the URL and other settings. + - Click on "Add Page" to create a new page. + - Enter the page title, select the page type (if applicable), and define the URL and + other settings. 3. **Organizing Page Hierarchy:** - * Arrange the page hierarchy by creating parent-child relationships between pages. - * Use drag-and-drop functionality to organize pages in a tree-like structure. + - Arrange the page hierarchy by creating parent-child relationships between pages. + - Use drag-and-drop functionality to organize pages in a tree-like structure. 4. **Managing Page Content:** - * Click on the settings icon of a page to access its settings - * Click on the eye icon of a page to access its content. - * Use placeholders to add content. Edit or add plugins (text, images, forms, etc.) into these placeholders. + - Click on the settings icon of a page to access its settings + - Click on the eye icon of a page to access its content. + - Use placeholders to add content. Edit or add plugins (text, images, forms, etc.) + into these placeholders. 5. **Editing Page Settings:** - Adjust page settings such as metadata (SEO-related information like meta titles, descriptions, keywords), publication dates, permissions, etc. + Adjust page settings such as metadata (SEO-related information like meta titles, + descriptions, keywords), publication dates, permissions, etc. + 6. **Preview and Publish:** - * Preview the page to see how it will look to visitors. - * Once satisfied, publish the page to make it live on the website. + - Preview the page to see how it will look to visitors. + - Once satisfied, publish the page to make it live on the website. + 7. **Managing Existing Pages:** - To edit an existing page, navigate to the Pages section, locate the page, and click on its eye icon to access its content. + To edit an existing page, navigate to the Pages section, locate the page, and click + on its eye icon to access its content. Make necessary changes to the content, settings, or structure. .. tip:: - **Permissions:** Adjust user permissions in Django CMS to control who can create, edit, or publish pages. - **URL Handling:** Django CMS often handles URL routing automatically, but you can customize URLs and slugs within the page settings. + **Permissions:** Adjust user permissions in Django CMS to control who can create, + edit, or publish pages. + + **URL Handling:** Django CMS often handles URL routing automatically, but you can + customize URLs and slugs within the page settings. - **Versioning and Revisions:** Django CMS keeps track of page revisions, allowing you to revert to previous versions if needed. + **Versioning and Revisions:** Django CMS keeps track of page revisions, allowing you + to revert to previous versions if needed. -Managing pages in Django CMS involves a mix of structural organization, content creation, and configuration adjustments. The system is designed to provide a user-friendly interface for content editors to manage the website's structure and content efficiently. +Managing pages in Django CMS involves a mix of structural organization, content +creation, and configuration adjustments. The system is designed to provide a +user-friendly interface for content editors to manage the website's structure and +content efficiently. diff --git a/user-guide/source/how-to/redirects.rst b/user-guide/source/how-to/redirects.rst index 9c8bd10..426b336 100644 --- a/user-guide/source/how-to/redirects.rst +++ b/user-guide/source/how-to/redirects.rst @@ -1,43 +1,49 @@ Managing redirects -################## +================== -By implementing redirects, you can retain the SEO rankings and authority of the old URL, transferring it to the new one. This helps to ensure that your website maintains its search engine visibility. +By implementing redirects, you can retain the SEO rankings and authority of the old URL, +transferring it to the new one. This helps to ensure that your website maintains its +search engine visibility. -Django CMS supports redirects as part of the :ref:`Page settings `. It happens on a per-language level. This means you can select different redirect targets for the different language contents of a page. +Django CMS supports redirects as part of the :ref:`Page settings `. It +happens on a per-language level. This means you can select different redirect targets +for the different language contents of a page. The simplest way to set redirects is: -1. **Accessing the Page Admin Interface:** - Select "Pages..." in the page menu of the toolbar. - +1. **Accessing the Page Admin Interface:** Select "Pages..." in the page menu of the + toolbar. 2. **Opening the page settings:** - * Find the page you want to redirect in the page tree. + - Find the page you want to redirect in the page tree. .. image:: ../tutorial/images/05-pagetree-form.jpg - :alt: django CMS page tree + :alt: django CMS page tree - * If the page is published, select "Create new draft" from the dropdown menu of the page status indicator (number 7). - * Click on the page settings icon (number 9: three horizontal sliders), + - If the page is published, select "Create new draft" from the dropdown menu of the + page status indicator (number 7). + - Click on the page settings icon (number 9: three horizontal sliders), 3. **Changing the redirect setting:** .. image:: ./images/redirect-settings.jpg - :alt: django CMS page settings + :alt: django CMS page settings - * Find the "URL options" section. - * Click "Show" to open the "URL options" section - * Change the "Redirect" setting by selecting the page which the current one should be redirected to - * Close the setting by clicking "Save" at the bottom + - Find the "URL options" section. + - Click "Show" to open the "URL options" section + - Change the "Redirect" setting by selecting the page which the current one should be + redirected to + - Close the setting by clicking "Save" at the bottom 4. **Publishing the change:** - * Select "Publish" from the dropdown menu of the page status indicator (number 7) + - Select "Publish" from the dropdown menu of the page status indicator (number 7) .. note:: - Changes can only be made to draft page contents and will only take effect once published. - - -Managing redirects in Django CMS happens on page level. The system is designed to provide a user-friendly interface for content editors to manage redirects and thereby ensure keeping SEO rankings. + Changes can only be made to draft page contents and will only take effect once + published. +Managing redirects in Django CMS happens on page level. The system is designed to +provide a user-friendly interface for content editors to manage redirects and thereby +ensure keeping SEO rankings. diff --git a/user-guide/source/how-to/versions.rst b/user-guide/source/how-to/versions.rst index 57cf0aa..77a98c2 100644 --- a/user-guide/source/how-to/versions.rst +++ b/user-guide/source/how-to/versions.rst @@ -1,60 +1,64 @@ Managing versions -################# +================= .. include:: ../versioning-note.include -Django CMS keeps track of page revisions, allowing you to revert to previous versions if needed. Here's a step-by-step guide on how to manage versions: +Django CMS keeps track of page revisions, allowing you to revert to previous versions if +needed. Here's a step-by-step guide on how to manage versions: 1. **Accessing the "manage versions" view:** Either - * Select "Pages..." in the page menu of the toolbar and look for the page the versions of which you want to manage. - * Click on the status indicator to open the dropdown menu - * Select "Manage versions..." + - Select "Pages..." in the page menu of the toolbar and look for the page the + versions of which you want to manage. + - Click on the status indicator to open the dropdown menu + - Select "Manage versions..." or - * Preview or edit the page the versions of which you want to manage. - * Click on the version menu and chose "Manage versions..." + - Preview or edit the page the versions of which you want to manage. + - Click on the version menu and chose "Manage versions..." .. image:: ../tutorial/images/08-version-menu-open.jpg - :scale: 50 - + :scale: 50 2. **Inspecting all versions:** .. image:: ./images/versions-changelist.jpg - :alt: Versions of a page content + :alt: Versions of a page content - * Created and modified dates - * Title and language - * Username of the author - * Status: Draft, Published, Unpublished, and Archived - * Action buttons + - Created and modified dates + - Title and language + - Username of the author + - Status: Draft, Published, Unpublished, and Archived + - Action buttons -3. **Acting upon versions:** - Actions differ by status of the version. They include +3. **Acting upon versions:** Actions differ by status of the version. They include - * Edit (pencil): Edit this version (draft) or create a new draft from this version (published) - * Archive: Mark this draft as archived for later usage - * Revert: Create new draft from this archived or unpublished version - * Publish: Publish this draft - * Unpublish: Make this published version unavailable - * Delete: Delete this draft version - * View: Preview this version + - Edit (pencil): Edit this version (draft) or create a new draft from this version + (published) + - Archive: Mark this draft as archived for later usage + - Revert: Create new draft from this archived or unpublished version + - Publish: Publish this draft + - Unpublish: Make this published version unavailable + - Delete: Delete this draft version + - View: Preview this version 4. **Comparing two versions:** - * Select exactly two versions to compare by checking the box on their left side - * From the pull-down menu marked ``-------`` select "Compare versions" - * Click "Go" + - Select exactly two versions to compare by checking the box on their left side + - From the pull-down menu marked ``-------`` select "Compare versions" + - Click "Go" .. image:: ../tutorial/images/08-comparing-versions.jpg - :alt: Comparing two versions + :alt: Comparing two versions .. note:: - Only draft versions can be deleted. Outdated versions are kept on purpose. + Only draft versions can be deleted. Outdated versions are kept on purpose. -Managing versions in Django CMS allows to unterstand the history of the page content. Drafts can be archived for later reuse. All versions currently public or once public are marked "published" or "unpublished", respectively. The content of versions can be compared with each other. +Managing versions in Django CMS allows to unterstand the history of the page content. +Drafts can be archived for later reuse. All versions currently public or once public are +marked "published" or "unpublished", respectively. The content of versions can be +compared with each other. diff --git a/user-guide/source/index.rst b/user-guide/source/index.rst index 208bbb2..3716d1d 100644 --- a/user-guide/source/index.rst +++ b/user-guide/source/index.rst @@ -45,61 +45,66 @@ .. _user-manual: -################ Using django CMS -################ +================ .. note:: - This is a new section in the django CMS documentation, and a priority - for the project. If you'd like to contribute to it, we'd love to hear - from you - join us on `our friendly Slack group - `_. + This is a new section in the django CMS documentation, and a priority for the + project. If you'd like to contribute to it, we'd love to hear from you - join us on + `our friendly Slack group `_. -This is a user guide for django CMS. The intended audience for this guide are content creators and site administrators. +This is a user guide for django CMS. The intended audience for this guide are content +creators and site administrators. -Django CMS sites are highly customisable and varied. The examples here follow the `quickstart project from Github `_. This provides certain features, which are entirely optional for your own site, and the features provided in the quickstart are used in this guide to demonstrate how django CMS can be used. +Django CMS sites are highly customisable and varied. The examples here follow the +`quickstart project from Github `_. +This provides certain features, which are entirely optional for your own site, and the +features provided in the quickstart are used in this guide to demonstrate how django CMS +can be used. -The origin of this document is a guide provided by `Kapt.mobi `_. It has been translated from the native French and extended. +The origin of this document is a guide provided by `Kapt.mobi +`_. It has been translated from the +native French and extended. Guide for content editors -######################### +------------------------- .. rst-class:: clearfix row .. rst-class:: column column2 top-left :ref:`user-tutorial` -==================== +~~~~~~~~~~~~~~~~~~~~ **Start here as a new django CMS content editor**: -* Getting to know the user interface -* Understanding the page tree -* Creating content +- Getting to know the user interface +- Understanding the page tree +- Creating content .. rst-class:: column column2 top-right :ref:`user-how-to` -================== +~~~~~~~~~~~~~~~~~~ -Practical **step-by-step guides** to get things done in the most simple way as a content editor +Practical **step-by-step guides** to get things done in the most simple way as a content +editor .. rst-class:: column column2 bottom-left :ref:`user-explanation` -======================= +~~~~~~~~~~~~~~~~~~~~~~~ What's a placeholder? What's a plugin? Understand key concepts of django CMS. .. rst-class:: column column2 bottom-right :ref:`user-reference` -===================== +~~~~~~~~~~~~~~~~~~~~~ Reference material for installed plugins. - .. rst-class:: clearfix row .. toctree:: diff --git a/user-guide/source/reference/index.rst b/user-guide/source/reference/index.rst index 8e9b274..a77b5ca 100644 --- a/user-guide/source/reference/index.rst +++ b/user-guide/source/reference/index.rst @@ -1,8 +1,7 @@ .. _user-reference: -############################# Reference for content editors -############################# +============================= .. include:: ../contribute-note.include diff --git a/user-guide/source/reference/plugins.rst b/user-guide/source/reference/plugins.rst index 9c66794..08904c3 100644 --- a/user-guide/source/reference/plugins.rst +++ b/user-guide/source/reference/plugins.rst @@ -1,97 +1,108 @@ Standard plugins -################ +================ -Each site has its own set of installed plugins. This reference is based on the plugins installed with django CMS quickstart. +Each site has its own set of installed plugins. This reference is based on the plugins +installed with django CMS quickstart. django CMS groups its plugins into categories. We list the plugins by category. Generic -======= +------- **Text** - The text plugin is a simple yet versatile plugin used for adding and editing text content. It allows you to directly insert formatted text, such as paragraphs, headings, lists, and links. - + The text plugin is a simple yet versatile plugin used for adding and editing text + content. It allows you to directly insert formatted text, such as paragraphs, + headings, lists, and links. **Alias** - The Alias plugin is a powerful tool that enables content editors to display certain content on many pages without duplicating it. The Alias plugin let predefined content blocks appear at its position by linking them. If the alias content is updated, the linked content also changes. - + The Alias plugin is a powerful tool that enables content editors to display certain + content on many pages without duplicating it. The Alias plugin let predefined + content blocks appear at its position by linking them. If the alias content is + updated, the linked content also changes. Frontend -======== +-------- .. include:: ../frontend-note.include - -The frontend plugins are part of the djangocms-frontend package, which might (or might not) be installed on your site. Its purpose is to provide web site components like sliders, accordions, etc. for content editors. Thóse components in most cases are implemented by the deisnger of the web site. The contend editors can use the component at any place on the site. +The frontend plugins are part of the djangocms-frontend package, which might (or might +not) be installed on your site. Its purpose is to provide web site components like +sliders, accordions, etc. for content editors. Thóse components in most cases are +implemented by the deisnger of the web site. The contend editors can use the component +at any place on the site. **Accordion** - Use the Accordion plugin to build vertically collapsing accordions. - + Use the Accordion plugin to build vertically collapsing accordions. **Alert** - Provide contextual feedback messages for typical user actions for a handful of contexts: success, warning, danger, info, .... + Provide contextual feedback messages for typical user actions for a handful of + contexts: success, warning, danger, info, .... **Badge** - Provide small counters or pieces of information for a handful of contexts: success, warning, danger, info, .... + Provide small counters or pieces of information for a handful of contexts: success, + warning, danger, info, .... **Blockquote** - Quote blocks of content from another source. Optionally provide a source. + Quote blocks of content from another source. Optionally provide a source. **Card** - Structure content with a flexible and extensible container with multiple variants and options + Structure content with a flexible and extensible container with multiple variants + and options **Card layout** - Organize several cards into one layout + Organize several cards into one layout **Carousel** - Cycle through elements, images or slides of text, like a carousel. + Cycle through elements, images or slides of text, like a carousel. **Code** - Present (computer) code blocks + Present (computer) code blocks **Collapse** - Toggle the visibility of content + Toggle the visibility of content **Container** - Contain, pad, and align your content within a given device or viewport for responsive designs + Contain, pad, and align your content within a given device or viewport for + responsive designs **Editor note** - Mark contents visible to editors only + Mark contents visible to editors only **Figure** - Display related images and text + Display related images and text **Heading** - Add headline with optional anchor. + Add headline with optional anchor. **Icon** - Give visual clues by adding icons + Give visual clues by adding icons **Jumbotron (deprecated)** - Showcase your hero unit + Showcase your hero unit **Link / Button** - Reference and link other contents + Reference and link other contents **List group** - Displaying a series of content flexibly. Modify and extend them to support just about any content within. + Displaying a series of content flexibly. Modify and extend them to support just + about any content within. **Media** - Construct highly repetitive components like blog comments, tweets, and the like + Construct highly repetitive components like blog comments, tweets, and the like **Picture / Image** - Show images from the media library + Show images from the media library **Row** and **Column** - Build responsive layouts of all shapes and sizes thanks to a twelve column system, six default responsive tiers + Build responsive layouts of all shapes and sizes thanks to a twelve column system, + six default responsive tiers **Spacing** - Add horizontal spaces around the child content + Add horizontal spaces around the child content **Table of contents** - Create a table of contents for all sections starting with the "Heading" plugin. + Create a table of contents for all sections starting with the "Heading" plugin. **Tabs** - Creat a tabbed interface for content that is only shown when the corresponding tab is activated. - - + Creat a tabbed interface for content that is only shown when the corresponding tab + is activated. diff --git a/user-guide/source/tutorial/01-login.rst b/user-guide/source/tutorial/01-login.rst index c09e8e5..c85b173 100644 --- a/user-guide/source/tutorial/01-login.rst +++ b/user-guide/source/tutorial/01-login.rst @@ -1,17 +1,27 @@ .. _editing: Logging-in -########## +========== -Once you have :ref:`created your site ` with the django CMS components you will want to customise the site and add content. To this you will need to log in and edit it. +Once you have :ref:`created your site ` with the django CMS +components you will want to customise the site and add content. To this you will need to +log in and edit it. -There are different ways of accessing your user account in django CMS. Please refer to what the respective developer of your project has told you. +There are different ways of accessing your user account in django CMS. Please refer to +what the respective developer of your project has told you. -The default way is to add ``/?toolbar_on`` to the end of your URL and use the toolbar to log in. The banner or login page will appear, asking you for your username and password. When you first log in, these two elements have been set by the developers. Therefore, if you are not sure how to fill in these fields, please contact them. +The default way is to add ``/?toolbar_on`` to the end of your URL and use the toolbar to +log in. The banner or login page will appear, asking you for your username and password. +When you first log in, these two elements have been set by the developers. Therefore, if +you are not sure how to fill in these fields, please contact them. -Logging in will allow you to access your site to add, modify or delete content. You will be able to perform a lot of actions using the django CMS menu bar, which is present when you are logged in to your site. +Logging in will allow you to access your site to add, modify or delete content. You will +be able to perform a lot of actions using the django CMS menu bar, which is present when +you are logged in to your site. .. image:: ./images/01-toolbar-on.jpg - :alt: django CMS toolbar login + :alt: django CMS toolbar login -Upon logging into your site, you will be able to see your site's pages and other content with a toolbar at the top of the visible area. This toolbar is used to make changes to your site. +Upon logging into your site, you will be able to see your site's pages and other content +with a toolbar at the top of the visible area. This toolbar is used to make changes to +your site. diff --git a/user-guide/source/tutorial/02-toolbar.rst b/user-guide/source/tutorial/02-toolbar.rst index 22945cb..b2d073a 100644 --- a/user-guide/source/tutorial/02-toolbar.rst +++ b/user-guide/source/tutorial/02-toolbar.rst @@ -1,137 +1,182 @@ .. _toolbar: The toolbar -########### +=========== Overview -======== +-------- -When connected to your site, the Django CMS toolbar appears. It can also be called a menu bar since it offers you several menus performing various actions. +When connected to your site, the Django CMS toolbar appears. It can also be called a +menu bar since it offers you several menus performing various actions. .. image:: ./images/02-toolbar.jpg - :alt: The django CMS toolbar + :alt: The django CMS toolbar -Depending on the modules present on your site and the page you are on, you can find various elements. The only ones that will always be present are "Project", "Page" and "Language". The other proposals that may appear depend on the CMS modules present on your website and where you are located. For example, "Blog" will only be displayed if you have this module and you are on your blog page or article pages. +Depending on the modules present on your site and the page you are on, you can find +various elements. The only ones that will always be present are "Project", "Page" and +"Language". The other proposals that may appear depend on the CMS modules present on +your website and where you are located. For example, "Blog" will only be displayed if +you have this module and you are on your blog page or article pages. -Another element that is constantly present in your toolbar: the django CMS logo. If you click on it, it will simply take you back to your home page. +Another element that is constantly present in your toolbar: the django CMS logo. If you +click on it, it will simply take you back to your home page. -To the right of the logo follows the project menu, the page menu and potentially some more menus: Here the version and language menu. The language menu will be missing in single-language configurations. +To the right of the logo follows the project menu, the page menu and potentially some +more menus: Here the version and language menu. The language menu will be missing in +single-language configurations. -On the right handside you see the color scheme toggle which you can use to switch the color scheme of django CMS interface elements between light and dark. It is followed by action buttons which are highly context dependent. Finally, on the right hand corner, there is the structure board toggle which might be disabled. It is central to editing content. +On the right handside you see the color scheme toggle which you can use to switch the +color scheme of django CMS interface elements between light and dark. It is followed by +action buttons which are highly context dependent. Finally, on the right hand corner, +there is the structure board toggle which might be disabled. It is central to editing +content. The Project menu -================== +---------------- -This is the part of the django CMS toolbar that corresponds to your site. Normally, the name of your website is displayed instead of "example.com". +This is the part of the django CMS toolbar that corresponds to your site. Normally, the +name of your website is displayed instead of "example.com". .. image:: ./images/02-project-menu.jpg - :alt: The Project menu - :scale: 50 + :alt: The Project menu + :scale: 50 .. note:: - You might not see all of the elements described here, or even more elements. This strongly depends on your django CMS setup. - -* **Pages...** - allows you to access the page tree of your site by opening the side bar. -* **Users...** - gives you access to the user management panel in the side bar. -* **Administration...** - Allows you to manage various features via the administration window. -* **Aliases...** - Allows you to access content elements which are re-used within your sites, such as footers or announcements. -* **User settings** - Allows you to change the language of the administrator interface and the menu/toolbar. -* **Disable Toolbar** - allows you to completely disable the toolbar and the front-end editor, regardless of the login and status of the person logged in. -* **Shortcuts** - gives access to your shortcuts. -* **Logout ** - the user will be logged out. - -Generally, by choosing one of the items of this menu, the content will be displayed in the sidebar overlay or in a new page. In the case of the sidebar, you can close it with the cross at the top right. + You might not see all of the elements described here, or even more elements. This + strongly depends on your django CMS setup. + +- **Pages...** - allows you to access the page tree of your site by opening the side + bar. +- **Users...** - gives you access to the user management panel in the side bar. +- **Administration...** - Allows you to manage various features via the administration + window. +- **Aliases...** - Allows you to access content elements which are re-used within your + sites, such as footers or announcements. +- **User settings** - Allows you to change the language of the administrator interface + and the menu/toolbar. +- **Disable Toolbar** - allows you to completely disable the toolbar and the front-end + editor, regardless of the login and status of the person logged in. +- **Shortcuts** - gives access to your shortcuts. +- **Logout ** - the user will be logged out. + +Generally, by choosing one of the items of this menu, the content will be displayed in +the sidebar overlay or in a new page. In the case of the sidebar, you can close it with +the cross at the top right. .. note:: - If you disable the toolbar, you can only make it reappear by adding ``?toolbar_on`` to the end of the URL in your browser window. + If you disable the toolbar, you can only make it reappear by adding ``?toolbar_on`` + to the end of the URL in your browser window. The "Page" menu -=============== +--------------- .. image:: ./images/02-page-menu.jpg - :alt: The Page menu - :scale: 50 + :alt: The Page menu + :scale: 50 The "Page" menu allows you to perform the following actions: -* **Create new pages** - you have the choice to create a new page, a new sub-page or to duplicate the page you are on. +- **Create new pages** - you have the choice to create a new page, a new sub-page or to + duplicate the page you are on. .. note:: - A parent page is a page that contains a group of several other pages of which your page is part. + A parent page is a page that contains a group of several other pages of which your + page is part. - A sibling page is a page of the same level as your current page: they belong to the same group. Sibling pages either have both no parents or the same parent page. + A sibling page is a page of the same level as your current page: they belong to + the same group. Sibling pages either have both no parents or the same parent page. - A sub page is a page nested within the parent page group. A parent page is the "parent" of the sub page which if also called child page. + A sub page is a page nested within the parent page group. A parent page is the + "parent" of the sub page which if also called child page. - This is called page inheritance.and explained in more detail in the `section on the tree structure `_ of your site later in this document. + This is called page inheritance.and explained in more detail in the `section on + the tree structure `_ of your site later in this document. -* **Edit this page** - allows you to edit the page you are on. Changes to a page are only possible if your are in edit mode. -* **Page settings…** - gives you access to the settings of the current page. -* **Advanced settings** - allows you to access the advanced settings of the page. Amongst the advanced settings of a page are their permissions. -* **Templates** - allows you to choose the template of your page. You can also choose to have your page inherit the template of the "closest parent", i.e. apply the template of its parent or sister page. -* **Hide/show in navigation** - toggles if the page should appear in the sites navigation -* **Delete page** - deletes the page. +- **Edit this page** - allows you to edit the page you are on. Changes to a page are + only possible if your are in edit mode. +- **Page settings…** - gives you access to the settings of the current page. +- **Advanced settings** - allows you to access the advanced settings of the page. + Amongst the advanced settings of a page are their permissions. +- **Templates** - allows you to choose the template of your page. You can also choose to + have your page inherit the template of the "closest parent", i.e. apply the template + of its parent or sister page. +- **Hide/show in navigation** - toggles if the page should appear in the sites + navigation +- **Delete page** - deletes the page. Page settings -------------- +~~~~~~~~~~~~~ -The screenshot below give you a quick overview of the basic settings dialogs for your page. +The screenshot below give you a quick overview of the basic settings dialogs for your +page. -We will see them in more detail when we create your page, but here are some important information: +We will see them in more detail when we create your page, but here are some important +information: -* **Title:** field dedicated to the title of your page that you enter when creating your page. -* **Slug:** automatically generated, it is what appears at the end of the URL. +- **Title:** field dedicated to the title of your page that you enter when creating your + page. +- **Slug:** automatically generated, it is what appears at the end of the URL. -You will probably not use the advanced settings because they are mainly used for redirects. +You will probably not use the advanced settings because they are mainly used for +redirects. .. image:: ./images/02-page-settings.jpg - :alt: The page settings dialogue + :alt: The page settings dialogue -Note that the page settings are available separately for all languages of the page. Use the language tabs to navigate between settings in different languages. +Note that the page settings are available separately for all languages of the page. Use +the language tabs to navigate between settings in different languages. The version menu -================ +---------------- .. image:: ./images/02-version-menu.jpg - :alt: The version menu - :scale: 50 + :alt: The version menu + :scale: 50 -The version menu allows you to manage current and past versions of the page you are viewing. The menu title includes the version number of the current page (counted by language) and its status: -* Draft: The copy you are currently editing -* Published: The version that currently is publicly visible. -* Unpublished: Any version that once was publicly visible but now is not any more. -* Archived: Any draft version that has been archived for later use. +The version menu allows you to manage current and past versions of the page you are +viewing. The menu title includes the version number of the current page (counted by +language) and its status: * Draft: The copy you are currently editing * Published: The +version that currently is publicly visible. * Unpublished: Any version that once was +publicly visible but now is not any more. * Archived: Any draft version that has been +archived for later use. You can perform the following actions: -* **Manage versions...** - get a list of all versions of this page in the sidebar. -* **Compare to version ...** - get a visual comparison on how the currently viewed version differs from any other version of the pasge. Difference are highlighted by colors either on the page or the page's source code. -* **Discard Changes** - makes all changes of the current draft undone - +- **Manage versions...** - get a list of all versions of this page in the sidebar. +- **Compare to version ...** - get a visual comparison on how the currently viewed + version differs from any other version of the pasge. Difference are highlighted by + colors either on the page or the page's source code. +- **Discard Changes** - makes all changes of the current draft undone The language menu -================= +----------------- .. image:: ./images/02-language-menu.jpg - :alt: The language menu - :scale: 50 + :alt: The language menu + :scale: 50 -The "Language" menu allows you to switch between the different language versions on the page you are viewing, and to manage the different translations. +The "Language" menu allows you to switch between the different language versions on the +page you are viewing, and to manage the different translations. -You can add a missing translation, delete an existing one or copy all plugins and their content from an existing translation to the current one. +You can add a missing translation, delete an existing one or copy all plugins and their +content from an existing translation to the current one. The action buttons -================== +------------------ On the right hand side are the action buttons. -* The **Create** button opens up the content creation wizard which allows you to easily create a new page or potentially other content elements installed at your site. -* The **Edit** button to open the page to make changes in editing mode, (appearance of the structure menu & possibility to double-click to modify the content), -* The **New Draft** button to create a new draft copy of the page end open it in edit mode. -* The **Preview** button switches to the preview mode. Here, no changes are possible. Also works for non-public content, such as unpublished pages. -* The **View published** button redirects to the currently visible version of the page. -* The **Publish** button which makes the current draft the new published content. A previously published version of the page becomes unpublished. - +- The **Create** button opens up the content creation wizard which allows you to easily + create a new page or potentially other content elements installed at your site. +- The **Edit** button to open the page to make changes in editing mode, (appearance of + the structure menu & possibility to double-click to modify the content), +- The **New Draft** button to create a new draft copy of the page end open it in edit + mode. +- The **Preview** button switches to the preview mode. Here, no changes are possible. + Also works for non-public content, such as unpublished pages. +- The **View published** button redirects to the currently visible version of the page. +- The **Publish** button which makes the current draft the new published content. A + previously published version of the page becomes unpublished. diff --git a/user-guide/source/tutorial/03-sidebar.rst b/user-guide/source/tutorial/03-sidebar.rst index 4564769..c4fda4d 100644 --- a/user-guide/source/tutorial/03-sidebar.rst +++ b/user-guide/source/tutorial/03-sidebar.rst @@ -1,15 +1,21 @@ .. _sidebar: Administration side bar -####################### +======================= Introduction -============ +------------ -When you click on "Administration" in the project menu, the administration or admin window opens. It covers most the content of your page. If you want to go back to your page, just click the close button or into the area outside the side bar. It covers the full administration interface of your site, including those added by django CMS. Depending on the modules installed on your site, its content may vary. It is identical to the content on the sites admin pages. +When you click on "Administration" in the project menu, the administration or admin +window opens. It covers most the content of your page. If you want to go back to your +page, just click the close button or into the area outside the side bar. It covers the +full administration interface of your site, including those added by django CMS. +Depending on the modules installed on your site, its content may vary. It is identical +to the content on the sites admin pages. -From this page, you can access the different administration sections of your site: management of pages, media files, users, ... +From this page, you can access the different administration sections of your site: +management of pages, media files, users, ... .. image:: ./images/03-sidebar.jpg - :alt: Example sidebar - :width: 800 + :alt: Example sidebar + :width: 800 diff --git a/user-guide/source/tutorial/04-filer.rst b/user-guide/source/tutorial/04-filer.rst index 56b8fd8..e661843 100644 --- a/user-guide/source/tutorial/04-filer.rst +++ b/user-guide/source/tutorial/04-filer.rst @@ -1,32 +1,41 @@ - The media library -################# +================= -The Media library allows you to access all your files, folders and images on your site. You reach the media library through the Administration menu entry in the project menu. It opens in the sidebar. +The Media library allows you to access all your files, folders and images on your site. +You reach the media library through the Administration menu entry in the project menu. +It opens in the sidebar. -By accessing it, you will be able to modify the titles, alt tags, captions and other information of your images, and also manage your folders and files. +By accessing it, you will be able to modify the titles, alt tags, captions and other +information of your images, and also manage your folders and files. Access the Media library -======================== +------------------------ + To manage the files on your site, look for the Filer section and click on "Folders": .. image:: ./images/04-filer-section.jpg - :scale: 50 - :alt: The filer section of the admin sidebar contains the media library + :scale: 50 + :alt: The filer section of the admin sidebar contains the media library Description of the Media library -================================ +-------------------------------- Media files live in folders just like in a regular file system. -The greyed out "Unsorted uploads" file contains all the images that do not belong to any folder and that have been directly uploaded to a CMS page or a blog post. +The greyed out "Unsorted uploads" file contains all the images that do not belong to any +folder and that have been directly uploaded to a CMS page or a blog post. -The blue folder "Blog" might contain all your picture folders used in your blog. You will be able to manage all the photo folders, add or delete them... +The blue folder "Blog" might contain all your picture folders used in your blog. You +will be able to manage all the photo folders, add or delete them... .. warning:: - Important: Before deleting a folder or an image, make sure that the contents of the folder or the image are not used on your site. If, for example, you delete an image while it is present in an article, it will disappear from this same article. + Important: Before deleting a folder or an image, make sure that the contents of the + folder or the image are not used on your site. If, for example, you delete an image + while it is present in an article, it will disappear from this same article. .. warning:: - Would you like to see more content here? Please `join us on Slack `_ and the Slack ``#workgroup-documentation`` to add content here. + Would you like to see more content here? Please `join us on Slack + `_ and the Slack ``#workgroup-documentation`` to + add content here. diff --git a/user-guide/source/tutorial/05-pagetree.rst b/user-guide/source/tutorial/05-pagetree.rst index b086781..5d649c0 100644 --- a/user-guide/source/tutorial/05-pagetree.rst +++ b/user-guide/source/tutorial/05-pagetree.rst @@ -1,81 +1,113 @@ .. _pagetree: The page tree structure -####################### +======================= -The tree structure of your site allows you to access all your pages. Many features and information are present in this part of your site. To better understand them, we suggest you look at how to access your tree structure, and understand the principles that are linked to it and its features. +The tree structure of your site allows you to access all your pages. Many features and +information are present in this part of your site. To better understand them, we suggest +you look at how to access your tree structure, and understand the principles that are +linked to it and its features. See the page tree -================= +----------------- -To access the tree structure of your site, go to the project menu (which has the name of your site, or "example.com" on the screenshots here), and choose "Pages...". The side bar opens and shows the complete tree structure of your site. That is to say, all the pages that make up your site: visible and non-visible, pages and sub-pages, published or not. +To access the tree structure of your site, go to the project menu (which has the name of +your site, or "example.com" on the screenshots here), and choose "Pages...". The side +bar opens and shows the complete tree structure of your site. That is to say, all the +pages that make up your site: visible and non-visible, pages and sub-pages, published or +not. -Alternatively, you can reach the page tree by clicking "Page contents" in the admin sidebar, which you find in the "Django CMS" section. +Alternatively, you can reach the page tree by clicking "Page contents" in the admin +sidebar, which you find in the "Django CMS" section. Principles of the parent, child and sibling pages -================================================= +------------------------------------------------- -This section is intended to give you a better understanding of what is meant by page inheritance and the names given to it. +This section is intended to give you a better understanding of what is meant by page +inheritance and the names given to it. -The page tree structure is divided into different sections: these are the pages at different levels. Each page can be nested in another one, i.e. a page can contain several sub-pages. This page is then called the "parent page" and its sub-pages are its "child pages". A child page can also have its own child pages. The idea is to organize your site in several different levels so that it is clearer for the user. +The page tree structure is divided into different sections: these are the pages at +different levels. Each page can be nested in another one, i.e. a page can contain +several sub-pages. This page is then called the "parent page" and its sub-pages are its +"child pages". A child page can also have its own child pages. The idea is to organize +your site in several different levels so that it is clearer for the user. To better understand, let us take the image of a tree as a metaphor: -* Your **home page** is the trunk, it presents all the thematic pages of your site. -* The **top-level pages** are the branches of your tree and have other small branches. We call these top-level pages "parent pages". -* The small branches correspond to the **child pages** of your top-level pages (the "parents"). Each parent page may or may not have child pages, just as the branch of a tree may or may not have smaller branches. -* The leaves of your tree represent the content of your pages or the sub-pages of your child pages, which do not have any child pages of their own. +- Your **home page** is the trunk, it presents all the thematic pages of your site. +- The **top-level pages** are the branches of your tree and have other small branches. + We call these top-level pages "parent pages". +- The small branches correspond to the **child pages** of your top-level pages (the + "parents"). Each parent page may or may not have child pages, just as the branch of a + tree may or may not have smaller branches. +- The leaves of your tree represent the content of your pages or the sub-pages of your + child pages, which do not have any child pages of their own. .. figure:: images/05-pagetree.jpg - :alt: The page tree structure of django CMS + :alt: The page tree structure of django CMS - The page tree structure: Related pages, child and sibling pages. A small branch is composed of pages 3, 4 and 5. The leaves are in this example are pages 2, 4 and 5. + The page tree structure: Related pages, child and sibling pages. A small branch is + composed of pages 3, 4 and 5. The leaves are in this example are pages 2, 4 and 5. -Each page is thus nested in the others when they have a common point: all your blog posts correspond to the parent page "Blog" for example. All your pages having the same the same central goal can be grouped together in a group and form the set of child pages of a parent page bearing the name of this topic. Thus, your parent page allows access to the content of your daughter pages and helps the user to better find his way around your site in relation to what he is looking for and wants to do. +Each page is thus nested in the others when they have a common point: all your blog +posts correspond to the parent page "Blog" for example. All your pages having the same +the same central goal can be grouped together in a group and form the set of child pages +of a parent page bearing the name of this topic. Thus, your parent page allows access to +the content of your daughter pages and helps the user to better find his way around your +site in relation to what he is looking for and wants to do. -As for a sibling page, it is simply a page at the same level as those around it in the tree. In a group of child pages, all pages are siblings. The same applies to parent pages. +As for a sibling page, it is simply a page at the same level as those around it in the +tree. In a group of child pages, all pages are siblings. The same applies to parent +pages. Managing the page tree -====================== +---------------------- -The page tree is a list of all the pages of your site. It gives you an overview of your pages and their status. +The page tree is a list of all the pages of your site. It gives you an overview of your +pages and their status. By default, the following information is displayed: .. image:: ./images/05-pagetree-form.jpg - :alt: The django CMS page tree form + :alt: The django CMS page tree form From left to right, you will find the following items: 1. The **language menu** which decides which language version of the page tree you see 2. The dotted bar on the left to **move the pages** using Drag & Drop -3. The **hide arrow**, present only in the case of a parent page. It shows or hides the page's child pages. -4. The **title of the page** in the selected language. If this says "Empty title" there is no version of that page in the selected language, yet. -5. The **root indicator** (house) indicating which page is presented at the root URL of the site. A puzzle symbol at this place indicates that the page is handled by a third-party application. +3. The **hide arrow**, present only in the case of a parent page. It shows or hides the + page's child pages. +4. The **title of the page** in the selected language. If this says "Empty title" there + is no version of that page in the selected language, yet. +5. The **root indicator** (house) indicating which page is presented at the root URL of + the site. A puzzle symbol at this place indicates that the page is handled by a + third-party application. 6. The **eye icon** allows you to preview the page 7. The **publication status menu** menu. Its color provides the following information: - * **Blank**: the translation of the page into this language does not exist. - * **White with blue border**: An unpublished draft of the page exists. There is not public version of the page. - * **Green**: the translation exists and the page is published, - * **Blue**: changes on the page have not been published. If you go to this page, the button at the top right will suggest you to publish the changes so that they are visible to the user. + - **Blank**: the translation of the page into this language does not exist. + - **White with blue border**: An unpublished draft of the page exists. There is + not public version of the page. + - **Green**: the translation exists and the page is published, + - **Blue**: changes on the page have not been published. If you go to this page, + the button at the top right will suggest you to publish the changes so that + they are visible to the user. 8. **"Menu"** indicates whether the page appears in the navigation menu of your site or not, - * Green / check: the page is visible in the navigation menu - * Gray / unchecked: the page does not appear + - Green / check: the page is visible in the navigation menu + - Gray / unchecked: the page does not appear 9. The **settings button** opens the page settings. 10. The **add button** adds a child page. -11. The **hamburger context menu** offers additional actions: - * Copy - * Cut - * Paste - * Delete... - * Set as home - * Advanced settings - * Miscellaneous information: the date of the last change, the access (restricted or not), the author of the last modifications. +11. The **hamburger context menu** offers additional actions: * Copy * Cut * Paste * + Delete... * Set as home * Advanced settings * Miscellaneous information: the date of + the last change, the access (restricted or not), the author of the last + modifications. -At the top right is a small menu, composed of a search button allowing you to find a specific page in your tree, a "..." button to choose the site whose tree you want to see (in many installations you will only see one site), and a button to add a new page. +At the top right is a small menu, composed of a search button allowing you to find a +specific page in your tree, a "..." button to choose the site whose tree you want to see +(in many installations you will only see one site), and a button to add a new page. -At the bottom right there is the legend with a complete list of all symbols used in the page tree view. Open it by clicking on the information icon: +At the bottom right there is the legend with a complete list of all symbols used in the +page tree view. Open it by clicking on the information icon: .. image:: ./images/05-pagetree-legend.jpg - :scale: 50 - :alt: Legend for the page tree + :scale: 50 + :alt: Legend for the page tree diff --git a/user-guide/source/tutorial/06-content.rst b/user-guide/source/tutorial/06-content.rst index 5ede463..1bb6e7e 100644 --- a/user-guide/source/tutorial/06-content.rst +++ b/user-guide/source/tutorial/06-content.rst @@ -1,76 +1,113 @@ .. _content: -########################### Creating places for content -########################### +=========================== -Content needs a place to live. Typically those are pages, but you also may have other content models, like aliases (chunks of content that are re-used elsewhere) or blog posts. +Content needs a place to live. Typically those are pages, but you also may have other +content models, like aliases (chunks of content that are re-used elsewhere) or blog +posts. We will work with pages in this guide. Create a page -############# +------------- To create a new page, you have three options: -1. Go to the **project menu**, select "Pages...". The sidebar will appear. Click on the button "New page" to open the page dialog box. +1. Go to the **project menu**, select "Pages...". The sidebar will appear. Click on the + button "New page" to open the page dialog box. +2. Use the **wizard** by clicking on the "Create" button at the top right of the + toolbar. The wizard dialog appears, where you can select "New page" or "New sub page" -2. Use the **wizard** by clicking on the "Create" button at the top right of the toolbar. The wizard dialog appears, where you can select "New page" or "New sub page" - .. image:: ./images/06-wizard-1.jpg - :alt: Step 1 of the wizard dialog + .. image:: ./images/06-wizard-1.jpg + :alt: Step 1 of the wizard dialog -3. In the **"Page" menu**, select "Create a page" then "New page..." (or "New sub-page...). The page dialog box appears. +3. In the **"Page" menu**, select "Create a page" then "New page..." (or "New + sub-page...). The page dialog box appears. -The page dialog is more extensive than the wizard dialog and contains all elements of the page settings. +The page dialog is more extensive than the wizard dialog and contains all elements of +the page settings. .. image:: ./images/06-create-page.jpg - :alt: aAge dialog box + :alt: aAge dialog box -In the page dialog box, give a title and possibly a menu and page title then save. The slug field will be filled automatically based on the page title. Of course, you can manually change it. +In the page dialog box, give a title and possibly a menu and page title then save. The +slug field will be filled automatically based on the page title. Of course, you can +manually change it. -Your newly created page is displayed, as well as the Django CMS menu/toolbar with the main content management tools. A newly created page is empty. Adding content is done via the structure board, in the upper right corner. +Your newly created page is displayed, as well as the Django CMS menu/toolbar with the +main content management tools. A newly created page is empty. Adding content is done via +the structure board, in the upper right corner. -The color, the size of the text... everything is generated automatically according to the page template of your site which in turn should be based on your individual graphics design. To change the design, there are options to modify the page template. If you want to change the design, talk to the developers to review it. +The color, the size of the text... everything is generated automatically according to +the page template of your site which in turn should be based on your individual graphics +design. To change the design, there are options to modify the page template. If you want +to change the design, talk to the developers to review it. .. _page-settings: Change page settings -#################### +-------------------- To view the page settings, go to "Page Settings..." in the Page menu. -These are the same parameters that are displayed when you create a page using the page dialog box. You can also access them by selecting the settings icon that appears in the page tree. +These are the same parameters that are displayed when you create a page using the page +dialog box. You can also access them by selecting the settings icon that appears in the +page tree. Required fields -=============== +~~~~~~~~~~~~~~~ -* **Title**: it will be used by the template of your site and displayed at the top of the page, in the tab of the site on the browser, and in the favorites. Search engines will also use it. It is therefore a field that must be filled in. - -* **Slug**: this is part of the URL of your page. In general, you will want it to reflect the title of your page, and it will be automatically generated from it in an appropriate format. Keep in mind that it is always valuable to keep your slugs as short and sweet / pleasant / concise as possible. +- **Title**: it will be used by the template of your site and displayed at the top of + the page, in the tab of the site on the browser, and in the favorites. Search engines + will also use it. It is therefore a field that must be filled in. +- **Slug**: this is part of the URL of your page. In general, you will want it to + reflect the title of your page, and it will be automatically generated from it in an + appropriate format. Keep in mind that it is always valuable to keep your slugs as + short and sweet / pleasant / concise as possible. .. note:: - For your SEO, it is essential that the title and slug of your page contain words related to the content of your page. + For your SEO, it is essential that the title and slug of your page contain words + related to the content of your page. Optional fields -=============== -* **Menu title**: If set this is used in your site's navigation menu otherwise the title field of the page is used. This useful if the entire title is too long to be used in navigation. For example, the title "Partner Company:Our Story" will be far too long to work well in the navigation menu, especially for your users on smartphones. "Our Story" would make a more appropriate menu title. -* **Page title**: If set it replaces the title which is displayed in search engine results and in the browser tab. +~~~~~~~~~~~~~~~ + +- **Menu title**: If set this is used in your site's navigation menu otherwise the title + field of the page is used. This useful if the entire title is too long to be used in + navigation. For example, the title "Partner Company:Our Story" will be far too long to + work well in the navigation menu, especially for your users on smartphones. "Our + Story" would make a more appropriate menu title. +- **Page title**: If set it replaces the title which is displayed in search engine + results and in the browser tab. Brief review of the different title fields -========================================== +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -1. The **title** field is mandatory, it is the default title that is displayed on your page. It contains the keywords and is reused for menus and as page title of those fields do not overwrite it. +1. The **title** field is mandatory, it is the default title that is displayed on your + page. It contains the keywords and is reused for menus and as page title of those + fields do not overwrite it. 2. The **menu title** is only used in menus where titles should be shorter. -3. The **page title** appears in the search engine results and in the browser tab. It is longer, and contains a maximum of keywords. Be careful, however, not to go too far beyond the 60 characters, which seems to be the current display limit on Google. +3. The **page title** appears in the search engine results and in the browser tab. It is + longer, and contains a maximum of keywords. Be careful, however, not to go too far + beyond the 60 characters, which seems to be the current display limit on Google. URL options -=========== +~~~~~~~~~~~ -The URL options appear as a section a bit down in the page settings dialog. You might need to click "show" to make them visible. +The URL options appear as a section a bit down in the page settings dialog. You might +need to click "show" to make them visible. .. image:: ./images/06-url-options.jpg - :alt: URL options in the page settings dialog - -* **Overwrite URL**: allows you to modify the URL. By default, the URL of the page is the slug of your current page, placed after the slug of its parent pages. For example, its default URL could be: ``/a-propos/company/our-vision/``. Overwriting the URL would allow you to shorten it to ``/our-vision/``, even though the page still keeps its parents and children organized in the same way (About page, Company daughter page, Our Vision grandchild page). We do not recommend using this function. -* **Redirect**: Allows you to redirect the user to a different page. This is useful if you've moved content to another page but don't want to break the URL that your users may have bookmarked or affect the rank of that page in search engine results. + :alt: URL options in the page settings dialog + +- **Overwrite URL**: allows you to modify the URL. By default, the URL of the page is + the slug of your current page, placed after the slug of its parent pages. For example, + its default URL could be: ``/a-propos/company/our-vision/``. Overwriting the URL would + allow you to shorten it to ``/our-vision/``, even though the page still keeps its + parents and children organized in the same way (About page, Company daughter page, Our + Vision grandchild page). We do not recommend using this function. +- **Redirect**: Allows you to redirect the user to a different page. This is useful if + you've moved content to another page but don't want to break the URL that your users + may have bookmarked or affect the rank of that page in search engine results. diff --git a/user-guide/source/tutorial/07-plugins.rst b/user-guide/source/tutorial/07-plugins.rst index 91affa6..7d2be5b 100644 --- a/user-guide/source/tutorial/07-plugins.rst +++ b/user-guide/source/tutorial/07-plugins.rst @@ -1,115 +1,144 @@ .. _plugins: -################## Filling in content -################## +================== -Now that you have created a place where your content can live, you can start filling in actual content. Like the page tree, content is structured in so called "plugins" which live in plugin trees inside placeholders. +Now that you have created a place where your content can live, you can start filling in +actual content. Like the page tree, content is structured in so called "plugins" which +live in plugin trees inside placeholders. Structure board -############### +--------------- -Your page will have one or more placeholders to fill with content. They are displayed in the **structure board**. +Your page will have one or more placeholders to fill with content. They are displayed in +the **structure board**. -To add plugins to your page (or alias, or blog), you need go to open the structure board by clicking the button on the far right side of the menu bar. +To add plugins to your page (or alias, or blog), you need go to open the structure board +by clicking the button on the far right side of the menu bar. .. image:: ./images/07-structure-toggle.jpg - :alt: Toggle button for the structure board - :scale: 50 + :alt: Toggle button for the structure board + :scale: 50 -There are different types of plugins for adding content, each with a specific purpose. The ones you will mainly need are the "classic" rich text, image, video, link and button plugins. +There are different types of plugins for adding content, each with a specific purpose. +The ones you will mainly need are the "classic" rich text, image, video, link and button +plugins. .. note:: - Which plugins are available on your site strongly depends on the installation. Take this guide as a blueprint on how to interact with plugins. Even if you have different plugin options installed the editing process is always the same. + Which plugins are available on your site strongly depends on the installation. Take + this guide as a blueprint on how to interact with plugins. Even if you have + different plugin options installed the editing process is always the same. -Once you have clicked on the structure board button, the structure board will open on the right side of your browser window. It will show one or more placeholders. +Once you have clicked on the structure board button, the structure board will open on +the right side of your browser window. It will show one or more placeholders. .. image:: ./images/07-structure-board.jpg - :alt: django CMS structure board - :scale: 50 + :alt: django CMS structure board + :scale: 50 Adding plugins -############## +-------------- -To add content to a page, click on the button . A dialog box will open, showing you the list of content you can add. Make your choice, a new dialog box opens. +To add content to a page, click on the button . A dialog box will open, showing you the +list of content you can add. Make your choice, a new dialog box opens. .. image:: ./images/07-add-plugin.jpg - :scale: 50 - :alt: Select a plugin to add + :scale: 50 + :alt: Select a plugin to add -Fill in the fields (in the container example below you do not have to fill any fields - all are optional), and save. The new content is displayed on your page. +Fill in the fields (in the container example below you do not have to fill any fields - +all are optional), and save. The new content is displayed on your page. .. image:: ./images/07-add-container.jpg - :scale: 50 - :alt: Add container dialog box + :scale: 50 + :alt: Add container dialog box .. note:: - The exact content of the add or edit plugin depends on the plugin itself. The container plugin in the example is one of many plugins provided by the django CMS Frontend package which are designed to structure your page. + The exact content of the add or edit plugin depends on the plugin itself. The + container plugin in the example is one of many plugins provided by the django CMS + Frontend package which are designed to structure your page. - Those plugins do have a set of tabs (colored in blue) at the top of the dialog and offer a wide set of design options, most of which are optional. + Those plugins do have a set of tabs (colored in blue) at the top of the dialog and + offer a wide set of design options, most of which are optional. Repeat the operation as many times as you want and for as much content as you want. -If you want to move content to arrange their layout, for example to move an image before or after text, use the "drag & drop" function of the CMS via the notch on the left of the content type. +If you want to move content to arrange their layout, for example to move an image before +or after text, use the "drag & drop" function of the CMS via the notch on the left of +the content type. +You can also add content to change your layout; some of this content is nestable (you +can put text in columns, which are themselves inserted in a section). -You can also add content to change your layout; some of this content is nestable (you can put text in columns, which are themselves inserted in a section). - -If this element allows the addition of nestable content, the add plugin button will be available at the same level as the module title. The triangle icon will appear next to the dotted line of the drag and drop button to show or hide the nested content: +If this element allows the addition of nestable content, the add plugin button will be +available at the same level as the module title. The triangle icon will appear next to +the dotted line of the drag and drop button to show or hide the nested content: .. image:: ./images/07-nested-plugins.jpg - :scale: 50 - :alt: Nested plugins in a placeholder + :scale: 50 + :alt: Nested plugins in a placeholder .. tip:: - If you **hover** over the structure menu items while pressing the **SHIFT** key, the content displayed on the CMS page will be highlighted, so you can see what each plugin corresponds to. + If you **hover** over the structure menu items while pressing the **SHIFT** key, the + content displayed on the CMS page will be highlighted, so you can see what each + plugin corresponds to. Editing plugins -############### +--------------- You can change existing plugins by either -* **double clicking** on the content in the page (when in edit mode) -* **clicking the pencil icon** of the plugin in the structure board. +- **double clicking** on the content in the page (when in edit mode) +- **clicking the pencil icon** of the plugin in the structure board. Editing works exactly like creating a plugin - Integrating content -################### +------------------- -When you add content to your page, you may want to integrate text, a video, clickable buttons or links into your text. +When you add content to your page, you may want to integrate text, a video, clickable +buttons or links into your text. Text -==== +~~~~ -django CMS includes a rich text editor. Its interface is particularly simple, since it only consists of the text you want to enter: +django CMS includes a rich text editor. Its interface is particularly simple, since it +only consists of the text you want to enter: .. image:: ./images/07-ckeditor.jpg - :alt: django CMS' integrated rich text editor + :alt: django CMS' integrated rich text editor .. tip:: - If your installation has inline editing enabled, you can even edit text right on the web page if the pencil button in the toolbar is activated: + If your installation has inline editing enabled, you can even edit text right on the + web page if the pencil button in the toolbar is activated: - .. image:: ./images/07-inline-editing.jpg - :alt: django CMS text inline editing + .. image:: ./images/07-inline-editing.jpg + :alt: django CMS text inline editing .. tip:: - All plugins show a few words of summary in the plugin tree. Those plugin trees can get huge, though. To keep an overview, use a feature of the Container plugin: + All plugins show a few words of summary in the plugin tree. Those plugin trees can + get huge, though. To keep an overview, use a feature of the Container plugin: - The title field is a text field to briefly describe the container content. It will be displayed in the plugin tree. It is a good practice to use separate containers for different sections of your page and fill the title for quick navigation in the plugin tree. + The title field is a text field to briefly describe the container content. It will + be displayed in the plugin tree. It is a good practice to use separate containers + for different sections of your page and fill the title for quick navigation in the + plugin tree. -Some plugins can even be added directly to a text plugin using the "CMS Plugins" menu within the text editor. This is useful for adding dynamic links to your text. Dynamic links are links to other pages of your site which - should the destination change its URL - will be automatically kept up-to-date. +Some plugins can even be added directly to a text plugin using the "CMS Plugins" menu +within the text editor. This is useful for adding dynamic links to your text. Dynamic +links are links to other pages of your site which - should the destination change its +URL - will be automatically kept up-to-date. .. image:: ./images/07-text-enabled-plugins.jpg - :alt: The CMS Plugins menu in the rich text editor - + :alt: The CMS Plugins menu in the rich text editor .. warning:: - Would you like to see more content here, e.g. on images, videos, links and buttons? Please `join us on Slack `_ and the Slack ``#workgroup-documentation`` to add content here. + Would you like to see more content here, e.g. on images, videos, links and buttons? + Please `join us on Slack `_ and the Slack + ``#workgroup-documentation`` to add content here. diff --git a/user-guide/source/tutorial/08-publishing.rst b/user-guide/source/tutorial/08-publishing.rst index e138c16..f0c9b31 100644 --- a/user-guide/source/tutorial/08-publishing.rst +++ b/user-guide/source/tutorial/08-publishing.rst @@ -1,89 +1,108 @@ .. _publishing: -################## Publishing content -################## +================== .. include:: ../versioning-note.include -Once you have finished filling in your newly created page (or blog post), it is saved as a draft. It will not be published until you decide to do so. As an editor, you can view drafts, but any site visitors will only see published pages. +Once you have finished filling in your newly created page (or blog post), it is saved as +a draft. It will not be published until you decide to do so. As an editor, you can view +drafts, but any site visitors will only see published pages. -To publish a page, click on the highlighted "Publish" button in the toolbar. This button is visible in the page's edit mode. (If there is a highlighted "Edit" button instead, click it first to get to edit mode.) +To publish a page, click on the highlighted "Publish" button in the toolbar. This button +is visible in the page's edit mode. (If there is a highlighted "Edit" button instead, +click it first to get to edit mode.) .. image:: ./images/08-publish-button.jpg - :scale: 50 - :alt: The version menu showing "published" state. + :scale: 50 + :alt: The version menu showing "published" state. -When published you will be taken to the published page or the "manage versions" dialog, depending on the setup of your site. If you're taken to the manage versions dialog, click on the eye button of the top listed version to get back to the page you just published. +When published you will be taken to the published page or the "manage versions" dialog, +depending on the setup of your site. If you're taken to the manage versions dialog, +click on the eye button of the top listed version to get back to the page you just +published. -You will see in the toolbar that the version menu now shows that the content is "published". +You will see in the toolbar that the version menu now shows that the content is +"published". .. image:: ./images/08-version-menu.jpg - :scale: 50 - :alt: The version menu showing "published" state. - + :scale: 50 + :alt: The version menu showing "published" state. Version states -============== +-------------- -Since django CMS 4, pages and other publishable content can have more than the two states "draft" and "published". +Since django CMS 4, pages and other publishable content can have more than the two +states "draft" and "published". .. note:: - Versioning is managed by an optional package like django CMS Versioning. Your installation might manage versions differently. This guide assumes that django CMS Versioning is installed. -The **"published" state** marks the only version of the page that is currently visible to web site visitors. + Versioning is managed by an optional package like django CMS Versioning. Your + installation might manage versions differently. This guide assumes that django CMS + Versioning is installed. + +The **"published" state** marks the only version of the page that is currently visible +to web site visitors. The **"draft" state** of a page is the one which the editor can change. -Any version that has been published at any point in time will get the **"unpublished" state** once it is either unpublished manually or implicitly when another version of the page is published. +Any version that has been published at any point in time will get the **"unpublished" +state** once it is either unpublished manually or implicitly when another version of the +page is published. -Versions in the **"archived" state** have not been published but retained by a user for later use. +Versions in the **"archived" state** have not been published but retained by a user for +later use. -.. figure:: /images/version-states.png - :alt: Version states and the editing process +.. figure:: images/08-version-states.png + :alt: Version states and the editing process - This diagram summarizes the possible states and the actions which create a change in the state of a version. + This diagram summarizes the possible states and the actions which create a change in + the state of a version. Managing versions -================= +----------------- -To manage versions of the currently displayed page, go to the Version menu and select "Manage Versions...": +To manage versions of the currently displayed page, go to the Version menu and select +"Manage Versions...": .. image:: ./images/08-version-menu-open.jpg - :alt: open version menu - :scale: 50 + :alt: open version menu + :scale: 50 This opens the sidebar with the manage versions dialog: .. image:: ./images/08-manage-versions.jpg - :alt: Manage versions dialog + :alt: Manage versions dialog -You will see (a potentially long) list of all versions created, ever. On the right side of the list you see the action buttons. You can +You will see (a potentially long) list of all versions created, ever. On the right side +of the list you see the action buttons. You can -* **Pencil**: Go back to the **edit** view of a draft -* **Archive**: Archive a draft version for later re-use. -* **Antenna**: Publish a draft -* **Litter bin**: Delete a draft -* **Eye**: View an old version. Note: Those cannot be edited any more. -* **No-antenna**: Unpublish a currently public version -* **Undo**: Revert an archived or unpublished version into a new draft version +- **Pencil**: Go back to the **edit** view of a draft +- **Archive**: Archive a draft version for later re-use. +- **Antenna**: Publish a draft +- **Litter bin**: Delete a draft +- **Eye**: View an old version. Note: Those cannot be edited any more. +- **No-antenna**: Unpublish a currently public version +- **Undo**: Revert an archived or unpublished version into a new draft version Comparing versions -================== +------------------ -With many versions being available, it sometimes is difficult to keep track of changes. You can visually compare two versions by +With many versions being available, it sometimes is difficult to keep track of changes. +You can visually compare two versions by -* Either selecting two versions in the manage versions dialog and the choosing the "Compare versions" from the actions dropdown and hitting "Go". -* From the Version menu +- Either selecting two versions in the manage versions dialog and the choosing the + "Compare versions" from the actions dropdown and hitting "Go". +- From the Version menu An example of a visual comparison is shown here: .. image:: ./images/08-comparing-versions.jpg - :alt: Visual comparison of versions + :alt: Visual comparison of versions Added content is marked green, deleted content is marked red. .. tip:: - If you want to see the changes in the generate HTML code you can select "Source" in the upper right of the compare view. - + If you want to see the changes in the generate HTML code you can select "Source" in + the upper right of the compare view. diff --git a/user-guide/source/tutorial/images/08-version-states.png b/user-guide/source/tutorial/images/08-version-states.png new file mode 100644 index 0000000..d0b8af8 Binary files /dev/null and b/user-guide/source/tutorial/images/08-version-states.png differ diff --git a/user-guide/source/tutorial/index.rst b/user-guide/source/tutorial/index.rst index a1a51a5..6010645 100644 --- a/user-guide/source/tutorial/index.rst +++ b/user-guide/source/tutorial/index.rst @@ -1,14 +1,13 @@ .. _user-tutorial: -######## Tutorial -######## +======== .. include:: ../contribute-note.include -It's strongly recommended that you follow this tutorial step-by-step. It has -been designed to introduce you to the system in a methodical way, and each -step builds on the previous one. +It's strongly recommended that you follow this tutorial step-by-step. It has been +designed to introduce you to the system in a methodical way, and each step builds on the +previous one. .. toctree:: :maxdepth: 1 @@ -22,11 +21,15 @@ step builds on the previous one. 07-plugins 08-publishing -.. note:: **Touch-screen users** +.. note:: - django CMS supports touch-screen interfaces, though there are currently some limitations in - support. You will be able to complete the tutorial using a touch-screen device, but please - consult :ref:`touch`, and see the notes on :ref:`device-support`. + **Touch-screen users** + + django CMS supports touch-screen interfaces, though there are currently some + limitations in support. You will be able to complete the tutorial using a + touch-screen device, but please consult :ref:`touch`, and see the notes on + :ref:`device-support`. .. _django-cms-developers: https://groups.google.com/group/django-cms-developers -.. _freenode : http://freenode.net/ + +.. _freenode: http://freenode.net/