Resource Search Paths: If you have attended Adobe’s AEM or CQ5 developer training, they undoubtably told you that sling would look for components “First in /apps, then in /libs”. Well the truth is that sling will go down this list and look for resources by going through this list in order. Thus, things in /apps (unless specified using /libs at the beginning of the path) will be found first and that is why how that overlay works.
This can be helpful if, for some reason, you want to overlay something in /libs with a generic version of something (e.g. shared code you install on all projects) and then overlay again in /apps.
Still, I suggest leaving this setting alone. Many AEM developers are not aware of this configuration and can become confused if you change it.
Namespace Mangling: This is usually enabled by default. It replaces the “:” character in ‘jcr:content’ for instance with an _, and prefixes such items with another underscore. Thus, “jcr:content” becomes “_jcr_content”. As the description notes, this is because the colon character doesn’t get handled well in filenames or URLs on a number of systems. Even though it’s a valid character for a URL, it isn’t regularly a valid character in filenames which will cause issues for dispatcher down the line.
Allow Direct Mapping: This enabled (which it usually should be) injects a “org.apache.sling.jcr.resource.internal.helper.Mapping.DIRECT” object at the beginning of the mappings list, which supplies direct 1:1 url mapping according to the source. Note: even if you disable this, by default the property for URL Mappings (resource.resolver.mappings) is set to /-/, which is essentially the same as direct mapping. In general (for your own sanity in testing) you should leave this option on, especially if you are otherwise playing with URL mappings below.
Virtual URLS: Stored in a “org.apache.commons.collections.BidiMap” — I point this out because this is built into the system and a useful class to be aware of, allowing equally fast lookups for key->value or value->key. In this case, I’ve never really used this feature. The idea is to allow you to set up “fake” urls that get translated to “real” urls. NOTE: this is for URLs not paths. So a sample value would be
/my/vanity/url.html:/content/myproject/myhomepage.html
At this point, going to http://server/my/vanity/url.html would load the same thing as going to http://server/content/myproject/myhomepage.html
Because I haven’t used this much, I’m not sure how this setting responds to a multi-site install.
URL Mappings: Related to “Allow Direct Mappings” above — the resource resolver factory stores an internal array of Mapping objects. If allow Direct is set to true, it prefixes that mapping with one that is essentially identical to the “/:/” map that comes as default. A setting like “/content/myproject/home-page/:/” will inject /content/myproject/home-page as a prefix to all incoming requests. This can be useful for removing such path prefixes. Unfortunately, I’ve found it doesn’t play nice with everything. For instance, the ACS commons multifield widget will find things in the wrong location, etc. Mapping to “/” is the problem. It’s easier when you just shorten a prefix, e..g “/en/”, which as mapping against the root “/” path has a large range of possible conflicts and interactions.
Mapping Location: Defaults to /etc/map. Look at the documentation for sling mappings. This setting is used to have different mappings for author/publisher or different mappings for different environments, e.g. QA, Development, and Production servers.
Default Vanity Path Redirect Status: Defaults to “302”. When you have sling:redirect set to true on a resource with a sling:vanityPath set, the server will respond with this status code. Should be left alone. In recent projects, I’ve completely overridden the built-in redirect behavior to better handle SEO, server load, and caching. Using vanity redirects like this will prevent the dispatcher from caching the redirect path, resulting in extra server load. Thus, it’s better to detect this at the page level (without using sling:redirect at all) and output a JS-based redirect page using document.location.replace and setting a canonical URL — this also makes the back button work properly.
Enable Vanity Paths: Pretty self-explanatory. With this turned off, sling ignores the sling:vanityPath property. Internally, vanitypaths are added to a mapping table that is used by the resource resolver to do the mapping. If this is off, those paths are never added to the table, and thus not used for resource resolution.
Optimize alias resolution: Creates an internal cache of aliases, meaning that if a mapping is successful that result is cached to avoid as much computation in the future. But building the cache and updating it can also get expensive over time — but that’s extremely rare. This should almost always be left enabled.
Allowed Vanity Path Location: When sling looks for resources with sling:vanityPath set it only looks under the trees specified in this setting. By default, /apps/, /libs/, and /content/ are configured. If blank the whole repository is fair game.
Denied vanity path location: Overrides settings in the “allowed” setting. For instance, you can allow “/content/” but deny certain subpaths under /content using this setting — in fact, that’s the exact usage of the default “/content/usergenerated” setting.
Vanity Path Precedence: Normally, mappings that come from resources with a sling:vanityPath and mappings pulled from the sling mappings location are pulled into one big table and then sorted by the STRING LENGTH (craziness) of that mapping. This rather odd choice can result in some very bizarre behavior, especially fighting between vanity paths and mappings under /etc/map or your custom location. By enabling this setting, vanity paths take precedence. Defaults to false, I suggest setting it to true unless that causes you issues.
At this point, going to http://server/my/vanity/url.html would load the same thing as going to http://server/content/myproject/myhomepage.html
Because I haven’t used this much, I’m not sure how this setting responds to a multi-site install.
URL Mappings: Related to “Allow Direct Mappings” above — the resource resolver factory stores an internal array of Mapping objects. If allow Direct is set to true, it prefixes that mapping with one that is essentially identical to the “/:/” map that comes as default. A setting like “/content/myproject/home-page/:/” will inject /content/myproject/home-page as a prefix to all incoming requests. This can be useful for removing such path prefixes. Unfortunately, I’ve found it doesn’t play nice with everything. For instance, the ACS commons multifield widget will find things in the wrong location, etc. Mapping to “/” is the problem. It’s easier when you just shorten a prefix, e..g “/en/”, which as mapping against the root “/” path has a large range of possible conflicts and interactions.
Mapping Location: Defaults to /etc/map. Look at the documentation for sling mappings. This setting is used to have different mappings for author/publisher or different mappings for different environments, e.g. QA, Development, and Production servers.
Default Vanity Path Redirect Status: Defaults to “302”. When you have sling:redirect set to true on a resource with a sling:vanityPath set, the server will respond with this status code. Should be left alone. In recent projects, I’ve completely overridden the built-in redirect behavior to better handle SEO, server load, and caching. Using vanity redirects like this will prevent the dispatcher from caching the redirect path, resulting in extra server load. Thus, it’s better to detect this at the page level (without using sling:redirect at all) and output a JS-based redirect page using document.location.replace and setting a canonical URL — this also makes the back button work properly.
Enable Vanity Paths: Pretty self-explanatory. With this turned off, sling ignores the sling:vanityPath property. Internally, vanitypaths are added to a mapping table that is used by the resource resolver to do the mapping. If this is off, those paths are never added to the table, and thus not used for resource resolution.
Optimize alias resolution: Creates an internal cache of aliases, meaning that if a mapping is successful that result is cached to avoid as much computation in the future. But building the cache and updating it can also get expensive over time — but that’s extremely rare. This should almost always be left enabled.
Allowed Vanity Path Location: When sling looks for resources with sling:vanityPath set it only looks under the trees specified in this setting. By default, /apps/, /libs/, and /content/ are configured. If blank the whole repository is fair game.
Denied vanity path location: Overrides settings in the “allowed” setting. For instance, you can allow “/content/” but deny certain subpaths under /content using this setting — in fact, that’s the exact usage of the default “/content/usergenerated” setting.
Vanity Path Precedence: Normally, mappings that come from resources with a sling:vanityPath and mappings pulled from the sling mappings location are pulled into one big table and then sorted by the STRING LENGTH (craziness) of that mapping. This rather odd choice can result in some very bizarre behavior, especially fighting between vanity paths and mappings under /etc/map or your custom location. By enabling this setting, vanity paths take precedence. Defaults to false, I suggest setting it to true unless that causes you issues.
No comments:
Post a Comment
If you have any doubts or questions, please let us know.