diff --git a/.github/ISSUE_TEMPLATE/new-issue-form.yml b/.github/ISSUE_TEMPLATE/new-issue-form.yml index ec0be7e160..92f61cdc3e 100644 --- a/.github/ISSUE_TEMPLATE/new-issue-form.yml +++ b/.github/ISSUE_TEMPLATE/new-issue-form.yml @@ -17,6 +17,6 @@ body: id: description attributes: label: Description - description: Include include screenshots and any other helpful information. + description: Include screenshots and any other helpful information. validations: required: true diff --git a/.github/boring-cyborg.yml b/.github/boring-cyborg.yml new file mode 100644 index 0000000000..7ccb43e29e --- /dev/null +++ b/.github/boring-cyborg.yml @@ -0,0 +1,133 @@ +# boring-cyborg.yml +# https://probot.github.io/apps/boring-cyborg/ + +##### Labeler ########################################################################################################## +## Enable "labeler" for your PR that would add labels to PRs based on the paths that are modified in the PR. +#labelPRBasedOnFilePath: +# # Add 'label1' to any changes within 'example' folder or any subfolders +# label1: +# - example/**/* +# +# # Add 'label2' to any file changes within 'example2' folder +# label2: +# - example2/* +# +# # Complex: Add 'area/core' label to any change within the 'core' package +# area/core: +# - src/core/* +# - src/core/**/* +# +# # Add 'test' label to any change to *.spec.js files within the source dir +# test: +# - src/**/*.spec.js +# +# Various Flags to control behaviour of the "Labeler" +#labelerFlags: +# # If this flag is changed to 'false', labels would only be added when the PR is first created and not when existing +# # PR is updated. +# # The default is 'true' which means the labels would be added when PR is updated even if they were removed by the user +# labelOnPRUpdates: true + +##### Reviewer ######################################################################################################### +# Enable "Reviewer" for your PR that would add reviewers to PRs based on the labels that exist on the PR. +# You have the option to set a default reviewer that gets added to every PR, or you can omit that config variable to skip it. +addReviewerBasedOnLabel: + # add list of reviewers to add by default to all PRs + defaultReviewers: + - stevepiercy + # specify PR labels that you want to auto assign reviewers based on +# labels: +# label1: +# - tyler-mairose-sp +# - jordan-violet-sp +# label2: +# - kaxil + +##### Greetings ######################################################################################################## +# Comment to be posted to welcome users when they open their first PR +firstPRWelcomeComment: > + Thanks for submitting your first pull request! You are awesome! :hugs: + +
If you haven't done so already, read + [Plone's Code of Conduct](https://plone.org/foundation/about/materials/foundation-resolutions/code-of-conduct) + and [Contribute to documentation](https://6.docs.plone.org/contributing/documentation/index.html), + as this will greatly help the review process. + +
Welcome to the Plone community! :tada: + +# Comment to be posted to congratulate user on their first merged PR +firstPRMergeComment: > + Congratulations on your first merged pull request in this project! :tada: + + ![Congratulations](https://raw.githubusercontent.com/plone/documentation/fda4eadee4b0b71c4bcd0da739847444f74d3fc5/.github/images/congratulations.jpg) + +
Thank you for contributing, we are very proud of you! :heart: + +# Comment to be posted to on first time issues +firstIssueWelcomeComment: > + Thanks for opening your first issue here! + Your engagement is essential for open source projects, including Plone. :hugs: + +
If you haven't done so already, + read [Plone's Code of Conduct](https://plone.org/foundation/about/materials/foundation-resolutions/code-of-conduct). + Also please follow the issue template, as it helps both you and other community members contribute more effectively. + +
If your issue is a feature request, others may raise its prominence through + [feature voting](https://github.com/plone/documentation/issues?q=is%3Aissue%20state%3Aopen%20sort%3Areactions-%2B1-desc%20). + +
Welcome to the Plone community! :tada: + +###### IssueLink Adder ################################################################################################# +# Insert Issue (Jira/Github etc) link in PR description based on the Issue ID in PR title. +#insertIssueLinkInPrDescription: +# # specify the placeholder for the issue link that should be present in the description +# descriptionIssuePlaceholderRegexp: "^Issue link: (.*)$" +# matchers: +# # you can have several matches - for different types of issues +# # only the first matching entry is replaced +# jiraIssueMatch: +# # specify the regexp of issue id that you can find in the title of the PR +# # the match groups can be used to build the issue id (${1}, ${2}, etc.). +# titleIssueIdRegexp: \[(AIRFLOW-[0-9]{4})\] +# # the issue link to be added. ${1}, ${2} ... are replaced with the match groups from the +# # title match (remember to use quotes) +# descriptionIssueLink: "[${1}](https://issues.apache.org/jira/browse/${1}/)" +# docOnlyIssueMatch: +# titleIssueIdRegexp: \[(AIRFLOW-X{4})\] +# descriptionIssueLink: "`Document only change, no JIRA issue`" +# +###### Title Validator ################################################################################################# +# Verifies if commit/PR titles match the regexp specified +#verifyTitles: +# # Regular expression that should be matched by titles of commits or PR +# titleRegexp: ^\[AIRFLOW-[0-9]{4}\].*$|^\[AIRFLOW-XXXX\].*$ +# # If set to true, it will always check the PR title (as opposed to the individual commits). +# alwaysUsePrTitle: true +# # If set to true, it will only check the commit in case there is a single commit. +# # In case of multiple commits it will check PR title. +# # This reflects the standard behaviour of Github that for `Squash & Merge` GitHub +# # uses the PR title rather than commit messages for the squashed commit ¯\_(ツ)_/¯ +# # For single-commit PRs it takes the squashed commit message from the commit as expected. +# # +# # If set to false it will check all commit messages. This is useful when you do not squash commits at merge. +# validateEitherPrOrSingleCommitTitle: true +# # The title the GitHub status should appear from. +# statusTitle: "Title Validator" +# # A custom message to be displayed when the title passes validation. +# successMessage: "Validation successful!" +# # A custom message to be displayed when the title fails validation. +# # Allows insertion of ${type} (commit/PR), ${title} (the title validated) and ${regex} (the titleRegexp above). +# failureMessage: "Wrong ${type} title: ${title}" +# +###### PR/Branch Up-To-Date Checker #################################################################################### +## Check if the branch is up to date with master when certain files are modified +#checkUpToDate: +# # The default branch is "master", change the branch if you want to check against a different target branch +# targetBranch: master +# files: +# # File paths that you want to check for +# # In this example, it checks if the branch is up to date when alembic migrations are modified in the PR. +# # It helps avoid multiple heads in alembic migrations in a collaborative development project. +# - airflow/migrations/* +# - airflow/migrations/**/* +# - airflow/alembic.ini diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000000..0d08e261a2 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,11 @@ +# To get started with Dependabot version updates, you'll need to specify which +# package ecosystems to update and where the package manifests are located. +# Please see the documentation for all configuration options: +# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file + +version: 2 +updates: + - package-ecosystem: "github-actions" # See documentation for possible values + directory: "/" # Location of package manifests + schedule: + interval: "weekly" diff --git a/.github/images/congratulations.jpg b/.github/images/congratulations.jpg new file mode 100644 index 0000000000..f60a81079b Binary files /dev/null and b/.github/images/congratulations.jpg differ diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index ba6cd265ef..16258e7cfb 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -11,9 +11,9 @@ Thank you for your contribution to the Plone Documentation. Before submitting this pull request, please make sure you follow our guides: - [Contributing to Plone documentation](https://6.docs.plone.org/contributing/index.html) -- [Building and checking the quality of documentation](https://6.docs.plone.org/contributing/setup-build.html) -- [Authors guide](https://6.docs.plone.org/contributing/authors.html) -- [MyST reference](https://6.docs.plone.org/contributing/myst-reference.html) +- [Building and checking the quality of documentation](https://6.docs.plone.org/contributing/documentation/setup-build.html) +- [Authors guide](https://6.docs.plone.org/contributing/documentation/authors.html) +- [MyST reference](https://6.docs.plone.org/contributing/documentation/myst-reference.html) ## Issue number diff --git a/.github/workflows/build_deploy.yml b/.github/workflows/build_deploy.yml index e8bbdf4c94..9cf11ee24e 100644 --- a/.github/workflows/build_deploy.yml +++ b/.github/workflows/build_deploy.yml @@ -5,6 +5,9 @@ on: branches: - "6.0" +env: + node-version: 20.x + jobs: build_deploy: runs-on: ubuntu-latest @@ -12,13 +15,13 @@ jobs: name: docs.plone.org url: https://docs.plone.org steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v6 - name: Setup Graphviz - uses: ts-graphviz/setup-graphviz@v1 - - name: Set up Python 3.10 - uses: actions/setup-python@v4 + uses: ts-graphviz/setup-graphviz@v2 + - name: Set up Python 3.12 + uses: actions/setup-python@v6 with: - python-version: '3.10' + python-version: '3.12' cache: 'pip' - name: Install dependencies run: | @@ -35,31 +38,32 @@ jobs: - name: Prepare deploy run: make deploy - # node setup - - name: Use Node.js 16 - uses: actions/setup-node@v3 + - name: Use Node.js ${{ env.node-version }} + uses: actions/setup-node@v6 with: - node-version: '16' - - name: Install Yarn - run: npm install -g yarn - # node cache - - name: Get yarn cache directory path - id: yarn-cache-dir-path - working-directory: submodules/volto - run: echo "dir=$(yarn config get cacheFolder)" >> $GITHUB_OUTPUT - - uses: actions/cache@v3 - id: yarn-cache # use this to check for `cache-hit` (`steps.yarn-cache.outputs.cache-hit != 'true'`) + node-version: ${{ env.node-version }} + + - name: Enable corepack + shell: bash + run: | + npm i -g corepack@latest + corepack enable + + - name: Get pnpm store directory + shell: bash + run: | + echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV + + - uses: actions/cache@v5 + name: Setup pnpm cache with: - path: ${{ steps.yarn-cache-dir-path.outputs.dir }} - key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }} + path: ${{ env.STORE_PATH }} + key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }} restore-keys: | - ${{ runner.os }}-yarn- + ${{ runner.os }}-pnpm-store- - name: StoryBook build - run: | - cd submodules/volto - yarn install --immutable - yarn build-storybook -o ../../_build/html/storybook + run: make storybook - name: Deploy to server id: deploy diff --git a/.github/workflows/rtd-pr-preview.yml b/.github/workflows/rtd-pr-preview.yml new file mode 100644 index 0000000000..bf7bd5aef9 --- /dev/null +++ b/.github/workflows/rtd-pr-preview.yml @@ -0,0 +1,22 @@ +# .github/workflows/rtd-pr-preview.yml +name: readthedocs/actions +on: + pull_request_target: + types: + - opened + # Execute this action only on PRs that touch + # documentation files. + # paths: + # - "docs/**" + +permissions: + pull-requests: write + +jobs: + documentation-links: + runs-on: ubuntu-latest + steps: + - uses: readthedocs/actions/preview@v1 + with: + project-slug: "plone6" + single-version: "true" diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index f99fc8cab7..7fc4a35d54 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -6,12 +6,12 @@ jobs: if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.event.pull_request.base.repo.full_name runs-on: ubuntu-latest steps: - - uses: actions/checkout@v1 + - uses: actions/checkout@v6 - name: Set up Python ${{ matrix.python-version }} - uses: actions/setup-python@v4 + uses: actions/setup-python@v6 with: - python-version: "3.10" + python-version: "3.12" - name: Install dependencies run: | diff --git a/.github/workflows/update_submodule.yml b/.github/workflows/update_submodule.yml index 1161b2a0bd..a1a1001914 100644 --- a/.github/workflows/update_submodule.yml +++ b/.github/workflows/update_submodule.yml @@ -1,3 +1,4 @@ +# See https://github.com/plone/documentation/issues/1214 for current status name: Get latest version of submodules and push back to 6.0 branch on: @@ -8,7 +9,7 @@ jobs: runs-on: ubuntu-latest steps: # Checkout - - uses: actions/checkout@v3 + - uses: actions/checkout@v6 with: ref: 6.0 submodules: true diff --git a/.gitignore b/.gitignore index 82863e71d7..a825459902 100644 --- a/.gitignore +++ b/.gitignore @@ -1,19 +1,15 @@ # Dependencies -/bin -/include -/lib -/lib64 +/venv # Generated files -pyvenv.cfg /_build -/styles/Microsoft /share +/styles/Microsoft # symlinked from submodule -docs/volto -docs/plone.restapi docs/plone.api +docs/plone.restapi +docs/volto # editor files .vscode diff --git a/.gitmodules b/.gitmodules index 7e3c9e4d0d..0e7410d058 100644 --- a/.gitmodules +++ b/.gitmodules @@ -9,4 +9,4 @@ [submodule "submodules/plone.api"] path = submodules/plone.api url = https://github.com/plone/plone.api.git - branch = master + branch = main diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000000..7ebd03b0c7 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,25 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.com/platform/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the OS, Python version and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.12" + commands: + # Cancel building pull requests when there aren't changes in the docs directory or YAML file. + # You can add any other files or directories that you'd like here as well, + # like your docs requirements file, or other files that will change your docs build. + # + # If there are no changes (git diff exits with 0) we force the command to return with 183. + # This is a special exit code on Read the Docs that will cancel the build immediately. + - | + if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/6.0 -- docs/ Makefile .readthedocs.yaml requirements-initial.txt requirements.txt; + then + exit 183; + fi + - make rtd-pr-preview diff --git a/.vale.ini b/.vale.ini index f89759a516..df7f09b27f 100644 --- a/.vale.ini +++ b/.vale.ini @@ -10,3 +10,5 @@ Packages = Microsoft BasedOnStyles = Vale, Microsoft Microsoft.Contractions = suggestion Microsoft.Units = suggestion +; ignore MyST reference targets +TokenIgnores = \([a-zA-Z0-9._-]*\)= diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000000..a836b007c7 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,5 @@ +{ + "[markdown]": { + "editor.formatOnSave": false + } +} diff --git a/Makefile b/Makefile index 057129a659..492f479d40 100644 --- a/Makefile +++ b/Makefile @@ -5,10 +5,11 @@ SHELL = bash # You can set these variables from the command line. SPHINXOPTS ?= PAPER ?= +VALEOPTS ?= # Internal variables. -SPHINXBUILD = $(realpath bin/sphinx-build) -SPHINXAUTOBUILD = $(realpath bin/sphinx-autobuild) +SPHINXBUILD = "$(realpath venv/bin/sphinx-build)" +SPHINXAUTOBUILD = "$(realpath venv/bin/sphinx-autobuild)" DOCS_DIR = ./docs/ BUILDDIR = ../_build PAPEROPT_a4 = -D latex_paper_size=a4 @@ -29,116 +30,120 @@ clean: ## Clean docs build directory cd $(DOCS_DIR) && rm -rf $(BUILDDIR)/ .PHONY: distclean -distclean: ## Clean docs build directory and Python virtual environment - cd $(DOCS_DIR) && rm -rf $(BUILDDIR)/ - rm -rf ./bin/ ./lib/ ./lib64 ./include ./pyvenv.cfg - +distclean: clean ## Clean Python virtual environment and symlinks to submodules + rm -rf venv + rm docs/plone.api + rm docs/plone.restapi + rm docs/volto + @echo "Cleaned Python virtual environment and symlinks to submodules." + @echo -bin/python: - python3 -m venv . || virtualenv --clear --python=python3 . - bin/pip install -r requirements-initial.txt - bin/pip install -r requirements.txt +venv/bin/python: ## Setup up Python virtual environment and install requirements + python3 -m venv venv + venv/bin/pip install -r requirements-initial.txt + venv/bin/pip install -r requirements.txt + @echo "Installation of requirements completed." + @echo -docs/plone.api: - git submodule init; \ - git submodule update; \ - bin/pip install -e submodules/plone.api/"[test]"; \ +docs/plone.api: ## Setup plone.api docs + git submodule init + git submodule update ln -s ../submodules/plone.api/docs ./docs/plone.api - @echo @echo "Documentation of plone.api initialized." + @echo -docs/plone.restapi: - git submodule init; \ - git submodule update; \ - ln -s ../submodules/plone.restapi ./docs/plone.restapi +venv/plone.api-install: docs/plone.api + touch venv/plone.api-install + venv/bin/pip install plone.api -c submodules/plone.api/constraints.txt + venv/bin/pip install --no-deps -e submodules/plone.api/"[test]" + @echo "plone.api installed." @echo + +docs/plone.restapi: ## Setup plone.restapi docs + git submodule init + git submodule update + ln -s ../submodules/plone.restapi ./docs/plone.restapi @echo "Documentation of plone.restapi initialized." + @echo -docs/volto: - git submodule init; \ - git submodule update; \ +docs/volto: ## Setup Volto docs + git submodule init + git submodule update ln -s ../submodules/volto/docs/source ./docs/volto - @echo @echo "Documentation of volto initialized." + @echo -.PHONY: deps -deps: bin/python docs/volto docs/plone.restapi docs/plone.api ## Create Python virtual environment, install requirements, initialize or update the volto, plone.restapi, and plone.api submodules, and finally create symlinks to the source files. +ln-seven: ## Toggle the symlink to Seven + rm docs/volto + ln -s ../submodules/volto/docs ./docs/volto + @echo "Symlink to Volto changed to Seven." + @echo +ln-volto: ## Toggle the symlink to Volto + rm docs/volto + ln -s ../submodules/volto/docs/source ./docs/volto + @echo "Symlink to Seven changed to Volto." + @echo + +.PHONY: deps +deps: venv/bin/python docs/volto docs/plone.restapi venv/plone.api-install ## Create Python virtual environment, install requirements, initialize or update the volto, plone.restapi, and plone.api submodules, create symlinks to the source files, and finally install plone.api. .PHONY: html html: deps ## Build html cd $(DOCS_DIR) && $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + @echo .PHONY: manual manual: deps cd $(DOCS_DIR) && $(SPHINXBUILD) -b html -t manual . $(BUILDDIR)/manual + @echo "Build finished. The manual pages are in $(BUILDDIR)/manual." + @echo .PHONY: dirhtml dirhtml: deps cd $(DOCS_DIR) && $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + @echo .PHONY: singlehtml singlehtml: deps cd $(DOCS_DIR) && $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + @echo .PHONY: pickle pickle: deps cd $(DOCS_DIR) && $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo @echo "Build finished; now you can process the pickle files." + @echo .PHONY: json json: deps cd $(DOCS_DIR) && $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo @echo "Build finished; now you can process the JSON files." + @echo .PHONY: htmlhelp htmlhelp: deps cd $(DOCS_DIR) && $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo @echo "Build finished; now you can run HTML Help Workshop with the" \ ".hhp project file in $(BUILDDIR)/htmlhelp." - -.PHONY: qthelp -qthelp: deps - cd $(DOCS_DIR) && $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/MasteringPlone.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/MasteringPlone.qhc" - -.PHONY: devhelp -devhelp: deps - cd $(DOCS_DIR) && $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/MasteringPlone" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/MasteringPlone" - @echo "# devhelp" .PHONY: epub epub: deps cd $(DOCS_DIR) && $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + @echo .PHONY: latex latex: deps cd $(DOCS_DIR) && $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." @echo "Run \`make' in that directory to run these through (pdf)latex" \ "(use \`make latexpdf' here to do that automatically)." + @echo .PHONY: latexpdf latexpdf: deps @@ -146,26 +151,27 @@ latexpdf: deps @echo "Running LaTeX files through pdflatex..." $(MAKE) -C $(BUILDDIR)/latex all-pdf @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + @echo .PHONY: text text: deps cd $(DOCS_DIR) && $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo @echo "Build finished. The text files are in $(BUILDDIR)/text." + @echo .PHONY: man man: deps cd $(DOCS_DIR) && $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + @echo .PHONY: texinfo texinfo: deps cd $(DOCS_DIR) && $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." @echo "Run \`make' in that directory to run these through makeinfo" \ "(use \`make info' here to do that automatically)." + @echo .PHONY: info info: deps @@ -173,33 +179,34 @@ info: deps @echo "Running Texinfo files through makeinfo..." make -C $(BUILDDIR)/texinfo info @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + @echo .PHONY: changes changes: deps cd $(DOCS_DIR) && $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo @echo "The overview file is in $(BUILDDIR)/changes." + @echo .PHONY: linkcheck linkcheck: deps ## Run linkcheck cd $(DOCS_DIR) && $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo @echo "Link check complete; look for any errors in the above output " \ "or in $(BUILDDIR)/linkcheck/ ." + @echo .PHONY: linkcheckbroken linkcheckbroken: deps ## Run linkcheck and show only broken links cd $(DOCS_DIR) && $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck | GREP_COLORS='0;31' grep -wi "broken\|redirect" --color=always | GREP_COLORS='0;31' grep -vi "https://github.com/plone/volto/issues/" --color=always && if test $$? = 0; then exit 1; fi || test $$? = 1 - @echo @echo "Link check complete; look for any errors in the above output " \ "or in $(BUILDDIR)/linkcheck/ ." + @echo .PHONY: vale vale: deps ## Run Vale style, grammar, and spell checks - vale sync - vale --no-wrap $(VALEFILES) - @echo + venv/bin/vale sync + venv/bin/vale --no-wrap $(VALEOPTS) $(VALEFILES) @echo "Vale is finished; look for any errors in the above output." + @echo .PHONY: html_meta html_meta: deps ## Add meta data headers to all Markdown pages @@ -210,6 +217,7 @@ doctest: deps cd $(DOCS_DIR) && $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest @echo "Testing of doctests in the sources finished, look at the " \ "results in $(BUILDDIR)/doctest/output.txt." + @echo .PHONY: test test: clean linkcheckbroken ## Clean docs build, then run linkcheckbroken @@ -222,24 +230,27 @@ livehtml: deps ## Rebuild Sphinx documentation on changes, with live-reload in cd "$(DOCS_DIR)" && ${SPHINXAUTOBUILD} \ --ignore "*.swp" \ --port 8050 \ + --watch volto \ + --watch plone.api \ + --watch plone.restapi \ -b html . "$(BUILDDIR)/html" $(SPHINXOPTS) $(O) -.PHONY: netlify -netlify: +.PHONY: rtd-pr-preview +rtd-pr-preview: ## Build pull request preview on Read the Docs pip install -r requirements-initial.txt pip install -r requirements.txt - pip install -r requirements-netlify.txt - git submodule init; \ - git submodule update; \ - pip install -e submodules/plone.api[test]; \ + git submodule init + git submodule update + pip install plone.api -c submodules/plone.api/constraints.txt + pip install --no-deps -e submodules/plone.api[test] ln -s ../submodules/volto/docs/source ./docs/volto ln -s ../submodules/plone.restapi ./docs/plone.restapi ln -s ../submodules/plone.api/docs ./docs/plone.api - cd $(DOCS_DIR) && sphinx-build -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + cd $(DOCS_DIR) && sphinx-build -b html $(ALLSPHINXOPTS) ${READTHEDOCS_OUTPUT}/html/ .PHONY: storybook storybook: - cd submodules/volto && yarn && yarn build-storybook -o ../../_build/html/storybook + cd submodules/volto && pnpm i && pnpm build:registry && pnpm build:components && pnpm --filter @plone/volto build-storybook -o ../../../../_build/html/storybook .PHONY: all all: clean vale linkcheck html ## Clean docs build, then run vale and linkcheck, and build html diff --git a/coredev/agreement.md b/coredev/agreement.md deleted file mode 100644 index 337895245f..0000000000 --- a/coredev/agreement.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -myst: - html_meta: - "description": "Contributing to Plone" - "property=og:description": "Contributing to Plone" - "property=og:title": "Contributing to Plone" - "keywords": "Contributing, Plone" ---- - -(contributing-to-plone-label)= - -# Contributing to Plone - -There are many people and companies who rely on Plone on a day-to-day basis, so we must enforce some level of code quality control. - -Plone's source code is hosted in git repositories at , but only members of the developer team have commit rights. - -Sending in a contributors agreement does not guarantee your commit access to the repositories, but once you send it in we will always have it on file for when you are ready to contribute. - -We ask that before requesting core access you familiarize yourself a little with the community since they will help you get ramped up: - -- Ask and (especially) answer questions on [the Plone forum](https://community.plone.org/) and in {doc}`Plone chat ` with a focus on getting to know the active developers a bit. - -- Attend a [conference](https://plone.org/news-and-events/events/plone-conferences), [symposium](https://plone.org/news-and-events/events/regional), or participate in a [sprint](https://plone.org/news-and-events/events/sprints). - - There are plenty of opportunities to meet the community and start contributing through various coding sessions, either in person or on the web. - - You may even be able to get immediate core access at a conference if you are flexing your mad coding skills and the right people are attending. - -- Get your feet wet by contributing to the [collective](https://collective.github.io/). - Don't worry about getting it perfect or asking for help. - This way you get to know us and we improve our code together as a community. - -- **Patches:** Historically we encouraged people to submit patches to the ticket collector. - These tickets are usually ignored forever. - Technically, for us to accept your patch, you must sign the contributors agreement. - If you want to contribute fixes, please just sign the agreement and go through the standard GitHub pull request process described below until you feel comfortable to bypass review. - If the ticket is trivial, you do not need to sign a contributor's agreement. - -Once you have familiarized yourself with the community and you are excited to contribute to the core: - -- Sign the contributor agreement at , then either send by postal mail to the address provided, or scan and email it to . - This offers both copyright protection and ensures that the Plone Foundation is able to exercise some control over the codebase, ensuring it is not appropriated for someone's unethical purposes. - For questions about why the agreement is required, please see [About the Plone Contributor Agreement -](https://plone.org/foundation/contributors-agreement). - -If you aren't sure where to start or just want more direction, feel free to get in the forum or in chat, and ask for help. -While there is no official mentoring process, there are plenty of people willing to act in that role and guide you through the steps of getting involved in the community. -A common way to start contributing is to participate in a [Plone sprint](https://plone.org/news-and-events/events/sprints). - -**Welcome to the Plone community!** - - -## Dealing with pull requests on GitHub - -Before we can merge a pull request, we must ensure that the author has signed the Plone Contributor Agreement. - -If they're listed in either the [Developers](https://github.com/orgs/plone/teams/developers/members) or [Contributors](https://github.com/orgs/plone/teams/contributors/members) team, the author has signed the Plone Contributor Agreement, so we can go ahead and merge. - -If they aren't listed there, they may have signed and returned the Plone Contributor Agreement, but they were not yet added to a team. -You can ask agreements@plone.org to verify. - -Pull requests without a signed Plone Contributor Agreement can only be merged in trivial cases, and only by the release manager. diff --git a/coredev/continous-integration.md b/coredev/continous-integration.md deleted file mode 100644 index a1458cf41d..0000000000 --- a/coredev/continous-integration.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -myst: - html_meta: - "description": "Essential continuous integration practices" - "property=og:description": "Essential continuous integration practices" - "property=og:title": "Essential continuous integration practices" - "keywords": "Plone, continuous integration, best practices" ---- - -# Essential continuous integration practices - -The CI system at [jenkins.plone.org](https://jenkins.plone.org) is a shared resource for Plone core developers to notify them of regressions in Plone core code. - -Build breakages are a normal and expected part of the development process. -Our aim is to find errors and eliminate them as quickly as possible, without expecting perfection and zero errors. -Though, there are some essential rules that needs to be followed in order to achieve a stable build. - - -## 1) Don't check in on a broken build - -Do not make things more complicated for the developer who is responsible for breaking the build. - -If the build breaks, the developer has to identify the cause of the breakage as soon as possible and should fix it. -If we adopt this strategy, we will always be in the best position to find out what caused the breakage and fix it immediately. -If one of the developers has made a check-in and broken the build as a result, we have the best chance of fixing the build if we have a clear look at the problem. -Checking in further changes and triggering new builds will just lead to more problems. - -If the build is broken over a longer period of time (more than a couple of hours) you should either notify the developer who is responsible for the breakage, fix the problem yourself, or just revert the commit in order to be able to continue to work. - -```note -There is one exception to this rule. -Sometimes there are changes or tests that depend on changes in other packages. -If this is the case, there is no way around breaking a single build for a certain period of time. -In this case run the all tests locally with all the changes and commit them within a time frame of ten minutes. -``` - - -## 2) Always run all commit tests locally before committing - -Following this practice ensures the build stays green, and other developers can continue to work without breaking the first rule. - -There might be changes that have been checked in before your last update from the version control that might lead to a build failure in Jenkins in combination with your changes. -Therefore it is essential that you check out ({command}`git pull`) and run the tests again before you push your changes to GitHub. - -Furthermore, a common source of errors on check-in is to forget to add some files to the repository. - -If you follow this rule and your local build passes, you can be sure that this is because someone else checked in in the meantime, or because you forgot to add a new class or configuration file that you have been working on into the version control system. - - -## 3) Wait for commit tests to pass before moving on - -Always monitor the build's progress, and fix the problem right away if it fails. -You have a far better chance of fixing the build, if you just introduced a regression than later. -Also another developer might have committed in the meantime (by breaking rule 1), making things more complicated for yours. - - -## 4) Never go home on a broken build - -Taking into account the first rule of CI ("Don't check in on a broken build"), breaking the build essentially stops all other developers from working on it. -Therefore going home on a broken build (or even on a build that has not finished yet) is **not** acceptable. -It will prevent all the other developers to stop working on the build or fixing the errors that you introduced. - - -## 5) Always be prepared to revert to the previous revision - -In order for the other developers to be able to work on the build, you should always be prepared to revert to the previous (passing) revision. - - -## 6) Time-box fixing before reverting - -When the build breaks on check-in, try to fix it for ten minutes. -If, after ten minutes, you aren't finished with the solution, revert to the previous version from your version control system. -This way you will allow other developers to continue to work. - - -## 7) Don't comment out failing tests - -Once you begin to enforce the previous rule, the result is often that developers start commenting out failing tests in order to get the build passing again as quick as possible. -While this impulse is understandable, it is **wrong**. - -The tests have been passing for a while and then start to fail. -This means that we either caused a regression, made assumptions that are no longer valid, or the application has changed the functionality being tested for a valid reason. - -You should always either fix the code (if a regression has been found), modify the test (if one of the assumptions has changed), or delete it (if the functionality under test no longer exists). - - -## 8) Take responsibility for all breakages that result from your changes - -If you commit a change and all the tests you wrote pass, but others break, the build is still broken. -This also applies to tests that fail in `buildout.coredev` and don't belong directly to the package you worked on. -This means that you have introduced a regression bug into the application. - -It is **your responsibility**—because you made the change—to fix all tests that are not passing as a result of your changes. - -There are some tests in Plone that fail randomly, we are always working on fixing those. -If you think you hit such a test, try to fix it (better) or re-run the Jenkins job to see if it passes again. - -In any case the developer who made the commit is responsible to make it pass. - - -## Further Reading - -Those rules were taken from the excellent book "Continuous Delivery" by Jez Humble and David Farley (Addison Wesley), and have been adopted and rewritten for the Plone community. - -If you want to learn more about continuous integration and continuous delivery, I'd recommend that you buy this book. diff --git a/coredev/contributors_agreement_explained.md b/coredev/contributors_agreement_explained.md deleted file mode 100644 index 88851f6c85..0000000000 --- a/coredev/contributors_agreement_explained.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -myst: - html_meta: - "description": "Contributor's Agreement for Plone explained" - "property=og:description": "Contributor's Agreement for Plone explained" - "property=og:title": "Contributor's Agreement for Plone explained" - "keywords": "Contributor, Agreement, Plone" ---- - -```{todo} -All this content should be audited against the plone.org site, probably removed, and replaced with a link to the authorative content on plone.org. -Duplicating content is a maintenance burden. -``` - -# Contributor's Agreement for Plone explained - -Prospective contributors to the Plone code base are required to sign a contributor's agreement, which assigns copyright in the code to the Plone Foundation, the non-profit organization which stewards the Plone code base. - -This document explains the purposes of this, along with questions and answers about what this means. - -The Plone Contributor's Agreement can be found at https://plone.org/foundation/contributors-agreement. - - -## About the Plone Contributor Agreement - -The Foundation feels that it benefits the community for a single organization to hold the rights to Plone. -Prior to the Foundation, the intellectual property of Plone was jointly held by individual developers and by Alan Runyan and Alexander Limi. - -The community members who formed the Foundation felt that having the Foundation hold these rights provides several benefits: - -1. **Minimizing confusion / maximizing business compatibility** -- Organizations considering adopting Plone have a simple answer for "Who owns this?", rather than a more complicated answer that might scare away the legally-cautious. -2. **Trademark protection** -- By having the Foundation hold the trademarks and rights to the Plone branding assets, it can effectively protect these from unfair use. -3. **Guarantee of future Open Source versions** -- The Foundation's contributor agreement ensures that there will **always** be an OSI-approved version of Plone. - - -## Questions and answers - -What does the Contributor's Agreement cover? - -> This agreement is for the Plone core codebase only. -> The Plone core codebase is that code which lives in the Plone core version repositories, currently located at [https://github.com/plone]. -> Contributions to the "Collective", currently located at [https://github.com/collective] are not assigned to the Plone Foundation, and are made available under whatever license the project developers wish to use, although add-on products that import from GPLed Plone code are of course subject to the terms of the GPL, which requires derived works to be GPL licensed. - -What rights will I continue to have for my contributions? - -> Contributors are asked to transfer their intellectual property rights to the Foundation. -> In return, they will be given back irrevocable rights to use and distribute their contributions. -> They can even give their contributions to other Open Source projects (as long as those projects are compatible with the license Plone itself is issued under) or use them in non-Open Source commercial applications (if that is compatible with the license Plone is under). - -Do I have to sign the contributor's agreement to make changes to the Plone core codebase? - -> Yes. - -Do I have to sign the contributor's agreement to submit a patch to the Plone core codebase? - -> We enthusiastically welcome patches, but we can't merge them until you sign and return a contributor's agreement. -> (Unless, in the judgement of the Plone Release Manager, the patch is so tiny as not to constitute a "creative work". -> See the [Policy for Contributor Agreements and Patches] for more detail on this policy.) - -Can I grant the Plone foundation a non-exclusive license to my contributions rather than an exclusive license, so that I can contribute the same code to other projects under different terms or use the contribution for other commercial endeavors? - -> Not under the current version of the contributors agreement. - -Does the Foundation control use of the Plone trademark? - -> Yes. -> In order to keep the trademark, the Foundation (or any trademark owner) must demonstrate that they have acted to protect it. - -Will Plone always be available under an OSI-approved/Open Source license? -Couldn't the Board change its mind about this? - -> Plone will always be available under an OSI-approved license; this is written into the language of the contributor agreement each developer and the foundation sign. - -Will Plone ever be available under a non-GPL license? - -> The current Plone approach states that companies can negotiate a non-GPL license. -> Thus, the Foundation might pursue a dual-licensing (GPL and non-GPL) scheme - -> but, at this time, the Board has not yet created any policies on this. -> This is an important question for the community, of course, and the Foundation intends to have this conversation in a transparent way. - -Why would anyone want a non-GPL Plone? - -> Two possible reasons: some companies are reluctant to do in-house modifications of framework-like systems (such as Plone) that are under the GPL, fearing that a clause in the GPL might force them to disclose their internal work - thus wanting to license it under (for example) a BSD-style license. -> Second, companies may wish to offer a commercial version of Plone, under a conventional shrink-wrap license, without the obligation to reveal source code or share changes. - -How much would a non-GPL version of Plone cost? - -> Would a small company be able to afford one? -> Neither the Foundation nor the Board have made any decisions about a non-GPL version, let alone about pricing. -> However, one of the Foundation's stated goals is to maintain a level playing field for Plone while trying to benefit all of the Plone commons. -> If a non-GPL version was available, and a large company bought it, -> added features to it, and sold it, wouldn't they be using our work without an obligation to give back? -> It's helpful to remember the core value open source provides: distributed development, maintenance, security checking, and support. -> Companies that build large features for Plone are **already** having to make decisions of whether to release their products under an open source license or not (since they could always release them as a Product, not as a modification to the Plone core). -> Despite this, though, many large and excellent contributions—such as Archetypes—have been made, and the Foundation hopes that companies will continue to do so. -> In any event, a company that purchases a non-GPL license (should such ever become available) is contributing financial resources to our community, which can be used to further develop, market, and protect the GPL version of Plone. - -- https://plone.org/foundation/contributors-agreement/agreement.pdf -- https://github.com/collective -- https://github.com/plone -- [Policy for Contributor Agreements and patches](https://plone.org/foundation/materials/foundation-resolutions/patch-policy-052011) diff --git a/coredev/culture.md b/coredev/culture.md deleted file mode 100644 index 545b90996a..0000000000 --- a/coredev/culture.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -myst: - html_meta: - "description": "Plone developer culture" - "property=og:description": "Plone developer culture" - "property=og:title": "Plone developer culture" - "keywords": "Plone, developer, culture" ---- - -```{todo} -This content is probably redundant and should be purged. -``` - -# Plone developer culture - -If you are going to contribute to Plone, we ask a couple things. -First, please join the [Plone forum](https://community.plone.org) and at minimum lurk around. -You will quickly see how people work and what kind of things are best suited for group discussion. -Second, please ask for help setting up your environment, in the forum. - -Most of our developers work there and you will get the best advice there. - -If you are actively committing code, always keep an eye on our [Jenkins CI](https://jenkins.plone.org/) to know if your recent commits have broken (or fixed!) the build. - -If you are in a timezone when things are not very active, please post to the forum or grab a drink and wait for people to wake up. - -**When in doubt, please ask** - -The code base is very complicated and everyone is vested in the right thing happening. -Despite the occasional grouch here and there, most Plone developers will go out of their way to get you on the right path. diff --git a/coredev/getting-started-with-development.md b/coredev/getting-started-with-development.md deleted file mode 100644 index 5975adc21d..0000000000 --- a/coredev/getting-started-with-development.md +++ /dev/null @@ -1,387 +0,0 @@ ---- -myst: - html_meta: - "description": "Getting started with Plone development" - "property=og:description": "Getting started with Plone development" - "property=og:title": "Getting started with Plone development" - "keywords": "Plone, development" ---- - -# Getting started with development - -This document assumes you want to run the current latest Plone source, fix a bug in Plone, or test an add-on in the context of the latest code, and will detail the full process. -For how to write Plone Improvement Proposals (PLIPs), read {doc}`plips`. - - -## Version support policy - -If you are triaging or fixing bugs, keep in mind that Plone has a [version support policy](https://plone.org/download/release-schedule#91815aec-0513-40e0-a804-55ea787a8c68). - - -## Dependencies - -- git. See [Set up Git](https://docs.github.com/en/get-started/quickstart/set-up-git). -- [Python](https://python.org/). See the [current supported versions of Python](https://plone.org/download/release-schedule). -- If you are on macOS, you will need to install [XCode](https://developer.apple.com/xcode/). - You can do this through the App Store or registering through the Apple Developer Program. -- [Pillow](https://pypi.org/project/Pillow/). -- [GCC](https://gcc.gnu.org/) in order to compile ZODB, Zope and lxml. -- [libxml2 and libxslt](https://gitlab.gnome.org/GNOME/libxslt/-/releases), including development headers. - - -(setup-development-environment)= - -## Set up your development environment - -The first step in fixing a bug is getting this [buildout](https://github.com/plone/buildout.coredev) running. -We recommend fixing the bug on the latest branch, and then [backporting](https://en.wikipedia.org/wiki/Backporting) as necessary. -Dependent on the current development cycle, there may exist a future branch. -For example, `6.0` is the actively maintained stable branch. -[Some other branch] is the future, currently unstable, active development branch. -More information on switching release branches is described below. - -To set up a plone 6 development environment. - -```shell -cd ~/projects # or wherever you want to put things -git clone -b 6.0 https://github.com/plone/buildout.coredev ./plone6devel -cd ./plone6devel -./bootstrap.sh -``` - -If you run into issues in this process, please see {doc}`troubleshooting`. - -This will run for a long time if it is your first pull (approximately 20 minutes). -Once that is done pulling down eggs, you can start your new instance with: - -```shell -./bin/instance fg -``` - -or as a WSGI service with: - -```shell -./bin/wsgi -``` - -To login, the defaults are: - -- username: admin -- password: admin - - -## Switching branches - -If your bug is specific to one branch, or you think it should be backported, you can switch branches. -The first time you get a branch, you must do: - -```shell -git checkout -t origin/6.0 -``` - -This should set up a local 6.0 branch tracking the one on GitHub. -From then on you can just do: - -```shell -git checkout 6.0 -``` - -To see what branch you are currently on: - -```shell -git branch -``` - -The line with a `*` by it will indicate the branch on which you are currently working. - -```{important} -Make sure to rerun buildout if you were in a different branch earlier to get the correct versions of packages, otherwise you will get some weird behavior. -``` - - -## Jenkins and mr.roboto - -Plone has a continuous integration (CI) setup and follows CI rules. - -When you push a change to any Plone package, our testing/CI middleware `mr.roboto` starts running all the tests that are needed to make sure that you don't break anything. -For each Plone and Python version we run two jobs, one for the package itself (which will give you a fast feedback, within 10 minutes) and one on the full `coredev` build (which can take up to an hour, but makes sure no other packages are effected by your change. - -For more information you can read {doc}`Mr. Roboto workflow ` or our [Jenkins machine](https://jenkins.plone.org/). - -The CI system at `jenkins.plone.org` is a shared resource for Plone developers to notify them of regressions in Plone code. -Build breakages are a normal and expected part of the development process. -Our aim is to find errors and eliminate them as quickly as possible, without expecting perfection and zero errors. -Though, there are some essential practices that need to be followed in order to achieve a stable build: - -1. Don't check in on a broken build. Check Jenkins first. -2. Always run all commit tests locally before committing. -3. Wait for commit tests to pass before moving on. -4. Never go home on a broken build. -5. Always be prepared to revert to the previous revision. -6. Time-box fixing before reverting. -7. Don't comment out failing tests. -8. Take responsibility for all breakages that result from your changes. - -See {doc}`continous-integration` for more information. - -Since it can be burdensome to check this manually, install the tools locally to always see the current state of the Plone CI Server: - -- For Linux and X11 environments, there is [BuildNotify](https://pypi.org/project/BuildNotify/). -- For macOS there is [CCMenu](http://ccmenu.org/). -- For windows there is [CCTray](https://cruisecontrolnet.org/cctray_download_plugin-2/). -- For Firefox there is [CruiseControl Monitor](https://addons.thunderbird.net/EN-US/firefox/addon/cruisecontrol-monitor/?src=cb-dl-name) (no longer supported), and many other [Jenkins plugins](https://addons.mozilla.org/en-US/firefox/search/?q=jenkins). - -These tools were built to parse a specific file that CruiseControl, another CI tool, generated. -Jenkins generates this file too. -You can configure your notifier of choice with this url: `https://jenkins.plone.org/cc.xml` [which is a 404, LOL!] - - -## Check out packages to fix - -Most packages are not in {file}`src/` by default, so you can use `mr.developer` to get the latest and make sure you are always up to date. -It can be a little daunting at first to find out which packages cause the bug in question, but just ask in https://community.plone.org/ if you need some help. -Once you know which packages you want, pull their source. - -You can get the source of the package with `mr.developer` and the checkout command, or you can go directly to editing {file}`checkouts.cfg`. -We recommend the latter but will describe both. -In the end, {file}`checkouts.cfg` must be configured, so you might as well start there. - -At the base of your buildout, open {file}`checkouts.cfg` and add your package if it's not already there: - -```cfg -auto-checkout = - # my modified packages - plone.app.caching - plone.caching - # others - ... -``` - -Then rerun buildout to get the source packages: - -```shell -./bin/buildout -``` - -Alternatively, we can manage checkouts from the command line, by using `mr.developer`'s `bin/develop` command to get the latest source. -For example, if the issue is in `plone.app.caching` and `plone.caching`: - -```shell -./bin/develop co plone.app.caching -./bin/develop co plone.caching -./bin/buildout -``` - -Don't forget to rerun buildout! -In both methods, `mr.developer` will download the source from GitHub (or otherwise) and put the package in the {file}`src/` directory. -You can repeat this process with as many or as few packages as you need. -For some more tips on working with `mr.developer`, please read {doc}`mrdeveloper`. - - -## Testing Locally - -To run a test for the specific module you modify: - -```shell -./bin/test -m plone.app.caching -``` - -These should all run without error. -Please don't check in anything that doesn't succeed! -Now write a test case for the bug you are fixing, and make sure everything is running as it should. - -After the module level tests run with your change, please make sure other modules aren't affected by the change by running the full suite, including robot-tests (remove the `--all` to run without robot tests): - -```shell -./bin/test --all -``` - -```{note} -Tests take a long time to run. -Once you become a master of bugfixes, -you may just let jenkins do this part for you. -More on that below. -``` - - -## Updating `CHANGES.rst` and `checkouts.cfg` - -Once all the tests are running locally on your machine, you are **ALMOST** ready to commit the changes. -You must perform a couple housekeeping chores before moving on. - -First, edit {file}`CHANGES.rst` (or {file}`CHANGES.txt`, or {file}`HISTORY.txt`) in each package you have modified and add a summary of the change. -This change note will be collated for the next Plone release and is important for integrators and developers to be able to see what they will get if they upgrade. -New changelog entries should be added at the very top of {file}`CHANGES.rst`. -Some packages already switched to use [towncrier](https://pypi.org/project/towncrier/). -If this is the case you'll find a note at the top of the `CHANGES.rst` file. - -Most importantly, if you didn't do it earlier, edit the file {file}`checkouts.cfg` in the buildout directory, and add your changes package to the `auto-checkout` list. -This lets the release manager know that the package has been updated, so that when the next release of Plone is cut, a new egg will be released, and Plone will need to pin to the next version of that package. -In other words, this is how your fix becomes an egg! - -Note that there is a section separator called "# Test Fixes Only". -Make sure your egg is above that line, else your egg probably won't get made very quickly. -This just tells the release manager that any eggs below this line have tests that are updated, but no code changes. - -Modifying the file {file}`checkouts.cfg` also triggers the buildbot, [jenkins](https://jenkins.plone.org/), to pull in the egg and run all the tests against the changes you just made. -Not that you would ever skip running all tests. - -If your bug is in more than one release, for example 5.2 and 6.0, please checkout both branches, and add it to the file {file}`checkouts.cfg`. - - -## Commits and pull requests - -Review the following checklist: - -- Did you fix the original bug? -- Is your code consistent with our [Style Guides](https://5.docs.plone.org/develop/styleguide/index.html)? -- Did you remove any extra code and lingering pdbs? -- Did you write a test case for that bug? -- DO all test cases for the modules and Plone pass? -- Did you update {file}`CHANGES.rst` in each packages you touched? -- Did you add your changed packages to {file}`checkouts.cfg`? - -If you answered *YES* to all of these questions, then you are ready to push your changes! -A couple quick reminders: - -- Only commit directly to the development branch if you're confident that your code won't break anything badly and the changes are small and fairly trivial. - Otherwise, please create a `pull request` (more on that below). -- Please try to make one change per commit. - If you are fixing three bugs, make three commits. - That way, it is easier to see what was done when, and easier to roll back any changes if necessary. - If you want to make large changes cleaning up whitespace or renaming variables, it is especially important to do so in a separate commit for this reason. -- We have a few angels that follow the changes and each commit to see what happens to their favourite CMS! - If you commit something REALLY sketchy, they will politely contact you, most likely after immediately reverting changes. - There are no official people assigned to this so if you are especially nervous, ask in https://community.plone.org/. - - -## Commit to `Products.CMFPlone` - -If you are working a bug fix on `Products.CMFPlone`, there are a couple other things to take notice of. -First and foremost, you'll see that there are several branches. -At the time of writing this document, there are branches for 4.2.x, 4.3.x and master, which is the implied 5.0. -This may change faster than this documentation, so check the branch dropdown on GitHub. - -If the fix is only for one version, make sure to get that branch. -However, chances are the bug is in multiple branches. - -Let's say the bug starts in 4.1. -Pull the 4.1 branch and fix and commit there with tests. - -If your fix only involved a single commit, you can use git's `cherry-pick` command to apply the same commit to a different branch. - -First check out the branch: - -```shell -git checkout 4.2 -``` - -And then cherry-pick the commit (you can get the SHA hash from git log): - -```shell -git cherry-pick b6ff4309 -``` - -There may be conflicts. -If so, resolve them, then follow the directions git gives you to complete the cherry-pick. - -If your fix involved multiple commits, cherry-picking them one by one can get tedious. -In this case, things are easiest if you did your fix in a separate feature branch. - -In that scenario, you first merge the feature branch to the 4.1 branch: - -```shell -git checkout 4.1 -git merge my-awesome-feature -``` - -Then return to the feature branch, and make a branch for rebasing it onto the 4.2 branch: - -```shell -git checkout my-awesome-feature -git checkout -b my-awesome-feature-4.2 -git rebase ef978a --onto 4.2 -``` - -(`ef978a` happens to be the last commit in the feature branch's history before it was branched off of 4.1. -You can look at `git log` to find this.) - -At this point, the feature branch's history has been updated, but it hasn't actually been merged to 4.2 yet. -This lets you deal with resolving conflicts before you actually merge it to the 4.2 release branch. -Let's do that now: - -```shell -git checkout 4.2 -git merge my-awesome-feature-4.2 -``` - -### Branches and forks and direct commits - oh my! - -```{note} -This section needs a rewrite. -Meanwhile we do not allow direct commits, except in very rare cases. -``` - -Plone used to be in an svn repository, so everyone is familiar and accustomed to committing directly to the branches. -After the migration to GitHub, the community decided to maintain this spirit. -If you have signed the [contributor agreement](https://plone.org/foundation/contributors-agreement), you can commit directly to the branch. -For Plone, this would be the version branch, whereas for most other packages this would be `main`. - -HOWEVER, there are a few situations where a branch is appropriate. -If you: - -- are just getting started -- are not sure about your changes -- want feedback or code review -- are implementing a non-trivial change - -then you should create a branch of whatever packages you are using, and then use the [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) feature of GitHub to get review. -Everything about this process would be the same except you need to work on a branch. -Take the `plone.app.caching` example. -After checking it out with `mr.developer`, create your own branch with: - -```shell -cd src/plone.app.caching -git checkout -b my_descriptive_branch_name -``` - -```{note} -Branching or forking is your choice. -I prefer branching, and I'm writing the docs so this uses the branch method. -If you branch, it helps us because we *know* that you have committer rights. -Either way it's your call. -``` - -Proceed as normal. -When you are ready to push your fix, push to a remote branch with: - -```shell -git push origin my_descriptive_branch_name -``` - -This will make a remote branch in GitHub. -Navigate to this branch in the GitHub user interface, and on the top right, there will be a button that says {guilabel}`Pull Request`. -This will turn your request into a pull request on the main branch. -There are people who look once a week or more for pending pull requests and will confirm whether or not it's a good fix, and give you feedback where necessary. -The reviewers are informal and very nice, so don't worry. -They are there to help! -If you want immediate feedback, visit https://community.plone.org/ with the pull request link and ask for a review. - -```{note} -You still need to update the file {file}`checkouts.cfg` in the correct branches of `buildout.coredev`! -``` - - -## Finalize issues - -If you are working from an issue, please don't forget to go back to the issue, and add a link to the change set. -We don't have integration with GitHub yet so it's a nice way to track changes. -It also lets the reporter know that you care. -If the bug is really bad, consider pinging the release manager and asking them to make a release. - - -## FAQ - -How do I know when my package got made? -: You can follow the project on GitHub, and watch its [timeline](https://github.com/orgs/plone/dashboard). - You can also check the {file}`CHANGES.rst` of every plone release for a comprehensive list of all changes, and validate that yours is present. diff --git a/coredev/git.md b/coredev/git.md deleted file mode 100644 index 9c9034f756..0000000000 --- a/coredev/git.md +++ /dev/null @@ -1,642 +0,0 @@ ---- -myst: - html_meta: - "description": "" - "property=og:description": "" - "property=og:title": "" - "keywords": "" ---- - -```{todo} -I seriously question the value of this entire guide. -I think it should be purged. -Plone should not be in the business of teaching how to use git or GitHub. -``` - -# Working with Git and GitHub - -## The Plone Git workflow and branching model - -Our repository on GitHub has the following layout: - -- **feature branches**: - All development for new features must be done in dedicated branches, normally one branch per feature. -- **main** or **master** **branch**: - when features get completed they are merged into the master branch; bugfixes are commited directly on the master branch, -- **tags**: - whenever we create a new release, we tag the repository so we can later retrace our steps, or rerelease versions. - - -## Git basics - -Some introductory definitions and concepts, if you are already familiar enough with Git, head to next section: {ref}`general-guidelines-label`. - - -### Mental working model - -With Git (as well as all modern [DVCS](http://en.wikipedia.org/wiki/Distributed_revision_control)), distributing changes to others is a two steps process (contrary to traditional VCS like `svn`). - -This way what on svn is a single `svn ci` in Git is two commands: `git commit` and `git push`. - -This may seem to be a drawback, but instead it's a feature. - -**You are working locally until you decide to push your changes.** - -Not a single commit anymore, but a series of them, meaning that all those fears, concerns, doubts are taken away! - -You can freely fix/change/remove/rework/update/... your commits afterwards. - -Push your changes whenever you are sure they are what you, and others, expect them to be. - - -### Concepts - -In Git there are: - -commits - -: A patch made out of changes (additions, removals) on files tracked by Git. - -branches - -: Series of commits that have a name. - -tags - -: A name attached to a single commit. - -`HEAD` - -: A pointer that always tells you where you are (extremely useful when doing some operations). - -The index - -: A temporal staging storage with changes on files that are pending to be added to a commit. - If your Git output is colored, green filenames are those in the index. - -Working tree - -: Your current modified files. - This is the only place where you can loose your changes. - If your Git output is colored, red filenames are those in the working tree. - -Stash - -: Temporal storage for changes, again, extremely useful in some scenarios, see further below for examples. - -### Branches - -Another great feature of DVCS is cheap branching, i.e. branching in Git is effortless and really useful. -As it's no longer too much effort to branch, there is no need to always work on the master branch. - -A developer can branch easily for each fix/feature. - -Branches allow you to tinker with your changes while keeping the master branch clean. - -Not only that, it also allows you to keep modifying your changes until you and your peers are fine with them. - -Further documentation: -[Introduction to branching](http://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell). - -### Commands - -Some of the most useful/common commands (note that most of them have switches that enhance/*completely twist* their functionality): - -Just append `--help` on all of them to get their full definitions and options, -i.e. `git add --help`. - -clone - -: Download a repository from a given remote URL. - -add - -: Add the given files to the index. - - ```{note} - **pro tip**: once a file is add via `git add` your changes will never be lost! - As long as you don't remove the `.git` folder, even if you remove the file you just added, the changes you made before doing `git add` are still there ready to be recovered at any time! - ``` - -status - -: Get an overview of the repository status. - - If there are files on the index, or files not tracked by Git, or the status of your local branch with regards to the remote, etc. - -diff - -: See the current changes made to the files already tracked by Git. - - ```note} - Fear not, if you used `git add SOME_FILE` and then `git diff` doesn't output anything you haven't lost your changes! - - Just try `git diff --cached`. - Now you know how to see the working tree changes (`git diff`) and index changes (`git diff --cached`). - ``` - -commit - -: Create/record changes to the repository (locally only, nothing is sent over the wire). - -push - -: Send your changes, - either commits or a complete new branch, - to the configured remote repository. - -show - -: Display the given commit(s) details. - -log - -: Shows the repository history. - Sorted by date (last commit at the top), - and like all other commands, - extremely versatile with all its switches. - - See further below for an example of a powerful combination of switches. - -branch - -: Create a branch. - -fetch - -: Download changes from the remote repository. - - **Without** changing the current `HEAD` (see rebase and pull commands). - -pull - -: Fetch and integrate changes from remote repository. - - Internally that means to do a `git fetch` plus either `git merge` or `git rebase`. - - :::{note} - Used careless most probably adds extra superfluous commits. - See further down. - ::: - -merge - -: Join two, - or more, - branches together. - -rebase - -: Forward-port your current local commits (or branch) to be based on top of another commit. - - An image is worth 1000 words: - -checkout - -: Change to the given branch or get the given file to its latest committed version. - - :::{note} - If Git is criticized for being complex, - this command is one of the main sources of complains. - - You can compare it with `svn switch` if you happen to know it. - - Fear not though, - two main use cases are: - change branches and reset a file to its last committed version. - Still, - the syntax for both cases is really simple. - ::: - -cherry-pick - -: Apply a commit(s) to the current working branch. - -stash - -: Use a temporal storage to save/restore current changes still not meant to be used on a commit. - - :::{note} - Seems a bit not so useful on a first look, - but it is indeed. - - Think about this scenario: - you are working on your branch coding away. - All of the sudden you notice a small fix that should be done directly on master. - Thanks to `git stash` you can save your changes quickly and safely, - move to master branch, - do the quick fix, - commit and push it, - move back to your branch and `git stash pop` to recover your changes and continue hacking away. - ::: - -reflog - -: When things go bad you will **love** this command. - - It effectively shows you a histogram of what happened on the repository, - allowing you to rollback you repository to a previous stage. - - Extremely useful once a bad interactive rebase has happened. - -(general-guidelines-label)= - -## General guidelines - -### Pulling code - -Let's compare this two histories: - -``` -* 3333333 (HEAD, master) Merge branch 'feature-branch' into master -|\ -| * 2222222 (feature-branch) Last changes on feature-branch -| * 1111111 Merge branch 'master' into feature-branch -| |\ -| * | 0000000 More changes on feature branch -| * | fffffff Merge branch 'master' into feature-branch -| |\ \ -* | | | eeeeeee master keeps rocking -| |_|/ -|/| | -* | | ddddddd master goes and goes -| |/ -|/| -* | ccccccc master evolves -| * bbbbbbb First commit on feature-branch -|/ -* aaaaaaa commit on master # this is where feature-branch was created -``` - -With: - -``` -* 3333333 (HEAD, master) Merge branch 'feature-branch' into master -|\ -| * 2222221 (feature-branch) Last changes on feature-branch -| * 0000001 More changes on feature branch -| * bbbbbb1 First commit on feature-branch -|/ -* eeeeeee master keeps rocking -* ddddddd master goes and goes -* ccccccc master evolves -* aaaaaaa commit on master -``` - -What do we see above? Actually and contrary to what it seems, -exactly the same **result** -(as how the files and its content look like on commit `333333`). - -The second version is far more easy to understand what happened and removes two superfluous commits -(the two partial merges with master (`fffffff` and `1111111`). - -This happens if you have not properly configured `git pull`. -By default it does a `merge` meaning that an extra commit is always added, -tangling the history and making this more complex when looking back for what happened there. - -#### How to solve it? - -*ALWAYS* do a {command}`git pull --rebase` when fetching new code, -configure Git to do always so with: - -``` -git config branch.autosetuprebase always # add the --global switch to make it default everywhere -``` - -This way you do not introduce new extra commits and the Git history is kept as simple as possible. - -This is especially important when trying to understand why some changes were made, -or who did actually change that line, -etc. - -A couple of further explanations: - - - - -Search for `git merge vs rebase`, you will find plenty of literature. - -### Reviewing your changes - -After hacking for some minutes/hours/days you are finished and about to commit your changes, -great! - -*BUT*, -please, -do so with {command}`git add --patch`. - -The `--patch` (also `-p`) switch allows you to select which hunks you want to add on a commit. - -This is not only great to split changes into different commits, -but is also the time when you actually **review** your code before anyone else sees it. - -This is the time when you spot typos, pep8 errors, misaligned code, lack of docstrings in methods, -that a permission is not defined on Generic Setup, that an upgrade should be needed... - -Remember that the first code review is the one you do on your own. -Some inspiration/better phrasing: - - -And please, do remember the gold metric about reviewing code: - - -#### One commit does one thing - -Repeat with me: *One commit does one thing*. Period. - -When someone else needs to review your code, most probably she will give up or just skim over your code -if there are too many (unrelated) changes. - -Reviewing commits with +20 files doing all sorts of changes on them (maybe even unrelated) -is no fun and adds complexity and [cognitive load](http://en.wikipedia.org/wiki/Cognitive_load). - -Something that should mostly be a verification of a checklist like: - -- the browser view is registered on ZCML? - -- is there an interface for that form? - -- the pt and py are there? - -- ... - -Turns instead into a list of questions: - -- why is this interface renamed here if it has nothing to do with this adapter? -- all this removal of deprecated code while adding new features just mixes the diff, - am I missing something? -- *others* - -If you can not express what has been changed within 50 characters (suggested length of a commit message subject), -or you say it like "it does XXX and YYY", you most probably need to split that commit into, at least, -two or more commits. - -That doesn't mean that a +20 files or +100 lines of code changes are bad per se, you may be doing -a simple refactoring across lots of files, that's fine and good actually. - -As long as a commit is just and only about a specific purpose, and not a mixed selection of the following: - -- refactoring code -- moving things around -- fixing some bugs while at it -- adding some docs -- a new cool feature -- fixing typos on documentation -- pep8 fixes - -It is absolutely fine to refactor. - -And this is actually to help both your present self and your +5 years from now that will have to refactor that code of yours, -and maybe is struggling to understand what was going on there. - -Following this advice will: - -- keep things simple where there's no gain in adding complexity -- make your changes easy to be reviewed -- make later on lookups on those changes easy to follow - -### Making commits - -For commit messages see: {ref}`git_commit_message_style_guide`. - -#### Adding references to issues - -Always add the full URL to the issue/pull request you are fixing/referring to. - -Maybe within the Git repository it makes sense, but as soon as you are outside of it, it will not. - -Take into account mr.roboto automatic commits to buildout.coredev for example, if your commit message goes like *Fix for #33*, -which issue/pull request is that fixing? - -The one in buildout.coredev itself? On another issue tracker? Somewhere else? - -It would be far better if the commit goes instead like: - -``` -Brief description - -Further explanation. - -Fixes: https://github.com/plone/plone.app.discussion/issue/999 -``` - -#### Bad examples - -Some bad examples of commit messages: - - -Commit messages goes like *"Make note about how this interface is now for BBB only"*. - -Question: if it's BBB only, where is the new place to look for that interface now? - -The problem is that, in this case Martin, wrote that in 2009, so most probably once a refactor of that package -is done later on 2015, Martin is no longer around, and if he was, most probably he would not remember something from +6 years ago. - -Ask yourself a question: - -If someone comes to you asking details about a random commit done by you +5 years ago, what will you reply? - -Try that, get one project that you worked 5 years ago, get a random commit and: - -See if, just by reading the commit message, you are given enough information of what changes have been made, -when comparing the commit message and the actual code. -Does the commit message match the code changed? - -### Before pushing commits - -Code is reviewed, spread into nice isolated commits, descriptive enough commit messages are written, *what's left?* - -A final overview of what you are about to push. - -To do so, you can get an idea with the following Git alias (to be added on your `~/.gitconfig`): - -``` -[alias] - fulllog = log --graph --decorate --pretty=oneline --abbrev-commit --all -``` - -Now run {command}`git fulllog` on your Git repository, you will see a nice graph showing you the current situation. - -Maybe it makes you realize that commits need to be reordered, commit messages could get some improvements, -that you forgot to add a reference to an issue, ... - -## Pull requests - -Some specific tips and best practices for pull requests. - -### Always rebase - -Always rebase on top of the branch you want your changes to be merged before sending a pull request, -and as your pull request is still pending to be merged and the master branch evolves, keep rebasing it. - -To do so: - -``` -git checkout -git rebase master # or the branch you are targeting to integrate your changes to -# done! -# or if there are conflicts, -# fix them and follow instructions from git itself -``` - -The principle is, if you do merges with master, you are actually spreading your pull request into more commits, -and at the end making it more difficult to track what was changed. - -On top of that, the commit history is more complex to follow. - -See the history example above: {ref}`general-guidelines-label`. - -Unfortunately the flat view from GitHub prevents us from seeing that, -which is a shame. - -### One line one commit - -On a series of commits make sure the same code line is not changed twice, -the worst thing you can do to the one reviewing your changes, -is to make him/her spend time reviewing some code changes that one the next commit are changed again to do something else. - -It will not only make your commits smaller, but it will also make it easy to do atomic commits. - -### No cleanup commits please - -*On the context of a pull request* - -Ask yourself: What relation does a cleanup commit, say pep8 fixes or other code analysis fixes, -have with your pull request? - -Couldn't that pep8 fixes commit or small refactoring go straight into master branch? - -Or even if you send a pull request for it, chances are that it will be merged right away. -As long as it is a cleanup commit, there's not much to argue with it. - -The same goes with commits that improve or actually fix previous commits (within the same pull request). -A series of commits like this: - -``` -* 11ba28c Last fix, finally -* 11ba28c Fix tests, again -* 11ba28c Fix tests -* 11ba28c Do something fancy -* 11ba28c Failing test, we are doing TDD right? -``` - -Only tells you that the author did not take care at all about the one who will review it, -and specially about the person that in +5 years will try to understand that test. -Specially because now the test is not only spread between 4 commits, but most probably during those 5 years -it has already been refactored, maybe a {command}`git blame` will report that within that test method, -there are +5 related current commits to check, not nice right? - -#### Squashing commits - -To fix the previous example, run the following command: - -``` -git rebase ---interactive # which mostly is usually master -``` - -This allows you to rewrite the story of your branch. -See a more [elaborate description with examples](https://www.atlassian.com/git/tutorials/rewriting-history/git-rebase-i/). - -:::{note} -Be careful on not to run that on master itself! -Please take your time to really understand it. - -It's a really powerful tool, -and as [Stan Lee says](http://en.wikiquote.org/wiki/Stan_Lee), -it comes with great responsibility. -::: - -To actually make it easier you can do commits like this: - -``` -git commit --fixup HASH -``` - -Where `HASH` is the commit hash you want the changes you are about to commit be merged with. - -This way, when running {command}`git rebase --interactive`, Git will already reorder the commits as you already want. - -### No side changes - -That's an extension to the previous point. - -Keeping pull requests simple and to the point, without changes not related to the pull request itself, -will make your changes easier to understand and easier to follow. - -Again this applies: - - -### The review-change-push-review cycle - -After you have made a pull request, -you should ask for a review via the GitHub interface. - -After the review you will frequently have to do some changes of your PR, -perhaps add a missing changelog entry, and so on. - -When the changes are done, rebase your branch again -and squash any fixup-commits, all as described above. - -Finally you should force push your feature branch to GitHub. -Only force push on your own feature branches! -Never on branches shared with other people. - -After the update of your branch, -the GitHub PR interface will pick up the changes, -ready for returning to the reviewer, -and hopefully get a final go for the merge. - -## Recipes - -Assorted list of tips and tricks. - -### Change branches with uncommitted changes - -**Situation:** you are working on a pull request and while working on it founds that some cleanups are needed, -how to proceed forward? - -**Solution:** `git stash` or `git commit --amend -m"TMP"`. - -The basic idea here is: store your current changes safely (either on a Git stash commit or directly on a commit on the branch, -whichever you prefer), move to the canonical branch (`master` usually), do the fixes/cleanups/refactorings there, -commit those changes, rebase your branch on top of the changes you made, hack away. - -Command line version: - -``` -git stash # or git commit --amend -m"TMP" -git checkout master # or whatever happens to be the canonical branch name (i.e. 5.0 on buildout.coredev) -# do the cleanups && push them -git checkout your-branch # get back to your branch -git rebase master # again the canonical branch where you made the changes -git stash pop # or git reset HEAD^ if you did a git commit --amend -m"TMP" -# if needed, fix the conflicts, with patience and practise that's a piece of cake once you are used to -``` - -### Git visual applications - -Not everyone is a fan of the command line, for them there is a list of GUI clients on the official Git website: - - - -### Enhanced Git prompt - -Do one (or more) of the following: - -- -- -- - -### Git dotfiles - -Plone developers have dotfiles similar to these: -. - -## Learn more - -What's here is just the tip of the iceberg, there's plenty of Git knowledge on the web. - -A few good further resources are listed here (contributions welcome): - -- official online Git book: [Pro Git](http://git-scm.com/book/en/v2) -- PyCon 2015 talk: [Advanced Git by David Baumgold](https://www.youtube.com/watch?v=4EOZvow1mk4) diff --git a/coredev/guidelines.md b/coredev/guidelines.md deleted file mode 100644 index 6c9ea0236d..0000000000 --- a/coredev/guidelines.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -myst: - html_meta: - "description": "" - "property=og:description": "" - "property=og:title": "" - "keywords": "" ---- - -```todo -This should probably be purged. -It is redundant to the default [CONTRUBITING.md](https://github.com/plone/.github/blob/main/CONTRIBUTING.md) and other files. -``` - -% Note: this page is linked to from CONTRIBUTING.rst in all packages. Keep it short! - -# Guidelines for contributing to Plone Core - -You probably came here by clicking one of the 'guidelines for contributing' links on GitHub. -You probably have an issue to report or you want to create a pull request. -Thanks a lot! -Let's bring you up to speed with the minimum you need to know to start contributing. - -## Create an issue - -- If you know the issue is for a specific package, you can add an issue there. - When in doubt, create one in the [CMFPlone issue tracker](https://github.com/plone/Products.CMFPlone/issues). - -- Please specify a few things: - - - What steps reproduce the problem? - - What do you expect when you do that? - - What happens instead? - - Which Plone version are you using? - -- If it is a visual issue, can you add a screen shot? - -- If there is an error in the Site Setup error log, please include it. - Especially a traceback is helpful. - Click on the 'Display traceback as text' link if you see it in the error log. - - -## Create a pull request - -- Legally, you can NOT contribute code unless you have signed the {doc}`contributor agreement `. - This means that we can NOT accept pull requests from you unless this is done, so please don't put the code reviewers at risk and do it anyways. -- Add a changelog entry as file in the news directory. - For helpful instructions, please see: -- For new features, an addition to README.rst is probably needed. - A package may include other documentation that needs updating. -- All text that can be shown in a browser must be translatable. - Please mark all such strings as translatable. -- Be nice and use code quality checkers like flake8 and jshint. -- See if you can use git to squash multiple commits into one where this makes sense. - If you are not comfortable with git, never mind. -- If after reading this you become hesitant: don't worry. - You can always create a pull request, mark it as WIP (work in progress), and improve the above points later. diff --git a/coredev/index.md b/coredev/index.md deleted file mode 100644 index 80eb9b6130..0000000000 --- a/coredev/index.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -myst: - html_meta: - "description": "Development in Plone" - "property=og:description": "Development in Plone" - "property=og:title": "Development in Plone" - "keywords": "Developing, Plone, Contributing" ---- - -# Development in Plone - -This part describes the process of development in Plone. -It is primarily a technical resource for setting up your development environment, fixing bugs, and writing Plone Improvement Proposals (PLIPs). - - -## Plone Contributor Agreement - -You must sign the [Plone Contributor Agreement](https://plone.org/foundation/contributors-agreement). - -We can **NOT** accept pull requests from you until you have signed and returned the Contributor Agreement, and been approved. -Please don't put the code reviewers at risk by ignoring this requirement. - - -## Contents - -```{toctree} -:maxdepth: 2 - -guidelines -agreement -culture -getting-started-with-development -documentation -plips -issues -release -git -package-dependencies -``` - - -## Additional material - -These are some documents used as reference for this documentation. - -```{toctree} -:maxdepth: 1 - -contributors-agreement-explained -continous-integration -roboto -mrdeveloper -plip-review -``` - -```{todo} -The style guides are ancient and need to be overhauled. -``` - -Documenation's style is guided by Vale and the Microsoft Style Guide. -See [Contributing to Documentation](https://6.docs.plone.org/contributing/index.html). - -Our coding style guides are located at the [Plone Style Guide](https://5.docs.plone.org/develop/styleguide/index.html section. diff --git a/coredev/mrdeveloper.md b/coredev/mrdeveloper.md deleted file mode 100644 index 83d90a553f..0000000000 --- a/coredev/mrdeveloper.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -myst: - html_meta: - "description": "mr.developer" - "property=og:description": "mr.developer" - "property=og:title": "mr.developer" - "keywords": "mr.developer" ---- - -# `mr.developer` - -This buildout uses `mr.developer` to manage package development. -See https://pypi.org/project/mr.developer/ for more information, or run `bin/develop help` for a list of available commands. - -The most common workflow to get all the latest updates is: - -```shell -git pull -bin/develop rb -``` - -This will get you the latest `coredev` configuration, checkout and update all packages via git and Subversion in src, and run buildout to configure the whole thing. - -From time to time you can check if some old cruft has accumulated: - -```shell -bin/develop st -``` - -If this prints any lines with a question mark in front, you can cleanup by: - -```shell -bin/develop purge -``` - -This will remove packages from {file}`src/` which are no longer needed, as they have been replaced by proper egg releases of these packages. diff --git a/coredev/packages-dependencies.md b/coredev/packages-dependencies.md deleted file mode 100644 index d6bcd581a1..0000000000 --- a/coredev/packages-dependencies.md +++ /dev/null @@ -1,354 +0,0 @@ ---- -myst: - html_meta: - "description": "This chapter describes the architecture of Plone's packages and dependencies." - "property=og:description": "This chapter describes the architecture of Plone's packages and dependencies." - "property=og:title": "Architecture: packages and dependecies" - "keywords": "Architecture, packages, dependecies, Plone" ---- - -# Architecture: packages and dependecies - -This chapter describes the architecture of Plone's packages and dependencies. - - -## Motivation - -In the past, lots of indirections were introduced in Plone's packages and dependecies. -Our goal in the long run is to untangle them and get a direct dependency graph. -This document shows the current state as an orientation. - - -## Overview - -There are multiple level of dependencies: - -- package level (`setup.py`/`setup.cfg`) -- Python level (imports) -- ZCML level (includes) -- testing (need for layers, such as functional testing) - -We do not have any circular dependencies at the package level anymore. -This was solved already. - -Nevertheless we have indirection on all other levels. -Since Plone consists of a lot of packages, it is complex to untangle those. - - -## Mental model - -A base mental model for how Plone is organized in Plone 6 since alpha 4 is shown in the following diagram: - -``` -┌────────────────────────────┐ -│ │ -│ On top of Products.CMFPlone│ -│ like: │ -│ - Plone │ -│ - plone.api │ -│ - plone.volto │ -│ - plone.app.iterate │ -│ - plone.app.update │ -│ │ -├────────────────────────────┤ -│ │ -│ Products.CMFPlone │ -│ │ -├────────────────────────────┤ -│ │ -│ The space between │ -│ │ -│ - most of plone.app.* │ -│ - but also some other │ -│ │ -├────────────────────────────┤ -│ │ -│ plone.base │ -│ │ -├────────────────────────────┤ -│ │ -│ The Foundations │ -│ │ -│ - Zope │ -│ - CMFCore │ -│ - PAS/PlonePAS │ -│ - plone.registry │ -│ - plone.dexterity │ -│ - plone.behavior │ -│ - .... │ -│ │ -└────────────────────────────┘ -``` - -As a rough model we have two packages as dividing lines: - -1. `Products.CMFPlone` -2. `plone.base` - - -## Packages in detail - -If we look deeper into those, we have more sub-dividers, but first group all into the three groups: - -Then, based on the 6.0.0.a4 release, these are the packages: - - -### Above `Products.CMFPlone` - -- Plone -- plone.api -- plone.app.iterate -- plone.app.upgrade -- plone.restapi -- plone.volto -- Products.CMFPlacefulWorkflow - - -### Between `Products.CMFPlone` and `plone.base` - -- collective.monkeypatcher -- plone.app.caching -- plone.app.content -- plone.app.contentlisting -- plone.app.contentmenu -- plone.app.contentrules -- plone.app.contenttypes -- plone.app.customerize -- plone.app.dexterity -- plone.app.discussion -- plone.app.event -- plone.app.i18n -- plone.app.intid -- plone.app.layout -- plone.app.linkintegrity -- plone.app.locales -- plone.app.lockingbehavior -- plone.app.multilingual -- plone.app.portlets -- plone.app.querystring -- plone.app.redirector -- plone.app.registry -- plone.app.relationfield -- plone.app.textfield -- plone.app.theming -- plone.app.users -- plone.app.uuid -- plone.app.versioningbehavior -- plone.app.viewletmanager -- plone.app.vocabularies -- plone.app.widgets -- plone.app.workflow -- plone.app.z3cform -- plone.browserlayer -- plone.cachepurging -- plone.contentrules -- plone.formwidget.namedfile -- plone.formwidget.recurrence -- plone.i18n -- plone.namedfile -- plone.outputfilters -- plone.portlet.collection -- plone.portlet.static -- plone.portlets -- plone.protect -- plone.resourceeditor -- plone.rfc822 -- plone.schemaeditor -- plone.session -- plone.staticresources -- plone.stringinterp -- plone.theme -- plonetheme.barceloneta -- Products.isurlinportal - - -### The foundation below `plone.base` - - -#### Plone world - -- borg.localrole -- plone.alterego -- plone.autoform -- plone.autoinclude -- plone.batching -- plone.behavior -- plone.caching -- plone.dexterity -- plone.event -- plone.folder -- plone.indexer -- plone.intelligenttext -- plone.keyring -- plone.locking -- plone.memoize -- plone.registry -- plone.resource -- plone.rest -- plone.scale -- plone.schema -- plone.subrequest -- plone.supermodel -- plone.transformchain -- plone.uuid -- plone.z3cform -- Products.DateRecurringIndex -- Products.ExtendedPathIndex -- Products.MimetypesRegistry -- Products.PlonePAS -- Products.PortalTransforms -- Products.statusmessages - - -#### Zope ecosystem - -- Chameleon -- diazo -- five.customerize -- five.intid -- five.localsitemanager -- icalendar -- Products.CMFCore -- Products.CMFDiffTool -- Products.CMFDynamicViewFTI -- Products.CMFEditions -- Products.CMFUid -- Products.DCWorkflow -- Products.ExternalMethod -- Products.GenericSetup -- Products.MailHost -- Products.PluggableAuthService -- Products.PluginRegistry -- Products.PythonScripts -- Products.Sessions -- Products.SiteErrorLog -- Products.StandardCacheManagers -- Products.ZopeVersionControl -- repoze.xmliter -- webresource -- z3c.caching -- z3c.form -- z3c.formwidget.query -- z3c.objpath -- z3c.pt -- z3c.relationfield -- z3c.zcmlhook -- zc.recipe.egg -- zc.relation -- zodbverify -- zope.copy -- zope.intid -- zope.keyreference - - -#### Zope core - -- AccessControl -- Acquisition -- AuthEncoding -- beautifulsoup4 -- BTrees -- DateTime -- DocumentTemplate -- ExtensionClass -- Missing -- MultiMapping -- Persistence -- persistent -- Products.BTreeFolder2 -- Products.ZCatalog -- Record -- RestrictedPython -- transaction -- zc.lockfile -- ZConfig -- zdaemon -- ZEO -- zExceptions -- ZODB -- ZODB3 -- zodbpickle -- Zope -- zope.annotation -- zope.app.locales -- zope.browser -- zope.browsermenu -- zope.browserpage -- zope.browserresource -- zope.cachedescriptors -- zope.component -- zope.componentvocabulary -- zope.configuration -- zope.container -- zope.contentprovider -- zope.contenttype -- zope.datetime -- zope.deferredimport -- zope.deprecation -- zope.dottedname -- zope.event -- zope.exceptions -- zope.filerepresentation -- zope.globalrequest -- zope.hookable -- zope.i18n -- zope.i18nmessageid -- zope.interface -- zope.lifecycleevent -- zope.location -- zope.pagetemplate -- zope.processlifetime -- zope.proxy -- zope.ptresource -- zope.publisher -- zope.ramcache -- zope.schema -- zope.security -- zope.sendmail -- zope.sequencesort -- zope.site -- zope.size -- zope.structuredtext -- zope.tal -- zope.tales -- zope.testbrowser -- zope.testing -- zope.traversing -- zope.viewlet -- Zope2 - - -#### Libraries - -- attrs -- cffi -- cssselect -- decorator -- docutils -- feedparser -- future -- importlib_metadata -- jsonschema -- Markdown -- multipart -- Paste -- PasteDeploy -- piexif -- Pillow -- pycparser -- PyJWT -- pyrsistent -- python_dotenv -- python_gettext -- requests -- roman -- sgmllib3k -- simplejson -- soupsieve -- Unidecode -- urllib3 -- waitress -- WebOb -- WebTest -- WSGIProxy2 -- zipp diff --git a/coredev/plip-review.md b/coredev/plip-review.md deleted file mode 100644 index 78aed655ad..0000000000 --- a/coredev/plip-review.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -myst: - html_meta: - "description": "PLIP review" - "property=og:description": "PLIP review" - "property=og:title": "PLIP review" - "keywords": "PLIP, review, Plone Improvement Proposal, Plone" ---- - -# PLIP review - -A Plone Improvement Proposal (PLIP) is a formal process to propose a change to improve Plone. - - -## Expectations - -A good PLIP review takes about four hours. -Please plan accordingly. -When you are done, if you have access to core, commit the review to the `plips` folder, and reference the PLIP in your commit message. -If you do not have access, attach your review to the PLIP ticket itself. - - -## Setting up the environment - -Follow the instructions in {doc}`getting-started-with-development`. -You will need to checkout the branch to which the PLIP is assigned. -Instead of running the buildout with the default buildout file, you will run the configuration specific to that PLIP: - -```shell -./bin/buildout -c plips/plipXXXX.cfg -``` - - -## Functionality review - -This section describes the topics that may be addressed in a PLIP review, depending on the nature of the PLIP itself. - - -### General - -- Does the PLIP actually do what the implementers proposed? - Are there incomplete variations? -- Were there any errors running buildout? - Did the migration(s) work? -- Do error and status messages make sense? - Are they properly internationalized? -- Are there any performance considerations? - Has the implementer addressed them, if so? - - -### Bugs - -- Are there any bugs? - Nothing is too big nor small. -- Do fields handle wacky data? - How about strings in date fields, or nulls in required? -- Is validation up to snuff and sensical? - Is it too restrictive or not restrictive enough? - - -### Usability Issues - -- Is the implementation usable? -- How will novice end users respond to the change? -- Does this PLIP need a usability review? - If you think this PLIP needs a usability review, change the state to "please review" and add a note in the comments. -- Is the PLIP consistent with the rest of Plone? - For example, if there is control panel configuration, does the new form fit in with the rest of the panels? -- Does everything flow nicely for novice and advanced users? - Is there any workflow that feels odd? -- Are there any new permissions and do they work properly? - Does their role assignment make sense? - - -### Documentation Issues - -- Is the corresponding documentation for the end user, be it developer or Plone user, sufficient? -- Is the change itself properly documented? - -Report bugs or issues on GitHub as you would for any Plone bug. -Reference the PLIP in the bug, assign to its implementer, and add a tag for the PLIP in the form of `plip-xxx`. -This way the implementer can find help if they need it. -Also set a priority for the ticket. -The PLIP will not be merged until all blockers and critical bugs are fixed. - - -### Code Review - - -#### Python - -- Is this code maintainable? -- Is the code properly documented? -- Does the code adhere to PEP8 standards (more or less)? -- Are they importing deprecated modules? - - -#### JavaScript - -- Does the JavaScript meet our set of JavaScript standards? - See our section about [JavaScript](https://5.docs.plone.org/develop/addons/javascript/index.html) and the [JavaScript Style Guide](https://5.docs.plone.org/develop/styleguide/javascript.html). -- Does the JavaScript work in all currently supported browsers? - Is it performant? - -```{todo} -Update links from Plone 5 Documentation to Plone 6 Documentation, when they exist. -See https://github.com/plone/documentation/issues/1330 -``` - -#### ME/TAL - -- Does the PLIP use views appropriately, avoiding too much logic? -- Is there any code in a loop that could potentially be a performance issue? -- Are there any deprecated or old style ME/TAL lines of code, such as using `DateTime`? -- Is the rendered HTML compliant with standards? Are IDs and classes used appropriately? diff --git a/coredev/plips.md b/coredev/plips.md deleted file mode 100644 index 408793d471..0000000000 --- a/coredev/plips.md +++ /dev/null @@ -1,295 +0,0 @@ ---- -myst: - html_meta: - "description": "Plone Improvement Proposals (PLIPs)" - "property=og:description": "Plone Improvement Proposals (PLIPs)" - "property=og:title": "Plone Improvement Proposals (PLIPs)" - "keywords": "Plone Improvement Proposal, PLIP)" ---- - -# Plone Improvement Proposals (PLIPs) - -A PLIP is a Plone Improvement Proposal. -It is a change to a Plone package that would affect everyone. -PLIPs go through a different process than bug fixes because of their broad reaching effect. -The Plone Framework Team reviews all PLIPs to be sure that it's in the best interest of the broader community to be implemented and that it is of high quality. - - -## Frequently asked questions about PLIPs - -This section provides detailed answers to common questions about PLIPs. - - -### PLIP or bugfix? - -In general, anything that changes the API of Plone in the backend or the user interface (UI) on the front end should be filed as a PLIP. -When in doubt, submit it as a PLIP. -The Framework Team is eager to reduce its own workload and will reclassify it for you. -If the change you are proposing is not in the scope of a PLIP, a GitHub pull request or issue is the right format. -The key point here is that each change must be documented, allowing it to be tracked and understood. - - -### Who can submit PLIPs? - -Anyone who has signed a Plone Contributor Agreement can work on a PLIP. -Don't let the wording freak you out: signing the agreement is easy and you will get access almost immediately. - -You do not have to be the most amazing coder in the entire world to submit a PLIP. -The Framework Team is happy to help you at any point in the process. - -Submitting a PLIP can be a great learning process. -We encourage people of all backgrounds to submit a PLIP. -When the PLIP is accepted, a Framework Team member will "champion" your PLIP and be dedicated to its completion. - -PLIPs are not just for code monkeys. -If you have ideas on new interactions or UI your ideas are more than welcome. - -We will help you pair up with implementers if needed. - - -### What is a PLIP champion? - -When you submit your PLIP and it is approved, a Framework Team member who is especially excited about seeing the PLIP completed will be assigned to your PLIP as a champion. - -They are there to push you through completion, as well as answer any questions and provide guidance. - -A champion fulfill the following tasks. - -- Answer any questions the PLIP implementor has, technical or otherwise. -- Encourage the PLIP author by constantly giving feedback and encouragement. -- Keep the implementer aware of timelines, and push to get things done on time. -- Assist with finding additional help when needed to complete the implementation in a timely matter. - -Keep in mind that champions are in passive mode by default. -If you need help or guidance, please reach out to them as soon as possible to activate help mode. - - -### Can I get involved in other ways? - -If you want to experience the process and how it works, help us review PLIPs as the implementations finish up. -Ask one of the Framework Team members what PLIPs are available for review, or check the status of PLIPs at the [GitHub issues](https://github.com/plone/Products.CMFPlone/issues) page -for [Products.CMFPlone](https://github.com/Plone/Products.CMFPlone) -for [issues tagged with "03 type: feature (plip)"](https://github.com/plone/Products.CMFPlone/labels/03%20type%3A%20feature%20%28plip%29). - -Make sure to let us know you intend to review the PLIP by communicating that to the [Framework Team](https://community.plone.org/c/development/framework-team). - -Then, follow the instructions for {doc}`reviewing a PLIP `. - -Thank you in advance! - - -### When can I submit a PLIP? - -Today, tomorrow, any time! - -After the PLIP is accepted, the Framework Team will try to judge complexity and time to completion, and assign it to a milestone. - -You can begin work immediately, and we encourage submitting fast and furious. - - -### When is the PLIP due? - -**Summary: As soon as you get it done.** - -Technically, we want to see it completed for the release to which it's assigned. -We know that things get busy, and new problems may make PLIPs more complicated, and we will push it to the next release. - -In general, we don't want to track a PLIP for more than a year. - -If your PLIP is accepted and we haven't seen activity in over a year, we will probably ask you to restart the whole process. - - -### What happens if your PLIP is not accepted? - -If a PLIP isn't accepted in core, it doesn't mean it's a bad idea. -It is often the case that there are competing implementations, and we want to see it vetted as an add-on before "blessing" a preferred implementation. - - -## Process Overview - -1. Submit a PLIP at any time. -2. PLIP is approved for inclusion into core for a given release. -3. Developer implements PLIP (code, tests, documentation). -4. PLIP is submitted for review by developer. -5. Framework Team reviews the PLIP and gives feedback. -6. Developer addresses concerns in feedback and re-submits the PLIP, if necessary. -7. This may go back and forth a few times, until both the Framework Team and developer are happy with the result. -8. PLIP is approved for merge. - In rare circumstances, a PLIP will be rejected. - This is usually the result of the developer not responding to feedback or dropping out of the process. - Hang in there! -9. After all other PLIPs are merged, a release is cut. - Standby for bugs! - - -(how-to-submit-a-plip)= - -## How to submit a PLIP - -Whether you want to update the default theme, or rip out a piece of architecture, everyone should go through the PLIP process. -If you need help at any point in this process, please contact a member of the Framework Team personally or ask for help at the [Framework Team Space](https://community.plone.org/c/development/framework-team). - -A PLIP is a [GitHub issue](https://github.com/plone/Products.CMFPlone/issues/new) on [`Products.CMFPlone`](https://github.com/Plone/Products.CMFPlone) with a special template and a specific tag. - -To get started, open a new issue. -The issue will be prefilled with headings and comments for a bug or a PLIP. -Remove the bug part. -Fill in all applicable fields. -After submitting, select the tag `03 type: feature (plip)` for the issues. - -When writing a PLIP, be as specific and to-the-point as you can. -Remember your audience. -To get support for your proposal, people will have to be able to read it! - -A good PLIP is sufficiently clear for a knowledgeable Plone user to understand the proposed changes, and sufficiently detailed for the release manager and other developers to understand the full impact the proposal would have on the code base. - -You don't have to list every line of code that needs to be changed, but you should also give an indication that you have some idea of how the change can be feasibly implemented. - -After your PLIP is written, solicit feedback on your idea on the [Plone Community Forum](https://community.plone.org/). -In this vetting process, you want to make sure that the change won't adversely affect other people on accident. -Others may be able to point out risks or even offer up better or existing solutions. - -Please note a few things: - -- It is very rare that the "Risks" section will be empty or none. -- If you find this is the case, and your PLIP is anything more than trivial, maybe some more vetting should be done. -- The seconder field is REQUIRED. - -We will send the PLIP back to you if it is not filled in. -Currently, this is just someone else who thinks your PLIP is a good idea, a +1. - -In the near future, we will start asking that the seconder is either a coding partner, or someone who is willing and able to finish the PLIP should something happen to the implementer. - - -### Evaluating PLIPs - -After you submit your PLIP, the Framework Team will meet within a couple weeks, and let you know if the PLIP is accepted. -If the PLIP is not accepted, please don't be sad! - -We encourage most PLIPs to go through the add-on process at first, if at all possible, to make sure the majority of the community uses it. - -All communication with you occurs on the PLIP issue itself. -Please keep your eyes and inbox open for changes. - -These are the criteria by which the framework team will review your work: - -- What is size and status of the work needed to be done? -- Is it already an add-on and well established? -- Is this idea well baked and expressed clearly? -- Does the work proposed belong in Plone now, or in the future? -- Is this PLIP more appropriate as a qualified add-on? -- Is this PLIP too risky? - -See the {doc}`plip-review` page for more information. - - -## Implementing your PLIP - -You can start the development at any time, but if you are going to modify Plone itself, it is a good idea to wait to see if your idea is approved. - - -### General Rules - -- Any new packages must be in a branch in the `plone` namespace in GitHub. - You don't have to develop there, but it must be there when submitted. - We recommend using branches off of the repositories under the Plone GitHub organization, and will detail that below. -- Most importantly, the PLIP reviewers must be able run buildout and everything should "just work"™. -- Any new code must: - - - Be {doc}`properly documented `. - - Have clear code. - - [Follow our style guides](https://5.docs.plone.org/develop/styleguide/index.html). - For convenience and better code quality use Python, JavaScript, and other code linting plugins in your editor. - - [Be tested](https://5.docs.plone.org/develop/testing/index.html). - -```{todo} -Update links from Plone 5 to Plone 6 Documentation, once content is migrated. -See https://github.com/plone/documentation/issues/1330 and other issues. -``` - - -### Creating a new PLIP branch - -Create a buildout configuration file for your PLIP in the `plips` folder. -Give it a descriptive name, starting with the PLIP number, for example, {file}`plip-1234-widget-frobbing.cfg`. - -The PLIP number is your PLIP's issue number. - -This file will define the branches you're working with in your PLIP, along with other buildout configuration. - -It should look something like the following, such as in a file {file}`plips/plip-1234-widget-frobbing.cfg`. - -```ini -[buildout] -extends = plipbase.cfg -auto-checkout += - plone.somepackage - plone.app.someotherpackage - -[sources] -plone.somepackage = git https://github.com/plone/plone.somepackage.git branch=plip-1234-widget-frobbing -plone.app.someotherpackage = git https://github.com/plone/plone.app.somepackage.git branch=plip-1234-widget-frobbing - -[instance] -eggs += - plone.somepackage - plone.app.someotherpackage -zcml += - plone.somepackage - plone.app.someotherpackage -``` - -Use the same naming convention when you branch existing packages. -You should always branch packages when working on PLIPs. - - -### Working on a PLIP - -To work on a PLIP, you bootstrap buildout, and then invoke buildout with your PLIP configuration: - -```shell -virtualenv . -./bin/pip install -r requirements.txt -./bin/buildout -c plips/plip-1234-widget-frobbing.cfg -``` - -If you are using a {file}`local.cfg` to extend your PLIP file with some changes that you do not want to commit accidentally, be aware that you need to override some settings from {file}`plipbase.cfg` to avoid some files being created in the {file}`plips` directory or in the directory above the buildout directory. -This is done as shown below. - -```ini -[buildout] -extends = plips/plip-1234-widget-frobbing.cfg -develop-eggs-directory = ./develop-eggs -bin-directory = ./bin -parts-directory = ./parts -sources-dir = ./src -installed = .installed.cfg - -[instance] -var = ./var -``` - - -### Finishing up - -Before marking your PLIP as ready for review, please add a file to give a set of instructions to the PLIP reviewer. -This file should be called {file}`plip__notes.txt`. -This should include, but is not limited to: - -- URLs pointing to all documentation created and updated -- Any concerns and issues still remaining -- Any weird buildout things - -Once you have finished, update your PLIP issue to indicate that it is ready for review. -The Framework Team will assign 2-3 people to review your PLIP. -They will follow the guidelines listed at {doc}`plip-review`. - -After the PLIP has been accepted by the Framework Team and the release manager, you will be asked to merge your work into the main development line. -Merging the PLIP in is not the hardest part, but you must think about it when you develop. - -You'll have to interact with a large number of people to get it all set up. -The merge may cause problems with other PLIPs coming in. -During the merge phase you must be prepared to help out with all the features and bugs that arise. - -If all went as planned, the next Plone release will carry on with your PLIP in it. -You'll be expected to help out with that feature after it's been released (within reason). diff --git a/coredev/roboto.md b/coredev/roboto.md deleted file mode 100644 index 89d42038f0..0000000000 --- a/coredev/roboto.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -myst: - html_meta: - "description": "Mr. Roboto" - "property=og:description": "Mr. Roboto" - "property=og:title": "Mr. Roboto" - "keywords": "Mr. Roboto, mr.roboto, Plone" ---- - -# Mr. Roboto - -```{todo} -Add brief description of what is Mr. Roboto and what it does. -``` - -## GitHub push - -When a push happens on GitHub, `mr.roboto` is triggered and it starts to analyze the push. - -- If it's on `buildout-coredev`, it starts the job of the branch that has been pushed. - In this case, we send to `plone-cvs` the commit to keep track of the commits on that list. -- If it's on a package that's on the {file}`sources.cfg` of a `buildout-coredev`, it starts the coredev jobs that are linked to that package and a kgs job with that package. - This kgs job is a snapshot of the last working version of the `buildout.coredev` with the newest version of the package that is involved on the push. - These jobs are really fast, as we only test the package applied to the kgs Plone and Python version `coredev` buildout. -- If it's on a PLIP specification, it runs the job that is configured Through The Web on the `mr.roboto` interface at http://jenkins.plone.org/roboto/plips. - -```{todo} -`http://jenkins.plone.org/roboto/plips` is obsolete, and returns a 404 not found. -``` - - -## Job finishes - -When Jenkins finishes a job, it makes a callback to `mr.roboto`, which in turn does the following: - -- If it comes from a `coredev` job, when all the `coredev` jobs related to that push are finished, it writes a comment on the GitHub commit with all the information. - It does this one time only, with all the information, so no more empty mails from the GitHub notification system. -- If it comes from a kgs job and all the kgs jobs are finished, (that may take max 10 min) and some have failed, we send an email to the testbot mailing list saying that a commit failed on the kgs job. - We also send an email to [plone-cvs](https://sourceforge.net/projects/plone/lists/plone-cvs) with the information to keep track of all the commits. -- If it comes from a kgs job and all the kgs jobs are finished, and all are working, we send an email to [plone-cvs](https://sourceforge.net/projects/plone/lists/plone-cvs) with the information to keep track of all the commits. - -For all kgs jobs jenkins sends an email to the author with the results when is finished. - -All the notifications have an URL similar to http://jenkins.plone.org/roboto/get_info?push=9a183de85b3f48abb363fa8286928a10. - -```{todo} -http://jenkins.plone.org/roboto/get_info?push=9a183de85b3f48abb363fa8286928a10 is obsolete, and returns a 404 not found. -``` - -On this URL, there is the commit hash, who committed it, the diff, the files, and the result for each Jenkins job. - -- [plone-testbot](https://lists.plone.org/mailman/listinfo/plone-testbot) mailing list receives messages only when a test fails on the kgs environment, and may take up to ten minutes from the push. -- [plone-cvs](https://sourceforge.net/projects/plone/lists/plone-cvs) always has the commit, diff, and the information, and it may take ten minutes to get there after the push. -- The author receives the results of tests failing against kgs after ten minutes after the push. - -```{note} -In case of integration errors with other packages that may fail because of the push, kgs will not be aware of that. -It's important that at the end (and after the fifty minutes that takes the `coredev` jobs to complete), that you also check the latest version of `coredev` with your push. -``` diff --git a/coredev/troubleshooting.md b/coredev/troubleshooting.md deleted file mode 100644 index db636fd806..0000000000 --- a/coredev/troubleshooting.md +++ /dev/null @@ -1,182 +0,0 @@ ---- -myst: - html_meta: - "description": "Troubleshooting development issues in Plone" - "property=og:description": "Troubleshooting development issues in Plone" - "property=og:title": "Troubleshooting development issues in Plone" - "keywords": "Troubleshooting, development issues, Plone" ---- - -# Troubleshooting - -This chapter describes how to troubleshoot development issues in Plone. - - -## Buildout issues - -Buildout can be frustrating for those unfamiliar with parsing through autistic robot language. -These errors are almost always a quick fix, and a little bit of understanding goes a long way. - - -### Errors running `bootstrap.py` - -You may not even get to running buildout, and then you will already have an error. -Let's take this one for example: - -```console - File "/usr/local/lib/python2.6/site-packages/distribute-0.6.13-py2.6.egg/pkg_resources.py", line 556, in resolve - raise VersionConflict(dist,req) # XXX put more info here - pkg_resources.VersionConflict: (zc.buildout 1.5.1 (/usr/local/lib/python2.6/site-packages/zc.buildout-1.5.1-py2.6.egg), Requirement.parse('zc.buildout==1.5.2')) -``` - -Buildout has simply noticed that the version of buildout required by the file `bootstrap.py` you are trying to run does not match the version of buildout in your Python library. -In the error above, your system has buildout 1.5.1 installed and the `bootstrap.py` file wants to run with 1.5.2. - -To fix, you have a couple options. -First, you can force buildout to run with the version you already have installed by invoking the version tag. -This tells your Plone `bootstrap.py` file to play nicely with the version that you already have installed. -In the case of the error pasted above, that would be: - -```shell -python bootstrap.py --version=1.5.1 -``` - -I personally know that versions 1.4.4, 1.5.1, and 1.5.2 all work this way. - -The other option is to delete your current egg and force the upgrade. -In the case of the error above, delete the egg the system currently has, for example: - -```shell -rm -rf /usr/local/lib/python2.6/site-packages/zc.buildout-1.5.1-py2.6.egg -``` - -When you rerun bootstrap, it will look for the buildout of the egg, note that there isn't one, and then go fetch a new egg in the version that it wants for you. - -Do one of those and re-run bootstrap. - -One other thing of note is that running bootstrap effectively ties that Python executable and all of its libraries to your buildout. -If you have several Python installs, and want to switch which Python is tied to your buildout, simply rerun `bootstrap.py` with the new Python (and then rerun buildout). -You may get the same error above again, but now that you know how to fix it, you can spend that time drinking beer instead of smashing your keyboard. - -Hooray! - - -### When `mr.developer` is unhappy - -`mr.developer` is never unhappy, except when it is. -Although this technically isn't a buildout issue, it happens when running buildout, so I'm putting it under buildout issues. - -When working with the dev instance, especially with all the moving back and forth between GitHub and Subversion, you may have an old copy of a `src` package. -The error looks like: - -```console -mr.developer: Can't update package 'Products.CMFPlone' because its URL doesn't match. -``` - -As long as you don't have any pending commits, you just need to remove the package from {file}`src/` and it will recheck it out for you when it updates. - -You can also get such fun errors as: - -```console -Link to http://sphinx.pocoo.org/ ***BLOCKED*** by --allow-hosts -``` - -These are OK to ignore if and only if the lines following it say: - -```console -Getting distribution for 'Sphinx==1.0.7'. -Got Sphinx 1.0.7. -``` - -If buildout ends with warning you that some packages could not be downloaded, then chances are that package wasn't downloaded. -This is bad and could cause all sorts of whack out errors when you start or try to run things because it never actually downloaded the package. - -There are two ways to get this error to go away. - -The first is to delete all instances of host filtering. -Go through all the files and delete any lines which say `allow-hosts =` and `allow-hosts +=`. -In theory, by restricting which hosts you download from, buildout will go faster. -The point is that they are safely deletable. - -The second option is to allow the host that it is pointing to by adding something like this to your `.cfg`: - -```cfg -allow-hosts += sphinx.pocoo.org -``` - -Again, this is only necessary if the package wasn't found in the end. - - -### `mr.developer` path errors - -```console -ERROR: You are not in a path which has mr.developer installed (:file:`.mr.developer.cfg` not found). -``` - -When running any {command}`./bin/develop` command. - -To fix, do: - -```shell -ln -s plips/.mr.developer.cfg -``` - - -## Other random issues - -```{TODO} -These need to be revalidated -``` - - -### Dirty packages - -```console -ERROR: Can't update package 'Some package', because it's dirty. -``` - - -#### Fix - -`mr.developer` is complaining because a file has been changed or added, but not committed. - -Use `bin/develop update --force`. -Adding `*.pyc *~.nib *.egg-info .installed.cfg *.pt.py *.cpt.py *.zpt.py *.html.py *.egg` to your subversion configuration's `global-ignores` has been suggested as a more permanent solution. - - -### No module named zope 2 - -```console -ImportError: No module named Zope2" when building using a PLIP cfg file. -``` - -Appears to not actually be the case. -Delete {file}`mkzopeinstance.py` from {file}`bin/`, and rerun buildout to correct this if you're finding it irksome. - - -### Can't open file '/Startup/run.py' - -Two possible fixes. - -If you use Python 2.4 by mistake, use 2.6 instead. - -Or you may need to make sure you run `bin/buildout …` after `bin/develop …`. -Try removing {file}`parts/*`, {file}`bin/*`, {file}`.installed.cfg`, then re-bootstrap and re-run buildout, develop, buildout. - - -### Missing PIL - -{file}`pil.cfg` is included within this buildout to aid in PIL installation. -Run {command}`bin/buildout -c pil.cfg` to install. -This method does not work on Windows. -We're unable to run it by default. - - -### Modified egg issues - -{command}`bin/develop status` is showing that the `Products.CMFActionIcons` egg has been modified, but I haven't touched it. -And this is preventing `bin/develop up` from updating all the eggs. - -#### Fix - -Edit {file}`~/.subversion/config` and add `eggtest\*.egg` to the list of `global-ignores`. diff --git a/docs/_inc/_continuous-integration.md b/docs/_inc/_continuous-integration.md new file mode 100644 index 0000000000..4b29642242 --- /dev/null +++ b/docs/_inc/_continuous-integration.md @@ -0,0 +1,7 @@ +Plone project repositories use {term}`continuous integration` (CI) to run tests, ensure code quality, or provide previews for every contribution. +Plone uses GitHub workflows, Jenkins, Cypress, Read the Docs, and other services for CI. +All of a project's CI jobs must pass before a contribution may be accepted. + +```{seealso} +{doc}`/contributing/core/continuous-integration` +``` diff --git a/docs/_inc/_create-classic-ui-instance.md b/docs/_inc/_create-classic-ui-instance.md new file mode 100644 index 0000000000..2c768d90e3 --- /dev/null +++ b/docs/_inc/_create-classic-ui-instance.md @@ -0,0 +1,15 @@ + +Your instance starts in foreground mode. +This should be used only for troubleshooting or local demonstration purposes. + +Now you can visit `http://localhost:8080` in your browser. +Click the button {guilabel}`Create Classic UI Plone site`. + +Enter {guilabel}`username` of `admin`, and {guilabel}`password` of `admin`. + +Enter values in the form, and click the button {guilabel}`Create Plone Site`. + +You will be redirected to your new Classic UI Plone site. + +To stop the Plone instance in foreground mode, type {kbd}`ctrl-c`. + diff --git a/docs/_inc/_install-browser-reqs-classic-ui.md b/docs/_inc/_install-browser-reqs-classic-ui.md new file mode 100644 index 0000000000..3c5834310d --- /dev/null +++ b/docs/_inc/_install-browser-reqs-classic-ui.md @@ -0,0 +1,16 @@ +You can view the list of supported browsers for Classic UI at [Browserslist](https://browsersl.ist/#q=%3E%3D+0.5%25%0Alast+2+major+versions%0Anot+dead%0AChrome+%3E%3D+60%0AFirefox+%3E%3D+60%0AFirefox+ESR%0AiOS+%3E%3D+12%0ASafari+%3E%3D+12%0Anot+Explorer+%3C%3D+11). + +The supported web browsers for Classic UI are set according to [Bootstrap](https://getbootstrap.com/docs/5.3/getting-started/browsers-devices/#supported-browsers). +The following code snippet is the [browserslist configuration for Bootstrap 5.3.3](https://github.com/twbs/bootstrap/blob/v5.3.3/.browserslistrc). + +```shell +>= 0.5% +last 2 major versions +not dead +Chrome >= 60 +Firefox >= 60 +Firefox ESR +iOS >= 12 +Safari >= 12 +not Explorer <= 11 +``` diff --git a/docs/_inc/_install-pillow.md b/docs/_inc/_install-pillow.md new file mode 100644 index 0000000000..acd418fdd0 --- /dev/null +++ b/docs/_inc/_install-pillow.md @@ -0,0 +1,24 @@ +``````{note} +After generating a project, then running `make install`, if you see an error message `ERROR: Failed building wheel for Pillow` or `The headers or library files could not be found for jpeg, a required dependency when compiling Pillow from source.`, then you need to install Pillow's dependencies. + +`````{tab-set} + +````{tab-item} macOS +```shell +brew install zlib libjpeg +``` +```` + +````{tab-item} Linux +```shell +apt install zlib1g-dev libjpeg8-dev +``` +```` +````` + +You will then need to run `make install` again. + +```{seealso} +See also the Pillow documentation [External Libraries](https://pillow.readthedocs.io/en/latest/installation/building-from-source.html#external-libraries) for additional libraries that you might need. +``` +`````` diff --git a/docs/_inc/_install-python-plone61.md b/docs/_inc/_install-python-plone61.md new file mode 100644 index 0000000000..b819d58578 --- /dev/null +++ b/docs/_inc/_install-python-plone61.md @@ -0,0 +1,9 @@ +Installing Python is beyond the scope of this documentation. +However, it is recommended to use a Python version manager, {term}`pyenv`, that allows you to install multiple versions of Python on your development environment without destroying your system's Python. + +```{warning} +Do not create or activate a Python virtual environment at this time. +The instructions below will create one. +``` + +Plone 6.1 requires Python version {{SUPPORTED_PYTHON_VERSIONS_PLONE61}}. diff --git a/docs/_static/classic-ui.png b/docs/_static/classic-ui.png new file mode 100644 index 0000000000..595d0b0fe3 Binary files /dev/null and b/docs/_static/classic-ui.png differ diff --git a/docs/_static/conceptual-guides/xkcd-1987-python-environment.png b/docs/_static/conceptual-guides/xkcd-1987-python-environment.png new file mode 100644 index 0000000000..a8e8fd619e Binary files /dev/null and b/docs/_static/conceptual-guides/xkcd-1987-python-environment.png differ diff --git a/docs/_static/contributing/core/icon-build-now.svg b/docs/_static/contributing/core/icon-build-now.svg new file mode 100644 index 0000000000..70b5d54b25 --- /dev/null +++ b/docs/_static/contributing/core/icon-build-now.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/_static/contributing/core/icon-retry.svg b/docs/_static/contributing/core/icon-retry.svg new file mode 100644 index 0000000000..cd349c5073 --- /dev/null +++ b/docs/_static/contributing/core/icon-retry.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/_static/contributing/core/icon-terminal.svg b/docs/_static/contributing/core/icon-terminal.svg new file mode 100644 index 0000000000..9f15c271a8 --- /dev/null +++ b/docs/_static/contributing/core/icon-terminal.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/_static/contributing/git-commit-submodule.jpg b/docs/_static/contributing/git-commit-submodule.jpg new file mode 100644 index 0000000000..f4bd9b45f0 Binary files /dev/null and b/docs/_static/contributing/git-commit-submodule.jpg differ diff --git a/docs/_static/contributing/github-navigation.png b/docs/_static/contributing/github-navigation.png new file mode 100644 index 0000000000..6c3da925ed Binary files /dev/null and b/docs/_static/contributing/github-navigation.png differ diff --git a/docs/_static/custom.css b/docs/_static/custom.css deleted file mode 100644 index 41bdd4361a..0000000000 --- a/docs/_static/custom.css +++ /dev/null @@ -1,468 +0,0 @@ -:root { - /* Add Font Awesome 5 icon and color for todo */ - --pst-icon-clipboard-list: '\f46d'; - --pst-icon-admonition-todo: var(--pst-icon-clipboard-list); - --pst-color-admonition-todo: 161, 46, 233; - --target-color: #b9ee9e; - --codeblock-color: #aad993; -} - -.visuallyhidden { - display: none; -} - -pre { - border-radius: 0; - background-color: white; - box-shadow: none; -} - -a, -a:visited, -main.bd-content #main-content a, -main.bd-content #main-content a:visited { - color: #2980b9; -} - -a:hover, -main.bd-content #main-content a:hover { - color: #1a567e; - text-decoration: none; -} - -ul { - list-style-type: square; -} - -ul li>p { - margin-bottom: 0.3rem; -} - -ol li>p { - margin-bottom: 0.3rem; -} - -img { - margin: 1rem 0; -} - -figure img, -img.figure, -.figure img { - box-shadow: 0 6px 24px 0 rgba(153, 153, 153, 0.3); -} - -.sidebar img.logo { - box-shadow: none; - width: 200px; - margin-bottom: 1rem; -} - -img.inline { - margin: 0; - height: 1em; -} - -span.linenos { - padding-right: 1em; -} - -p.ploneorglink img { - vertical-align: bottom; -} - -dt:target, -span.highlighted, -ul.search li span.highlighted { - background-color: var(--target-color); -} - -.bd-sidebar .nav ul { - padding: 0 0 0 1rem; -} - -.bd-sidebar .nav .toctree-checkbox~label i { - transform: rotate(90deg); -} - -.bd-sidebar .nav .toctree-checkbox:checked~label i { - transform: rotate(0deg); -} - -.toctree-wrapper .caption { - font-weight: bold; - font-size: 1.2em; - margin-top: 3rem; -} - -.toctree-wrapper ul { - list-style: none; -} - -section:not(#glossary) h1~dl { - display: grid; - grid-template-columns: max-content auto; -} - -section:not(#glossary) h1~dl dd { - margin-bottom: unset !important; -} - -div.section { - margin-bottom: 5rem; -} - -div.section div.section { - margin-bottom: 5rem; -} - -div.section div.section div.section { - margin-bottom: 2rem; -} - -/* admonitions */ -.admonition { - border-radius: 0; - border: none; - border-left: .2rem solid; - border-left-color: rgba(var(--pst-color-admonition-default), 1); -} - -.admonition .admonition-title { - margin-bottom: 1.5rem !important; -} - -/* admonition todo */ -.admonition.admonition-todo, -div.admonition.admonition-todo { - border-color: rgba(var(--pst-color-admonition-todo), 1); -} - -.admonition.admonition-todo>.admonition-title, -div.admonition.admonition-todo>.admonition-title { - background-color: rgba(var(--pst-color-admonition-todo), .1); -} - -.admonition.admonition-todo>.admonition-title::before, -div.admonition.admonition-todo>.admonition-title::before { - color: rgba(var(--pst-color-admonition-todo), 1); - content: var(--pst-icon-admonition-todo); -} - -.admonition-github-only.admonition { - display: none; -} - -/* admonition margin */ -.admonition.margin ul, -.admonition.margin ol { - padding-left: 1rem; -} - -.topic { - padding: 1.5em 1em .5em 1em; -} - -.topic-title { - font-weight: bold; -} - - -/* Bootstrap */ -.btn-primary { - color: #fff; - background-color: #2980b9; - border-color: #2980b9; -} - -.btn-primary { - background-color: #1f86ca; - border-color: #2980b9; -} - -/* Search */ - -/* Show search form. It is hidden by default. */ -#search-documentation, -#search-documentation~form, -#search-documentation~p { - display: block; -} - -#search-form:focus-within #shortcut-page, -.bd-search:focus-within #shortcut { - display: none; -} - -#shortcut-page.input-group-text { - padding-top: 0; - padding-bottom: 0; -} - -input#q { - border-radius: .25rem 0 0 .25rem; -} - -.form-control:focus { - box-shadow: none; - border-width: 2px; -} - -ul.search { - margin-left: 0; -} - -p.search-summary { - margin: 1em 0 2rem 0; -} - -#search-results ul { - list-style-type: none; - padding-left: 0; -} - -#search-results ul li, -ul.search li { - margin-bottom: 2rem; - padding: 0; - background-image: none; - border-bottom: none; -} - -#search-results ul li h3 { - margin: 0.4rem 0 .5rem; - font-size: 1.5rem; -} - -#search-results ul li .breadcrumbs { - display: flex; - flex-direction: row; - flex-wrap: wrap; -} - -#search-results ul li .breadcrumbs a { - font-weight: normal; -} - -#search-results ul li .breadcrumbs .lastbreadcrumb { - white-space: nowrap; - display: inline-block; - max-width: 12rem; - overflow: hidden; - /* "overflow"-Wert darf nicht "visible" sein */ - - text-overflow: ellipsis; -} - -ul.search li p.context { - margin-left: 0; -} - -/* Search form sidebar */ - -.bd-search { - font-size: .8rem; -} - -.bd-search:focus-within #search-input { - border-radius: .25rem; -} - -#shortcut.input-group-text { - padding-top: 0; - padding-bottom: 0; -} - -.bd-search input, -.bd-search .input-group-text { - font-size: .8rem; - padding-left: .5em; -} - -input#search-input { - padding-left: 2.1875rem; - border-radius: .25rem 0 0 .25rem; -} - -.search-icon { - position: absolute; - color: #a4a6a7; - left: .625rem; - z-index: 100; - align-self: center; -} - -.input-group-text kbd { - padding: 0rem 0.4rem; - font-size: 135%; -} - -.pathseparator { - padding: 0 0.7rem; -} - -/* header-article */ -div.header-article__label { - display: flex; - align-items: center; - margin: 0 auto 0 1em; - font-size: 80%; - overflow: hidden; - white-space: nowrap; -} - -/* submenu */ -.bd-toc { - box-shadow: 0 .2rem .5rem rgba(0, 0, 0, .05), 0 0 .0625rem rgba(0, 0, 0, .1); -} - -/* extra sidebar */ -div.sidebar:not(.margin) { - width: 40%; - float: right; - clear: right; - margin: .3rem 0 .3rem 0.5em; - padding: 2rem 0 1.5rem 1rem !important; - background-color: rgba(var(--pst-color-admonition-note), .1); - border: none; - border-left: 8px rgba(var(--pst-color-admonition-default), 1) solid; - border-radius: .2rem; - box-shadow: 0 .2rem .5rem rgba(0, 0, 0, .05), 0 0 .0625rem rgba(0, 0, 0, .1); -} - -div.sidebar:not(.margin) .figure { - margin-top: 0; - padding-top: 0; - margin-left: 0; - padding-left: 0; -} - -div.sidebar:not(.margin) img.logo { - margin-top: 0; - margin-bottom: .3rem; -} - -div.sidebar:not(.margin) p { - margin-bottom: 0; -} - -div.sidebar:not(.margin) p.sidebar-title { - display: none; -} - -div.sidebar:not(.margin) div.topic { - padding: .5em 0; - background-color: transparent; - border: none; -} - -div.sidebar:not(.margin) pre { - margin: .5em 0 1.5em 0; -} - -div.sidebar:not(.margin) div[class*="highlight-"] { - margin-right: .5em; -} - -div.sidebar:not(.margin) .admonition { - margin-right: .5em; - background-color: #ffffff; -} - -@media (min-width:768px) { - div.sidebar:not(.margin) { - width: 50%; - margin-left: 1.5em; - margin-right: -28%; - } -} - - -main.bd-content #main-content dl.simple dt { - margin-top: .8em; -} - -main.bd-content #main-content dl.simple dt:nth-of-type(1) { - margin-top: 0; -} - -main.bd-content #main-content dl.simple dd { - margin-top: .8em; -} - -main.bd-content #main-content dl.simple dt+dd { - margin-top: 0; -} - -.prev-next-bottom { - margin: 20px 0 30px 0; -} - -.prev-next-bottom a.left-prev, -.prev-next-bottom a.right-next { - padding: 5px 10px; - border: 1px solid rgba(0, 0, 0, .2); - max-width: 45%; - overflow-x: hidden; - color: rgba(0, 0, 0, .65); - border-radius: 10px; -} - -/* Local navigation */ -li.nav-item.toc-entry { - line-height: 1.25em; - margin-bottom: 0.25em; -} - -span.guilabel, -span.menuselection { - border: none; - background: #e7f2fa; - border-radius: 4px; - padding: 4px 5px; - font-size: 90%; - font-weight: bold; - font-style: italic; - white-space: nowrap; -} - - -/* - * extensions - */ - -/* definitions */ -dl.py.function { - margin-bottom: 5rem; -} - -dl.py.function>dt { - background-color: var(--codeblock-color); - padding: 4px 5px; -} - -dl.py.function>dt:target { - background-color: var(--target-color); -} - -dl.field-list>dt { - padding-left: 0; -} - -/* code blocks */ -div.viewcode-block:target { - padding: 10px 10px; - background-color: var(--codeblock-color); - border-top: 1px solid var(--codeblock-color); - border-bottom: 1px solid var(--codeblock-color); -} - -/* Fix paragraphs in list items. */ -#main-content ol > li > p:nth-child(n+2), -#main-content ul > li > p:nth-child(n+2) { - margin-top: 1em; -} - -video { - width: 100%; -} diff --git a/docs/_static/documentation.css b/docs/_static/documentation.css new file mode 100644 index 0000000000..e4590caa12 --- /dev/null +++ b/docs/_static/documentation.css @@ -0,0 +1,17 @@ +/* + Remove the external link icon from Plone Sphinx Theme for links + in submodules that refer to Plone 6 Documentation via Intersphinx. + Although these links have `external` in their class, they are + actually internal to Plone 6 Documentation. +*/ +.reference.external::after { + all: unset; +} +a:not([title="(in Plone Documentation v6)"]).reference.external::after { + margin-left: .3em; + display: inline-block; + content: var(--pst-icon-external-link); + white-space: nowrap; + font: var(--fa-font-solid); + font-size: .75em; +} diff --git a/docs/_static/github-navigation.png b/docs/_static/github-navigation.png deleted file mode 100644 index ef6f90d1c7..0000000000 Binary files a/docs/_static/github-navigation.png and /dev/null differ diff --git a/docs/_static/images-test/examples.png b/docs/_static/images-test/examples.png new file mode 100644 index 0000000000..d0c9eae883 Binary files /dev/null and b/docs/_static/images-test/examples.png differ diff --git a/docs/_static/images-test/image-srcset.png b/docs/_static/images-test/image-srcset.png new file mode 100644 index 0000000000..f91fe2a1c8 Binary files /dev/null and b/docs/_static/images-test/image-srcset.png differ diff --git a/docs/_static/images-test/images-test.png b/docs/_static/images-test/images-test.png new file mode 100644 index 0000000000..d8cbf912ec Binary files /dev/null and b/docs/_static/images-test/images-test.png differ diff --git a/docs/_static/images-test/picture-tags.png b/docs/_static/images-test/picture-tags.png new file mode 100644 index 0000000000..9b33032484 Binary files /dev/null and b/docs/_static/images-test/picture-tags.png differ diff --git a/docs/_static/patch_scrollToActive.js b/docs/_static/patch_scrollToActive.js deleted file mode 100644 index 6cad65df0b..0000000000 --- a/docs/_static/patch_scrollToActive.js +++ /dev/null @@ -1,41 +0,0 @@ -/** - * Patch of scrollToActive of sphinxbook theme - * Scroll to active navigation item - */ - -/** - * A helper function to load scripts when the DOM is loaded. - * This waits for everything to be on the page first before running, since - * some functionality doesn't behave properly until everything is ready. - */ - var sbRunWhenDOMLoaded = (cb) => { - if (document.readyState != "loading") { - cb(); - } else if (document.addEventListener) { - document.addEventListener("DOMContentLoaded", cb); - } else { - document.attachEvent("onreadystatechange", function () { - if (document.readyState == "complete") cb(); - }); - } -}; - -/** - * Sidebar scroll on load. - * - * Detect the active page in the sidebar, and scroll so that it is centered on - * the screen. - */ - -var scrollToActive = () => { - let navbar_scrollable = $("#site-navigation").children()[0]; - let active_navigation_item = $("#site-navigation .active").last(); - if (active_navigation_item) { - if (active_navigation_item.offset().top > $(window).height() * 0.5) { - navbar_scrollable.scrollTop = active_navigation_item.offset().top - $(window).height() * 0.2; - } - } -}; - - -sbRunWhenDOMLoaded(scrollToActive); diff --git a/docs/_static/plone-classic-ui-home-page.png b/docs/_static/plone-classic-ui-home-page.png new file mode 100644 index 0000000000..5440e9a778 Binary files /dev/null and b/docs/_static/plone-classic-ui-home-page.png differ diff --git a/docs/_static/plone-classic-ui-landing-page.png b/docs/_static/plone-classic-ui-landing-page.png index 018b0af215..a4f101987a 100644 Binary files a/docs/_static/plone-classic-ui-landing-page.png and b/docs/_static/plone-classic-ui-landing-page.png differ diff --git a/docs/_static/plone-classic-ui-login-page.png b/docs/_static/plone-classic-ui-login-page.png new file mode 100644 index 0000000000..60b3e2b5fd Binary files /dev/null and b/docs/_static/plone-classic-ui-login-page.png differ diff --git a/docs/_static/plone-classic-ui-site-page.png b/docs/_static/plone-classic-ui-site-page.png new file mode 100644 index 0000000000..7c27b5ad9e Binary files /dev/null and b/docs/_static/plone-classic-ui-site-page.png differ diff --git a/docs/_static/plone-home-page.png b/docs/_static/plone-home-page.png index c670a93602..b2321e0eaf 100644 Binary files a/docs/_static/plone-home-page.png and b/docs/_static/plone-home-page.png differ diff --git a/docs/_static/plone-login-page.png b/docs/_static/plone-login-page.png index 25a1d0a31f..8a2f90e723 100644 Binary files a/docs/_static/plone-login-page.png and b/docs/_static/plone-login-page.png differ diff --git a/docs/_static/search_shortcut.js b/docs/_static/search_shortcut.js deleted file mode 100644 index 177bf7f1a1..0000000000 --- a/docs/_static/search_shortcut.js +++ /dev/null @@ -1,35 +0,0 @@ -/** - * Add shortcut `ctrl+k` to focus on search field - */ - - $(document).ready(() => { - if (window.location.pathname === '/search.html') { - $('form.bd-search .input-group').hide(); // Hide Sidebar Search field - - $(document).keydown(function(event) { - if ((event.ctrlKey || event.metaKey) && event.key == "k") { - event.preventDefault(); - $('#q').focus(); - } - }); - } else { - $(document).keydown(function(event) { - if ((event.ctrlKey || event.metaKey) && event.key == "k") { - event.preventDefault(); - $('#search-input').focus(); - } - }); - } - - // if OS isn't Mac change visual indication of search field - if (navigator.platform.indexOf('Mac') === -1) { - $('#search-shortcut').html("^"); - $('#search-page-shortcut').html("^"); - } - -}); - -function onReset() { - $('#search-form').trigger('reset'); - $('#search-form').trigger('submit'); -} \ No newline at end of file diff --git a/docs/_static/searchtools.js b/docs/_static/searchtools.js index a9b62c7e9e..e6a1aafb7f 100644 --- a/docs/_static/searchtools.js +++ b/docs/_static/searchtools.js @@ -1,27 +1,45 @@ /* - * searchtools.js - * ~~~~~~~~~~~~~~~~ - * * Sphinx JavaScript utilities for the full-text search. - * - * :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS. - * :license: BSD, see LICENSE for details. - * */ +"use strict"; -var title_documentation = 'Plone Documentation'; +var title_repository = 'Plone documentation'; -if (!Scorer) { - /** - * Simple result scoring code. - */ +/** + * Return array with titles of ancestors of file. + * @param {number} idx - The index of the result item in global list of files + * @returns array + */ +function _getParentTitles(idx, docNames, titles) { + let path = docNames[idx] + let parentpathtokens = path.split('/').slice(0, -1); + + let parentTitles = parentpathtokens.map((el, index) => { + let foo = `${parentpathtokens.slice(0, index+1).join('/')}` + let parentId = docNames.indexOf(foo); + if (parentId === -1) { + foo = `${parentpathtokens.slice(0, index+1).join('/')}/index` + parentId = docNames.indexOf(foo); + } + let title = parentId === -1 ? title_repository : titles[parentId]; + return title + }) + + return parentTitles +} + +/** + * Simple result scoring code. + */ +if (typeof Scorer === "undefined") { var Scorer = { // Implement the following function to further tweak the score for each result - // The function takes a result array [filename, title, anchor, descr, score] + // The function takes a result array [docname, title, anchor, descr, score, filename] // and returns the new score. /* - score: function(result) { - return result[4]; + score: result => { + const [docname, title, anchor, descr, score, filename, kind] = result + return score }, */ @@ -30,9 +48,11 @@ if (!Scorer) { // or matches in the last dotted part of the object name objPartialMatch: 6, // Additive scores depending on the priority of the object - objPrio: {0: 15, // used to be importantResults - 1: 5, // used to be objectResults - 2: -5}, // used to be unimportantResults + objPrio: { + 0: 15, // used to be importantResults + 1: 5, // used to be objectResults + 2: -5, // used to be unimportantResults + }, // Used when the priority is not in the mapping. objPrioDefault: 0, @@ -41,522 +61,610 @@ if (!Scorer) { partialTitle: 7, // query found in terms term: 5, - partialTerm: 2 + partialTerm: 2, }; } -if (!splitQuery) { - function splitQuery(query) { - return query.split(/\s+/); +// Global search result kind enum, used by themes to style search results. +class SearchResultKind { + static get index() { return "index"; } + static get object() { return "object"; } + static get text() { return "text"; } + static get title() { return "title"; } +} + +const _removeChildren = (element) => { + while (element && element.lastChild) element.removeChild(element.lastChild); +}; + +/** + * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#escaping + */ +const _escapeRegExp = (string) => + string.replace(/[.*+\-?^${}()|[\]\\]/g, "\\$&"); // $& means the whole matched string + +function _getBreadcrumbs(item, linkUrl) { + // No breadcrumbs for top level pages + if (item[0].split('/')[1] == 'index') { + return null } + let parentTitles = item[6]; + + let parentDefaultTitles = [ + "Plone documentation", + "Documentation for Plone developers" + ]; + parentTitles = Array.isArray(parentTitles) ? parentTitles : parentDefaultTitles; + let pathTokens = item[0].split('/') + .slice(0, -1); + let pathArray = pathTokens.map((el, index) => { + return { + "path": pathTokens.slice(0, index+1).join('/'), + "title": parentTitles[index] + } + }) + let markup = pathArray + .map((el, idx) => { + return `${el.title}` + }) + markup.push(`${item[1]}`) + return markup.join(' > '); +} + +const _displayItem = (item, searchTerms, highlightTerms) => { + const docBuilder = DOCUMENTATION_OPTIONS.BUILDER; + const docFileSuffix = DOCUMENTATION_OPTIONS.FILE_SUFFIX; + const docLinkSuffix = DOCUMENTATION_OPTIONS.LINK_SUFFIX; + const showSearchSummary = DOCUMENTATION_OPTIONS.SHOW_SEARCH_SUMMARY; + const contentRoot = document.documentElement.dataset.content_root; + + const [docName, title, anchor, descr, score, _filename, kind] = item; + + let listItem = document.createElement("li"); + // Add a class representing the item's type: + // can be used by a theme's CSS selector for styling + // See SearchResultKind for the class names. + // listItem.classList.add(`kind-${kind}`); + let requestUrl; + let linkUrl; + if (docBuilder === "dirhtml") { + // dirhtml builder + let dirname = docName + "/"; + if (dirname.match(/\/index\/$/)) + dirname = dirname.substring(0, dirname.length - 6); + else if (dirname === "index/") dirname = ""; + requestUrl = contentRoot + dirname; + linkUrl = requestUrl; + } else { + // normal html builders + requestUrl = contentRoot + docName + docFileSuffix; + linkUrl = docName + docLinkSuffix; + } + + let breadcrumbs = _getBreadcrumbs(item, linkUrl); + if (breadcrumbs) { + let breadcrumbsNode = document.createElement("div"); + breadcrumbsNode.innerHTML = breadcrumbs; + breadcrumbsNode.classList.add("breadcrumbs"); + listItem.appendChild(breadcrumbsNode); + } + + // Title links to chapter + let linkEl = listItem.appendChild(document.createElement("a")); + linkEl.href = linkUrl + anchor; + linkEl.dataset.score = score; + linkEl.innerHTML = title; + if (descr) { + listItem.appendChild(document.createElement("span")).innerHTML = + " (" + descr + ")"; + // highlight search terms in the description + if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js + highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted")); + } + else if (showSearchSummary) + fetch(requestUrl) + .then((responseData) => responseData.text()) + .then((data) => { + if (data) + listItem.appendChild( + Search.makeSearchSummary(data, searchTerms, anchor) + ); + // highlight search terms in the summary + if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js + highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted")); + }); + Search.output.appendChild(listItem); +}; +const _finishSearch = (resultCount) => { + Search.stopPulse(); + Search.title.innerText = _("Search Results"); + if (!resultCount) + Search.status.innerText = Documentation.gettext( + "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories." + ); + else + Search.status.innerText = Documentation.ngettext( + "Search finished, found one page matching the search query.", + "Search finished, found ${resultCount} pages matching the search query.", + resultCount, + ).replace('${resultCount}', resultCount); +}; +const _displayNextItem = ( + results, + resultCount, + searchTerms, + highlightTerms, +) => { + // results left, load the summary and display it + // this is intended to be dynamic (don't sub resultsCount) + if (results.length) { + _displayItem(results.pop(), searchTerms, highlightTerms); + setTimeout( + () => _displayNextItem(results, resultCount, searchTerms, highlightTerms), + 5 + ); + } + // search finished, update title and status message + else _finishSearch(resultCount); +}; +// Helper function used by query() to order search results. +// Each input is an array of [docname, title, anchor, descr, score, filename, kind]. +// Order the results by score (in opposite order of appearance, since the +// `_displayNextItem` function uses pop() to retrieve items) and then alphabetically. +const _orderResultsByScoreThenName = (a, b) => { + const leftScore = a[4]; + const rightScore = b[4]; + if (leftScore === rightScore) { + // same score: sort alphabetically + const leftTitle = a[1].toLowerCase(); + const rightTitle = b[1].toLowerCase(); + if (leftTitle === rightTitle) return 0; + return leftTitle > rightTitle ? -1 : 1; // inverted is intentional + } + return leftScore > rightScore ? 1 : -1; +}; + +/** + * Default splitQuery function. Can be overridden in ``sphinx.search`` with a + * custom function per language. + * + * The regular expression works by splitting the string on consecutive characters + * that are not Unicode letters, numbers, underscores, or emoji characters. + * This is the same as ``\W+`` in Python, preserving the surrogate pair area. + */ +if (typeof splitQuery === "undefined") { + var splitQuery = (query) => query + .split(/[^\p{Letter}\p{Number}_\p{Emoji_Presentation}]+/gu) + .filter(term => term) // remove remaining empty strings } /** * Search Module */ -var Search = { - - _index : null, - _queued_query : null, - _pulse_status : -1, - - htmlToText : function(htmlString) { - var virtualDocument = document.implementation.createHTMLDocument('virtual'); - var htmlElement = $(htmlString, virtualDocument); - htmlElement.find('.headerlink').remove(); - docContent = htmlElement.find('[role=main]')[0]; - if(docContent === undefined) { - console.warn("Content block not found. Sphinx search tries to obtain it " + - "via '[role=main]'. Could you check your theme or template."); - return ""; - } - return docContent.textContent || docContent.innerText; - }, +const Search = { + _index: null, + _queued_query: null, + _pulse_status: -1, + + htmlToText: (htmlString, anchor) => { + const htmlElement = new DOMParser().parseFromString(htmlString, 'text/html'); + for (const removalQuery of [".headerlink", "script", "style"]) { + htmlElement.querySelectorAll(removalQuery).forEach((el) => { el.remove() }); + } + if (anchor) { + const anchorContent = htmlElement.querySelector(`[role="main"] ${anchor}`); + if (anchorContent) return anchorContent.textContent; - init : function() { - var params = $.getQueryParameters(); - let doc_section = params.doc_section ? params.doc_section[0] : 'all'; - $('input[id="doc_section_' + doc_section + '"]').prop("checked", true) - if (params.q) { - var query = params.q[0]; - $('input[name="q"]')[0].value = query; - $('input[name="q"]')[1].value = query; - this.performSearch(query, doc_section); - } + console.warn( + `Anchored content block not found. Sphinx search tries to obtain it via DOM query '[role=main] ${anchor}'. Check your theme or template.` + ); + } + + // if anchor not specified or not found, fall back to main content + const docContent = htmlElement.querySelector('[role="main"]'); + if (docContent) return docContent.textContent; + + console.warn( + "Content block not found. Sphinx search tries to obtain it via DOM query '[role=main]'. Check your theme or template." + ); + return ""; }, - loadIndex : function(url) { - $.ajax({type: "GET", url: url, data: null, - dataType: "script", cache: true, - complete: function(jqxhr, textstatus) { - if (textstatus != "success") { - document.getElementById("searchindexloader").src = url; - } - }}); + init: () => { + const query = new URLSearchParams(window.location.search).get("q"); + document + .querySelectorAll('input[name="q"]') + .forEach((el) => (el.value = query)); + if (query) Search.performSearch(query); }, - setIndex : function(index) { - var q; - this._index = index; - if ((q = this._queued_query) !== null) { - this._queued_query = null; - Search.query(q); + loadIndex: (url) => + (document.body.appendChild(document.createElement("script")).src = url), + + setIndex: (index) => { + Search._index = index; + if (Search._queued_query !== null) { + const query = Search._queued_query; + Search._queued_query = null; + Search.query(query); } }, - hasIndex : function() { - return this._index !== null; - }, + hasIndex: () => Search._index !== null, - deferQuery : function(query) { - this._queued_query = query; - }, + deferQuery: (query) => (Search._queued_query = query), - stopPulse : function() { - this._pulse_status = 0; - }, + stopPulse: () => (Search._pulse_status = -1), - startPulse : function() { - if (this._pulse_status >= 0) - return; - function pulse() { - var i; + startPulse: () => { + if (Search._pulse_status >= 0) return; + + const pulse = () => { Search._pulse_status = (Search._pulse_status + 1) % 4; - var dotString = ''; - for (i = 0; i < Search._pulse_status; i++) - dotString += '.'; - Search.dots.text(dotString); - if (Search._pulse_status > -1) - window.setTimeout(pulse, 500); - } + Search.dots.innerText = ".".repeat(Search._pulse_status); + if (Search._pulse_status >= 0) window.setTimeout(pulse, 500); + }; pulse(); }, /** * perform a search for something (or wait until index is loaded) */ - performSearch : function(query, doc_section) { + performSearch: (query) => { // create the required interface elements - this.out = $('#search-results'); - this.title = $('').appendTo(this.out); - this.dots = $('').appendTo(this.title); - this.status = $('

 

').appendTo(this.out); - this.output = $('
    ').appendTo(this.out); - - $('#search-progress').text(_('Preparing search...')); - this.startPulse(); + const searchText = document.createElement("h2"); + searchText.textContent = _("Searching"); + const searchSummary = document.createElement("p"); + searchSummary.classList.add("search-summary"); + searchSummary.innerText = ""; + const searchList = document.createElement("ul"); + searchList.setAttribute("role", "list"); + searchList.classList.add("search"); + + const out = document.getElementById("search-results"); + Search.title = out.appendChild(searchText); + Search.dots = Search.title.appendChild(document.createElement("span")); + Search.status = out.appendChild(searchSummary); + Search.output = out.appendChild(searchList); + + const searchProgress = document.getElementById("search-progress"); + // Some themes don't use the search progress node + if (searchProgress) { + searchProgress.innerText = _("Preparing search..."); + } + Search.startPulse(); // index already loaded, the browser was quick! - if (this.hasIndex()) { - this.query(query, doc_section); - } else { - this.deferQuery(query); - } + if (Search.hasIndex()) Search.query(query); + else Search.deferQuery(query); }, - /** - * execute search (requires search index to be loaded) - */ - query : function(query, doc_section) { - var i; - - // stem the searchterms and add them to the correct list - var stemmer = new Stemmer(); - var searchterms = []; - var excluded = []; - var hlterms = []; - var tmp = splitQuery(query); - var objectterms = []; - for (i = 0; i < tmp.length; i++) { - if (tmp[i] !== "") { - objectterms.push(tmp[i].toLowerCase()); - } + _parseQuery: (query) => { + // stem the search terms and add them to the correct list + const stemmer = new Stemmer(); + const searchTerms = new Set(); + const excludedTerms = new Set(); + const highlightTerms = new Set(); + const objectTerms = new Set(splitQuery(query.toLowerCase().trim())); + splitQuery(query.trim()).forEach((queryTerm) => { + const queryTermLower = queryTerm.toLowerCase(); + + // maybe skip this "word" + // stopwords array is from language_data.js + if ( + stopwords.indexOf(queryTermLower) !== -1 || + queryTerm.match(/^\d+$/) + ) + return; - if ($u.indexOf(stopwords, tmp[i].toLowerCase()) != -1 || tmp[i] === "") { - // skip this "word" - continue; - } // stem the word - var word = stemmer.stemWord(tmp[i].toLowerCase()); - // prevent stemmer from cutting word smaller than two chars - if(word.length < 3 && tmp[i].length >= 3) { - word = tmp[i]; - } - var toAppend; + let word = stemmer.stemWord(queryTermLower); // select the correct list - if (word[0] == '-') { - toAppend = excluded; - word = word.substr(1); - } + if (word[0] === "-") excludedTerms.add(word.substr(1)); else { - toAppend = searchterms; - hlterms.push(tmp[i].toLowerCase()); + searchTerms.add(word); + highlightTerms.add(queryTermLower); } - // only add if not already in the list - if (!$u.contains(toAppend, word)) - toAppend.push(word); + }); + + if (SPHINX_HIGHLIGHT_ENABLED) { // set in sphinx_highlight.js + localStorage.setItem("sphinx_highlight_terms", [...highlightTerms].join(" ")) } - var highlightstring = '?highlight=' + $.urlencode(hlterms.join(" ")); - // prepare search - var terms = this._index.terms; - var titleterms = this._index.titleterms; + // console.debug("SEARCH: searching for:"); + // console.info("required: ", [...searchTerms]); + // console.info("excluded: ", [...excludedTerms]); - // array of [filename, title, anchor, descr, score] - var results = []; - $('#search-progress').empty(); + return [query, searchTerms, excludedTerms, highlightTerms, objectTerms]; + }, - // lookup as object - for (i = 0; i < objectterms.length; i++) { - var others = [].concat(objectterms.slice(0, i), - objectterms.slice(i+1, objectterms.length)); - results = results.concat(this.performObjectSearch(objectterms[i], others)); + /** + * execute search (requires search index to be loaded) + */ + _performSearch: (query, searchTerms, excludedTerms, highlightTerms, objectTerms) => { + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const titles = Search._index.titles; + const allTitles = Search._index.alltitles; + const indexEntries = Search._index.indexentries; + + // Collect multiple result groups to be sorted separately and then ordered. + // Each is an array of [docname, title, anchor, descr, score, filename, kind]. + const normalResults = []; + const nonMainIndexResults = []; + + _removeChildren(document.getElementById("search-progress")); + + const queryLower = query.toLowerCase().trim(); + for (const [title, foundTitles] of Object.entries(allTitles)) { + if (title.toLowerCase().trim().includes(queryLower) && (queryLower.length >= title.length/2)) { + for (const [file, id] of foundTitles) { + const score = Math.round(Scorer.title * queryLower.length / title.length); + const boost = titles[file] === title ? 1 : 0; // add a boost for document titles + normalResults.push([ + docNames[file], + titles[file] !== title ? `${titles[file]} > ${title}` : title, + id !== null ? "#" + id : "", + null, + score + boost, + filenames[file], + _getParentTitles(file, docNames, titles), + ]); + } + } + } + + // search for explicit entries in index directives + for (const [entry, foundEntries] of Object.entries(indexEntries)) { + if (entry.includes(queryLower) && (queryLower.length >= entry.length/2)) { + for (const [file, id, isMain] of foundEntries) { + const score = Math.round(100 * queryLower.length / entry.length); + const result = [ + docNames[file], + titles[file], + id ? "#" + id : "", + null, + score, + filenames[file], + SearchResultKind.index, + ]; + if (isMain) { + normalResults.push(result); + } else { + nonMainIndexResults.push(result); + } + } + } } + // lookup as object + objectTerms.forEach((term) => + normalResults.push(...Search.performObjectSearch(term, objectTerms)) + ); + // lookup as search terms in fulltext - results = results.concat(this.performTermsSearch(searchterms, excluded, terms, titleterms)); + normalResults.push(...Search.performTermsSearch(searchTerms, excludedTerms)); // let the scorer override scores with a custom scoring function if (Scorer.score) { - for (i = 0; i < results.length; i++) - results[i][4] = Scorer.score(results[i]); + normalResults.forEach((item) => (item[4] = Scorer.score(item))); + nonMainIndexResults.forEach((item) => (item[4] = Scorer.score(item))); } - // Filter results by doc_section - if (doc_section && doc_section !== 'all') { - results = results.filter(result => { - let condition = result[0].split('/')[0] === doc_section; - return condition - }) - } - - // Enrich item with parent doc_section title - for (i = 0; i < results.length; i++) - results[i][6] = results[i][6] || title_documentation; - - // now sort the results by score (in opposite order of appearance, since the - // display function below uses pop() to retrieve items) and then - // alphabetically - results.sort(function(a, b) { - var left = a[4]; - var right = b[4]; - if (left > right) { - return 1; - } else if (left < right) { - return -1; - } else { - // same score: sort alphabetically - left = a[1].toLowerCase(); - right = b[1].toLowerCase(); - return (left > right) ? -1 : ((left < right) ? 1 : 0); + // Sort each group of results by score and then alphabetically by name. + normalResults.sort(_orderResultsByScoreThenName); + nonMainIndexResults.sort(_orderResultsByScoreThenName); + + // Combine the result groups in (reverse) order. + // Non-main index entries are typically arbitrary cross-references, + // so display them after other results. + let results = [...nonMainIndexResults, ...normalResults]; + + // remove duplicate search results + // note the reversing of results, so that in the case of duplicates, the highest-scoring entry is kept + let seen = new Set(); + results = results.reverse().reduce((acc, result) => { + let resultStr = result.slice(0, 4).concat([result[5]]).map(v => String(v)).join(','); + if (!seen.has(resultStr)) { + acc.push(result); + seen.add(resultStr); } - }); + return acc; + }, []); - function _getBreadcrumbs(item, linkUrl) { - let parentTitles = item[6]; - let ploneApiTitles = [ - "A Plone API", - "List of all API methods with descriptions" - ]; - // ugly hack for plone.api documentation integrated via git submodule - parentTitles = Array.isArray(parentTitles) ? parentTitles : ploneApiTitles; - let path = item[0].split('/') - .slice(0, -1); - path = path.map((el, index) => { - return { - "path": path.slice(0, index+1).join('/'), - "title": parentTitles[index] - } - }) - let markup = path - .map((el, idx) => { - return `${el.title}` - }) - markup.push(`${item[1]}`) - return markup.join('>'); - } + return results.reverse(); + }, - // Print the results. - var resultCount = results.length; - function displayNextItem() { - // results left, load the summary and display it - if (results.length) { - var item = results.pop(); - var listItem = $('
  • '); - var requestUrl = ""; - var linkUrl = ""; - if (DOCUMENTATION_OPTIONS.BUILDER === 'dirhtml') { - // dirhtml builder - var dirname = item[0] + '/'; - if (dirname.match(/\/index\/$/)) { - dirname = dirname.substring(0, dirname.length-6); - } else if (dirname == 'index/') { - dirname = ''; - } - requestUrl = DOCUMENTATION_OPTIONS.URL_ROOT + dirname; - linkUrl = requestUrl; + query: (query) => { + const [searchQuery, searchTerms, excludedTerms, highlightTerms, objectTerms] = Search._parseQuery(query); + const results = Search._performSearch(searchQuery, searchTerms, excludedTerms, highlightTerms, objectTerms); + const qresults = results; - } else { - // normal html builders - requestUrl = DOCUMENTATION_OPTIONS.URL_ROOT + item[0] + DOCUMENTATION_OPTIONS.FILE_SUFFIX; - linkUrl = item[0] + DOCUMENTATION_OPTIONS.LINK_SUFFIX; - } - let breadcrumbs = _getBreadcrumbs(item, linkUrl); - breadcrumbs = $("
    " + breadcrumbs + "
    "); - listItem.append(breadcrumbs); - let headline = $('

    '); - headline.append($('').attr('href', - linkUrl + - highlightstring + item[2]).html(item[1])); - - listItem.append(headline); - - if (item[3]) { - listItem.append($(' (' + item[3] + ')')); - Search.output.append(listItem); - setTimeout(function() { - displayNextItem(); - }, 5); - } else if (DOCUMENTATION_OPTIONS.HAS_SOURCE) { - $.ajax({url: requestUrl, - dataType: "text", - complete: function(jqxhr, textstatus) { - var data = jqxhr.responseText; - if (data !== '' && data !== undefined) { - listItem.append(Search.makeSearchSummary(data, searchterms, hlterms)); - } - Search.output.append(listItem); - setTimeout(function() { - displayNextItem(); - }, 5); - }}); - } else { - // no source available, just display title - Search.output.append(listItem); - setTimeout(function() { - displayNextItem(); - }, 5); - } - } - // search finished, update title and status message - else { - Search.stopPulse(); - Search.title.text(_('Search Results')); - if (query === '') { - Search.status.text(_('No query, no results.')); - } - else if (!resultCount) - Search.status.text(_('Your search did not match any documents. Please make sure that all words are spelled correctly. Searching for multiple words only shows matches that contain all words.')); - else - Search.status.text(_('Found %s page(s) matching the search query.').replace('%s', resultCount)); - Search.status.fadeIn(500); - } - } - displayNextItem(); + // for debugging + //Search.lastresults = results.slice(); // a copy + // console.info("search results:", Search.lastresults); + + // print the results + _displayNextItem(results, results.length, searchTerms, highlightTerms); }, /** * search for object names */ - performObjectSearch : function(object, otherterms) { - var filenames = this._index.filenames; - var docnames = this._index.docnames; - var objects = this._index.objects; - var objnames = this._index.objnames; - var titles = this._index.titles; - - var i; - var results = []; - - for (var prefix in objects) { - for (var iMatch = 0; iMatch != objects[prefix].length; ++iMatch) { - var match = objects[prefix][iMatch]; - var name = match[4]; - var fullname = (prefix ? prefix + '.' : '') + name; - var fullnameLower = fullname.toLowerCase() - if (fullnameLower.indexOf(object) > -1) { - var score = 0; - var parts = fullnameLower.split('.'); - // check for different match types: exact matches of full name or - // "last name" (i.e. last dotted part) - if (fullnameLower == object || parts[parts.length - 1] == object) { - score += Scorer.objNameMatch; - // matches in last name - } else if (parts[parts.length - 1].indexOf(object) > -1) { - score += Scorer.objPartialMatch; - } - var objname = objnames[match[1]][2]; - var title = titles[match[0]]; - // If more than one term searched for, we require other words to be - // found in the name/title/description - if (otherterms.length > 0) { - var haystack = (prefix + ' ' + name + ' ' + - objname + ' ' + title).toLowerCase(); - var allfound = true; - for (i = 0; i < otherterms.length; i++) { - if (haystack.indexOf(otherterms[i]) == -1) { - allfound = false; - break; - } - } - if (!allfound) { - continue; - } - } - var descr = objname + _(', in ') + title; - - var anchor = match[3]; - if (anchor === '') - anchor = fullname; - else if (anchor == '-') - anchor = objnames[match[1]][1] + '-' + fullname; - // add custom score for some objects according to scorer - if (Scorer.objPrio.hasOwnProperty(match[2])) { - score += Scorer.objPrio[match[2]]; - } else { - score += Scorer.objPrioDefault; - } - results.push([docnames[match[0]], fullname, '#'+anchor, descr, score, filenames[match[0]]]); - } + performObjectSearch: (object, objectTerms) => { + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const objects = Search._index.objects; + const objNames = Search._index.objnames; + const titles = Search._index.titles; + + const results = []; + + const objectSearchCallback = (prefix, match) => { + const name = match[4] + const fullname = (prefix ? prefix + "." : "") + name; + const fullnameLower = fullname.toLowerCase(); + if (fullnameLower.indexOf(object) < 0) return; + + let score = 0; + const parts = fullnameLower.split("."); + + // check for different match types: exact matches of full name or + // "last name" (i.e. last dotted part) + if (fullnameLower === object || parts.slice(-1)[0] === object) + score += Scorer.objNameMatch; + else if (parts.slice(-1)[0].indexOf(object) > -1) + score += Scorer.objPartialMatch; // matches in last name + + const objName = objNames[match[1]][2]; + const title = titles[match[0]]; + + // If more than one term searched for, we require other words to be + // found in the name/title/description + const otherTerms = new Set(objectTerms); + otherTerms.delete(object); + if (otherTerms.size > 0) { + const haystack = `${prefix} ${name} ${objName} ${title}`.toLowerCase(); + if ( + [...otherTerms].some((otherTerm) => haystack.indexOf(otherTerm) < 0) + ) + return; } - } + let anchor = match[3]; + if (anchor === "") anchor = fullname; + else if (anchor === "-") anchor = objNames[match[1]][1] + "-" + fullname; + + const descr = objName + _(", in ") + title; + + // add custom score for some objects according to scorer + if (Scorer.objPrio.hasOwnProperty(match[2])) + score += Scorer.objPrio[match[2]]; + else score += Scorer.objPrioDefault; + + results.push([ + docNames[match[0]], + fullname, + "#" + anchor, + descr, + score, + filenames[match[0]], + SearchResultKind.object, + ]); + }; + Object.keys(objects).forEach((prefix) => + objects[prefix].forEach((array) => + objectSearchCallback(prefix, array) + ) + ); return results; }, - /** - * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions - */ - escapeRegExp : function(string) { - return string.replace(/[.*+\-?^${}()|[\]\\]/g, '\\$&'); // $& means the whole matched string - }, - /** * search for full-text terms in the index */ - performTermsSearch : function(searchterms, excluded, terms, titleterms) { - var docnames = this._index.docnames; - var filenames = this._index.filenames; - var titles = this._index.titles; + performTermsSearch: (searchTerms, excludedTerms) => { + // prepare search + const terms = Search._index.terms; + const titleTerms = Search._index.titleterms; + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const titles = Search._index.titles; - var i, j, file; - var fileMap = {}; - var scoreMap = {}; - var results = []; + const scoreMap = new Map(); + const fileMap = new Map(); // perform the search on the required terms - for (i = 0; i < searchterms.length; i++) { - var word = searchterms[i]; - var files = []; - var _o = [ - {files: terms[word], score: Scorer.term}, - {files: titleterms[word], score: Scorer.title} + searchTerms.forEach((word) => { + const files = []; + // find documents, if any, containing the query word in their text/title term indices + // use Object.hasOwnProperty to avoid mismatching against prototype properties + const arr = [ + { files: terms.hasOwnProperty(word) ? terms[word] : undefined, score: Scorer.term }, + { files: titleTerms.hasOwnProperty(word) ? titleTerms[word] : undefined, score: Scorer.title }, ]; // add support for partial matches if (word.length > 2) { - var word_regex = this.escapeRegExp(word); - for (var w in terms) { - if (w.match(word_regex) && !terms[word]) { - _o.push({files: terms[w], score: Scorer.partialTerm}) - } + const escapedWord = _escapeRegExp(word); + if (!terms.hasOwnProperty(word)) { + Object.keys(terms).forEach((term) => { + if (term.match(escapedWord)) + arr.push({ files: terms[term], score: Scorer.partialTerm }); + }); } - for (var w in titleterms) { - if (w.match(word_regex) && !titleterms[word]) { - _o.push({files: titleterms[w], score: Scorer.partialTitle}) - } + if (!titleTerms.hasOwnProperty(word)) { + Object.keys(titleTerms).forEach((term) => { + if (term.match(escapedWord)) + arr.push({ files: titleTerms[term], score: Scorer.partialTitle }); + }); } } // no match but word was a required one - if ($u.every(_o, function(o){return o.files === undefined;})) { - break; - } + if (arr.every((record) => record.files === undefined)) return; + // found search word in contents - $u.each(_o, function(o) { - var _files = o.files; - if (_files === undefined) - return - - if (_files.length === undefined) - _files = [_files]; - files = files.concat(_files); - - // set score for the word in each file to Scorer.term - for (j = 0; j < _files.length; j++) { - file = _files[j]; - if (!(file in scoreMap)) - scoreMap[file] = {}; - scoreMap[file][word] = o.score; - } + arr.forEach((record) => { + if (record.files === undefined) return; + + let recordFiles = record.files; + if (recordFiles.length === undefined) recordFiles = [recordFiles]; + files.push(...recordFiles); + + // set score for the word in each file + recordFiles.forEach((file) => { + if (!scoreMap.has(file)) scoreMap.set(file, new Map()); + const fileScores = scoreMap.get(file); + fileScores.set(word, record.score); + }); }); // create the mapping - for (j = 0; j < files.length; j++) { - file = files[j]; - if (file in fileMap && fileMap[file].indexOf(word) === -1) - fileMap[file].push(word); - else - fileMap[file] = [word]; - } - } + files.forEach((file) => { + if (!fileMap.has(file)) fileMap.set(file, [word]); + else if (fileMap.get(file).indexOf(word) === -1) fileMap.get(file).push(word); + }); + }); // now check if the files don't contain excluded terms - for (file in fileMap) { - var valid = true; - + const results = []; + for (const [file, wordList] of fileMap) { // check if all requirements are matched - var filteredTermCount = // as search terms with length < 3 are discarded: ignore - searchterms.filter(function(term){return term.length > 2}).length + + // as search terms with length < 3 are discarded + const filteredTermCount = [...searchTerms].filter( + (term) => term.length > 2 + ).length; if ( - fileMap[file].length != searchterms.length && - fileMap[file].length != filteredTermCount - ) continue; + wordList.length !== searchTerms.size && + wordList.length !== filteredTermCount + ) + continue; // ensure that none of the excluded terms is in the search result - for (i = 0; i < excluded.length; i++) { - if (terms[excluded[i]] == file || - titleterms[excluded[i]] == file || - $u.contains(terms[excluded[i]] || [], file) || - $u.contains(titleterms[excluded[i]] || [], file)) { - valid = false; - break; - } - } - // if we have still a valid result we can add it to the result list - if (valid) { - /** - * file: index - * docnames: array of paths - * titles: array of titles - */ - - // select one (max) score for the file. - // for better ranking, we should calculate ranking by using words statistics like basic tf-idf... - var score = $u.max($u.map(fileMap[file], function(w){return scoreMap[file][w]})); - - /** - * Return array with titles of ancestors of file. - * @param {number} idx - The index of the result item in global list of files - * @returns array - */ - function getParentTitles(idx) { - let path = docnames[idx] - - let foo = path.split('/').slice(0, -1); - foo = foo.map((el, index) => { - return `${foo.slice(0, index+1).join('/')}/index` - }) - - let parentTitles = foo.map(el => { - let parentId = docnames.indexOf(el); - let title = parentId === -1 ? title_documentation : titles[parentId]; - return title - }) - return parentTitles - } + if ( + [...excludedTerms].some( + (term) => + terms[term] === file || + titleTerms[term] === file || + (terms[term] || []).includes(file) || + (titleTerms[term] || []).includes(file) + ) + ) + break; - results.push([docnames[file], titles[file], '', null, score, filenames[file], getParentTitles(file)]); - } + // select one (max) score for the file. + const score = Math.max(...wordList.map((w) => scoreMap.get(file).get(w))); + // add result to the result list + results.push([ + docNames[file], + titles[file], + "", + null, + score, + filenames[file], + _getParentTitles(file, docNames, titles) + ]); } return results; }, @@ -564,41 +672,28 @@ var Search = { /** * helper function to return a node containing the * search summary for a given text. keywords is a list - * of stemmed words, hlwords is the list of normal, unstemmed - * words. the first one is used to find the occurrence, the - * latter for highlighting it. + * of stemmed words. */ - makeSearchSummary : function(htmlText, keywords, hlwords) { - var text = Search.htmlToText(htmlText); - var textLower = text.toLowerCase(); - var start = 0; - $.each(keywords, function() { - var i = textLower.indexOf(this.toLowerCase()); - if (i > -1) - start = i; - }); - start = Math.max(start - 120, 0); - var excerpt = ((start > 0) ? '...' : '') + - $.trim(text.substr(start, 240)) + - ((start + 240 - text.length) ? '...' : ''); - var rv = $('

    ').text(excerpt); - $.each(hlwords, function() { - rv = rv.highlightText(this, 'highlighted'); - }); - return rv; - } + makeSearchSummary: (htmlText, keywords, anchor) => { + const text = Search.htmlToText(htmlText, anchor); + if (text === "") return null; + + const textLower = text.toLowerCase(); + const actualStartPosition = [...keywords] + .map((k) => textLower.indexOf(k.toLowerCase())) + .filter((i) => i > -1) + .slice(-1)[0]; + const startWithContext = Math.max(actualStartPosition - 120, 0); + + const top = startWithContext === 0 ? "" : "..."; + const tail = startWithContext + 240 < text.length ? "..." : ""; + + let summary = document.createElement("p"); + summary.classList.add("context"); + summary.textContent = top + text.substr(startWithContext, 240).trim() + tail; + + return summary; + }, }; -$(document).ready(function() { - Search.init(); - $('#q').focus(); - $('input[name="doc_section"]').change(function() { - this.form.submit(); - }); - - function clearSearchField() { - $('#q').val(''); - this.form.submit(); - } - $( "button.clear_search" ).on( "click", clearSearchField ); -}); +_ready(Search.init); diff --git a/docs/_static/settings.json b/docs/_static/settings.json new file mode 100644 index 0000000000..a836b007c7 --- /dev/null +++ b/docs/_static/settings.json @@ -0,0 +1,5 @@ +{ + "[markdown]": { + "editor.formatOnSave": false + } +} diff --git a/docs/_static/switcher.json b/docs/_static/switcher.json index eef57af73b..bcdf3e9f6c 100644 --- a/docs/_static/switcher.json +++ b/docs/_static/switcher.json @@ -1,7 +1,7 @@ [ { "name": "6 (stable)", - "version": "6.0", + "version": "6", "url": "https://6.docs.plone.org/" }, { diff --git a/docs/_static/test-rendering/bootstrap-cheatsheet.png b/docs/_static/test-rendering/bootstrap-cheatsheet.png new file mode 100644 index 0000000000..86638d4624 Binary files /dev/null and b/docs/_static/test-rendering/bootstrap-cheatsheet.png differ diff --git a/docs/_static/test-rendering/icons.png b/docs/_static/test-rendering/icons.png new file mode 100644 index 0000000000..03983b2df7 Binary files /dev/null and b/docs/_static/test-rendering/icons.png differ diff --git a/docs/_static/test-rendering/test-rendering.png b/docs/_static/test-rendering/test-rendering.png new file mode 100644 index 0000000000..34f1dffcef Binary files /dev/null and b/docs/_static/test-rendering/test-rendering.png differ diff --git a/docs/_static/volto-ui.png b/docs/_static/volto-ui.png new file mode 100644 index 0000000000..8adacef1ee Binary files /dev/null and b/docs/_static/volto-ui.png differ diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html index 6757818f07..799ca64d7d 100644 --- a/docs/_templates/layout.html +++ b/docs/_templates/layout.html @@ -10,8 +10,3 @@ {% endblock %} - - -{% block body_tag %} - -{%- endblock %} \ No newline at end of file diff --git a/docs/_templates/page.html b/docs/_templates/page.html deleted file mode 100644 index e9c9683332..0000000000 --- a/docs/_templates/page.html +++ /dev/null @@ -1,18 +0,0 @@ -{% extends "!page.html" %} - -{%- block htmltitle %} -{{ title|striptags|e }}{%- for parent in parents %} – {{ parent.title }}{%- endfor %}{{ titlesuffix }} -{%- endblock %} - - -{% block footer %} - - -{% endblock %} \ No newline at end of file diff --git a/docs/_templates/search-field.html b/docs/_templates/search-field.html deleted file mode 100644 index 9c3bfe9885..0000000000 --- a/docs/_templates/search-field.html +++ /dev/null @@ -1,19 +0,0 @@ -
    -
    - - - -
    - - ⌘ K - -
    -
    -
    \ No newline at end of file diff --git a/docs/_templates/search.html b/docs/_templates/search.html index 9f88c309cf..c17e5f1b50 100644 --- a/docs/_templates/search.html +++ b/docs/_templates/search.html @@ -1,136 +1,42 @@ -{# - basic/search.html - ~~~~~~~~~~~~~~~~~ - - Template for the search page. - - :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS. - :license: BSD, see LICENSE for details. -#} -{%- extends "layout.html" %} -{% set title = _('Search') %} -{% block header %} - - -{% endblock %} -{%- block scripts %} +{%- extends "page.html" %} +{# Over-ride the body to be custom search structure we want #} +{% block docs_body %} +
    +

    {{ _("Search") }}

    + + {% block searchtext %} +
    + {% trans %}Searching for multiple words only shows matches that contain + all words.{% endtrans %} +
    + {% endblock %} + {% include "components/search-field.html" %} +
    +
    + +{% endblock docs_body %} +{# Below sections just re-create the behavior of Sphinx default search #} +{# Page metadata #} +{%- block htmltitle -%} + {{ _("Search") }} - {{ title or docstitle }} +{%- endblock htmltitle -%} +{# Manually include the search JS that Sphinx includes #} +{% block scripts -%} {{ super() }} -{%- endblock %} -{% block extrahead %} - - {{ super() }} -{% endblock %} -{% block body %} -

    {{ _('Search') }}

    - {% block scriptwarning %} -
    - -

    - {% trans %}Please activate JavaScript to enable the search - functionality.{% endtrans %} -

    -
    - {% endblock %} - {% block searchtext %} -

    - {% trans %}Searching for multiple words only shows matches that contain - all words.{% endtrans %} -

    - {% endblock %} - {% block searchbox %} -
    -
    -
    - - -
    - - ⌘ K - -
    -
    - -
    -
    - -
    -
    -
    - -
    - -
    -
    - - -
    - {% for id, title in - [ - ["backend","Backend"], - ["plone.api","plone.api"], - ["plone.restapi","plone.restapi"], - ["classic-ui","Classic UI"], - ["volto","Frontend"], - ["contributing","Contributing"], - ] %} -
    - - -
    - {% endfor %} -
    -
    - - -
    - {% endblock %} - - {% block searchresults %} -     - {% endblock %} -{% endblock %} - - -{% block footer %} - - -{% endblock %} \ No newline at end of file + +{%- endblock scripts %} diff --git a/docs/_templates/sections/header-article.html b/docs/_templates/sections/header-article.html deleted file mode 100644 index 136ce58e5c..0000000000 --- a/docs/_templates/sections/header-article.html +++ /dev/null @@ -1,35 +0,0 @@ -{# To trigger whether the TOC and its button show up #} -{% set page_toc = generate_toc_html() %} -{% from "../macros/buttons.html" import render_funcs, render_label_input_button with context %} - -
    -
    - {% if theme_single_page != True %} - {{ render_label_input_button(for_input="__navigation", tooltip="Toggle navigation", icon="fas fa-bars", tooltip_placement="right") }} - {% endif %} -
    -
    - {{ title|striptags|e }}{%- for parent in parents[:1] %} – {{ parent.title }}{%- endfor %} -
    -
    - {%- for button in header_buttons -%} - {{ render_funcs[button.pop("type")](**button) }} - {%- endfor -%} - - {% if page_toc -%} - {{ render_label_input_button("__page-toc", icon="fas fa-list", label="page-toc") }} - {%- endif %} -
    -
    - - -
    - {%- if page_toc | length >= 1 %} -
    - {{ translate(theme_toc_title) }} -
    - - {%- endif %} -
    diff --git a/docs/_templates/sections/sidebar.html b/docs/_templates/sections/sidebar.html deleted file mode 100644 index 054e9cc9b3..0000000000 --- a/docs/_templates/sections/sidebar.html +++ /dev/null @@ -1,4 +0,0 @@ -{%- for sidebartemplate in sidebars %} -{%- include sidebartemplate %} -{%- endfor %} -{%- include 'version-switcher.html' -%} diff --git a/docs/admin-guide/add-ons.md b/docs/admin-guide/add-ons.md new file mode 100644 index 0000000000..d2f0c7e735 --- /dev/null +++ b/docs/admin-guide/add-ons.md @@ -0,0 +1,224 @@ +--- +myst: + html_meta: + "description": "Install Plone add-ons" + "property=og:description": "Install Plone add-ons" + "property=og:title": "Install Plone add-ons" + "keywords": "Plone 6, add-on, package, plugin, extension, install" +--- + +(install-plone-add-ons-label)= + +# Install Plone add-ons + +This chapter explains how to install {term}`add-ons ` as Python packages to extend the functionality of the Plone backend or Classic UI. + +```{note} +The Volto frontend has its own system of add-ons using Node.js packages. +See {doc}`/volto/development/add-ons/index`. +``` + + +## Cookieplone + +Use the following instructions if you installed Plone with Cookieplone. + + +### Install an add-on + +Add the name of your add-on in the file {file}`backend/pyproject.toml` in the section `dependencies`. +This example adds [`collective.easyform`](https://pypi.org/project/collective.easyform/). + +```{code-block} toml +:emphasize-lines: 6 +dependencies = [ + "Products.CMFPlone==6.1.1", + "plone.api", + "plone.classicui", + "plone.app.caching", + "collective.easyform==4.4.0", +] +``` + +```{tip} +Including the add-on version, or "pinning a version", ensures that it won't unintentionally get upgraded in the future. +``` + +Also add the add-on to `zcml_package_includes` in the file {file}`backend/instance.yaml` to make sure its configuration will be loaded. + +```yaml +default_context: + zcml_package_includes: project_title, collective.easyform +``` + +Stop the backend with {kbd}`ctrl-c`. + +To actually download and install the new add-on, run the following command. + +```shell +make backend-build +``` + +Now restart the backend. + +```{seealso} +{doc}`run-plone` +``` + +In your web browser, and assuming you are currently logged in as an administrator, visit the URL http://localhost:8080/Plone/prefs_install_products_form. + +Then click the {guilabel}`Install` button next to your add-on to complete installation of the add-on. + +Some add-ons have configuration options. +To configure such add-ons, return to the {guilabel}`Site Setup` control panel. +At the bottom of the page, you should see the heading {guilabel}`Add-on Configuration`, and a control panel to configure the add-on that you just installed. + + +### Install an add-on from source + +An add-on can be installed from a source control system such as GitHub. + +Add a line with the name of your add-on in the file {file}`backend/requirements.txt`. +This example uses [`collective.easyform`](https://pypi.org/project/collective.easyform/). + +``` +collective.easyform +``` + +```{note} +When installing an add-on from source, it's best not to pin a version. +This way you always get the version that's currently available in the source control system. +``` + +Next add the add-on to `zcml_package_includes` in the file {file}`backend/instance.yaml` so that its configuration will load. + +```yaml +default_context: + zcml_package_includes: project_title, collective.easyform +``` + +Finally, add the package's source to the file {file}`mx.ini`. + +```cfg +[collective.easyform] +url=git@github.com:collective/collective.easyform.git +branch=dev-branch-name +extras=test +``` + +```{seealso} +The {file}`mx.ini` file configures a tool called {term}`mxdev`. +See the [documentation of `mxdev` in its README.md](https://github.com/mxstack/mxdev/blob/main/README.md) for complete information. +``` + +Stop the backend with {kbd}`ctrl-c`. + +To actually download and install the new add-on, run the following command. + +```shell +make backend-build +``` + +Now restart the backend. + +```{seealso} +{doc}`run-plone` +``` + +In your web browser, and assuming you are currently logged in as an administrator, visit the URL http://localhost:8080/Plone/prefs_install_products_form. +An upgrade step might need to be performed in the Plone control panel. +Follow the upgrade information, if present. +Else click the {guilabel}`Install` button to complete installation of the add-on. + + +## Buildout + +Use the following instructions if you installed Plone with Buildout. + +### Install an add-on + +Update the file {file}`buildout.cfg`. +This example uses [`collective.easyform`](https://pypi.org/project/collective.easyform/). + +```cfg +[buildout] +extends = + https://dist.plone.org/release/6-latest/versions.cfg + +parts = + instance + +[instance] +recipe = plone.recipe.zope2instance +user = admin:admin +http-address = 8080 +eggs = + Plone + collective.easyform + +[versions] +collective.easyform = 4.2.1 +``` + +```{tip} +Including the add-on version, or "pinning a version", ensures that it won't unintentionally get upgraded in the future. +``` + +To actually download and install the new add-on, run the following command. + +```shell +bin/buildout +``` + +Then restart your instance. + +```{seealso} +{doc}`run-plone` +``` + + +### Install an add-on from source + +You can install an add-on from a source control system such as GitHub. + +Update the file {file}`buildout.cfg`. +This example uses [`collective.easyform`](https://pypi.org/project/collective.easyform/). + +```cfg +[buildout] +extends = + https://dist.plone.org/release/6-latest/versions.cfg +extensions = mr.developer +auto-checkout = + collective.easyform + +parts = + instance + +[instance] +recipe = plone.recipe.zope2instance +user = admin:admin +http-address = 8080 +eggs = + Plone + collective.easyform + +[sources] +collective.easyform = git https://github.com/collective/collective.easyform.git +``` + +To actually download and install the new add-on, run the following command. + +```shell +bin/buildout +``` + +Then restart your instance. + +```{seealso} +{doc}`run-plone` +``` + +```{seealso} +This approach uses the [`mr.developer`](https://pypi.org/project/mr.developer/) Buildout extension. +``` diff --git a/docs/admin-guide/add-site.md b/docs/admin-guide/add-site.md new file mode 100644 index 0000000000..971f10496c --- /dev/null +++ b/docs/admin-guide/add-site.md @@ -0,0 +1,82 @@ +--- +myst: + html_meta: + "description": "How to add a Plone site to an existing Zope instance" + "property=og:description": "How to add a Plone site to an existing Zope instance" + "property=og:title": "Add a Plone site" + "keywords": "Plone 6, create, add, factory, distributions" +--- + +(add-a-plone-site-label)= + +# Add a Plone site + +This section explains how to add a Plone site to an existing Zope instance. +It assumes that you have already {doc}`installed ` and started Plone. + +Some installation methods create a Plone site for you already. +Follow these instructions if you used an installation method that did not do this, or if you need a second Plone site in the same instance for some reason. + +```{versionadded} Plone 6.1 +The user interface for creating a new Plone site was changed in Plone 6.1. +You can access it the same way in Plone 6.0, but the appearance and options are different. +``` + +Visit the Plone backend in a web browser. +Usually it is running at http://localhost:8080/. + +The launch screen prompts you to choose one of the available {term}`distributions` to create a new site. +You can read {doc}`/conceptual-guides/choose-user-interface` to help inform your choice between Volto and Classic UI. + +````{card} +```{image} /backend/upgrading/version-specific-migration/images/distribution-chooser.png +:alt: Launch screen for choosing a distribution +:target: /_images/distribution-chooser.png +``` ++++ +_Launch screen for choosing a distribution_ +```` + +Hover over your choice and click the {guilabel}`Create` button. + +Now complete the form with initial configuration for your site. +You can configure the following settings. + +Path Identifier +: The ID of the site. + This ends up as part of the URL unless hidden by an upstream web server. + +Title +: The name of the site in the HTML `title` element. + This will be shown as part of the title of the browser tab on each page. + +Site Description +: A brief description that will be served in an HTML `meta` tag. + +Site Logo +: Upload an image as the main site logo. + +Language +: The main language of the site. + +Timezone +: The default timezone setting of the portal. + +Finally, click the {guilabel}`Submit` button. + +Have fun with your new Plone site! + +```{important} +The launch screen for adding a site is hosted by the Plone backend server. +Regardless of the frontend you select, you will be redirected to the backend's user interface after you create the site. +If you select the Volto frontend, you can switch to it by changing the port number in the URL, usually `3000`, and visiting it at http://localhost:3000, for example. +``` + +## Related content + +- {doc}`/install/create-project-cookieplone` +- {doc}`/admin-guide/install-buildout` +- {doc}`/admin-guide/install-pip` +- {doc}`/conceptual-guides/distributions` +- {doc}`/developer-guide/create-a-distribution` +- {doc}`/conceptual-guides/choose-user-interface` diff --git a/docs/admin-guide/backup-restore-plone-buildout.md b/docs/admin-guide/backup-restore-plone-buildout.md new file mode 100644 index 0000000000..2e36751426 --- /dev/null +++ b/docs/admin-guide/backup-restore-plone-buildout.md @@ -0,0 +1,100 @@ +--- +myst: + html_meta: + "description": "How to Back up and restore a Plone site that was installed using buildout" + "property=og:description": "How to Back up and restore a Plone site that was installed using buildout" + "property=og:title": "Back up and restore a Plone site" + "keywords": "Plone 6, admin, install, configuration, upgrade, buildout" +--- + +(back-up-and-restore-a-plone-buildout-label)= + +# Back up and restore a Plone buildout + +This chapter explains how to back up and restore a Plone site that was installed using buildout. + +(backup-your-plone-site-label)= + +## Back up your Plone site + +```{danger} +Always back up your Plone site before upgrading. +``` + +This back up guide assumes the following. + +- You back up your Plone site. +- You back up your buildout and its caches. +- You back up your persistent data storage using a strategy that maintains data integrity without taking down your Plone site, that is performed periodically with adequate frequency, and that stores sufficient versions of your data. +- You've tested the restore process. + + +### Where's my data? + +Your Plone instance installation contains a directory {file}`./var`. +This directory is located in the same directory as the file {file}`buildout.cfg`. +It holds the frequently changing data files for the instance. +{file}`./var` contains the instance's log, process ID, and socket files. + +The following directories contain your instance's content. + + +#### {file}`./var/filestorage` + +The Zope Object Database ({term}`ZODB`) file storage is maintained in the directory {file}`./var/filestorage`. +The default file name is {file}`Data.fs`, although you could have multiple files or renamed it. +It's typically a large file which contains everything except {term}`blob`s. + +The other files in this directory with the file extensions of `.index`, `.lock`, `.old`, or `.tmp` are ephemeral, and will be recreated by Zope if they're absent. + + +#### {file}`./var/blobstorage` + +The directory {file}`./var/blobstorage` contains a deeply nested directory hierarchy that contains the blobs of your database. +These files may include PDFs, images, videos, office automation files, and other binary objects. + +`filestorage` and `blobstorage` are maintained synchronously. +`filestorage` has references to blobs in `blobstorage`. +If the two storages are not synchronized, you'll get errors whenever their data is accessed. + + +### `collective.recipe.backup` + +[`collective.recipe.backup`](https://pypi.org/project/collective.recipe.backup/) is a well-maintained buildout recipe that maintains data integrity for a live Plone database. + +See its `README.md`'s section [Introduction](https://github.com/collective/collective.recipe.backup?tab=readme-ov-file#introduction) for its buildout recipe configuration. + +The recipe supports several options, all of which are documented its `README.md`'s section [Supported options](https://github.com/collective/collective.recipe.backup/blob/master/README.rst#supported-options). + +Perhaps the most useful option is `location`, which sets the destination for backup files. +Its default value is `var/backups`, inside the buildout directory. +The backup destination, may be any attached location, including another partition, drive, or network storage. + + +#### Operation + +After running buildout to configure `collective.recipe.backup`, you'll find {file}`bin/backup` and {file}`bin/restore` scripts in your buildout directory. +Since all options are set via buildout, there are few command-line options, and operation is generally through bare commands. + +{file}`bin/restore` will accept a date-time argument, if you keep multiple backups. +For restore operations, stop Plone before starting your restore, and restart after the restore is complete. + +{file}`bin/backup` is commonly included in a cron table for regular operation. +You can run backup operations without stopping Plone. +Make sure you test your backup and restore process before you need it. + + +### Incremental backups + +`collective.recipe.backup` offers both incremental and full backups, and will maintain multiple versions of backups. +Tune these to meet your needs. + +When you enable incremental backups, the database packing operation will automatically cause the next backup to be a full backup. + +If your backup continuity need is critical, then your incremental backup schedule may need to be frequent. +Some Plone sites require incremental backups every few minutes. + +## Related content + +- {doc}`/admin-guide/export-import` +- {doc}`/admin-guide/install-buildout` \ No newline at end of file diff --git a/docs/admin-guide/configure-zope.md b/docs/admin-guide/configure-zope.md new file mode 100644 index 0000000000..e933e7d111 --- /dev/null +++ b/docs/admin-guide/configure-zope.md @@ -0,0 +1,35 @@ +--- +myst: + html_meta: + "description": "Configure Zope options" + "property=og:description": "Configure Zope options" + "property=og:title": "Configure Zope" + "keywords": "Plone 6, Zope, instance, app server, config, Cookieplone, Buildout, pip, cookiecutter-zope-instance, plone.recipe.zope2instance" +--- + +(configure-zope-label)= + +# Configure Zope + +Plone runs in an application server called {term}`Zope`. + +You can configure your Zope instance's options, including the following. + +- persistent storage: blobs, direct file storage, relational database, ZEO, and other storage mechanisms +- ports +- threads +- cache +- logging +- debugging and profiling for development + + +## Cookieplone + +If you installed Plone using Cookieplone or pip, then Zope is configured using {term}`cookiecutter-zope-instance`. +For a complete list of features, usage, and options, read [`cookiecutter-zope-instance`'s README](https://github.com/plone/cookiecutter-zope-instance#readme). + + +## Buildout + +If you installed Plone using Buildout, then Zope is configured using `plone.recipe.zope2instance`. +For a complete list of features, usage, and options, read [`plone.recipe.zope2instance`'s README](https://pypi.org/project/plone.recipe.zope2instance/). diff --git a/docs/admin-guide/export-import.md b/docs/admin-guide/export-import.md new file mode 100644 index 0000000000..ea908b7245 --- /dev/null +++ b/docs/admin-guide/export-import.md @@ -0,0 +1,118 @@ +--- +myst: + html_meta: + "description": "Export and import Plone site data with plone.exportimport" + "property=og:description": "Export and import Plone site data with plone.exportimport" + "property=og:title": "Export and import Plone site data with plone.exportimport" + "keywords": "Plone 6, plone.exportimport, export, import, site, data, Content, Principals, Relations, Translations, Discussions, Redirects" +--- + +(exportimport)= + +# Export and import site data + +The `plone.exportimport` package provides support to export and import all kinds of data from and to Plone sites using an intermediate JSON format. + +Most features use {doc}`plone.restapi <../plone.restapi/docs/source/index>` to serialize and deserialize data. + + +## Command line utilities + +This package provides two command line utilities, `plone-exporter` and `plone-importer`. + +### `plone-exporter` + +Export content from a Plone site to a directory in the file system. +You can call `plone-exporter` as shown. + +```shell +plone-exporter [--include-revisions] +``` + +The following command shows typical usage. + +```shell +plone-exporter instance/etc/zope.conf Plone /tmp/plone_data/ +``` + +By default, the revisions history (older versions of each content item) are not exported. +If you do want them, add `--include-revisions` on the command line. + + +### `plone-importer` + +Import content from a file system directory into an existing Plone site. + +You can call `plone-importer` as shown. + +```shell +plone-importer +``` + +The following command shows typical usage. + +```shell +plone-importer instance/etc/zope.conf Plone /tmp/plone_data/ +``` + + +## Supported data + +- Content (Dexterity content items) + - Ordering + - Local roles + - Versions (when using the `--include-revisions` command line option) + - Default pages +- Principals (members and groups) +- Relations (relationships between content items) +- Translations (translation groups) +- Discussions (content comments) +- Redirects (redirect information) + + +## Exported data structure + +Some goals of the new data structure are to: + +- support diff of exported data, and +- have blob files near the content item that uses it. + +After exporting content, at the top level directory, the following objects exist. + +| Name | Description | +| --- | --- | +| `content` | Directory containing content item information exported from the site | +| `discussions.json` | JSON File with discussions (comments) exported from the site | +| `principals.json` | JSON File with members and groups exported from the site | +| `redirects.json` | JSON File with redirect information exported from the site | +| `relations.json` | JSON File with content relations exported from the site | +| `translations.json` | JSON File with translation groups exported from the site | + + +### Content directory structure + +The {file}`content` directory contains all content items exported from the site. +Each content item has its own subdirectory, named with the UID of the content, including the serialized data and all blob files related to this content. + +One special case is the directory for the `Plone Site` object, which is named `plone_site_root`. + +| Name | Description | +| --- | --- | +| `content/__metadata__.json` | JSON File with metadata information about the exported content | +| `content/` | Directory with serialization for a content item | +| `content/plone_site_root` | Directory with serialization for the Plone Site Root | + + +#### Content item directory structure + +Consider a File content item with UID `3e0dd7c4b2714eafa1d6fc6a1493f953` and a PDF file named {file}`plone.pdf` (added in the `file` field), the exported directory will have the following structure. + +| Name | Description | +| --- | --- | +| `content/3e0dd7c4b2714eafa1d6fc6a1493f953/data.json` | JSON File with serialized representation of a content item | +| `content/3e0dd7c4b2714eafa1d6fc6a1493f953/file/plone.pdf` | Blob file stored in the `file` field in the content item | + +## Related content + +- {doc}`/admin-guide/backup-restore-plone-buildout` +- {ref}`add-a-plone-site-label` diff --git a/docs/admin-guide/index.md b/docs/admin-guide/index.md new file mode 100644 index 0000000000..8d78c7d07e --- /dev/null +++ b/docs/admin-guide/index.md @@ -0,0 +1,46 @@ +--- +myst: + html_meta: + "description": "How to install, operate, configure, and deploy Plone 6" + "property=og:description": "How to install, operate, configure, and deploy Plone 6" + "property=og:title": "Admin guide" + "keywords": "Plone 6, admin, install, configuration, deploy" +--- + +(admin-index-label)= + +# Admin guide + +In this part of the documentation, you can find how to install, operate, and configure Plone. + + +```{toctree} +:caption: Install +:maxdepth: 1 + +/install/create-project-cookieplone +install-buildout +install-pip +``` + +```{toctree} +:caption: Operate +:maxdepth: 1 + +run-plone +add-site +zope-manager-users +configure-zope +add-ons +export-import +override-core +backup-restore-plone-buildout +/upgrade/index +``` + +```{toctree} +:maxdepth: 1 +:caption: Deploy + +/install/containers/index +``` diff --git a/docs/admin-guide/install-buildout.md b/docs/admin-guide/install-buildout.md new file mode 100644 index 0000000000..5888502c1e --- /dev/null +++ b/docs/admin-guide/install-buildout.md @@ -0,0 +1,135 @@ +--- +myst: + html_meta: + "description": "Install Plone with Buildout" + "property=og:description": "Install Plone with Buildout" + "property=og:title": "Install Plone with Buildout" + "keywords": "Plone 6, install, Classic UI, Buildout" +--- + +(install-buildout-label)= + +# Install Plone with Buildout + +This chapter describes how you can install Plone using {term}`Buildout`. + +This is one way to install Plone with the Classic UI. +Using Buildout will be the most familiar approach for administrators who have experience with Plone 3, 4, or 5. + +```{seealso} +For other installation options, see {ref}`get-started-install-label`. +``` + +(install-buildout-prerequisites)= + + +## Supported web browsers + +```{include} /_inc/_install-browser-reqs-classic-ui.md +``` + + +## Prerequisites for installation + +- For Plone 6.1, Python {{SUPPORTED_PYTHON_VERSIONS_PLONE61}} + + +### Python + +```{include} /_inc/_install-python-plone61.md +``` + + +## Installation + +Select a directory of your choice, and change it to your working directory. + +```shell +mkdir -p /plone +cd /plone +``` + +Create a Python virtual environment. + +```shell +python3 -m venv venv +``` + +Install the minimal Python packages needed in order to run Buildout. + +```shell +venv/bin/pip install -r https://dist.plone.org/release/6-latest/requirements.txt +``` + + + +Create a {file}`buildout.cfg` file in your directory with the following contents. + +```cfg +[buildout] +extends = + https://dist.plone.org/release/6-latest/versions.cfg + +parts = + instance + +[instance] +recipe = plone.recipe.zope2instance +# user = username:password - Use a secure token in a production environment. +user = admin:admin +http-address = 8080 +eggs = + Plone +``` + +Use Buildout's [`bootstrap` command](https://www.buildout.org/en/latest/topics/bootstrapping.html) to install a local `buildout` script in the {file}`bin` directory. + +```shell +venv/bin/buildout bootstrap +``` + +Run Buildout. + +```shell +bin/buildout +``` + +This may take a few minutes. + +Whenever you change the Buildout configuration, run `./bin/buildout` again. + +## Start Plone in foreground mode + +Start the instance for a quick test in foreground mode: + +```shell +bin/instance fg +``` + +```{include} /_inc/_create-classic-ui-instance.md +``` + + +## Start Plone as a background service + +Start the instance. + +```shell +bin/instance start +``` + + +## Stop Plone as a background service + +Stop the instance. + +```shell +bin/instance stop +``` + +## Related content + +- {doc}`/admin-guide/add-site` +- {doc}`/admin-guide/install-pip` +- {doc}`/admin-guide/backup-restore-plone-buildout` +- {doc}`/conceptual-guides/compare-buildout-pip` diff --git a/docs/admin-guide/install-pip.md b/docs/admin-guide/install-pip.md new file mode 100644 index 0000000000..dddd40fbe4 --- /dev/null +++ b/docs/admin-guide/install-pip.md @@ -0,0 +1,105 @@ +--- +myst: + html_meta: + "description": "Install Plone with pip" + "property=og:description": "Install Plone with pip" + "property=og:title": "Install Plone with pip" + "keywords": "Plone 6, install, Classic UI, pip" +--- + +(install-pip-label)= + +# Install Plone with pip + +This chapter describes how you can install Plone using {term}`pip`. + +This is one way to install Plone with the Classic UI. +It provides a basic installation without many additional tools to help with development. + +```{seealso} +For other installation options, see {ref}`get-started-install-label`. +``` + + +## Supported web browsers + +```{include} /_inc/_install-browser-reqs-classic-ui.md +``` + + +(install-pip-prerequisites)= + +## Prerequisites for installation + +- For Plone 6.1, Python {{SUPPORTED_PYTHON_VERSIONS_PLONE61}} + + +### Python + +```{include} /_inc/_install-python-plone61.md +``` + + +## Installation + +Select a directory of your choice, and change it to your working directory. + +```shell +mkdir -p /plone +cd /plone +``` + +Create a Python virtual environment. + +```shell +python3 -m venv venv +``` + +Install Plone and a helper package, {term}`pipx`. + +```shell +venv/bin/pip install -c https://dist.plone.org/release/6-latest/constraints.txt Plone pipx +``` + + +## Create a Zope instance + +Create a file {file}`instance.yaml` in your directory with the following contents. + +```yaml +default_context: + initial_user_name: "admin" +# Use a secure token for the password in a production environment. + initial_user_password: "admin" + wsgi_listen: "localhost:8080" + debug_mode: false + verbose_security: false + db_storage: "direct" + environment: { + "zope_i18n_compile_mo_files": true, + } +``` + +Now run the {term}`cookiecutter` tool to create configuration for a Zope instance. + +``` +venv/bin/pipx run cookiecutter -f --no-input --config-file instance.yaml gh:plone/cookiecutter-zope-instance +``` + + +## Start Plone in foreground mode + +Start the instance for a quick test. + +```shell +venv/bin/runwsgi -v instance/etc/zope.ini +``` + +```{include} /_inc/_create-classic-ui-instance.md +``` + +## Related content + +- {doc}`/admin-guide/add-site` +- {doc}`/admin-guide/install-buildout` +- {doc}`/conceptual-guides/compare-buildout-pip` diff --git a/docs/admin-guide/override-core.md b/docs/admin-guide/override-core.md new file mode 100644 index 0000000000..7fc64f7397 --- /dev/null +++ b/docs/admin-guide/override-core.md @@ -0,0 +1,178 @@ +--- +myst: + html_meta: + "description": "Override core Plone packages" + "property=og:description": "Override core Plone packages" + "property=og:title": "Override core Plone packages" + "keywords": "Plone 6, core, package, version, override, Cookieplone, Buildout" +--- + +(override-core-plone-packages-label)= + +# Override core Plone packages + +Plone includes a few hundred Python packages. +Sometimes you will need to override one or more package versions to fix a bug. + + +## Cookieplone + +Use the following instructions if you installed Plone with Cookieplone. + + +### Override a core Plone package + +Add a version override to the file {file}`mx.ini`. +This example uses `plone.api`. + +``` +[settings] +version-overrides = + plone.api==2.0.0a3 +``` + +```{seealso} +The {file}`mx.ini` file configures a tool called {term}`mxdev`. +For an explanation of why Plone uses `mxdev`, see {ref}`manage-backend-python-packages-label`. +``` + +Stop the backend with {kbd}`ctrl-c`. + +To actually download and install the new package version, run the following command. + +```shell +make backend-build +``` + +Now restart the backend. + +```{seealso} +{doc}`run-plone` +``` + + +### Install a core Plone package from source + +You can also use `mxdev` to install core Plone packages from a source control system such as GitHub. + +Add the Plone package you want to check out in the file {file}`mx.ini`. +This example uses `plone.restapi`. + +```cfg +[plone.restapi] +url = git@github.com:plone/plone.restapi.git +branch = main +extras = test +``` + +Stop the backend with {kbd}`ctrl-c`. + +To actually download and install the new package version, run the following command. + +```shell +make backend-build +``` + +Now restart the backend. + +```{seealso} +{doc}`run-plone` +``` + + +## Buildout + +Use the following instructions if you installed Plone with Buildout. + +### Override a core Plone package + +Update the file {file}`buildout.cfg`. +This example uses `plone.api`. + +```cfg +[buildout] +extends = + https://dist.plone.org/release/6-latest/versions.cfg + +parts = + instance + +[instance] +recipe = plone.recipe.zope2instance +user = admin:admin +http-address = 8080 +eggs = + Plone + +[versions] +plone.api = 2.0.0a3 +``` + +```{note} +The version pins specified in the `[versions]` section will take precedence over the pins inherited from `https://dist.plone.org/release/6-latest/versions.cfg`. +``` + +To actually download and install the new package version, run the following command. + +```shell +bin/buildout +``` + +Then restart your instance. + +```{seealso} +{doc}`run-plone` +``` + + +### Install a core Plone package from source + +A core Plone package can be installed from a source control system such as GitHub. + +Update the file {file}`buildout.cfg`. +This example uses `plone.restapi`. + +```cfg +[buildout] +extends = + https://dist.plone.org/release/6-latest/versions.cfg +extensions = mr.developer +auto-checkout = + plone.restapi + +parts = + instance + +[instance] +recipe = plone.recipe.zope2instance +user = admin:admin +http-address = 8080 +eggs = + Plone + +[sources] +plone.restapi = git https://github.com/plone/plone.restapi.git + +[versions] +plone.restapi = +``` + +```{tip} +Setting an empty version ensures that the copy of `plone.restapi` from source control will be used, instead of the version pin inherited from https://dist.plone.org/release/6-latest/versions.cfg. +``` + +To actually download and install the new add-on, run the following command. + +```shell +bin/buildout +``` + +Then restart your instance. + +```{seealso} +{doc}`run-plone` +``` + +```{seealso} +This approach uses the [`mr.developer`](https://pypi.org/project/mr.developer/) Buildout extension. +``` diff --git a/docs/admin-guide/run-plone.md b/docs/admin-guide/run-plone.md new file mode 100644 index 0000000000..0a1bec7e02 --- /dev/null +++ b/docs/admin-guide/run-plone.md @@ -0,0 +1,100 @@ +--- +myst: + html_meta: + "description": "Run Plone" + "property=og:description": "Run Plone" + "property=og:title": "Run Plone" + "keywords": "Plone 6, run, start, command, Cookieplone, Buildout, pip" +--- + +(run-plone-label)= + +# Run Plone + +This chapter shows the commands to run Plone after it is installed. + +There are different commands to run Plone, depending on which method you used to install Plone. + +## Run Plone in foreground mode + +Running Plone in foreground mode will show output in the terminal. +This is recommended while developing a Plone site. +The command you use depends on the installation method you used. + +Cookieplone: +: ```shell + make backend-start + ``` + +Buildout: +: ```shell + bin/instance fg + ``` + +pip: +: ```shell + bin/runwsgi instance/etc/zope.ini + ``` + +For any of these commands, press {kbd}`ctrl-c` to stop the process. + + +## Run Volto + +If you use the Volto frontend, you need to run the frontend in a separate process and terminal session. + +Cookieplone: +: ```shell + make frontend-start + ``` + +For any of these commands, press {kbd}`ctrl-c` to stop the process. + + +## Start Plone as a background service + +Buildout: +: ```shell + bin/instance start + ``` + +## Stop Plone as a background service + +Buildout: +: ```shell + bin/instance stop + ``` + +## Run a debug console + +The debug console gives you a Python prompt with the Plone site's configuration loaded. +Use this for troubleshooting. + +Cookieplone: +: ```shell + make -C backend console + ``` + +Buildout: +: ```shell + bin/instance debug + ``` + +pip: +: ```shell + bin/zconsole debug instance/etc/zope.conf + ``` + +For any of these commands, press {kbd}`ctrl-d` to stop the process. + +### Set a "fake" request + +To make sure that the request is fully set up for any code that uses `zope.globalrequest.getRequest`, you might need to use the following code. + +```python +from Testing.makerequest import makerequest +from zope.globalrequest import setRequest + +app = makerequest(app) +setRequest(app.REQUEST) +``` diff --git a/docs/admin-guide/zope-manager-users.md b/docs/admin-guide/zope-manager-users.md new file mode 100644 index 0000000000..4093567c72 --- /dev/null +++ b/docs/admin-guide/zope-manager-users.md @@ -0,0 +1,109 @@ +--- +myst: + html_meta: + "description": "How to create a Zope manager user in an existing Zope instance" + "property=og:description": "How to create a Zope manager user in an existing Zope instance" + "property=og:title": "Zope manager users" + "keywords": "Plone, Zope, users, admin user, emergency user, administration, pip, buildout" +--- + +(admin-guide-zope-manager-user-label)= + +# Zope manager users + +This guide explains how to add a Zope user with the "manager" role—called a "Zope manager user"—to an existing Zope instance. + +Zope manager users have full access to the whole Zope instance. + +Some installation methods automatically create a Zope manager user named `admin` for you already. + +There are multiple reasons why you might need to add a Zope manager user, including the following. + +- Your installation method did not create one. +- You lost access to your instance. +- You inherited a project without proper documentation. + +```{note} +If you need to regain access to your instance, this user is also referred to as an "emergency user" in this context only. + +The emergency user is a superuser with full access to the Zope instance. +It is not limited to a specific Plone site. +Please be aware of the security implications. +Consider changing the passwords of the existing Zope manager users after you regain access to your instance. +``` + +(admin-guide-add-a-new-zope-manager-user-label)= + +## Add a new Zope manager user + +There are multiple methods to create a Zope manager user. +The method depends on how you created and manage your Zope instance, either via {term}`buildout` or {term}`pip`. + +```{important} +If you are running a standalone instance, you must stop it before adding the user. +``` + +(admin-guide-adduser-instance-command-label)= + +### `adduser` instance command + +If your site was installed with `buildout` and `plone.recipe.zope2instance`, you can add a Zope manager user via the instance script. + +Run the following command. + +```shell +bin/instance adduser username password +``` + +The name of the instance script might vary based on your installation. +Replace `username` and `password` with the desired values. + +If the command is successful, then it will return the following console output. + +```console +Created user: username +``` + +When you run the script, if the user already exists: + +- No user will be created. +- The password will not be changed. +- The command will return a message such as the following. + + ```console + Created user: None + ``` + +(admin-guide-addzopeuser-command-label)= + +### `addzopeuser` script + +For `pip` based installations, you will have a script called `addzopeuser` in the {file}`bin` directory of your virtual environment. +The `addzopeuser` script might also be available in `buildout` based installations. + +Run the following command. + +```shell +$ .venv/bin/addzopeuser -c path/to/etc/zope.conf username password +``` + +The `addzopeuser` script and {file}`zope.conf` locations might vary based on your installation. +Replace `username` and `password` with the desired values. + +If the command is successful, then it will return the following console output. + +```console +User username created. +``` + +When you run the script, if the user already exists: + +- No user will be created. +- The password will not be changed. +- The command will return a message such as the following. + + ```console + Got no result back. User creation may have failed. + Maybe the user already exists and nothing is done then. + Or the implementation does not give info when it succeeds. + ``` diff --git a/docs/backend/annotations.md b/docs/backend/annotations.md index 0f2ff39f27..7371002fd0 100644 --- a/docs/backend/annotations.md +++ b/docs/backend/annotations.md @@ -1,10 +1,10 @@ --- myst: html_meta: - "description": "" - "property=og:description": "" - "property=og:title": "" - "keywords": "" + "description": "Annotations store arbitrary values on Python objects—such as a Plone site or HTTP request—for storage and caching purposes." + "property=og:description": "Annotations store arbitrary values on Python objects—such as a Plone site or HTTP request—for storage and caching purposes." + "property=og:title": "Annotations" + "keywords": "Annotations, plone.memoize, cache, portal, content object" --- (backend-annotations-label)= diff --git a/docs/backend/behaviors.md b/docs/backend/behaviors.md index 3cb7271c28..0cab7e8055 100644 --- a/docs/backend/behaviors.md +++ b/docs/backend/behaviors.md @@ -378,3 +378,9 @@ The [README file of `plone.behavior`](https://github.com/plone/plone.behavior/bl Plone content objects have logic to look up the behaviors' names registered from their types' configuration, the {term}`Factory Type Information` (FTI). At runtime, the logic provides the interface (or marker) from the behavior to the object. This dynamically provided interface enables the component architecture to react to this new interface by adding additional form fields, bindings events, enabling more specific views, and more. + +## Related content + +- {doc}`/backend/content-types/index` +- {doc}`/backend/schemas` +- {doc}`/backend/fields` diff --git a/docs/backend/content-types/creating-content-types.md b/docs/backend/content-types/creating-content-types.md index 29781858ef..c3e6433baf 100644 --- a/docs/backend/content-types/creating-content-types.md +++ b/docs/backend/content-types/creating-content-types.md @@ -118,3 +118,11 @@ For now your content type doesn't have any custom schema with fields defined. See {doc}`/backend/schemas`, {doc}`/backend/fields` and {doc}`/backend/widgets` for information on how to add custom fields and widgets to your content type. Also have a look at Plone {doc}`/backend/behaviors`, which provide default features you can enable per content type. + +## Related content + +- {doc}`/backend/schemas` +- {doc}`/backend/fields` +- {doc}`/backend/widgets` +- {doc}`/backend/behaviors` +- {doc}`/backend/content-types/fti` diff --git a/docs/backend/content-types/index.md b/docs/backend/content-types/index.md index 165fbfec9e..676bccf8d4 100644 --- a/docs/backend/content-types/index.md +++ b/docs/backend/content-types/index.md @@ -7,6 +7,8 @@ myst: "keywords": "Content types, Dexterity, Plone" --- +(backend-content-types-index-label)= + # Content Types This part of the documentation describes how to develop content types in Plone. diff --git a/docs/backend/fields.md b/docs/backend/fields.md index 735fd74c32..b3c2212c8a 100644 --- a/docs/backend/fields.md +++ b/docs/backend/fields.md @@ -103,6 +103,27 @@ See [`plone.namedfile`](https://pypi.org/project/plone.namedfile/) and [plone.fo | `NamedBlobFile` | `NamedBlobFile` | A binary uploaded file stored as a ZODB blob. Requires the `blobs` extra to `plone.namedfile`. Otherwise identical to `NamedFile`. | `IField` | | `NamedBlobImage` | `NamedBlobImage` | A binary uploaded image stored as a ZODB blob. Requires the `blobs` extra to `plone.namedfile`. Otherwise identical to `NamedImage`. | `IField` | +#### `NamedBlobImage` + +The following example shows how to create an `Image` object, and attach the image file to it. + +```python +img_obj = api.content.create( + container=ww_article, + type="Image", + id="test.jpg", + image=NamedBlobImage( + data=img_file, + filename="test.jpg", + ) +) +``` + + + + + +(backend-fields-relation-fields-label)= ### Fields in `z3c.relationfield.schema` @@ -115,6 +136,8 @@ See [`z3c.relationfield`](https://pypi.org/project/z3c.relationfield/) for more | `RelationChoice` | `RelationValue` | A `Choice` field intended to store `RelationValue`s | See {ref}`Choice ` | +(backend-fields-richtext-label)= + ### Fields in `plone.app.textfield` See [`plone.app.textfield`](https://pypi.org/project/plone.app.textfield/) for more details. @@ -124,6 +147,172 @@ See [`plone.app.textfield`](https://pypi.org/project/plone.app.textfield/) for m | `RichText` | `RichTextValue` | Stores a `RichTextValue`, which encapsulates a raw text value, the source MIME type, and a cached copy of the raw text transformed to the default output MIME type. | `IField`, `IRichText` | +The `RichText` field allows for alternative markups and content filtering. +The following code sample shows how to create a schema with a `RichText` field. + +```python +from plone.app.textfield import RichText +from plone.supermodel import model + +class ITestSchema(model.Schema): + + body = RichText(title="Body text") +``` + +The `RichText` field constructor can take the following arguments, in addition to the usual arguments for a `Text` field. + +`default_mime_type` +: A string representing the default MIME type of the input markup. + This defaults to `text/html`. + +`output_mime_type` +: A string representing the default output MIME type. + This defaults to `text/x-html-safe`, which is a Plone-specific MIME type that disallows certain tags. + Use the {guilabel}`HTML Filtering` control panel in Plone to control the tags. + +`allowed_mime_types` +: A tuple of strings giving a vocabulary of allowed input MIME types. + If this is `None` (the default), the allowable types will be restricted to those set in Plone's {guilabel}`Markup` control panel. + +The *default* field can be set to either a Unicode object (in which case it will be assumed to be a string of the default MIME type) or a {ref}`backend-fields-richtextvalue-label`. + + +#### reStructuredText transformation + +Below is an example of a field that allows StructuredText and reStructuredText, transformed to HTML by default. + +```python +from plone.app.textfield import RichText +from plone.supermodel import model + +defaultBody = """\ +Background +========== + +Please fill this in + +Details +------- + +And this +""" + +class ITestSchema(model.Schema): + + body = RichText( + title="Body text", + default_mime_type="text/x-rst", + output_mime_type="text/x-html", + allowed_mime_types=("text/x-rst", "text/structured",), + default=defaultBody, + ) +``` + + +(backend-fields-richtextvalue-label)= + +#### `RichTextValue` + +The `RichText` field usually does not store a string. +Instead, it stores a `RichTextValue` object. +This is an immutable object that has the following properties. + +`raw` +: A Unicode string with the original input markup. + +`mimeType` +: The MIME type of the original markup, for example, `text/html` or `text/structured`. + +`encoding` +: The default character encoding used when transforming the input markup. + Most likely, this will be UTF-8. + +`raw_encoded` +: The raw input encoded in the given encoding. + +`outputMimeType` +: The MIME type of the default output, taken from the field at the time of instantiation. + +`output` +: A Unicode object representing the transformed output. + If possible, this is cached persistently, until the `RichTextValue` is replaced with a new one (as happens when an edit form is saved, for example). + +The storage of the `RichTextValue` object is optimized for the case where the transformed output will be read frequently (for example, on the view screen of the content object) and the raw value will be read infrequently (for example, on the edit screen). +Because the output value is cached indefinitely, you will need to replace the `RichTextValue` object with a new one if any of the transformation parameters change. +However, as we will see below, it is possible to apply a different transformation on demand, if you need to. + +The code snippet below shows how a `RichTextValue` object can be constructed in code. +In this case, we have a raw input string of type `text/plain` that will be transformed to a default output of `text/html`. +Note that we would normally look up the default output type from the field instance. + +```python +from plone.app.textfield.value import RichTextValue + +context.body = RichTextValue("Some input text", mimeType="text/html", outputMimeType="text/x-html-safe") +``` + +The standard widget used for a `RichText` field will correctly store this type of object for you, so it is rarely necessary to create one yourself. + + +##### `RichText` fields in templates + +If you use a `DisplayForm`, the display widget for the `RichText` field will render the transformed output markup automatically. +If you write TAL manually, you may try something like the following. + +```xml +
    +``` + +This, however, will render a string as follows. + +```html +RichTextValue object. (Did you mean .raw or .output?) +``` + +The correct syntax is: + +```xml +
    +``` + +This will render the cached, transformed output. +This operation is approximately as efficient as rendering a simple `Text` field, since the transformation is only applied once, when the value is first saved. + + +##### Alternative transformations + +Sometimes, you may want to invoke alternative transformations. +Under the hood, the default implementation uses the `portal_transforms` tool to calculate a transform chain from the raw value's input MIME type to the desired output MIME type. +If you need to write your own transforms, take a look at [Changing Portal Transforms Settings via Python](https://5.docs.plone.org/develop/plone/misc/portal_transforms.html). +This is abstracted behind an `ITransformer` adapter to allow alternative implementations. + +To invoke a transformation in code, you can use the following syntax. + +```python +from plone.app.textfield.interfaces import ITransformer + +transformer = ITransformer(context) +transformedValue = transformer(context.body, "text/plain") +``` + +The `__call__()` method of the `ITransformer` adapter takes a `RichTextValue` object and an output MIME type as parameters. + +If you write a page template, there is an even more convenient syntax. + +```xml +
    +``` + +The first traversal name segment gives the name of the field on the context (`body` in this case). +The second and third segments give the output MIME type. +If the MIME type is omitted, the default output MIME type will be used. + +```{note} +Unlike the `output` property, the value is not cached, and so will be calculated each time the page is rendered. +``` + + + ### Fields in `plone.schema` See {ref}`backend-ploneschema-label` for more details. @@ -136,19 +325,50 @@ See {ref}`backend-ploneschema-label` for more details. (backend-fields-schema-label)= -## schema +## Schema + +With `plone.autoform` and `plone.supermodel` we can use directives to add information to the schema fields. -(backend-fields-schema-autoform-label)= +(backend-fields-schema-autoform-permission)= -### `autoform` (directives) schema ordering, filtering, and permissions +### Protect a field with a permission +By default, fields are included in the form regardless of the user's permissions. +Fields can be protected using the `read_permission` and `write_permission` directives. +The read permission is checked when the field is in display mode, and the write permission is checked when the field is in input mode. +The permission should be given with its Zope 3-style name, such as `cmf.ManagePortal` instead of `Manage portal`. -(backend-fields-supermodel-label)= +In this example, the `secret` field is protected by the `cmf.ManagePortal` permission as both a read and write permission. +This means that in both display and input modes, the field will only be included in the form for users who have that permission: -## `supermodel` (XML) +```python +from plone.supermodel import model +from plone.autoform import directives as form +class IMySchema(model.Schema): + form.read_permission(secret="cmf.ManagePortal") + form.write_permission(secret="cmf.ManagePortal") + secret = schema.TextLine( + title = "Secret", + ) +``` + +In supermodel XML, the directives are `security:read-permission` and +`security:write-permission`: + +```xml + + Secret + +``` -(backend-fields-supermodel-autoform-label)= +## Related content -### `autoform` (directives) supermodel ordering, filtering, and permissions +- {doc}`/backend/schemas` +- {doc}`/backend/content-types/index` +- {doc}`/backend/vocabularies` +- {doc}`/backend/relations` diff --git a/docs/backend/indexing.md b/docs/backend/indexing.md index 103e6795ef..1b3e49ef30 100644 --- a/docs/backend/indexing.md +++ b/docs/backend/indexing.md @@ -226,3 +226,7 @@ Indexes the object path, such as `/news/news-item-1`. ## `Subject` (`KeywordIndex`) Indexes the `Subject` field which contains a list of object categories. + +## Related content + +- {doc}`/backend/search` diff --git a/docs/backend/relations.md b/docs/backend/relations.md index dc1cf66434..18a32c8acd 100644 --- a/docs/backend/relations.md +++ b/docs/backend/relations.md @@ -61,7 +61,7 @@ minions = RelationList( ) ``` -We can see that the [code for the behavior `IRelatedItems`](https://github.com/plone/plone.app.relationfield/blob/master/plone/app/relationfield/behavior.py) does exactly the same thing. +We can see that the [code for the behavior `IRelatedItems`](https://github.com/plone/plone.app.relationfield/blob/master/src/plone/app/relationfield/behavior.py) does exactly the same thing. (relations-controlling-relation-targets-label)= @@ -643,3 +643,10 @@ Thus the API for getting the target uses: In addition, the relation value knows under which attribute it has been stored as `from_attribute`. It is usually the name of the field with which the relation is created. But it can also be the name of a relation that is created by code, for example, through link integrity relations (`isReferencing`) or the relation between a working copy and the original (`iterate-working-copy`). + +## Related content + +- {doc}`/backend/schemas` +- {ref}`backend-fields-relation-fields-label` +- {doc}`/backend/content-types/index` +- {doc}`/backend/vocabularies` diff --git a/docs/backend/schemas.md b/docs/backend/schemas.md index 445b732723..8483cefa2a 100644 --- a/docs/backend/schemas.md +++ b/docs/backend/schemas.md @@ -39,6 +39,8 @@ Zope schemas are used for tasks such as: - specifying required attributes on an object - defining custom validators on input data +(schemas-fields-label)= + The basic unit of data model declaration is the {doc}`field `, which specifies what kind of data each Python attribute can hold. @@ -101,7 +103,6 @@ This schema can be used in {doc}`/classic-ui/forms` and Dexterity {doc}`/backend ```{note} In Dexterity {doc}`/backend/content-types/index`, the base class for a schema is `plone.supermodel.model.Schema`. -This provides functionalities to export and import schemas via XML and the {doc}` Through-the-web (TTW) ` editor. ``` @@ -217,6 +218,148 @@ Note this won't have behavior fields added to it at this stage, only the fields - {doc}`reference list of fields used in Plone ` +(backend-schemas-directives-label)= + +## Schema directives + +With `plone.autoform` and `plone.supermodel`, we can use directives to add information to the schema fields. + + +### Omit fields + +A field can be omitted entirely from all forms, or from some forms, using the `omitted` and `no_omit` directives. +In this example, the `dummy` field is omitted from all forms, and the `edit_only` field is omitted from all forms except those that provide the `IEditForm` interface: + +```{code-block} python +:emphasize-lines: 7,12,13 +:linenos: + +from z3c.form.interfaces import IEditForm +from plone.supermodel import model +from plone.autoform import directives as form + +class IMySchema(model.Schema): + + form.omitted("dummy") + dummy = schema.Text( + title="Dummy" + ) + + form.omitted("edit_only") + form.no_omit(IEditForm, "edit_only") + edit_only = schema.TextLine( + title = "Only included on edit forms", + ) +``` + +In supermodel XML, this can be specified as: + +```{code-block} xml +:emphasize-lines: 3,9 + + + Dummy + + + + Only included on edit form + +``` + +`form:omitted` may be either a single boolean value, or a space-separated list of `:` pairs. + + +### Reorder fields + +A field's position in the form can be influenced using the `order_before` and `order_after` directives. +In this example, the `not_last` field is placed before the `summary` field, even though it is defined afterward: + +```{code-block} python +:emphasize-lines: 12 +:linenos: + +from plone.supermodel import model +from plone.autoform import directives as form + +class IMySchema(model.Schema): + + summary = schema.Text( + title="Summary", + description="Summary of the body", + readonly=True + ) + + form.order_before(not_last="summary") + not_last = schema.TextLine( + title="Not last", + ) +``` + +The value passed to the directive may be either `*`, indicating before or after all fields, or the name of another field. +Use `.` to refer to the field in the current schema or a base schema. +Prefix with the schema name, such as `IDublinCore.title`, to refer to a field in another schema. +Use an unprefixed name to refer to a field in either the current or default schema for the form. + +In supermodel XML, the directives are called `form:before` and `form:after`. +For example: + +```{code-block} xml +:emphasize-lines: 3 + + + Not last + +``` + + +### Organizing fields into fieldsets + +Fields can be grouped into fieldsets, which will be rendered within an HTML `
    ` tag. +In this example the `footer` and `dummy` fields are placed within the `extra` fieldset: + +```{code-block} python +:emphasize-lines: 6-9 +:linenos: + +from plone.supermodel import model +from plone.autoform import directives as form + +class IMySchema(model.Schema): + + model.fieldset("extra", + label="Extra info", + fields=["footer", "dummy"] + ) + + footer = schema.Text( + title="Footer text", + ) + + dummy = schema.Text( + title="Dummy" + ) +``` + +In supermodel XML, fieldsets are specified by grouping fields within a `
    ` tag: + +```xml +
    + + Footer text + + + Dummy + +
    +``` + + ## Advanced ```{note} @@ -588,17 +731,11 @@ def fields(self): f.field = schema_field ``` -#### Don't use dict `{}` or list `[]` as a default value - -Because of how Python object construction works, giving `[]` or `{}` as a default value will make all created field values share this same object. +## Related content -```{seealso} -[The Hitchhiker's Guide to Python, Common Gotchas](https://docs.python-guide.org/writing/gotchas) -``` +- {doc}`/backend/fields` +- {doc}`/backend/content-types/index` +- {doc}`/classic-ui/forms` +- {doc}`/backend/vocabularies` -Use value adapters instead. - -```{seealso} -[`plone.directives.form` documentation of Value adapters](https://pypi.org/project/plone.directives.form/#value-adapters) -``` diff --git a/docs/backend/search.md b/docs/backend/search.md index 318453e55a..841d8fd69c 100644 --- a/docs/backend/search.md +++ b/docs/backend/search.md @@ -1,16 +1,30 @@ --- myst: html_meta: - "description": "" - "property=og:description": "" - "property=og:title": "" - "keywords": "" + "description": "How to index and search content in Plone" + "property=og:description": "How to index and search content in Plone" + "property=og:title": "Search" + "keywords": "Plone, search, index, querystring, catalog" --- (backend-search-label)= # Search +To index and search content in Plone, see the Plone 5 documentation {doc}`plone5:develop/plone/searching_and_indexing/index`. + +Alternatively, you can integrate any open source search engine with your Plone site. + +- [Solr](https://solr.apache.org/) - See the add-on [`collective.solr`](https://github.com/collective/collective.solr) and its [documentation](https://collectivesolr.readthedocs.io/en/latest/). +- [`collective.elasticsearch`](https://github.com/collective/collective.elasticsearch) +- [`collective.elastic.plone`](https://github.com/collective/collective.elastic.plone) + +You can find a comprehensive list of search options in [Awesome Plone - Searching and Categorizing](https://github.com/collective/awesome-plone?tab=readme-ov-file#searching-and-categorizing) + + +```{todo} +Help us [Migrate content from v5 "Queries, Search And Indexing" #1730](https://github.com/plone/documentation/issues/1730). +``` (backend-search-catalog-label)= @@ -21,3 +35,6 @@ myst: ## Querystring +## Related content + +- {doc}`/backend/indexing` diff --git a/docs/backend/subscribers.md b/docs/backend/subscribers.md index 04f8be0335..71d5b3c992 100644 --- a/docs/backend/subscribers.md +++ b/docs/backend/subscribers.md @@ -11,8 +11,168 @@ myst: # Subscribers (event handlers) -```{todo} -Move content from: -- https://5.docs.plone.org/external/plone.app.dexterity/docs/advanced/event-handlers.html -- https://5.docs.plone.org/develop/addons/components/events.html +A _subscriber_ is a callable object that takes one argument, an object that we call the _event_. + +_Events_ are objects that represent something happening in a system. +They are used to extend processing by providing processing plug points. + +A _notification_ alerts subscribers that an event has occurred. + +The {term}`Zope Component Architecture`'s [`zope.event`](https://zopeevent.readthedocs.io/en/latest/) package is used to manage subscribable events in Plone. + +The Plone event system has some notable characteristics: + +- It's simple. +- The calling order of subscribers is random. + You can't set the order in which event handlers are called. +- Events can't be cancelled. + All handlers will always get the event. +- Event handlers can't have return values. +- Exceptions raised in an event handler will interrupt the request processing. + + +## Register an event handler + +Plone events can be scoped: + +- globally (no scope) +- per content type +- per behavior or marker interface + + +### Register an event handler on content type creation + +The following example demonstrates how to register an event handler when a content type is created. + +In your {file}`.product/your/product/configure.zcml` insert the following code. + +{lineno-start=1} +```xml + ``` + +The second line defines to which interface you want to bind the execution of your code. +Here, the event handler code will only be executed if the object is a content type providing the interface `.interfaces.IMyContentTypeClass`. +If you want this to be interface agnostic, insert an asterix `*` as a wildcard instead. + +The third line defines the event on which this should happen, which is `IObjectCreatedEvent`. +For more available possible events to use as a trigger, see {ref}`subscribers-event-types-label`. + +The fourth line gives the path to the callable function to be executed. + +Create your {file}`.product/your/product/your_python_file.py` and insert the following code. + +```python +def your_subscriber(object, event): + # do something with your created content type +``` + + +### Subscribe to an event using ZCML + +Subscribe to a global event using {term}`ZCML` by inserting the following code in your {file}`.product/your/product/configure.zcml`. + +```xml + +``` + +For this event, the Python code in {file}`smartcard.py` would be the following. + +```python +def clear_extra_cookies_on_logout(event): + # What event contains depends on the + # triggerer of the event and event class + request = event.object.REQUEST +``` + +The following example for a custom event subscribes content types to all `IMyEvents` when fired by `IMyObject`. + +```xml + +``` + +The following example shows how to subscribe a content type to the life cycle event. + +```xml + +``` + + +## Fire an event + +Use `zope.event.notify()` to fire event objects to their subscribers. + +The following code shows how to fire an event in unit tests. + +```python +import zope.event +from plone.postpublicationhook.event import AfterPublicationEvent + +event = AfterPublicationEvent(self.portal, self.portal.REQUEST) +zope.event.notify(event) +``` + + +(subscribers-event-types-label)= + +## Event types + +Plone has the following types of events. + + +### Creation events + +`zope.lifecycleevent.IObjectCreatedEvent` is fired for all Zope-ish objects when they are created, or copied via `IObjectCopiedEvent`. +They don't have to be content objects. + +### Modified events + +`zope.lifecycleevent.IObjectModifiedEvent` is called for creation stage events as well, unlike the previous event type. + +### Delete events + +Delete events can be fired several times for the same object. +Some delete event transactions are rolled back. + +### Copy events + +`zope.lifecycleevent.IObjectCopiedEvent` is triggered when an object is copied. +It will also fire `IObjectCreatedEvent` event code. + +### Workflow events + +`Products.DCWorkflow.interfaces.IBeforeTransitionEvent` is triggered before a workflow transition is executed. + +`Products.DCWorkflow.interfaces.IAfterTransitionEvent` is triggered after a workflow transition has been executed. + +The DCWorkflow events are low-level events that can tell you a lot about the previous and current states. + +`Products.CMFCore.interfaces.IActionSucceededEvent` is a higher level event that is more commonly used to react after a workflow action has completed. + +### Zope startup events + +`zope.processlifetime.IProcessStarting` is triggered after the component registry has been loaded and Zope is starting up. + +`zope.processlifetime.IDatabaseOpened` is triggered after the main ZODB database has been opened. + +## Related content + +- {doc}`/backend/behaviors` +- {doc}`/backend/content-types/index` + diff --git a/docs/backend/traversal-acquisition.md b/docs/backend/traversal-acquisition.md index 89af1bb8e8..b686cb56f2 100644 --- a/docs/backend/traversal-acquisition.md +++ b/docs/backend/traversal-acquisition.md @@ -30,7 +30,7 @@ If not explicitly given, at the end a default view is looked up. This can be a registered page template, a callable view class, or a REST API endpoint. ```{seealso} -{ref}`Chapter Views ` +{doc}`/classic-ui/views` ``` In code, traversal can be achieved by using the `restrictedTraverse` and `unrestrictedTraverse` methods of content objects. @@ -87,3 +87,10 @@ For example, if object `A` contains object `B`, and object `A` has a property `x - About traversal: [Zope Developers Handbook, Chapter Object Publishing](https://zope.readthedocs.io/en/latest/zdgbook/ObjectPublishing.html) - About acquisition: [Zope Developers Handbook, Chapter Acquisition](https://zope.readthedocs.io/en/latest/zdgbook/Acquisition.html) ``` + +## Related content + +- {doc}`/backend/portal-actions` +- {doc}`/backend/security` +- {doc}`/classic-ui/views` + diff --git a/docs/backend/upgrading/intro.md b/docs/backend/upgrading/intro.md index 152cbb3a7b..8d2a1669a8 100644 --- a/docs/backend/upgrading/intro.md +++ b/docs/backend/upgrading/intro.md @@ -114,11 +114,9 @@ During in-place migrations, it is advisable **not to skip over** breaking (major Going from Plone 5.2 to Plone 6.0 is fine. -If you are at Plone 2.5 and want to upgrade to the latest Plone 6, you should approach this in several steps: +If you are at Plone 4 and want to upgrade to the latest Plone 6, you should approach this in several steps: -- First upgrade from Plone 2.5 to the latest Plone 3 version (3.3.6). -- Then upgrade from Plone 3 to the latest Plone 4 version (4.3.20). -- Then upgrade from Plone 4 to the latest Plone 5 version. +- First upgrade from Plone 4 to the latest Plone 5 version. - Then upgrade from Plone 5 to the latest Plone 6 version. diff --git a/docs/backend/upgrading/preparations.md b/docs/backend/upgrading/preparations.md index 85f8ecd45a..08f8693c7f 100644 --- a/docs/backend/upgrading/preparations.md +++ b/docs/backend/upgrading/preparations.md @@ -4,7 +4,7 @@ myst: "description": "Plone upgrade preparations" "property=og:description": "Plone upgrade preparations" "property=og:title": "Plone upgrade preparations" - "keywords": "Plone, upgrade, preparations" + "keywords": "Plone, upgrade, preparations, ZODB, collective.recipe.backup, buildout, backup, restore" --- @@ -12,7 +12,7 @@ myst: # Preparations -This chapter lists things to do before you migrate Plone. +This chapter describes things to do before you migrate Plone. (upgrade-gather-informationlabel)= @@ -52,22 +52,13 @@ If Plone is being upgraded at the same time as a Zope version, Plone will usuall ## Back up your Plone site -```{danger} -Always back up your Plone site before upgrading. -``` - ```{seealso} -See Plone 5.2 documentation, [Backing up your Plone deployment](https://5.docs.plone.org/manage/deploying/backup.html). +For a Plone site installed via buildout, follow {doc}`/admin-guide/backup-restore-plone-buildout` for details. ``` -```{todo} -Migrate the Plone 5.2 docs for Backing up your Plone deployment into Plone 6 docs. -``` - - (upgrade-setup-a-test-environment-to-rehearse-the-upgrade-label)= -## Setup a test environment to rehearse the upgrade +## Set up a test environment to rehearse the upgrade ```{danger} Never work directly on your live site until you know that the upgrade was successful. diff --git a/docs/backend/upgrading/version-specific-migration/images/distribution-chooser.png b/docs/backend/upgrading/version-specific-migration/images/distribution-chooser.png new file mode 100644 index 0000000000..afe6172273 Binary files /dev/null and b/docs/backend/upgrading/version-specific-migration/images/distribution-chooser.png differ diff --git a/docs/backend/upgrading/version-specific-migration/index.md b/docs/backend/upgrading/version-specific-migration/index.md index c210c3af05..c4279e294e 100644 --- a/docs/backend/upgrading/version-specific-migration/index.md +++ b/docs/backend/upgrading/version-specific-migration/index.md @@ -26,5 +26,7 @@ upgrade-to-52 upgrade-to-python3 upgrade-zodb-to-python3 upgrade-to-60 +upgrade-to-61 +upgrade-to-62 migrate-to-volto ``` diff --git a/docs/backend/upgrading/version-specific-migration/migrate-to-volto.md b/docs/backend/upgrading/version-specific-migration/migrate-to-volto.md index 9a7c5bda1f..eb8aa0896f 100644 --- a/docs/backend/upgrading/version-specific-migration/migrate-to-volto.md +++ b/docs/backend/upgrading/version-specific-migration/migrate-to-volto.md @@ -107,5 +107,5 @@ It is recommended to use the default settings, but you can choose to skip some m If you are migrating an existing site to Plone 6 using [{py:mod}`collective.exportimport`](https://pypi.org/project/collective.exportimport) and want to use Volto in the new site, then you do not need to use the form `@@migrate_to_volto`. All the changes documented above can be done efficiently during export and import. -[Read details](https://github.com/collective/collective.exportimport/issues/133). +[Read details](https://github.com/collective/collective.exportimport?tab=readme-ov-file#migrate-to-volto). ``` diff --git a/docs/backend/upgrading/version-specific-migration/p4x-to-p5x-upgrade.md b/docs/backend/upgrading/version-specific-migration/p4x-to-p5x-upgrade.md index 1b8a5a5c1f..31ae71cc84 100644 --- a/docs/backend/upgrading/version-specific-migration/p4x-to-p5x-upgrade.md +++ b/docs/backend/upgrading/version-specific-migration/p4x-to-p5x-upgrade.md @@ -26,7 +26,7 @@ To upgrade add-ons to Plone 5, see also {doc}`upgrade-addons-to-50`. - Always upgrade from the latest version of 4.x to the latest version of 5.x (4.3.20 to 5.2.9 at the time of writing). This will resolve many migration-specific issues. - If you have problems, ask for help on https://community.plone.org. -- The talk _How to upgrade sites to Plone 5_ has a [video](https://www.youtube.com/watch?t=1m17s&v=bQ-IpO-7F00&feature=youtu.be) and [slides](https://de.slideshare.net/derschmock/upgrade-to-plone-5). +- The talk _How to upgrade sites to Plone 5_ has a [video](https://www.youtube-nocookie.com/embed/bQ-IpO-7F00?privacy_mode=1&t=77) and [slides](https://www.slideshare.net/slideshow/upgrade-to-plone-5/54040952). (upgrading-plone-4.x-to-5.0-changes-due-to-implemented-plips-label)= @@ -448,7 +448,7 @@ The value you use for this CSS rule should identify one of the fontello icons in It is not possible at this time to set an icon for your add-on package control panels without including CSS in your package. -For documentation on how to use it in your own add-ons see {doc}`training:mastering-plone-5/registry`. +For documentation on how to use it in your own add-ons see {doc}`training-2023:mastering-plone-5/registry`. ### Properties diff --git a/docs/backend/upgrading/version-specific-migration/upgrade-to-51.md b/docs/backend/upgrading/version-specific-migration/upgrade-to-51.md index 8a90da856f..1570a51833 100644 --- a/docs/backend/upgrading/version-specific-migration/upgrade-to-51.md +++ b/docs/backend/upgrading/version-specific-migration/upgrade-to-51.md @@ -432,7 +432,7 @@ Your folderish content types should either use the templates from `plone.app.con ### Rejected And Postponed PLIPs -For details about rejected or postponed PLIPs see the [github PLIP project](https://github.com/plone/Products.CMFPlone/projects/1) and the [Framework Team PLIP status sheet](https://docs.google.com/spreadsheets/d/15Cut73TS5l_x8djkxNre5k8fd7haGC5OOSGigtL2drQ/edit). +For details about rejected or postponed PLIPs see the [github PLIP project](https://github.com/orgs/plone/projects/47) and the [Framework Team PLIP status sheet](https://docs.google.com/spreadsheets/d/15Cut73TS5l_x8djkxNre5k8fd7haGC5OOSGigtL2drQ/edit). ## Known Issues diff --git a/docs/backend/upgrading/version-specific-migration/upgrade-to-52.md b/docs/backend/upgrading/version-specific-migration/upgrade-to-52.md index 23fa888057..be670bb57d 100644 --- a/docs/backend/upgrading/version-specific-migration/upgrade-to-52.md +++ b/docs/backend/upgrading/version-specific-migration/upgrade-to-52.md @@ -81,7 +81,7 @@ This is [PLIP 1351](https://github.com/plone/Products.CMFPlone/issues/1351). #### For end users This has no changes for Editors. -Admins will notice that the ZMI has a new Twitter Bootstrap-based theme, and some control panels have moved. +Admins will notice that the ZMI has a new Bootstrap-based theme, and some control panels have moved. #### For developers diff --git a/docs/backend/upgrading/version-specific-migration/upgrade-to-60.md b/docs/backend/upgrading/version-specific-migration/upgrade-to-60.md index 0eeddda3a9..acbd9c6b43 100644 --- a/docs/backend/upgrading/version-specific-migration/upgrade-to-60.md +++ b/docs/backend/upgrading/version-specific-migration/upgrade-to-60.md @@ -128,9 +128,9 @@ zodb-temporary-storage = off (v60-templates-bootstrap-5-label)= -## Changed templates to Twitter Bootstrap 5 markup +## Changed templates to Bootstrap 5 markup -All templates in core Plone have been updated to use Twitter Bootstrap 5 markup. +All templates in core Plone have been updated to use Bootstrap 5 markup. Add-on authors are encouraged to do the same. If you have customized a core template, you should check if your change is still needed, and update it to fit the new markup. Any CSS and JavaScript that relies on a specific structure, or certain IDs or classes, should be checked as well. @@ -168,7 +168,7 @@ The standard theme in Classic UI was updated to Bootstrap 5, CSS variables, and If you have a theme that builds on Barceloneta, you most likely need various changes. It may be best to start with a fresh theme, and try to keep the changes minimal. -The training documentation lists {doc}`three possible theming strategies `: +The training documentation lists {doc}`three possible theming strategies `: - Create a theme based on Barceloneta. - Create a theme from scratch. @@ -212,7 +212,7 @@ Add-on authors may want to use this to get, create, or delete relations. Mockup contains the source of most Classic UI Plone JavaScript. The compiled version is in `plone.staticresources`. -Mockup is now based on [Patternslib 4](https://patternslib.com/). +Mockup is now based on [Patternslib 9](https://patternslib.com/). It uses ES6 module imports instead of RequireJS. Add-ons for Classic UI Plone that use JavaScript should be updated to use ES6 modules as well. @@ -223,6 +223,7 @@ Add-ons for Classic UI Plone only need to register bundles, not individual resou [PLIP 3211](https://github.com/plone/Products.CMFPlone/issues/3211) ``` +The cookie key for the folder contents page size has changed from `_fc_perPage` to `_fc_pageSize` due to an upgrade of the underlying `backbone.paginator` library. (v60-relations-control-panel-label)= @@ -600,5 +601,59 @@ The following example {file}`registry.xml` may be used for configuring TinyMCE w Please make sure you write valid JSON for the `template` option. ```{seealso} -See also the [TinyMCE 4 to 5 upgrade guide](https://www.tiny.cloud/docs/migration-from-4x/). -``` +See also [Migrating from TinyMCE 4 to TinyMCE 5](https://www.tiny.cloud/docs/tinymce/5/migration-from-4x/). +``` + +## Viewlets + +Plone 6.0 renames various viewlets or moves them to a different viewlet manager. +This is because some viewlet names contained the name of a viewlet manager. +This didn't always match the name of their actual viewlet manager, especially after moving them. +Plone 6.0 removes such references from the viewlet names to avoid confusion. + +- Plone 6.0 removes the `plone.header` viewlet from `plone.portaltop` manager, making it empty. +- Plone 6.0 renames the `plone.abovecontenttitle.documentactions` viewlet to `plone.documentactions`, and moves it from manager `plone.belowcontentbody` to `plone.belowcontent`. +- Plone 6.0 renames the `plone.abovecontenttitle.socialtags` viewlet to `plone.socialtags`. + It remains in manager `plone.abovecontenttitle`. +- Plone 6.0 renames the `plone.belowcontentbody.relateditems` viewlet to `plone.relateditems`. + It remains in manager `plone.belowcontentbody`. +- Plone 6.0 removes the `plone.manage_portlets_fallback` viewlet from the `plone.belowcontent` manager. +- Plone 6.0 renames the `plone.belowcontenttitle.documentbyline` viewlet to `plone.documentbyline`. + It remains in manager `plone.belowcontenttitle`. +- Plone 6.0 renames the `plone.belowcontenttitle.keywords` viewlet to `plone.keywords`, and moves it from manager `plone.belowcontent` to `plone.belowcontentbody`. +- Plone 6.0 adds the `plone.rights` viewlet in manager `plone.belowcontentbody`. + +The names in the following table have had the namespace `plone.` removed from them for display purposes only. +In your code, you should use the object's `plone.` namespace as a prefix. +This table shows the same information, but in tabular form. + +```{table} Viewlet changes from 5.2 to 6.0 + +| 5.2 viewlet name | 5.2 viewlet manager | 6.0 viewlet name | 6.0 viewlet manager | +| ---------------- | ------------------- | ---------------- | ------------------- | +| `header` | `portaltop` | | `portaltop` | +| `abovecontenttitle.documentactions` | `belowcontentbody` | `documentactions` | `belowcontent` | +| `abovecontenttitle.socialtags` | `abovecontenttitle` | `socialtags` | `abovecontenttitle` | +| `belowcontentbody.relateditems` | `belowcontentbody` | `relateditems` | `belowcontentbody` | +| `manage_portlets_fallback` | `belowcontent` | | `belowcontent` | +| `belowcontenttitle.documentbyline` | `belowcontenttitle` | `documentbyline` | `belowcontenttitle` | +| `belowcontenttitle.keywords` | `belowcontent` | `keywords` | `belowcontentbody` | +| | `belowcontentbody` | `rights` | `belowcontentbody` | +``` + +Plone 6.0 makes changes to two viewlet managers: + +- Plone 6.0 removes the `plone.documentactions` (`IDocumentActions`) viewlet manager. + In Plone 5.2 it was already empty. +- Plone 6.0 adds the `plone.belowcontentdescription` (`IBelowContentDescription`) viewlet manager. + By default this has no viewlets. + +One final change is that Plone 6.0 moves the `plone.footer` viewlet from `plone.app.layout/viewlets` to `plone.app.portlets`. +The viewlet remains in manager `plone.portalfooter`. +It renders the portlets from the `plone.footerportlets` portlet manager. + +## Boolean fields + +Since `zope.schema==6.1.0`, all `zope.schema.Bool` fields must have a `required=False` attribute. +This allows you to either tick or not tick the checkbox, submit the form, and process the field with either its value when ticked or `None` when unticked. +Otherwise, you can't save the form without ticking the checkbox, which effectively makes the field value always `True`. diff --git a/docs/backend/upgrading/version-specific-migration/upgrade-to-61.md b/docs/backend/upgrading/version-specific-migration/upgrade-to-61.md new file mode 100644 index 0000000000..8a9012c610 --- /dev/null +++ b/docs/backend/upgrading/version-specific-migration/upgrade-to-61.md @@ -0,0 +1,207 @@ +--- +myst: + html_meta: + "description": "How to upgrade to Plone 6.1" + "property=og:description": "How to upgrade to Plone 6.1" + "property=og:title": "How to upgrade to Plone 6.1" + "keywords": "Upgrade, Plone 6" +--- + +(backend-upgrade-plone-v61-label)= + +# Upgrade Plone 6.0 to 6.1 + +Plone 6.1 has seen the following major changes. +Some may require changes in your setup. + + +## Drop Python 3.8 and 3.9 + +We only support Python {{SUPPORTED_PYTHON_VERSIONS_PLONE61}}. + + +## TinyMCE upgraded in Classic UI + +In Plone 6.0, the Classic UI frontend uses TinyMCE 5, a rich text editor for websites. +TinyMCE 5 reached its end of support on April 20, 2023. +For Plone 6.1, Classic UI upgraded TinyMCE from version 5 to 7. + +If you upgrade a site using Classic UI from Plone 6.0 to 6.1, you do not need to take any action, unless you implemented custom plugins, or you use a plugin which got removed or moved to premium in TinyMCE versions 6 or 7. +To upgrade your plugin implementation to TinyMCE 7, see the [upgrade guides](https://www.tiny.cloud/docs/tinymce/6/migration-from-5x/#plugins). + + +### Enable the TinyMCE accordion plugin + +1. Install the add-on [`collective.outputfilters.tinymceaccordion`](https://pypi.org/project/collective.outputfilters.tinymceaccordion/) to use an output filter that transforms the TinyMCE markup to valid HTML markup for the Bootstrap 5 accordion. + Install via either pip or buildout. + + - Install using pip. + + ```shell + pip install collective.outputfilters.tinymceaccordion + ``` + + - Configure your local buildout file. + + ```cfg + [instance] + eggs += collective.outputfilters.tinymceaccordion + ``` + + Then run the command to install. + + ```shell + bin/buildout + ``` + +1. Start your Plone instance. + + ```shell + bin/instance fg + ``` + +1. Complete installation of the add-on by navigating to {menuselection}`Site Setup --> General --> Add-ons`, then clicking {guilabel}`Install` for `collective.outputfilters.tinymceaccordion`. + +1. Go to the {menuselection}`Site Setup --> General --> TinyMCE` control panel to manage TinyMCE settings. + +1. Under the {menuselection}`Plugins and Toolbar` tab, if not already checked, check {guilabel}`accordion` to enable the accordion plugin. + +1. Under the same tab, edit the `insert` menu by editing its `items` key as shown. + + ```json + { + "insert": { + "title": "Insert", + "items": "link media | template hr | accordion" + }, + } + ``` + +1. Click the {guilabel}`Save` button to save your settings. + +1. In the {menuselection}`Security --> HTML filtering` control panel, ensure that you have the following tags under {guilabel}`Valid tags`. + + - `button` + - `details` + - `summary` + +1. Also in the {menuselection}`Security --> HTML filtering` control panel, add a new attribute to {guilabel}`Custom attributes`, if not already present. + + - `open` + + +## `z3c.form` and `plone.app.z3cform` + +[`plone.app.z3cform`](https://github.com/plone/plone.app.z3cform) is the form widget integration package for [`z3c.form`](https://github.com/zopefoundation/z3c.form) in Plone. +This adds [Bootstrap 5](https://getbootstrap.com/) styling and mockup pattern options to all widgets. + +In Plone 6.1 all Classic UI widget classes were moved to the module `plone.app.z3cform.widgets`. +The previous paths are marked as deprecated and will be removed in Plone 7. + +The `BaseWidget` for patterns is refactored to the new `z3c.form` extendable attributes introduced in version 5.1 and doesn't use LXML anymore. +See https://github.com/zopefoundation/z3c.form/pull/116. +If you have customizations in your base pattern widget class, see the new implementation at https://github.com/plone/plone.app.z3cform/blob/e9d1ebf478e663d2da259cb9435927f7ad1ddb92/plone/app/z3cform/widgets/base.py. + +`RelatedItemsWidget` is marked as deprecated. +The implementation for selecting related items, internal links and images in TinyMCE, or internal paths for collection criteria is now done with the new `ContentBrowserWidget`. +This introduces a new pattern `pat-contentbrowser` from mockup. +See the next section for details. + + +## `mockup` new pattern `pat-contentbrowser` + +A new content browsing pattern [`pat-contentbrowser`](https://plone.github.io/mockup/pat/contenbrowser/) for Classic UI is now available. + +This is a [Miller column browser](https://en.wikipedia.org/wiki/Miller_columns) implementation which replaces [`pat-relateditems`](https://plone.github.io/mockup/pat/relateditems/) seamlessly. +All basic options from `pat-relateditems` are implemented and behave the same as before. + +Additionally `pat-contentbrowser` comes with some new features. + +- Keyboard navigation. +- Multi-selection of items with {kbd}`Shift/Ctrl/CMD + click` combination. + This comes in handy for selecting multiple related items in one step. +- Uploading items to the current path. + + +## `plone.app.multilingual` is a core add-on + +`plone.app.multilingual` is the package that adds multilingual support to Plone, allowing the storage and display of content in multiple languages. +In Plone 6.0 and earlier, this was a dependency of `Products.CMFPlone`, making it available for installation in all Plone sites. +In Plone 6.1 it is now a dependency of the `Plone` package. + +If your project or your add-on needs this package, and you only depend on `Products.CMFPlone` until now, you should add `plone.app.multilingual` as a dependency. +Then your project or add-on will keep working in both Plone 6.0 and 6.1. + +The goal of turning more of the current core packages into core add-ons is to make the core smaller, and in some cases solve circular dependencies. + + +(backend-upgrade-plone-v61-discussion-label)= + + +## Discussion is a core add-on + +Discussion is a feature that allows your site visitors to comment on web pages for any content object. +The code behind this is in the `plone.app.discussion` package. +In Plone 6.0 and earlier, this was a dependency of `Products.CMFPlone`, making it available for installation in all Plone sites. +In Plone 6.1 it's a dependency of the `Plone` package. + +Discussion is disabled by default in Plone 6.1 and later. +To enable discussion, you need to perform the following tasks. + +1. In your Python {file}`requirements.txt` or {file}`pyproject.toml` file, add the core add-on `plone.app.discussion` to your dependencies. +1. Run pip to install `plone.app.discussion`. +1. Restart the Plone backend to load `plone.app.discussion`. +1. Enable the {guilabel}`Discussion Support` add-on in the {guilabel}`Add-ons` control panel under {menuselection}`Site Setup --> General`. +1. If you use Plone Classic UI, you can then use the {guilabel}`Discussion` control panel to further configure this feature, for example, to enable comment moderation. +1. 🍻 + +If you have an existing Plone 5.2 or 6.0 site and you migrate to 6.1, then migration code handles the change as follows. + +- If the `plone.app.discussion` Python package is in your setup, the migration does nothing. + Existing discussion configuration and comments remain unchanged. +- If the `plone.app.discussion` Python package is _not_ in your setup, and the site has no existing comments (discussions), then the migration code removes the Discussion configuration from your site. + Apparently you were _not_ using comments in your site, so the configuration is no longer needed. +- If the `plone.app.discussion` Python package is _not_ in your setup, but the site has existing comments (discussions), then the migration code stops with an error. + Apparently you _were_ using comments in your site. + Add the `plone.app.discussion` package to your dependencies, and run the migration again. + + +## Distributions + +Plone 6.1 introduces the concept of a Plone {term}`distribution`. +A Plone distribution is a Python package that defines specific features, themes, add-ons, and configurations that get activated when creating a Plone site. +Now it is available in core Plone as the recommended way for {doc}`creating a new Plone site `. + +```{seealso} +For more information about distribution concepts, see {doc}`/conceptual-guides/distributions`. +``` + +Distributions are optional. +If your project only uses the `Products.CMFPlone` Python package, you can still create a Plone site in the old way. +Consider, however, that doing so you will have the following differences when compared to using distributions. + +- The configuration form is simpler and shorter. +- The created site has no content, and therefore no {guilabel}`News` or {guilabel}`Events` folders. +- You must activate add-ons through the {guilabel}`Add-ons` control panel. + +There are a few things you should consider when upgrading a project to, or making an add-on compatible with, Plone 6.1. + +- In general, you don't need to change anything. + Your existing site will keep working. + But adding a new site may change in the ways described earlier. +- Do you want to use the `Products.CMFPlone` package (no distributions), either `plone.volto` or `plone.classicui` (one distribution), or `Plone` (two distributions)? +- If your site uses Volto for the frontend, you will already have `plone.volto` as a dependency. + This can stay the same. +- If your site depends on the `Products.CMFPlone` package without the `Plone` or `plone.volto` packages, then the frontend is Classic UI. + This can stay the same, but you may want to depend on `plone.classicui`. + With that package you can still create a new site and have the same content as before. +- If your site uses the `Plone` package, you will have the two new distributions available. + This is fine. + If you know you only need `plone.volto` or only need `plone.classicui`, you can switch to only one or the other. + You can also limit the options for selecting a distribution by setting the environment variable `ALLOWED_DISTRIBUTIONS` with fewer options. + Set `ALLOWED_DISTRIBUTIONS=default` for the distribution targeting the Volto frontend (`plone.volto`). + Set `ALLOWED_DISTRIBUTIONS=classic` for the distribution with the Classic UI frontend (`plone.classicui`). +- If you switch from `Plone` to `plone.volto` or `plone.classicui`, you might want to install extra core add-ons, for example `plone.app.upgrade` or `plone.app.caching`. +- If your add-on is only for Volto, you might want to add `plone.volto` as a dependency. +- If your add-on is only for Classic UI, you might want to add `plone.classicui` as a dependency. + Note though that `plone.classicui` is not available for Plone 6.0. diff --git a/docs/backend/upgrading/version-specific-migration/upgrade-to-62.md b/docs/backend/upgrading/version-specific-migration/upgrade-to-62.md new file mode 100644 index 0000000000..e833139f9b --- /dev/null +++ b/docs/backend/upgrading/version-specific-migration/upgrade-to-62.md @@ -0,0 +1,101 @@ +--- +myst: + html_meta: + "description": "How to upgrade to Plone 6.2" + "property=og:description": "How to upgrade to Plone 6.2" + "property=og:title": "How to upgrade to Plone 6.2" + "keywords": "Upgrade, Plone 6" +--- + +(backend-upgrade-plone-v62-label)= + +# Upgrade Plone 6.1 to 6.2 + +Plone 6.2 has seen the following major changes. +Some may require changes in your setup. + + +## Move to native namespaces + +Plone 6.2 has migrated all core Python packages from `pkg_resources`-style namespaces to native namespaces. + +The Plone Python backend consists of over 200 packages. +Most of these are namespace packages. +Examples are `plone.batching` and `plone.api`, which share the `plone` namespace. + +There are three styles or techniques of namespaces. +For Plone only two are important: `pkg_resources` and native. +The third style is `pkgutil`, but Plone has never used it. + +Native namespaces are also referred to as implicit namespaces. +The two terms mean the same. + +```{seealso} +- [Python Packaging Guide on native namespaces](https://packaging.python.org/en/latest/guides/packaging-namespace-packages/#native-namespace-packages) +- [PEP 420 - Implicit Namespace Packages](https://peps.python.org/pep-0420/) +``` + +Native namespaces exist since Python 3.3. +Because Plone started in the days of Python 2, it has always used `pkg_resources`. +`pkg_resources` is part of the `setuptools` package. +This part is deprecated. +It's scheduled to be removed around the end of 2025, in `setuptools` 81. +This means Plone needs to move to native namespaces. + +In general, this move shouldn't cause problems for integrators. +To install Plone 6.2 you can keep using the same version of `pip` (or `uv`), or `zc.buildout` as you do for Plone 6.1. +This assumes that all packages within one namespace use the same namespace style or technique. + +You may encounter problems when this assumption isn't true. +As an example, say your Plone project uses a package `collective.example`, and this still uses `pkg_resources`-style namespaces. +Plone itself depends on a package `collective.monkeypatcher` which is now using native namespaces. +This may cause problems at startup, especially `ModuleNotFoundError`. +In a normal install: + +* `pip` works fine. +* `zc.buildout` 4 won't work. +* `zc.buildout` 5 works fine. + +If for one or both of these packages you don't use a final release from https://pypi.org, but an editable install, it may not work. +You can solve this by installing an extra package with `pip`, `horse-with-no-namespace`. + +```{note} +If you let `zc.buildout` install `horse-with-no-namespace`, it won't work. +It really must be installed by `pip` into the same virtual environment where you have installed `zc.buildout`. +``` + +The recommendation is to migrate all namespace packages to native namespaces. +This includes the `collective` namespace that a lot of Plone add-ons use. +This {doc}`guide ` describes the needed steps. + +## Start separating Classic UI code from the core + +In Plone 6, the Python backend includes the Classic UI frontend. +You can't get one without the other. +If you use the Volto frontend, this means that you get lots of code that you never use. + +Plone 6.2 starts separating Classic UI code from the core of Plone. +This is ongoing work, described in {term}`PLIP` [3953](https://github.com/plone/Products.CMFPlone/issues/3953). +You won't yet get less code yet. +This PLIP is preparation for a more complete separation in Plone 7. + +The focus currently is on moving page templates into the `plone.app.layout` package. +Templates from the following packages are now in a new location: + +* `plone.locking` +* `plone.protect` + +```{note} +If you use the `z3c.jbot` add-on to override a template that has been moved, your override will still work. +This is because we keep a mapping from the old to the new location. +For example, `plone.locking` registers that `plone.locking.browser.info.pt` has a new location, `plone.app.layout.viewlets.locking.pt`. +You should rename your override to the new location if you no longer need compatibility with Plone 6.1 or earlier. +``` + +## TinyMCE 8 for Classic UI + +The {term}`WYSIWYG` editor for Classic UI, {term}`TinyMCE`, was updated to version 8. + +You're now able to enter your commercial license key in the {menuselection}`TinyMCE` control panel. + +See {doc}`/classic-ui/tinymce-customization` for setup instructions. diff --git a/docs/backend/upgrading/version-specific-migration/upgrade-to-python3.md b/docs/backend/upgrading/version-specific-migration/upgrade-to-python3.md index d5554a1911..fc5e86f68a 100644 --- a/docs/backend/upgrading/version-specific-migration/upgrade-to-python3.md +++ b/docs/backend/upgrading/version-specific-migration/upgrade-to-python3.md @@ -14,9 +14,6 @@ myst: This chapter provides instructions and tips for porting Plone projects to Python 3. -```{seealso} -If you want to upgrade add-ons to Python 3, the list of all Plone packages that still need to be ported can be found on the GitHub project board [Python 3 porting state for Plone add-ons](https://github.com/orgs/collective/projects/1). -``` ## Principles @@ -385,6 +382,6 @@ Here is a list of helpful references on the topic of porting Python 2 to Python - https://eev.ee/blog/2016/07/31/python-faq-how-do-i-port-to-python-3/ - https://diveintopython3.net/ - https://docs.djangoproject.com/en/1.11/topics/python3/ -- https://docs.ansible.com/ansible/latest/dev_guide/developing_python_3.html +- https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_python_3.html - https://docs.python.org/2/library/doctest.html#debugging ``` diff --git a/docs/backend/vocabularies.md b/docs/backend/vocabularies.md index e4bc50cc22..780644ad64 100644 --- a/docs/backend/vocabularies.md +++ b/docs/backend/vocabularies.md @@ -18,4 +18,10 @@ See the chapter {ref}`training:vocabularies-label` from the Mastering Plone 6 Tr ```{todo} Contribute to this documentation! See issue [Backend > Vocabularies needs content](https://github.com/plone/documentation/issues/1306). -``` \ No newline at end of file +``` + +## Related content + +- {doc}`/backend/fields` +- {doc}`/backend/schemas` +- {doc}`/backend/content-types/index` \ No newline at end of file diff --git a/docs/backend/widgets.md b/docs/backend/widgets.md index 23e5d55dc9..5b6cf16f77 100644 --- a/docs/backend/widgets.md +++ b/docs/backend/widgets.md @@ -63,7 +63,75 @@ The main widgets are: - DateTime Picker -## Changing a field's widget +(backend-widgets-change-a-fields-display-label)= + +## Change a field's display mode + +A field's widget can be displayed in several modes. + +`input` +: Allows the user to enter data into the field + +`display` +: A read-only indication of the field's value + +`hidden` +: A record of the field's value that is included only in the HTML source + + +### `plone.autoform` `mode` directive + +In the following example, the mode for the `secret` field is set to `hidden` for most forms, but `input` for forms that provide the `IEditForm` interface. + +```{code-block} python +:emphasize-lines: 6,7 +:linenos: + +from plone.supermodel import model +from plone.autoform import directives as form + +class IMySchema(model.Schema): + + form.mode(secret="hidden") + form.mode(IEditForm, secret="input") + secret = schema.TextLine( + title="Secret", + default="Secret stuff (except on edit forms)" + ) +``` + +The corresponding supermodel XML directive is `form:mode`: + +```{code-block} xml +:emphasize-lines: 3 + + + Secret + Secret stuff (except on edit forms) + +``` + +The mode can be specified briefly, if it should be the same for all forms: + +```{code-block} xml +:emphasize-lines: 3 + + + Secret + Secret stuff + +``` + +In other words, `form:mode` may be either a single mode, or a space-separated list of `:` pairs. + + +(backend-widgets-change-a-fields-widget-label)= + +## Change a field's widget You can change the widget that you use for a field in several ways. This section describes these methods. @@ -404,6 +472,56 @@ self.widgets["ds_pregu_pers"].disabled = "disabled" ``` +### Customize existing widgets `pattern_options` + +There is a special attribute called `pattern_options` which is primarily used in Classic UI for pattern configuration. + +If you define your own schema, you can set this attribute with autoform directives. +See {ref}`relations-configure-the-relateditemsfieldwidget-label` for an example. + +To customize or extend `pattern_options` for existing schema widgets, you can create a `z3c.form.interface.IValue` multiadapter as shown. + +```{code-block} python +from z3c.form.interfaces import IForm +from z3c.form.interfaces import IValue +from z3c.form.interfaces import IWidget +from zope.component impport adapter +from zope.interface import implementer +from zope.interface import Interface +from zope.publisher.interfaces import IRequest +from zope.schema.interfaces import IField + +@implementer(IValue) +@adapter(Interface, IRequest, IForm, IField, IWidget) +class CustomPatternOptions: + + def __init__(self, context, request, form, field, widget): + self.context = context + self.request = request + self.form = form + self.field = field + self.widget = widget + + def get(self): + # return a dictionary with your custom options + return { + "myoption": "value", + } +``` + +This defines an adapter for every field widget in every form. + +You can define the adapter more explicitly by providing different interfaces. +See an example in {ref}`classic-ui-recipes-customize-pattern-options`. + +Now register the `pattern_options` named adapter with ZCML as shown. + +```xml + +``` + + ## Set widget templates You might want to customize the template of a widget with custom HTML code. @@ -470,8 +588,8 @@ class AddForm(DefaultAddForm): # Call parent to set-up initial widget data super().updateWidgets(self, prefix=prefix) - # Note we need to be discreet to different form modes (view, edit, hidden) - if self.fields["sections"].mode == INPUT_MODE: + # Please note that the different form modes (show, edit, hide) have to be taken into account. + if self.widgets["sections"].mode == INPUT_MODE: # Modify a widget with certain name for our purposes widget = self.widgets["sections"] @@ -506,7 +624,7 @@ You can set the template used by the widget with the `` ZCML ### Widget frame override You can override widget templates as instructed for `z3c.form`. -`plone.app.z3cform` renders [a frame around each widget](https://github.com/plone/plone.app.z3cform/blob/master/plone/app/z3cform/templates/widget.pt), which usually consists of: +`plone.app.z3cform` renders [a frame around each widget](https://github.com/plone/plone.app.z3cform/blob/master/src/plone/app/z3cform/templates/widget.pt), which usually consists of: - Label - Required marker @@ -515,7 +633,7 @@ You can override widget templates as instructed for `z3c.form`. You might want to customize this widget frame for your own form. Below is an example of how to do it. -Copy [`widget.pt`](https://github.com/plone/plone.app.z3cform/blob/master/plone/app/z3cform/templates/widget.pt) to your own package, rename it as `demo-widget.pt`, and edit it. +Copy [`widget.pt`](https://github.com/plone/plone.app.z3cform/blob/master/src/plone/app/z3cform/templates/widget.pt) to your own package, rename it as `demo-widget.pt`, and edit it. Then add the following code to `configure.zcml`. Remember to fix the path of the template according to your own paths. @@ -665,3 +783,10 @@ The code renders both widgets, {guilabel}`min` and {guilabel}`max`, in a single
    ``` + +## Related content + +- {doc}`/backend/fields` +- {doc}`/backend/schemas` +- {doc}`/classic-ui/forms` +- {doc}`/backend/content-types/index` diff --git a/docs/backend/workflows.md b/docs/backend/workflows.md index 3faeeefa03..68ae6ffa4d 100644 --- a/docs/backend/workflows.md +++ b/docs/backend/workflows.md @@ -12,7 +12,7 @@ myst: # Workflows ```{seealso} -See the training {ref}`training:workflow-label`. +See the training {ref}`training-2024:workflow-label`. ``` ```{todo} diff --git a/docs/backend/zodb.md b/docs/backend/zodb.md index 37d5164110..527ee61250 100644 --- a/docs/backend/zodb.md +++ b/docs/backend/zodb.md @@ -1,13 +1,76 @@ --- myst: html_meta: - "description": "" - "property=og:description": "" - "property=og:title": "" - "keywords": "" + "description": "Zope Object Database (ZODB)" + "property=og:description": "Zope Object Database (ZODB)" + "property=og:title": "Zope Object Database (ZODB)" + "keywords": "Plone, ZODB, Zope Object Database, RelStorage, ZEO, ZODB Enterprise Objects" --- +% TODO: Diátaxis conceptual guide + (backend-zodb-label)= -# ZODB +# Zope Object Database (ZODB) + +The {term}`Zope Object Database` (ZODB) is a Python native, object-oriented database designed for direct persistence of Python objects. +Unlike traditional relational databases that rely on tables and SQL queries, ZODB allows developers to work directly with Python objects, persisting them without the need for object-relational mapping (ORM). + + +## Core features of ZODB + +Transparent persistence +: Objects stored in ZODB automatically persist. + In a Plone request/response cycle, they do not require an explicit save or commit operation, since this is done automatically. + +No schema constraints +: Unlike relational databases, ZODB does not require predefined schemas, allowing for flexible and dynamic data structures. + The attributes of the Python objects themselves are stored. + +ACID compliance +: ZODB ensures data consistency through transactions that support atomicity, consistency, isolation, and durability (ACID). + +Automatic conflict resolution +: With its multi-version concurrency control (MVCC), ZODB can handle concurrent access efficiently. + +Built-in versioning and undo +: The database allows versioning, enabling rollback to previous states if needed. + +Scalability +: ZODB can be used in standalone applications or scaled with {term}`ZODB Enterprise Objects` (ZEO) for distributed storage. + Additionally, ZODB supports the {term}`RelStorage` adapter, which allows it to use relational databases, including PostgreSQL, MySQL, or Oracle, as a backend, providing flexibility for integration with existing database infrastructures. + + +## How ZODB works + +At its core, ZODB operates as an object store, maintaining serialized Python objects with some metadata in a hierarchical structure. + +Storage +: Handles how objects are stored on disk or in-memory. + + The default storage is {term}`FileStorage`, which writes data to `.fs` files. `FileStorage` does not scale, as only one process can work with it. + + {term}`ZEO` storage is used for distributed multi-client access to the same database, introducing scalability. + + {term}`RelStorage` is another highly scalable option. + It allows ZODB to use relational databases like PostgreSQL, MySQL, or Oracle as backend storage, combining object persistence with traditional database infrastructure. + RelStorage is used often in a containerized deployment environment. + +Connection +: Acts as the interface between Python applications and the database. + With ZEO for each active Zope thread, one connection is established. + Connections are pooled and re-used. + +Transaction manager +: Manages transactional operations, ensuring data integrity. + A transaction normally starts with the request, and ends with the response. + However, in long-running requests with lots of database writes, transactions can be committed in between. + +Indexing and caching +: Optimizes read and write operations for better performance. + Tuning the ZODB cache sizes to hardware environment and the kind of data stored may help to speed up the application. + + +## Further reading +More information can be found at the official [ZODB website](https://zodb.org/en/latest/). diff --git a/docs/classic-ui/forms.md b/docs/classic-ui/forms.md index 7ea2fc947c..23ee3fac4b 100644 --- a/docs/classic-ui/forms.md +++ b/docs/classic-ui/forms.md @@ -120,6 +120,53 @@ schema = IMyForm If your form is not bound to an object (such as a Dexterity object), set `ignoreContext = True`. +(classic-ui-controlling-form-presentation-label)= + +## Controlling form presentation + +Directives can be specified in the schema to control aspects of form presentation. + +### Control field and widget presentation + +See the corresponding chapters to learn how to control field and widget presentation in a form. + +```{seealso} +- {ref}`backend-fields-schema-autoform-permission` +- {ref}`backend-schemas-directives-label` +- {ref}`backend-widgets-change-a-fields-display-label` +- {ref}`backend-widgets-change-a-fields-widget-label` +``` + + +### Display Forms + +Sometimes rather than rendering a form for data entry, you want to display stored values based on the same schema. +This can be done using a "display form". +The display form renders each field's widget in "display mode", which means that it shows the field value in read-only form rather than as a form input. + +To use the display form, create a view that extends `WidgetsView` like this: + +```python +from plone.autoform.view import WidgetsView + +class MyView(WidgetsView): + schema = IMySchema + additionalSchemata = (ISchemaOne, ISchemaTwo,) +``` + +To render the form, do not override `__call__()`. +Instead, either implement the `render()` method, set an `index` attribute to a page template or other callable, or use the `template` attribute of the `` ZCML directive when registering the view. + +In the template, you can use the following variables: + +- `view/w` is a dictionary of all widgets, including those from non-default fieldsets. + By contrast, the `widgets` variable contains only those widgets in the default fieldset. + The keys are the field names, and the values are widget instances. + To render a widget (in display mode), you can do `tal:replace="structure view/w/myfield/render" />`. +- `view/fieldsets` is a dictionary of all fieldsets not including the default fieldset, in other words, those widgets not placed into a fieldset. + The keys are the fieldset names, and the values are the fieldset form instances, which in turn have variables, such as `widgets`, given a list of all widgets. + + (classic-ui-forms-dexterity-add-edit-forms-label)= ## Dexterity add and edit forms @@ -127,7 +174,7 @@ If your form is not bound to an object (such as a Dexterity object), set `ignore Dexterity content types come with default add and edit forms. You can build custom add and edit forms to adjust their behavior. -The implementation of the default edit and add forms is in [`plone.dexterity.browser.edit.py`](https://github.com/plone/plone.dexterity/blob/master/plone/dexterity/browser/edit.py) and [`plone.dexterity.browser.add.py`](https://github.com/plone/plone.dexterity/blob/master/plone/dexterity/browser/add.py). +The implementation of the default edit and add forms is in [`plone.dexterity.browser.edit.py`](https://github.com/plone/plone.dexterity/blob/master/src/plone/dexterity/browser/edit.py) and [`plone.dexterity.browser.add.py`](https://github.com/plone/plone.dexterity/blob/master/src/plone/dexterity/browser/add.py). ```{todo} Describe Add/Edit forms here and how to customize them. @@ -226,3 +273,9 @@ In your `configure.zcml`: ``` + +## Related content + +- {doc}`/backend/fields` +- {doc}`/backend/schemas` +- {doc}`/backend/widgets` diff --git a/docs/classic-ui/icons.md b/docs/classic-ui/icons.md index 3a5963e9e2..269b455cff 100644 --- a/docs/classic-ui/icons.md +++ b/docs/classic-ui/icons.md @@ -23,7 +23,7 @@ Examples include the following. ## Bootstrap Icons -Twitter Bootstrap 5 is the default CSS framework in Plone 6. +Bootstrap 5 is the default CSS framework in Plone 6. Plone uses its icons. Check out all the available Bootstrap icons at [icons.getbootstrap.com](https://icons.getbootstrap.com/). @@ -67,13 +67,14 @@ To use a different icon than the system default, you can override the registrati ## Icon expression -```{todo} -How does this work? We need an example here! -``` - -- The field `icon_expression` is used again to define icons for actions, content types, and other purposes. +- The field `icon_expr` is used again to define icons for actions, content types, and other purposes. - Use the icon name for icon expressions. +Example: + +```xml +string:list-check +``` (classic-ui-icons-icon-resolver-label)= diff --git a/docs/classic-ui/images.md b/docs/classic-ui/images.md index fe41c130cd..9d131755a9 100644 --- a/docs/classic-ui/images.md +++ b/docs/classic-ui/images.md @@ -114,7 +114,7 @@ tag = scale_util.tag( scale=None, height=None, width=None, - direction="thumbnail" + mode="scale" ) ``` @@ -233,20 +233,130 @@ image_scale = scaling_util.publishTraverse(context.REQUEST, groups[1]) ``` -(classic-ui-images-scaling-direction-label)= +(classic-ui-images-scaling-mode-label)= -## Scaling `direction` +## Scaling `mode` -The default direction is `thumbnail`. +```{versionchanged} 6.0 +Added `mode` to replace the deprecated `direction`. +Added new option names for `mode` to align with CSS `background-size` values, and deprecated previous names `keep`, `thumbnail`, `scale-crop-to-fit`, `down`, `scale-crop-to-fill`, and `up`. +``` + +Scaling is intended for the optimal display of images in a web browser. + +To scale an image, you can use the `mode` parameter to control the scaling output. +You must use either `width` or `height`, or both. + +Three different scaling options are supported. +They correspond to the CSS [`background-size`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/background-size) values. + +The possible options for `mode` are listed below, where the default option is `scale`. + +`scale` +: This is the default option. + `scale` scales to the requested dimensions without cropping. + The resulting image may have a different size than requested. + This option requires both `width` and `height` to be specified. + It does not scale up. + + Deprecated option names: `keep`, `thumbnail`. + +`contain` +: `contain` starts by scaling the image either to the smaller dimension when you give both `width` and `height`, or to the only given dimension, then crops to the other dimension if needed. + + Deprecated option names: `scale-crop-to-fit`, `down`. + +`cover` +: `cover` scales the image either to the larger dimension when you give both `width` and `height`, or to the only given dimension, up to the size you specify. + Despite the deprecated option name, it does not crop. + + Deprecated option names: `scale-crop-to-fill`, `up`. + +### Images test rendering -Other options are: +Plone's Classic UI includes special demonstration views that render ready-made examples of image handling and responsive image components using your site's active theme. +These views help developers verify image scaling, `srcset` generation, and explore available image optimization patterns. +These views work on image content types, including images and documents with images. -* `down` -* `keep` -* `scale-crop-to-fill` -* `scale-crop-to-fit` -* `thumbnail` -* `up` +Append the view name `/@@images-test` to an image URL, optionally followed by an anchor, such as `#srcset`, for specific sections. +You must be authenticated as a site admin to view this demo. + +For example, on the Classic UI demo site, the URL would be https://classic.demo.plone.org/en/demo/an-image.jpg/@@images-test#srcset. + +````{card} +```{image} /_static/images-test/images-test.png +:alt: Images test view +:target: /_static/images-test/images-test.png +``` ++++ +_Images test view_ +```` + +The view displays the following examples, all rendered with the current settings in `/@@imaging-controlpanel`. + +Standard image scales +: Shows the Classic UI Plone scales with different modes: + - Mini + - Mini mode=cover + - Mini mode=contain + + ````{card} + ```{image} /_static/images-test/examples.png + :alt: Example standard image scales + :target: /_static/images-test/examples.png + ``` + +++ + _Example standard image scales_ + ```` + +Picture tags +: Demonstrates the use of `` elements with configured picture variants. + If the site runs on Plone 5.2 or earlier, a regular `` tag is rendered instead. + + Picture Tag Large + : uses the configured `large` picture variant + + Picture Tag Medium + : uses the `medium` variant with multiple `` elements and media queries for art direction + + Picture Tag Small + : uses the `small` variant + + Picture Tag Small with title/alt + : same as the previous, but with `title` and `alt` attributes explicitly set + +````{card} +```{image} /_static/images-test/picture-tags.png +:alt: Picture tags +:target: /_static/images-test/picture-tags.png +``` ++++ +_Picture tags_ +```` + +`img` with `srcset` attributes +: Shows how to use Plone’s `@@images` view to generate a full responsive `` tag with a complete `srcset`. + The browser automatically selects the most appropriate scale based on the available space and device pixel ratio. + The example includes the required `sizes` attribute and demonstrates the resulting HTML output. + + ```{seealso} + {ref}`classic-ui-images-responsive-image-support` + ``` + +````{card} +```{image} /_static/images-test/image-srcset.png +:alt: img with srcset attributes +:target: /_static/images-test/image-srcset.png +``` ++++ +_img with srcset attributes_ +```` + +```{seealso} +{ref}`classic-ui-images-responsive-image-support` +``` + +This view is especially valuable for theme developers who need to verify that responsive images, picture variants, and `srcset` functionality are correctly styled and behave as expected across devices and Plone versions. (classic-ui-images-permissions-label)= @@ -261,18 +371,34 @@ To access image scales, which are normally not accessible to the current user, o ## Responsive image support -Plone supports the generation of picture tags with `srcset`s for image optimization. -Additionally, you can define [media queries](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries) for [art direction](classic-ui-images-responsive-image-support-art-direction) and further optimization. +Plone supports the generation of [`picture`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/picture) tags with `srcset`s for image optimization. +Additionally, you can define [media queries](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Media_queries/Using) for [art direction](classic-ui-images-responsive-image-support-art-direction) and further optimization. -The configuration allows you to define different picture variants, such as `Large`, `Medium`, or `Small`. +The configuration allows you to define different `picture` variants, such as `Large`, `Medium`, or `Small`. Users can choose from them in editors, such as TinyMCE, and developers can use them in templates. +To generate a `picture` tag, use the following code. + +```python +from plone import api + +scale_util = api.content.get_view("images", context, request) +tag = scale_util.picture("image", scale="larger", picture_variant="large") +``` + +The same can be done from a template. + +```xml +
    + +
    +``` (classic-ui-images-responsive-image-support-picture-variants)= -### Picture variants +### `picture` variants -In `/@@imaging-controlpanel` Plone allows you to define picture variants with a list of available image scales. +In `/@@imaging-controlpanel` Plone allows you to define `picture` variants with a list of available image scales. These are used for HTML {term}`srcset` attributes. A `srcset` attribute can help the browser to serve the best fitting image size for the current user's display. @@ -372,10 +498,10 @@ This means the generated `srcset` will contain the scales from `preview` up to ` (classic-ui-images-responsive-image-support-picture-variant-in-editor)= -#### Hiding a picture variant in editors +#### Hiding a `picture` variant in editors -It is possible to hide a picture variant in editors. -This is useful when you want to define a picture variant to be used in templates only. +It is possible to hide a `picture` variant in editors. +This is useful when you want to define a `picture` variant to be used in templates only. ```json "leadimage": { @@ -398,7 +524,7 @@ This is useful when you want to define a picture variant to be used in templates With image size optimization, the browser is able to choose the optimal image for each display size. But we have no control over which scale the browser will actually use. For example to force the browser to use a zoomed version of an image for smaller screens, we can use media queries. -The technique is called [art direction](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images#art_direction). +The technique is called [art direction](https://developer.mozilla.org/en-US/docs/Web/HTML/Guides/Responsive_images#art_direction). Let's have a look at a more advanced configuration: @@ -461,6 +587,39 @@ Please note that this example has the `resolve_uid_and_caption` filter disabled The real `src` URLs look more like `http://localhost:8080/Plone50/dsc04791.jpg/@@images/778f9c06-36b0-485d-ab80-12c623dc4bc3.jpeg`. ``` +### All image scales in the srcset + +Modern browsers can download appropriate sized images depending on their viewport width when URLs and widths are correctly provided in an attribute called `srcset` and the viewport width is provided in the attribute `sizes`. + +Examine the following {term}`TALES` example. + +```html + +``` + +This example will render the HTML `img` tag with the URLs of all scales configured in Plone, calculating the width of each of the scales, and will add the `sizes="90vw"` attribute. +The `sizes` attribute instructs the browser to retrieve the image that best fits in 90% of the current viewport width. + +This means that the appropriate scaled image will be downloaded and displayed. + +This also means that the developer does not need to worry about creating a specific scale. +Instead they only need to provide the correct media query to signal the required width. + +The `scrset` method of the `@@images` view also takes all other parameters that are HTML attributes of the `img` tag, such as `title`, `alt` or `loading`. + +```html + +``` + +```{note} +While using this approach may be useful for projects, using it in reusable add-ons is not recommended, because it may require overriding it to your needs in a project. +Use configurable picture variants instead. +``` ## Image scales from catalog brain For all `NamedBlobImage` fields, we can get existing scale information directly from the catalog brain. @@ -509,4 +668,4 @@ This information shows we have everything we need to generate our image URLs, wi width="${python: preview['width']}" height="${python: preview['height']}" /> -``` \ No newline at end of file +``` diff --git a/docs/classic-ui/index.md b/docs/classic-ui/index.md index 0e8995bc5c..085348419a 100644 --- a/docs/classic-ui/index.md +++ b/docs/classic-ui/index.md @@ -1,49 +1,22 @@ --- myst: html_meta: - "description": "Classic UI is a secondary user interface for Plone, but updated to use Twitter Bootstrap 5. It is familiar to users of Plone 5." - "property=og:description": "Classic UI is a secondary user interface for Plone, but updated to use Twitter Bootstrap 5. It is familiar to users of Plone 5." + "description": "Classic UI is a secondary user interface for Plone, but updated to use Bootstrap 5. It is familiar to users of Plone 5." + "property=og:description": "Classic UI is a secondary user interface for Plone, but updated to use Bootstrap 5. It is familiar to users of Plone 5." "property=og:title": "Classic UI" - "keywords": "Plone 6, Classic UI, Twitter Bootstrap 5" + "keywords": "Plone 6, Classic UI, Bootstrap 5" --- (classic-ui-index-label)= # Classic UI -```{todo} -Perhaps some of this introduction should be an include, so we don't have to repeat ourselves? -``` - -Plone 6 ships with two user interfaces or frontends. - -The default frontend of Plone 6 is Volto. -It is based on the React JavaScript framework. - -The other frontend is based on Twitter Bootstrap 5. -This frontend is now called {term}`Classic UI`. - - -## Which frontend? - -Choosing one frontend over another depends on several factors. +This chapter is a developer reference manual for working with {term}`Classic UI`. -Classic UI would be a better choice for the following situations. - -- Reason 1 -- Reason 2 -- Reason N - -The default frontend Volto would be a better choice for the following situations. - -- Reason 1 -- Reason 2 -- Reason N - - -## Contents - -This chapter is a developer reference manual for working with Classic UI. +```{seealso} +Plone has two user interfaces, Volto and Classic UI. +To understand their differences, see {doc}`/conceptual-guides/choose-user-interface`. +``` ```{toctree} :maxdepth: 2 @@ -53,12 +26,15 @@ forms icons images layers +module-federation +mockup portlets recipes static-resources template-global-variables templates theming/index +tinymce-customization viewlets views whatsnew diff --git a/docs/classic-ui/layers.md b/docs/classic-ui/layers.md index 9f3aca88cc..651ba0e653 100644 --- a/docs/classic-ui/layers.md +++ b/docs/classic-ui/layers.md @@ -314,3 +314,10 @@ from zope.interface import directlyProvides directlyProvides(self.portal.REQUEST, IThemeLayer) ``` + +## Related content + +- {doc}`/classic-ui/theming/index` +- {doc}`/classic-ui/theming/create-add-on` +- {doc}`/classic-ui/templates` +- {doc}`/classic-ui/viewlets` \ No newline at end of file diff --git a/docs/classic-ui/mockup.md b/docs/classic-ui/mockup.md new file mode 100644 index 0000000000..d117eeb0fe --- /dev/null +++ b/docs/classic-ui/mockup.md @@ -0,0 +1,148 @@ +--- +myst: + html_meta: + "description": "Mockup together with Patternslib are used to build the UI toolkit for Classic UI, a frontend for Plone." + "property=og:description": "Mockup together with Patternslib are used to build the UI toolkit for Classic UI, a frontend for Plone." + "property=og:title": "Mockup and Patternslib" + "keywords": "Mockup, Patternslib, Classic UI, plonecli, bobtemplates.plone, mr.bob, frontend, Plone" +--- + +(mockup-and-patternslib-label)= + +# Mockup and Patternslib + +{term}`Mockup` together with {term}`Patternslib` are used to build the UI toolkit for {term}`Classic UI`, a frontend for Plone. + +View the [interactive documentation of Mockup](https://plone.github.io/mockup/). + + +## Get started + +[`bobtemplates.plone`](https://github.com/plone/bobtemplates.plone) provides [`mr.bob`](https://github.com/collective/mr.bob) templates to generate packages for Plone projects. +[Plone CLI (`plonecli`)](https://github.com/plone/plonecli) provides a command line client for `bobtemplates.plone`. + +Install {term}`plonecli` into your Python user packages to make it available to all your projects. + +```shell +pip install plonecli --user +``` + +Create an add-on package with `plonecli`. + +```shell +plonecli create addon project.addon +``` + +This will create a package `project.addon`, which you can install in your Plone site. + +You can `cd` to the project, and add features to that package, such as content types, behaviors, control panels, or REST API endpoints. + +```shell +cd project.addon +plonecli add content_type +plonecli add behavior +plonecli theme_barceloneta +``` + +Each of the features asks several questions to create the desired feature, customized to your preferences. + +You can check the full list of available features using the `-l` parameter: + +```shell +plonecli -l +``` + +## Create a custom pattern + +To create a custom {term}`pattern` in your add-on, use the `mockup_pattern` {term}`bobtemplate`. + +```shell +cd project.addon +plonecli add mockup_pattern +``` + +Next, enter your pattern name without the `pat-` prefix +In the following example, its name is `testpattern`. + +```shell +--> Pattern name (without “pat-” prefix) [my-pattern]: testpattern +``` + +This creates the necessary JavaScript resources and webpack configuration for you, as shown in the following file system tree diagram. + +```text +... +├── resources +| ├── pat-testpattern +| | ├── documentation.md +| | ├── testpattern.js +| | ├── testpattern.scss +| | ├── testpattern.test.js +│ ├── bundle.js +│ ├── index.html +│ ├── index.js +├── package.json +├── webpack.config.js +... +``` + +All your pattern JavaScript code goes into {file}`resources/pat-testpattern/testpattern.js`. +SCSS files can be imported, too, since webpack provides the `sass-loader` module. + +Next, install the npm packages using {term}`yarn`. + +```shell +yarn install +``` + +When you finish writing your JavaScript code, you have to build the bundle with the following command. + +```shell +yarn build +``` + +This creates the webpack chunks, the JavaScript bundle files, and a demo browser view in your add-on package. + +```text +... +├── src +| ├── project +| | ├── addon +| | | ├── browser +| | | | ├── static +| | | | | ├── bundles +| | | | | | ├── chunks +| | | | | | ├── addon-remote.min.js +| | | | | | ├── addon-remote.min.js.map +| | | | | | ├── addon.min.js +| | | | | | ├── addon.min.js.map +| | | | ├── pattern-demo.pt +``` + +There is also an XML file in {file}`src/project/addon/profiles/default/registry/bundles.xml` which registers the {file}`addon-remote.min.js` in the resources registry. + +```{important} +You must re-import your profile with an upgrade step if you installed your add-on in Plone before adding the pattern. +Uninstall, then re-install, the add-on in the control panel. +Alternatively you can write a GenericSetup upgrade step. +``` + +You can access the demo browser view in your browser with `http://localhost:8080/Plone/@@addon-pattern-demo`. +Alternatively you can implement it in your own templates by adding the CSS class `pat-testpattern` to an HTML tag, such as an `img` tag. + +```html + +``` + + +## References + +- [`bobtemplates.plone` documentation](https://bobtemplatesplone.readthedocs.io/) +- [`mr.bob` documentation](https://mrbob.readthedocs.io/en/latest/) +- [Plone CLI documentation](https://plonecli.readthedocs.io/en/latest/) +- [`bobtemplates.plone` repository](https://github.com/plone/bobtemplates.plone) +- [`mr.bob` repository](https://github.com/collective/mr.bob) +- [Plone CLI (`plonecli`) repository](https://github.com/plone/plonecli) +- {ref}`v60-mockup-resource-registry-label` in Plone 6.0 +- [Mockup repository on GitHub](https://github.com/plone/mockup) +- [Patternslib](https://patternslib.com/) diff --git a/docs/classic-ui/module-federation.md b/docs/classic-ui/module-federation.md new file mode 100644 index 0000000000..230fb7cb44 --- /dev/null +++ b/docs/classic-ui/module-federation.md @@ -0,0 +1,100 @@ +--- +myst: + html_meta: + "description": "How to use Module Federation in Mockup and add-on bundles." + "property=og:description": "How to use Module Federation in Mockup and add-on bundles." + "property=og:title": "Module Federation in Mockup" + "keywords": "Plone, Classic UI, classic-ui, Mockup, Module Federation, webpack, JavaScript" +--- + +(classic-ui-module-federation-in-mockup-label)= + +# Module Federation in Mockup + +Module Federation allows sharing of dependencies between bundles. +Each bundle includes the whole set of dependencies. +However, if multiple bundles have the same dependencies, then they are loaded only once. + +For example, if bundle A and B both depend on jQuery and bundle A has already loaded it, then bundle B can just reuse the already loaded jQuery file. +But if only bundle B is loaded, it uses its own bundled version of the jQuery library. + +There is a host bundle, as in the fictional example above, our bundle A. +In Plone the host bundle is the main Mockup bundle. +Add-ons can add bundles called "remotes" which are initialized for Module Federation by the host bundle. + +```{seealso} +Webpack's documentation on [Module Federation](https://webpack.js.org/concepts/module-federation/). +``` + + +## Use Module Federation + +If you created an add-on with a Mockup pattern, and you want to include the respective JavaScript code in your theme code, then the following instructions are for you. + +Starting with the webpack configuration that you get when creating a Barceloneta theme package via [`plonecli`](https://pypi.org/project/plonecli/), add the following. + +Create a new entry point {file}`index.js` which only imports the normal entry point. + +```js +import("./patterns"); +``` + +Next add the Module Federation plugin in {file}`webpack.config.js`. +There is a configuration factory `mf_config` which you can use for that. +Add the following line near the top of the file. + +```js +const mf_config = require("@patternslib/dev/webpack/webpack.mf"); +``` + +Import all the dependencies you want to share. +Potentially these are the ones from [Patternslib](https://github.com/Patternslib/Patterns/blob/master/package.json), Mockup, and your own dependencies. +You can add the Patternslib and Mockup dependencies, even if you are not using them. + +```js +const package_json = require("./package.json"); +const package_json_mockup = require("@plone/mockup/package.json"); +const package_json_patternslib = require("@patternslib/patternslib/package.json"); +``` + +Then find the following line. + +```js +config = patternslib_config(env, argv, config, ["@plone/mockup"]); +``` + +Below this line add the following. + +```js +config.plugins.push( + mf_config({ + name: "myaddon", + filename: "myaddon-remote.min.js", + remote_entry: config.entry["myaddon.min"], + dependencies: { + ...package_json_patternslib.dependencies, + ...package_json_mockup.dependencies, + ...package_json.dependencies, + }, + }) +); +``` + +Replace the name `myaddon` with your add-on bundle's unique name. +Replace the file name {file}`myaddon-remote.min.js` with the file name you want to use for your remote bundle. +Finally replace `myaddon.min` with the corresponding key in `config.entry` that points to your {file}`index.js`. + +For a full and basic example, see the Patterns generator [pat-PATTERN-TEMPLATE](https://github.com/Patternslib/pat-PATTERN_TEMPLATE/blob/main/webpack.config.js) or any other Pattern add-on in the [patternslib GitHub organization](https://github.com/patternslib/). +For a complex example with Mockup integration see [`plone.app.mosaic`](https://github.com/plone/plone.app.mosaic/blob/master/webpack.config.js) and [Mockup](https://github.com/plone/mockup/blob/master/webpack.config.js) itself. + + +## Special case: global modules `jQuery` and `Bootstrap` + +To preserve compatibility with older add-ons and JavaScript implementations, the modules `jQuery` and `Bootstrap` are stored in the global `window` namespace. +Constructs like the following still work: + +```js +(function($) { + // JS code which uses $ +})(jQuery); +``` diff --git a/docs/classic-ui/recipes.md b/docs/classic-ui/recipes.md index 2db34ef751..b60b38eb2f 100644 --- a/docs/classic-ui/recipes.md +++ b/docs/classic-ui/recipes.md @@ -46,3 +46,51 @@ Then register the adapter in ZCML. name="myproject-customclasses" /> ``` + +(classic-ui-recipes-customize-pattern-options)= + +## Customize `pattern_options` + +The following example shows how to customize the {menuselection}`Favorites` menu in the `contentbrowser` pattern. + +First create a multiadapter as shown. + +```{code-block} python + +from plone import api +from plone.app.z3cform.interfaces import IContentBrowserWidget +from plone.dexterity.interfaces import IDexterityContent +from z3c.form.interfaces import IForm +from z3c.form.interfaces import IValue +from zope.component import adapter +from zope.interface import implementer +from zope.publisher.interfaces import IRequest +from zope.schema.interfaces import IField + +@implementer(IValue) +@adapter(IDexterityContent, IRequest, IForm, IField, IContentBrowserWidget) +class ContentbrowserPatternOptions: + + def __init__(self, context, request, form, field, widget): + self.context = context + self.request = request + self.form = form + self.field = field + self.widget = widget + + def get(self): + portal_path = "/".join(api.portal.get().getPhysicalPath()) + return { + "favorites": [ + {"title": "my favorite folder", "path": f"{portal_path}/path/to/my/favorite/folder"}, + {"title": "Portal", "path": portal_path}, + ], + } +``` + +Then register it with ZCML as shown. + +```xml + +``` diff --git a/docs/classic-ui/static-resources.md b/docs/classic-ui/static-resources.md index 0594a42a6a..f9715fca1c 100644 --- a/docs/classic-ui/static-resources.md +++ b/docs/classic-ui/static-resources.md @@ -12,7 +12,15 @@ myst: # Static resources We often want to ship a website with a static resource, such as an image, icon, CSS, or JavaScript file. -For this, we need to register static resources. +For CSS and JavaScript files, we can use the resource registry to register, then deliver, them to the client browser. + +The resource registry provides a programmatic way, either in code or through the web, to extend and configure the dependencies between static resources. +It also automatically manages caching of static resources. +If you were to hard-code these resources in templates with `` or ` ``` -Theming based on Diazo. + +### HTML template structure + +Your theme should be as simple as possible. +That will make your {file}`rules.xml` file also as simple as possible. + +The {file}`rules.xml` file declares which parts of theme will be replaced by the HTML produced by Plone. + +It is a good practice to have a `
    ` element called `content` in your theme, which will contain the maximum space of the content area of your site. +That way you can inject the HTML produced by Plone there using Plone's content section, too. + +Add a stanza in your {file}`rules.xml` file. + +```xml + +``` + + +### Minimize rules + +You can start with the provided {file}`rules.xml` file. + +You can read about how to write your rules and their syntax in the [official Diazo documentation](https://docs.diazo.org/en/latest/basic.html). + +You will need to write your own rules to bring the dynamic content from Plone into the theme. + +Sometimes you will face difficult situations where you may find it hard to put items in the same place that Plone produces in very different places. + +For instance, you may need to put together the main menu, the language change, and the search box. +Sometimes it is easier to override the corresponding template in Plone, build the new HTML structure there, and replace one thing in the {file}`rules.xml` file than trying to write complex Diazo rules or writing XSLT. + +The size of the {file}`rules.xml` file and the number of rules it contains can negatively impact the performance of your site. + + +### Disable Diazo for AJAX requests + +When sending an AJAX request to normal browser views in Plone, Plone prepares a response as an HTML page, then normally transforms it via the Diazo theming engine. +In some cases this is unnecessary overhead, such as when you want to inject a small snippet of HTML only into the page. + +To prevent this transformation, disable AJAX requests for Diazo themes by using the `ajax_load` HTTP request parameter. +`ajax_load` is used in Plone to indicate AJAX requests. +When added to the query string, `ajax_load=1` disables a full page rendering, whereas `ajax_load=0` enables it. + +```{versionadded} plonetheme.barceloneta 3.3.0 +In Plone Classic UI's standard theme, `plonetheme.barceloneta` version 3.3.0, the `ajax_load` theme parameter to disable Diazo was added. +If you use this theme version 3.3.0 or later, then the next steps are obsolete. +``` + +Manually add the HTTP request parameter and its value as follows. + +Add a theme parameter to your {file}`manifest.cfg` file. + +```cfg +[theme:parameters] +ajax_load = python:request.get('ajax_load') +``` + +Then disable Diazo for AJAX requests in your {file}`rules.xml` file. + +```xml + +``` + +Choose any method to load this change in your theme. + +- Restart your instance. +- In the {guilabel}`Theming` control panel, select another theme, then switch back to your own theme. +- For a programmatic way, see [(Re)Introduce the ajax_load theme parameter and skip diazo theming, if set. `plone/plonetheme.barceloneta` #404](https://github.com/plone/plonetheme.barceloneta/pull/404). + + +### Completely disable Diazo + +You can fully disable Diazo and `plone.app.theming` based themes by setting the `plone.app.theming.interfaces.IThemeSettings.enabled` registry entry to `False`. diff --git a/docs/classic-ui/theming/from-scratch.md b/docs/classic-ui/theming/from-scratch.md deleted file mode 100644 index 9d2110e07e..0000000000 --- a/docs/classic-ui/theming/from-scratch.md +++ /dev/null @@ -1,136 +0,0 @@ ---- -myst: - html_meta: - "description": "Plone Classic UI theming from scratch" - "property=og:description": "Plone Classic UI theming from scratch" - "property=og:title": "Plone Classic UI theming from scratch" - "keywords": "Plone, Classic UI, theming, scratch" ---- - -(classic-ui-theming-from-scratch-label)= - -# Classic UI theming from scratch - -```{todo} -This page is only an outline and needs a lot of work. -See https://github.com/plone/documentation/issues/1286 -``` - -Theming based on a filesystem package without any dependency. - -- Theming for Plone 6 Classic UI -- Theme stored in a filesystem package -- Built from scratch -- No dependencies to Barceloneta -- No Diazo needed - - -## Theme package - -- Create a theme package as explained here. -- Remove what you do not need -- Overrides -- Static files - - -## Static files - -Register directory to keep static files - -File: `src/plonetheme/munich/browser/configure.zcml` -Directory: `src/plonetheme/munich/browser/static` - -```xml - - -``` - -## Theme - -### Manifest - -- Manifest for your theme -- Keep rules empty to disable Diazo - -```ini -[theme] -title = Munich Theme -description = A modernized Plone 6 theme -preview = preview.png -rules = -prefix = /++theme++plonetheme.munich -doctype = -``` - -### Bundle registration - -```xml - - - - - ++theme++munich/js/munich.min.js - ++theme++munich/css/munich.min.css - True - False - 2020-12-06 12:00:00 - - - -``` - -### Theme registration - -Register your theme via theme.xml - -```xml - - - munich - true - -``` - -### Compile the bundle - -- Compile SASS to SCSS - -Install all requirements and dependencies from package.json: - -```shell -yarn install -``` - -Build the actual bundle: - -```shell -yarn dist -``` - - -### Theming - -- Make use of Bootstrap [variables](https://github.com/twbs/bootstrap/blob/main/scss/_variables.scss) -- Tweak basic settings like rounded corners, shadows, and so on. -- Set custom fonts -- Define your own stuff -- Import Boostrap (as basis) - - -#### Templates - -- Add `z3c.jbot` overrides -- Copy templates to customize -- Add custom views for your story - - -### Available themes - -- [`plonetheme.tokyo`](https://github.com/collective/plonetheme.tokyo/) (mobile first, one column) -- [`plonetheme.munich`](https://github.com/collective/plonetheme.munich/) (minimalistic) diff --git a/docs/classic-ui/theming/index.md b/docs/classic-ui/theming/index.md index 3048ee8465..5b05448646 100644 --- a/docs/classic-ui/theming/index.md +++ b/docs/classic-ui/theming/index.md @@ -9,19 +9,62 @@ myst: (classic-ui-theming-index-label)= -# Theming of Classic UI +# Theming Classic UI -```{todo} -This page is only an outline and needs a lot of work. -See https://github.com/plone/documentation/issues/1286 -``` +This section of the documentation describes how to theme Classic UI. + + +## TTW or add-on? + +Small theme changes—such as the site logo and favicon and minimal CSS changes—can be made by {doc}`changing theme settings through the web (TTW) `. +This method is especially useful for short-lived or prototype sites. +It allows you to make minor adjustments without needing to dive into code or production-level setups. +TTW can be convenient for quick experiments, websites that don't require complex theming, or short-lived websites. + +An add-on allows you to keep your customization modular, and it provides a more structured approach to larger-scale theming. +This method is ideal for more permanent or complex customizations since it enables easier maintenance and portability. + +The customized Barceloneta theme, creating a theme from scratch, and Diazo offer even more flexibility. + +Barceloneta theme +: Ideal for a starting point, especially if you want to tweak it as an existing, solid theme. + You can customize its components and styles without starting from zero. + +From scratch +: If your project requires something completely unique and none of the existing themes fit, building a theme from scratch would be the way to go. + This is most appropriate for highly customized websites with distinct design requirements. + +Diazo +: Diazo can be used where designers create a self-contained HTML page with CSS and JavaScript without customizing templates. + It can be used for simple themes or for more advanced methods. + + Its advantages include allowing more complex themes where content needs to remain flexible, and you want full control over the markup. + + Its disadvantages include a possible negative performance impact from the rendering process, and a more complex and difficult to maintain theme. + +To summarize: + +- Use {doc}`TTW ` for minor changes or testing. +- Use {doc}`add-ons ` for production-level theming that needs scalability, maintainability, and modularity to customize Barceloneta or to write themes from scratch. +- Use {doc}`Diazo ` in your add-on if you need to modify the markup without touching the page templates. + + +## How-to guides ```{toctree} :maxdepth: 2 -barceloneta +settings-ttw +create-add-on +color-modes diazo -from-scratch -through-the-web -color-mode -``` \ No newline at end of file +``` + +## Reference + +```{toctree} +:maxdepth: 2 + +scss-structure +css-custom-properties +``` diff --git a/docs/classic-ui/theming/scss-structure.md b/docs/classic-ui/theming/scss-structure.md new file mode 100644 index 0000000000..c992ef40e5 --- /dev/null +++ b/docs/classic-ui/theming/scss-structure.md @@ -0,0 +1,74 @@ +--- +myst: + html_meta: + "description": "SCSS structure for Classic UI themes for Plone" + "property=og:description": "SCSS structure for Classic UI themes for Plone" + "property=og:title": "SCSS structure for Classic UI themes for Plone" + "keywords": "Plone, Classic UI, theming, add-on" +--- + +(classic-ui-theming-theme-structure-label)= + +# Theme structure + +All the theming relevant files are now located inside `src/plonetheme/themebasedonbarceloneta/theme/`: + +```text +./src/plonetheme/themebasedonbarceloneta/theme/ +├── barceloneta-apple-touch-icon-114x114-precomposed.png +├── barceloneta-apple-touch-icon-144x144-precomposed.png +├── barceloneta-apple-touch-icon-57x57-precomposed.png +├── barceloneta-apple-touch-icon-72x72-precomposed.png +├── barceloneta-apple-touch-icon-precomposed.png +├── barceloneta-apple-touch-icon.png +├── barceloneta-favicon.ico +├── index.html +├── manifest.cfg +├── package.json +├── preview.png +├── rules.xml +├── scss +│ ├── _custom.scss +│ ├── _maps.scss +│ ├── _variables.scss +│ └── theme.scss +├── styles +│ ├── theme.css +│ └── theme.min.css +└── tinymce-templates + ├── README.rst + ├── card-group.html + └── list.html +``` + +`index.html` +: Basic HTML structure for the site layout. + +`manifest.cfg` +: Basic theme configuration for the backend. + +`package.json` +: npm package configuration which defines all requirements for theming with Barceloneta. + +`rules.xml` +: Diazo rules which translate the `index.html` and fills it with content from the backend. + +`scss/_custom.scss` +: Custom SCSS rules for your theme. + +`scss/_maps.scss` +: Override Bootstrap mapping variables here. + +`scss/_variables.scss` +: Override Bootstrap and/or Barceloneta variables here. + +`scss/theme.scss` +: Base theme file which follows "Option B" of customizing Bootstrap imports to enable custom variable and map injections. + Note that the order of these imports is mandatory to ensure overriding the defaults. + See https://getbootstrap.com/docs/5.3/customize/sass/#importing. + +`styles/theme.css[.min]` +: Compiled CSS styles. + +`tinymce-templates/*.html` +: HTML snippets for the TinyMCE `template` plugin. diff --git a/docs/classic-ui/theming/settings-ttw.md b/docs/classic-ui/theming/settings-ttw.md new file mode 100644 index 0000000000..75fb6b7a27 --- /dev/null +++ b/docs/classic-ui/theming/settings-ttw.md @@ -0,0 +1,62 @@ +--- +myst: + html_meta: + "description": "Change Classic UI theme settings through-the-web (TTW) in Plone 6" + "property=og:description": "Change Classic UI theme settings through-the-web (TTW) in Plone 6" + "property=og:title": "Change Classic UI theme settings through-the-web (TTW) in Plone 6" + "keywords": "Plone 6, Classic UI, Through-the-web, TTW, theme, customization" +--- + +(classic-ui-through-the-web-label)= + +# Change theme settings TTW + +This chapter describes how to change Classic UI theme settings through-the-web ({term}`TTW`) in Plone 6. + +Small theme changes can be made via control panels. +Other theming methods should be used for larger customizations or entire website designs. + + +(classic-ui-through-the-web-control-panels-label)= + +## Control panels + +You can make the following changes through control panels. + +- Logo +- Favicon +- Custom Styles + + +### Logo + +Navigate to {menuselection}`Admin --> Site Setup --> Site`, or visit the URL path `/@@site-controlpanel` in your web browser's address bar. + +Under {guilabel}`Site Logo`, you can upload a custom logo for your site. + + +### Favicon + +Navigate to {menuselection}`Admin --> Site Setup --> Site`, or visit the URL path `/@@site-controlpanel` in your web browser's address bar. + +Under {guilabel}`Site Favicon`, you can upload a custom favicon for your site. + +When you upload a new favicon, the previous field {guilabel}`MIME type of the site favicon` will update with the favicon's correct media type. + + +### Custom Styles + +Navigate to {menuselection}`Admin --> Site Setup --> Theming --> Advanced settings --> Custom Styles`, or visit the URL path `/@@theming-controlpanel#autotoc-item-autotoc-2` in your web browser's address bar. + +Enter any arbitrary styles, and save your changes. +The changes are stored in a `BrowserView` called `custom.css`. +It is shipped as the last resource after all other CSS files. +It can be used to override default CSS, sometimes with the use of the CSS property `!important` or specific CSS selectors. + +However, you should use it only for small changes to CSS. +For larger changes, see {doc}`create-add-on`. + + +## Themes + +Under {menuselection}`Admin --> Site Setup --> Theming --> Themes`, you are limited to downloading and uploading themes. diff --git a/docs/classic-ui/theming/through-the-web.md b/docs/classic-ui/theming/through-the-web.md deleted file mode 100644 index 2a9646bd6e..0000000000 --- a/docs/classic-ui/theming/through-the-web.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -myst: - html_meta: - "description": "Through-the-web (TTW) theme customization in Plone 6 Classic UI" - "property=og:description": "Through-the-web (TTW) theme customization in Plone 6 Classic UI" - "property=og:title": "Through-the-web (TTW) theme customization in Plone 6 Classic UI" - "keywords": "Plone 6, Classic UI, Through-the-web, TTW, theme, customization" ---- - -(classic-ui-through-the-web-label)= - -# Through-the-web (TTW) theme customization - -```{todo} -This page is only an outline and needs a lot of work. -See https://github.com/plone/documentation/issues/1286 -``` - -TTW customization is useful when you need to make small CSS changes. -Theme changes can be made via control panels or by updating Plone 6 Classic UI's `custom.css`. -Other theming methods should be used for larger customizations or entire website designs. - - -(classic-ui-through-the-web-control-panels-label)= - -## Control panels - -You can make the following changes through control panels. - -* Logo -* Favicon -* Custom CSS in `custom.css` - -With `custom.css`, you can make custom styles without compilation. -It is shipped as the last resource after all other CSS files. -It can be used to override default CSS, sometimes with the use of the CSS property `!important` or specific CSS selectors. - - -```{todo} -Provide usage. -Provide navigation through {menuselection}`Site Setup --> Theming` or {guilabel}`Button Name`. -Add screenshots. -``` - - -(classic-ui-through-the-web-css-variables-label)= - -## CSS variables - -Plone uses Twitter Bootstrap's CSS variables. -They are used to tweak colors, fonts, spacing, and other CSS attributes. - -```{todo} -Provide usage. -``` - - -(classic-ui-through-the-web-theming-control-panel-label)= - -## Theming control panel - -The Theming control panel is limited to downloading and uploading themes. - - -(classic-ui-through-the-web-templates-label)= - -### Templates - - -(classic-ui-through-the-web-restricted-python-label)= - -### Restricted python - - -(classic-ui-through-the-web-content-types-label)= - -### Content types - diff --git a/docs/classic-ui/tinymce-customization.md b/docs/classic-ui/tinymce-customization.md new file mode 100644 index 0000000000..930a05f1f0 --- /dev/null +++ b/docs/classic-ui/tinymce-customization.md @@ -0,0 +1,243 @@ +--- +myst: + html_meta: + "description": "TinyMCE customization in Plone 6" + "property=og:description": "TinyMCE customization in Plone 6" + "property=og:title": "TinyMCE customization in Plone 6" + "keywords": "Plone 6, Classic UI, Bootstrap 5, TinyMCE, customization" +--- + +(classic-ui-tinymce-customization-label)= + +# TinyMCE customization + +This chapter is a developer reference manual for customizing {term}`TinyMCE`. + + +## Customize {menuselection}`Format` menu + +There are several options to customize TinyMCE's {menuselection}`Format --> Formats` menu. + +The first two options use TinyMCE's [`formats` JSON configuration](https://www.tiny.cloud/docs/tinymce/latest/content-formatting/). +They are less complicated to implement than the third option. + + +### Add-on GenericSetup configuration file + +This option is best for system administrators and developers who write their own add-ons to ease reproducibility. + +You can add a GenericSetup configuration file to your add-on, such as {file}`profiles/default/registry/tinymce.xml`, with the JSON configuration of the custom format. + +```xml + + + { + "myformat": { + "block": "div", + "classes": "my-css-classes" + } + } + + +``` + +```{important} +The content of the `formats` record will overwrite the value in the {guilabel}`Formats` field in the TinyMCE control panel at {menuselection}`Site Setup --> TinyMCE --> Default`. +If you want to preserve the default content, you must copy it into your XML. +``` + +Next, define where to place the new format inside the {menuselection}`Format` menu's submenus. +You can add your custom format to one of the following menu items. +These menu items in the TinyMCE editor correspond to field items in the TinyMCE control panel at {menuselection}`Site Setup --> TinyMCE --> Default`. + +(tinymce-formats-styles-label)= + +- {guilabel}`Header styles` +- {guilabel}`Inline styles` +- {guilabel}`Block styles` +- {guilabel}`Alignment styles` +- {guilabel}`Table styles` + +The syntax for each element in those fields is `Title|format`. +The following example XML snippet adds your format to the {menuselection}`Inline styles` menu. +Unlike the previous example, the example does not remove the default values, but appends to it. + +```xml + + + My custom format|myformat + + +``` + + +### Edit the `Formats` option in the TinyMCE control panel + +This option is good for quick edits, but is not as reproducible as the GenericSetup option. + +You can manually customize the `Formats` value through-the-web in the TinyMCE control panel. + +1. Navigate to {menuselection}`Site Setup --> TinyMCE --> Default`, or append `@@tinymce-controlpanel` to the root of your website in your browser's location bar. +1. Scroll down to {guilabel}`Formats`, and edit the JSON configuration. +1. Insert your custom format to one of the fields mentioned above. +1. Click the {guilabel}`Save` button. + + +### Inject formats with files named {file}`tinymce-formats.css` + +This option is more complex to implement than the previous options. +However it is the only option where you can add items to the {menuselection}`Formats` submenu as siblings to the {ref}`Formats styles ` configurations. + +In Plone 6, TinyMCE has a special logic that automatically reads registered files named {file}`tinymce-formats.css` and adds the CSS classes defined in those files to TinyMCE's {menuselection}`Format --> Formats` menu by using the [`importcss_file_filter` option](https://www.tiny.cloud/docs/tinymce/latest/importcss/#importcss_file_filter). + +To add custom formats, you can provide your own files. + +1. Name the file {file}`tinymce-formats.css`. +1. Register the file as a resource in your Plone site. +1. Include the file in the TinyMCE control panel in the textarea input {guilabel}`Choose the CSS used in WYSIWYG Editor Area`. + 1. Navigate to {menuselection}`Site Setup --> TinyMCE --> Default`, or append `@@tinymce-controlpanel` to the root of your website in your browser's location bar. + 1. Scroll down to {guilabel}`Choose the CSS used in WYSIWYG Editor Area`. + +CSS styles defined in this file will automatically be added to the top level of TinyMCE's {menuselection}`Format --> Formats` menu. + + +## Remove imported formats + +Similar to adding formats, you can remove formats in a couple of ways. + + +### Add-on GenericSetup configuration file + +Alternatively, you can use GenericSetup in your add-on. + +```xml + + + ++theme++barceloneta/tinymce/tinymce-ui-content.css + + +``` + + +### Configure the TinyMCE control panel + +Plone 6 Classic UI ships with the Barceloneta theme which includes two custom formats, `highlight-inline` and `p.highlight-paragraph`, in the TinyMCE {menuselection}`Format --> Formats` menu. +You can remove these formats through the TinyMCE control panel. + +1. Navigate to {menuselection}`Site Setup --> TinyMCE --> Default`, or append `@@tinymce-controlpanel` to the root of your website in your browser's location bar. +1. Scroll down to {guilabel}`Choose the CSS used in WYSIWYG Editor Area`. +1. Remove the entry `++theme++barceloneta/tinymce/tinymce-formats.css`. +1. Click the {guilabel}`Save` button. + +Once removed, the custom formats will no longer appear in the menu. + + +## Configure `