OpenCms URLs
From OpenCms Wiki
(Difference between revisions)
Cschoenfeld (Talk | contribs) m (→Hints) |
|||
| (17 intermediate revisions by 2 users not shown) | |||
| Line 3: | Line 3: | ||
The cause for misunderstanding and trouble is that translation pays attention to the ''current site'' of the request. When logged into the workspace the site can be changed with the ''Site'' select box at the top of the window. The current site of external requests (from outside the workspace) is determined automatically from the request URL. | The cause for misunderstanding and trouble is that translation pays attention to the ''current site'' of the request. When logged into the workspace the site can be changed with the ''Site'' select box at the top of the window. The current site of external requests (from outside the workspace) is determined automatically from the request URL. | ||
| − | + | == Formal URL Syntax and request URL translation process == | |
The formal syntax of OpenCms URLs can be written as follows: | The formal syntax of OpenCms URLs can be written as follows: | ||
| Line 15: | Line 15: | ||
PathCharacter ::= A valid file or directory name character | PathCharacter ::= A valid file or directory name character | ||
| − | + | The ''Site'' is matched against the servers defined in ''opencms-system.xml''. The matching site's ''uri'' attribute is selected as the ''current site'' for the request. | |
| − | URL: | + | |
| + | In order to finally determine the VFS resource path of the requested file OpenCms adds the ''uri'' attribute of the ''current site'' in front of the ''ResourcePath'' unless the ''uri'' attribute is equal to the ''current site'' of the browser session. | ||
| + | |||
| + | When a ''SystemPath'' is requested no translation is applied. | ||
| + | |||
| + | == Example == | ||
| + | Consider a request for the following URL on the OpenCms default installation: | ||
http://localhost:8080/opencms/opencms/sites/default/index.jsp | http://localhost:8080/opencms/opencms/sites/default/index.jsp | ||
| − | ''opencms-system.xml'': | + | where ''opencms-system.xml'' defines a single default site: |
<sites> | <sites> | ||
<workplace-server>http://localhost:8080</workplace-server> | <workplace-server>http://localhost:8080</workplace-server> | ||
| Line 26: | Line 32: | ||
</sites> | </sites> | ||
| − | The | + | The URL is parsed into the following elements: |
Site: http://localhost:8080 | Site: http://localhost:8080 | ||
ServletPath: /opencms/opencms | ServletPath: /opencms/opencms | ||
RequestPath: /sites/default/index.jsp | RequestPath: /sites/default/index.jsp | ||
| − | The '' | + | The final VFS resource path after URL translation is |
| + | * ''/sites/default/index.jsp'' if called from a logged in browser (e.g. from the Explorer) | ||
| + | * ''/sites/default/sites/default/index.jsp'' if called from a logged out browser (HTTP 404) | ||
| + | |||
| + | In order to retrieve the file ''/sites/default/index.jsp'' using a | ||
| + | * logged in browser with current site ''/'', the correct URL would be http://localhost:8080/opencms/opencms/sites/default/index.jsp | ||
| + | * logged in browser with current site ''/sites/default'', the correct URL would be http://localhost:8080/opencms/opencms/index.jsp | ||
| + | * logged out browser, the correct URL would be http://localhost:8080/opencms/opencms/index.jsp | ||
| + | |||
| + | === Explanation: The effects of URL translation === | ||
| − | + | Mind this rule of thumb: The ''ResourcePath'' of an OpenCms URL must be relative to the current site. | |
| − | + | As a side effect of this the URL of a file changes whenever the current site changes. | |
| − | + | Example: | |
| + | # Click on ''/sites/default/index.jsp'' while the current site is ''/''. A preview browser window opens showing the URL ''http://localhost:8080/opencms/opencms/sites/default/index.jsp''. | ||
| + | # Change the current site to ''/sites/default'' and hit reload in the preview window. You will see an error message. | ||
| + | # Click on ''/sites/default/index.jsp'' again. The preview browser window URL changes to ''http://localhost:8080/opencms/opemcms/index.jsp''. | ||
| − | + | Be mindful that your browser may be caching the HTML from previous visits to each URL, which might skew these results. To ensure that OpenCms is actually serving each request, set your browser to check for a newer version of each page on every visit, or press the Reload button. | |
| − | The | + | == Hints == |
| + | Setting the ''uri'' attribute of a site in ''opencms-system.xml'' to ''/'' has two effects. | ||
| + | * It disables the above mentioned rule of thumb. The current site for external requests will always be ''/''. External URLs no longer change. However, the rule still applies for internal URLs (clicks within the workplace). | ||
| + | * The complete VFS content is exposed to external visitors which might be undesirable for security reasons. The default configuration exposes only the content of ''/sites/default'' and protects the rest of the VFS content. The ''SystemPath'' is always exposed. | ||
Latest revision as of 08:52, 31 January 2007
The URL retrieval mechanism in OpenCms can be confusing to new users. When processing a request, OpenCms translates the requested URL to a VFS resource path before delivering the file.
The cause for misunderstanding and trouble is that translation pays attention to the current site of the request. When logged into the workspace the site can be changed with the Site select box at the top of the window. The current site of external requests (from outside the workspace) is determined automatically from the request URL.
Contents |
Formal URL Syntax and request URL translation process
The formal syntax of OpenCms URLs can be written as follows:
OpenCmsUrl ::= Site ServletPath RequestPath
Site ::= Protocol "://" Host ":" {Port}
ServletPath ::= "/" WebappName "/opencms"
RequestPath ::= SystemPath | ResourcePath
SystemPath ::= "/system/" ResourcePath
ResourcePath ::= "/" { [PathCharacter]+ "/"? }*
PathCharacter ::= A valid file or directory name character
The Site is matched against the servers defined in opencms-system.xml. The matching site's uri attribute is selected as the current site for the request.
In order to finally determine the VFS resource path of the requested file OpenCms adds the uri attribute of the current site in front of the ResourcePath unless the uri attribute is equal to the current site of the browser session.
When a SystemPath is requested no translation is applied.
Example
Consider a request for the following URL on the OpenCms default installation:
http://localhost:8080/opencms/opencms/sites/default/index.jsp
where opencms-system.xml defines a single default site:
<sites> <workplace-server>http://localhost:8080</workplace-server> <default-uri>/sites/default</default-uri> <site server="http://localhost:8080" uri="/sites/default"/> </sites>
The URL is parsed into the following elements:
Site: http://localhost:8080 ServletPath: /opencms/opencms RequestPath: /sites/default/index.jsp
The final VFS resource path after URL translation is
- /sites/default/index.jsp if called from a logged in browser (e.g. from the Explorer)
- /sites/default/sites/default/index.jsp if called from a logged out browser (HTTP 404)
In order to retrieve the file /sites/default/index.jsp using a
- logged in browser with current site /, the correct URL would be http://localhost:8080/opencms/opencms/sites/default/index.jsp
- logged in browser with current site /sites/default, the correct URL would be http://localhost:8080/opencms/opencms/index.jsp
- logged out browser, the correct URL would be http://localhost:8080/opencms/opencms/index.jsp
Explanation: The effects of URL translation
Mind this rule of thumb: The ResourcePath of an OpenCms URL must be relative to the current site.
As a side effect of this the URL of a file changes whenever the current site changes.
Example:
- Click on /sites/default/index.jsp while the current site is /. A preview browser window opens showing the URL http://localhost:8080/opencms/opencms/sites/default/index.jsp.
- Change the current site to /sites/default and hit reload in the preview window. You will see an error message.
- Click on /sites/default/index.jsp again. The preview browser window URL changes to http://localhost:8080/opencms/opemcms/index.jsp.
Be mindful that your browser may be caching the HTML from previous visits to each URL, which might skew these results. To ensure that OpenCms is actually serving each request, set your browser to check for a newer version of each page on every visit, or press the Reload button.
Hints
Setting the uri attribute of a site in opencms-system.xml to / has two effects.
- It disables the above mentioned rule of thumb. The current site for external requests will always be /. External URLs no longer change. However, the rule still applies for internal URLs (clicks within the workplace).
- The complete VFS content is exposed to external visitors which might be undesirable for security reasons. The default configuration exposes only the content of /sites/default and protects the rest of the VFS content. The SystemPath is always exposed.
