Add article documentation#906
Conversation
alexander-schranz
left a comment
alexander-schranz
left a comment
There was a problem hiding this comment.
Some text change suggestions. And I would reduce the headlines as this mostly to the deeplinks which we mostly will send when questions come up:
- ArticleBundle
- Webspace Configuration
- Groups
| By default, articles are not linked to a specific webspace. You can configure the default main | ||
| webspace and additional webspaces that articles are published to in | ||
| ``config/packages/sulu_article.yaml``. |
There was a problem hiding this comment.
articles are not linked to a specific webspace.
Think this is misleading.
I would maybe more go with something like "Articles are global objects like snippets, .... they can be in one or multiple webspace defined via the settings tab. To avoid duplicate content issue, visiting the article on additional webspace URL Sulu will automatically set a canonical tag to configured main webspace. By default an article main webspace is the first webspace (not sure about this) and is still available in all additional webspaces (not sure abou this).
| Default Main Webspace | ||
| ~~~~~~~~~~~~~~~~~~~~~ | ||
|
|
||
| The ``default_main_webspace`` option sets which webspace an article is assigned to by default. | ||
| It can be provided as a simple string (applies to all locales) or as a locale-keyed mapping: | ||
|
|
||
| .. code-block:: yaml | ||
|
|
||
| # config/packages/sulu_article.yaml | ||
|
|
||
| # Same default webspace for all locales | ||
| sulu_article: | ||
| default_main_webspace: my_webspace | ||
|
|
||
| .. code-block:: yaml | ||
|
|
||
| # config/packages/sulu_article.yaml | ||
|
|
||
| # Different default webspace per locale | ||
| sulu_article: | ||
| default_main_webspace: | ||
| default: my_webspace | ||
| de: my_webspace_de | ||
|
|
||
| The ``default`` key is used as a fallback for locales that have no explicit entry. | ||
|
|
||
| Default Additional Webspaces | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
There was a problem hiding this comment.
would not split this into seperate sections / headlines. The "Webspace Configuration" headline is enough:
Would create one code block show "Main" and "Additional" with single selection:
sulu_article:
default_main_webspace: my_webspace
default_additional_webspaces:
- my_second_webspace
- my_third_webspaceAnd one per locale:
sulu_article:
default_main_webspace:
default: my_webspace
de: my_webspace_de
default_additional_webspaces:
default:
- my_second_webspace
de:
- my_second_webspace_de| Migrating Existing Articles After Webspace Config Changes | ||
| ---------------------------------------------------------- | ||
|
|
||
| If you change ``default_main_webspace`` or ``default_additional_webspaces`` after articles have | ||
| already been created, the existing articles are **not updated automatically**. You need to create | ||
| a database migration that applies the new defaults to all articles where the editor has not | ||
| enabled "Customize webspace settings" (``customizeWebspaceSettings = false``). | ||
|
|
||
| **Updating the main webspace:** Update the ``mainWebspace`` column in | ||
| ``ar_article_dimension_contents`` for all rows where ``customizeWebspaceSettings`` is ``false``. | ||
|
|
||
| **Adding an additional webspace:** Insert a new row into | ||
| ``ar_article_dimension_content_additional_webspaces`` for every ``ar_article_dimension_contents`` | ||
| record where ``customizeWebspaceSettings`` is ``false``. The ``name`` column holds the webspace | ||
| key and ``article_dimension_content_id`` references the dimension content record. | ||
|
|
||
| **Removing an additional webspace:** Delete all rows from | ||
| ``ar_article_dimension_content_additional_webspaces`` that match the removed webspace key in the | ||
| ``name`` column and belong to a dimension content record where ``customizeWebspaceSettings`` | ||
| is ``false``. |
There was a problem hiding this comment.
Would put this into a .. note in the section above, it is related to Webspace Configuration and so should be part of that section not an own section.
| .. code-block:: json | ||
|
|
||
| // translations/admin.en.json | ||
| { |
There was a problem hiding this comment.
if use a JS comment maybe better use js here or move path to translation file into text above:
| .. code-block:: json | |
| // translations/admin.en.json | |
| { | |
| .. code-block:: js |
martinlagler
force-pushed
the
feature/article-docs
branch
from
7c3b7a8 to
8f63265
Compare
| webspaces. Each article has a main webspace and optionally one or more additional webspaces; | ||
| it is accessible via all of them. The active webspaces per article can be configured | ||
| individually in the article's **Settings** tab in the Sulu admin, or set globally via | ||
| ``config/packages/sulu_article.yaml``. Note that ``default_main_webspace`` is required when |
There was a problem hiding this comment.
@alexander-schranz Should I maybe put this Note that ``default_main_webspace`` is required when using the article bundle. also in a warning? As it's pretty important.
There was a problem hiding this comment.
👍 but its only required when there are multiple webspaces? Else the skeleton is would be broken by default or? https://github.com/sulu/skeleton/blob/3.0/config/packages/sulu_article.yaml
| Both options can be provided as a simple string/list (applies to all locales) or as a | ||
| locale-keyed mapping. The ``default`` key is used as a fallback for locales with no explicit | ||
| entry: |
There was a problem hiding this comment.
would not mention the structure here like locale-keyed mapping or simple string/list (applies to all locales) as that is clearer by look at the example below.
Would go with just something like:
Both options allow to set a seperate value also per locale.
2 participants
What's in this PR?
Documentation for the ArticleBundle, Groups, group translations, webspace configs.