Repository navigation
docs(building-sites/contexts): fact-check pass, en/ru/es sync - #677
Open
Ibochkarev wants to merge 6 commits into
Open
Ibochkarev wants to merge 6 commits into
Ibochkarev wants to merge 6 commits into
Conversation
Mark-H
reviewed
Oct 20, 2026
| to | ||
| ## A Gateway of Its Own | ||
|
|
||
| This mechanism needs no Plugin. The file `index.php` reads the context from `config.context.php` next to it: |
Collaborator
There was a problem hiding this comment.
I think this needs a bit more explaining and context on how this works. There's a short section below, I think that should be extended to explain how this would work (i.e. have different directories per domains and link them to the same core with the config.core.php
Collaborator
There was a problem hiding this comment.
okay I see this is on the other page.. still feels like a vague introduction, perhaps just highlight the disctinction between approaches and link to it and skip the partial instructions
Mark-H
reviewed
Oct 20, 2026
| --- | ||
|
|
||
| This tutorial will demonstrate how to use a Context to create and manage a separate subdomain in a single Revolution install. We're going to create a subdomain at dev.modx.com (of course, not really, but you get the idea). | ||
| MODX 3 does not match a host with a context by itself. The gateway that starts a request chooses its context, so a second domain needs a second gateway: a directory with its own `index.php` and a `config.context.php` that names the context. |
Collaborator
There was a problem hiding this comment.
this suggests the virtual host approach is the only way to serve a second domain which just isn't true. the gateway plugin approach is much simpler for most people pointing multiple domains at the same virtual host; what was described in this page is a different approach where each domain has its own virtual host on the same machine.
title should probably be reverted to keep that distinction
Mark-H
reviewed
Oct 20, 2026
| The keys `mgr`, `web` and `root` are reserved by the core. | ||
|
|
||
| Note that new contexts don't automatically get "load" permission for Anonymous users in 2.2+ - you'll need to add that in manually. | ||
| A new context is granted access right away: the **Administrator** user group receives the *Context* policy, the anonymous user the *Load Only* policy — the right `load` and nothing else. The anonymous access is skipped when the request to the processor carries `enableAnonymous=0`. |
Collaborator
There was a problem hiding this comment.
"The anonymous access is skipped when the request to the processor carries enableAnonymous=0" should focus on the user not the underlying code. what is that property called in the UI?
Ibochkarev
added a commit
to Ibochkarev/Docs-MODX
that referenced
this pull request
Oct 21, 2026
Four remarks, all of them about how the page talks to the reader. **The two approaches to several domains were not told apart.** The page of the virtual host read as if it were the only way to serve a second domain. It now says that it describes the approach where every domain has a virtual host and a directory of its own on the same machine, and that when several domains point at one virtual host a Plugin picks the context instead — with a link to the other page. The title goes back to **Using Virtual Hosts**, which keeps that distinction. The URL of the page does not change. **The introduction of the gateway plugin page was vague.** It now opens with the two approaches side by side, says which one the page is about, and links to the other. The section that described the second approach in half is gone — the gateway plugin page is about the Plugin. **The gateway directory did not say what the copies have in common.** Three sentences now say that the copies of `index.php`, `config.core.php` and `.htaccess` point at the same core and the same database, and that only the context differs between the directories. **The anonymous access was described through the processor.** The page named the property `enableAnonymous=0` of the request. The reader sees the access in the manager: the entry of the anonymous user shows as **(anonymous)** in the **Access Permissions** tab of the context, and removing it there takes the access away. The Russian and the Spanish pages follow.
The section was written for MODX 2. The pages now describe what MODX 3
does, and the facts are taken from the code of the 3.x branch.
**Fixed**
- The path to the contexts is **Admin → Contexts** (`?a=context`), not
"System -> Contexts" and not a "Tools" menu — the menu of the core has
no `tools` entry at all (`_build/data/transport.core.menus.php:299`).
- The button of the grid is **Create**, not "Create New" — the lexicon
key `context_create` does not exist in 3.x
(`manager/assets/modext/widgets/core/modx.grid.js:1184`).
- The row menu of the grid offers **Edit**, not "Update Context"
(`manager/assets/modext/widgets/system/modx.grid.context.js:161`).
- The form of a new context asks for four fields: `key`, `name`,
`description` and `rank`; the first two are required
(`modx.grid.context.js:297-330`). The keys `mgr`, `web` and `root` are
reserved (`core/src/Revolution/modContext.php:31`).
- A new context is granted access right away: the **Administrator**
group gets the *Context* policy and the anonymous user gets the
*Load Only* policy (`core/src/Revolution/Processors/Context/Create.php:63-72,116-134`).
The page said the opposite — that the `load` permission has to be
added by hand since 2.2.
- The access to a context is granted on the **Contexts** tab of the
**Access Permissions** tab of a user group, reached through the lock
icon in the user menu → **Access Control Lists** — not through a
"Security/Permissions" menu, which does not exist in 3.x.
- The instruction to edit `$modx->initialize('web');` in `index.php` is
gone: the line does not exist in 3.x (`index.php:55-59` reads the
context key from `config.context.php` next to it).
- The file `core.config.php` is called `config.core.php`, and it holds
an absolute path to the core — the installer writes it that way
(`config.core.php:7`).
- The Apache block drops `NameVirtualHost` and `TransferLog`, both of
which are gone in Apache 2.4.
**Added**
- The two contexts of the core (`web` and `mgr`) and the constants
`CONTEXT_DEFAULT` and `CONTEXT_MANAGER`.
- The API: `switchContext()`, `getContext()`, `reloadContext()`,
`modContext::getOption()` and `makeUrl($id, $context)`. The
limitation of `switchContext()` — it does not load a custom session
handler, the gateway sets it — is stated.
- The events of the contexts, and a note that `OnContextSwitch`,
`OnSiteInit`, `OnSiteRender`, `OnManagerInit` and `OnBeforeRequest`
do not exist in MODX 3.
- The system settings that steer the contexts, with their values by
default.
- The processors of the contexts with the permission each one needs.
- The media source of an element per context, the table
`context_resource`, the values by default of the session settings,
and the order the `cultureKey` of a request is taken from.
**Rewritten**
- The page of the second domain opens with the fact that MODX 3 does
not match a host with a context by itself: the context is chosen by
the gateway. The recipe now builds the gateway with
`config.context.php`.
Both the Russian pages and the Spanish page of the section follow the
English one: the same headings, the same tables and the same examples.
Cut redundancy, lift the answers up, turn prose into lists and tables. - contexts.md: de-duplicate the session settings tables, turn the cultureKey precedence into a numbered list, point the session-handler warning at the gateway-plugin page - gateway-plugin.md: tighten the wording around the plugin example, make "The Session Handler" the single place where the rule is explained - virtual-host.md: turn the gateway directory setup into a numbered list of three steps No headings were renamed, so no anchors and no external links changed.
…ES locales The English pages went through an editorial pass; the Russian and the Spanish pages follow them with the same cuts: - the row about the session cookie is gone from the table of the settings a context overrides — those settings were named twice — and the defaults table keeps them with a lead sentence that says what they do; - the four sources of the `cultureKey` of a request are a numbered list in all three locales; - the session handler rule is stated once, in the gateway plugin page, and the contexts page links to it; - the gateway directory is a numbered list of three steps with the sample inside each step, and the table of the four files follows the order of the steps; - the heading of the session handler section in the Russian page is translated. The structure of the three locales is identical: the same headings, the same tables with the same number of rows and the same code examples.
…X 2 panel The two frames showed the Contexts grid and the "Crear Contexto" window of MODX 2. The page of the section is written for MODX 3 and no longer refers to them, so nothing points at them any more.
Four remarks, all of them about how the page talks to the reader. **The two approaches to several domains were not told apart.** The page of the virtual host read as if it were the only way to serve a second domain. It now says that it describes the approach where every domain has a virtual host and a directory of its own on the same machine, and that when several domains point at one virtual host a Plugin picks the context instead — with a link to the other page. The title goes back to **Using Virtual Hosts**, which keeps that distinction. The URL of the page does not change. **The introduction of the gateway plugin page was vague.** It now opens with the two approaches side by side, says which one the page is about, and links to the other. The section that described the second approach in half is gone — the gateway plugin page is about the Plugin. **The gateway directory did not say what the copies have in common.** Three sentences now say that the copies of `index.php`, `config.core.php` and `.htaccess` point at the same core and the same database, and that only the context differs between the directories. **The anonymous access was described through the processor.** The page named the property `enableAnonymous=0` of the request. The reader sees the access in the manager: the entry of the anonymous user shows as **(anonymous)** in the **Access Permissions** tab of the context, and removing it there takes the access away. The Russian and the Spanish pages follow.
Ibochkarev
force-pushed
the
docs/contexts
branch
from
October 23, 2026 05:11
3e91158 to
8f3d0f3
Compare
…untime The pages named fields the form does not show, listed an event that is not registered, and gave the session cookie a lifetime of 0.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Checked against MODX Revolution
313aabf84(22 October 2026).The contexts pages told a site builder to use field names, a cookie lifetime and an event that the manager and the runtime do not use. English, Russian and Spanish now follow the same rules.
Creating a context. The form labels are Context Key, Name, Description and Rank. The keys
mgr,webandrootare reserved. A key starts with a letter. After that it may contain letters, digits, a hyphen, a dot and a slash. An underscore is rejected, sodomain_2is not saved. Duplicate copies the settings, the access rules and the media sources. Duplicate resources is checked in that window and copies the resources. Clear the box to leave the resources where they are.Settings. A context setting overrides the system setting of the same name. A user group setting overrides the context setting. A user setting overrides the user group setting. The shipped
session_cookie_lifetimeis604800(7 days). A context can set0, and then the cookie lasts until the browser closes.Access. A user group's access panel has five tabs: Contexts, Resource Groups, Element Categories, Media Sources and Namespaces. A policy does not pick the tab. The policy template has to belong to the same group as the tab.
Language.
cultureKeycomes from the request, then the session, then the user setting, then the context, then the system setting. If every source is empty, or the value fails the character check, the language isen. The check allowsA-Z,a-z,0-9,_and-. In the manager,manager_languagereplaces that result.Switching.
switchContext()returns false when the context was not loaded, and when the key is already the current context. In the second case the context is not loaded again, soOnContextInitdoes not fire. On a request that is already indomain2, the failure check on the gateway page fails for that reason. Switching during the request leaves the language, the locale and the session cookie on the context thatindex.phpstarted in. A domain that needs its own language or cookie uses its own directory withconfig.context.php. The virtual-host page namessession_handler_classfor the handler of that gateway.Links and the tree. A link with
:context=is absolute when the named context is not the current one. A link withoutcontextstays relative when the resource belongs to the current context. When that resource belongs to another context, the link is the absolute URL of the context stored on the resource.default_context(web) is the context the create form uses when the resource is not created inside another context's branch. A branch of the tree uses that branch's context.context_tree_sortturns sorting of contexts in the resource tree on. The field iscontext_tree_sortby, shipped asrank.Russian and Spanish use that language's manager labels. The Spanish contexts page links without the
/current/en/prefix and setstranslationtobuilding-sites/contexts.Affected versions
3.x
Relevant issues
Left off the pages. Each one is a core defect, with the workaround or the correct behaviour written above:
OnContextUpdateis invoked when a context is saved in the manager and is not a registered event. The events table lists the registered context events.webin the processor. The page describes the create form and the tree branch.context_tree_sortdescription says the tree is sorted alphabetically. The page says the setting turns sorting on and the field iscontext_tree_sortby.use_context_resource_tableoff, loading a resource by request still consultscontext_resource. The page describes the table while the setting is on.Not checked
313aabf84.subctx1.pngis the tree image already in the repository. It was not reshot.