[GitHub] [sling-site] oliverlietz commented on a change in pull request #67: SLING-10733 consolidate script documentation

[GitBox <gi...@apache.org>]

oliverlietz commented on a change in pull request #67:
URL: https://github.com/apache/sling-site/pull/67#discussion_r688916510



##########
File path: src/main/jbake/content/documentation/bundles/scripting.md
##########
@@ -67,9 +67,143 @@ Mapping `html` to Thymeleaf 3.0:
       "html=Thymeleaf:3.0"
     ]
 
+## Scripts are Servlets
+
+The Sling API defines a `SlingScript` interface which is used to represent (executable) scripts inside of Sling. This interface is implemented in the [Scripting Core bundle][8] in the `DefaultSlingScript` class which also implements the `javax.servlet.Servlet`.
+
+To further simplify the access to scripts from the Resource tree, the `scripting/core` bundle registers an `AdapterFactory` to adapt Resources to Scripts and Servlets (the `SlingScriptAdapterFactory`). In fact the adapter factory returns instances of the `DefaultSlingScript` class for both Scripts and Servlets.
+
+From the perspective of the [Servlet resolver][7], scripts and servlets are handled exactly the same. In fact, internally, Sling only deals with Servlets, whereas scripts are packed inside a Servlet wrapping and representing the script.
+
+## Resource Scripts
+
+Scripts are looked up in a series of resource resolver locations defined by the `ResourceResolver.getSearchPath()` and the resource type (and resource super types) of the requested resource: 
+
+    {scriptPathPrefix}/{resourceTypePath} 
+    
+The pseudo code for iterating the locations would be something like: 
+    
+
+    var type = resource.getResourceType(); 
+    while (type != null) { 
+        for (String root: resourceResolver.getSearchPath()) { 
+            String path = root + type.toPath(); 
+            findScriptsIn(path); 
+        } 
+
+        if (type == defaultServlet) { 
+            type = null; 
+        } else { 
+            type = getResourceSuperType(type); 
+            if (type == null) { 
+                type = defaultServlet; 
+            } 
+        } 
+    } 
+
+### Resource script naming conventions
+
+Depending on whether request selectors are considered, a script may have two forms: 
+
+1. Ignoring request selectors (e.g. there are none in the request URI): `{resourceTypeLabel}.{requestExtension}.{requestMethod}.{scriptExtension}` 
+2. Handling request selectors: `{selectorStringPath}.{requestExtension}.{requestMethod}.{scriptExtension}`
+
+The constituents of these script names are as follows: 
+
+* `{resourceTypeLabel}` - The last path segment of the path created from the resource type. This part is optional if the `{requestExtension}` is used in the script name. The resource type might either be set via the `sling:resourceType` property on the accessed node or if that property is not there its primary node type (property `jcr:primaryType`) is taken as fall-back.
+* `{requestExtension}` - The request extension. This part may be omitted if the request extension is `html`, otherwise this part is required. If this part is omitted, the `{resourceTypeLabel}` is required in the case of ignoring the selectors.
+* `{requestMethod}` - The request's HTTP method. This part may be omitted if the script is meant for a `GET` or a `HEAD` request. This part is required for any other HTTP method.
+* `{scriptExtension}` - The extension identifying the scripting language used. This part is mandatory. For more details about the available Script Engines and their registered extensions check the [Sling Scripting](/documentation/bundles/scripting.html) page.
+* `{selectorStringPath}` - The selector string converted to a path, along the lines of `selectorString.replace('.', '/')`. If less selectors are specified in the script name than given in the request, the script will only be taken into consideration if the given selectors are the **first** selectors in the request. This means *sel1/sel2.html.jsp* will be a candidate for the request url */content/test.sel1.sel2.sel3.html* but not for */content/test.sel3.sel1.sel2.html*. So the order of selectors is relevant!
+
+
 ## Bundled Scripts
 
-Scripts may also be provided in OSGi bundles (precompiled or embedded) since [Sling Servlet Resolver 2.7.0](https://github.com/apache/sling-org-apache-sling-servlets-resolver#bundled-scripts).
+Scripts may also be provided in OSGi bundles (precompiled or embedded) since [Sling Servlet Resolver 2.7.0](https://github.com/apache/sling-org-apache-sling-servlets-resolver#bundled-scripts) through the org.apache.sling.servlets.resolver.bundle.tracker API in addition to classical Resource based scripts.
+
+Although traditionally scripts are deployed as content stored in the search paths of a Sling instance, this leaves very little
+room for script evolution in a backwards compatible way. Furthermore, versioning scripts is a difficult process if the only
+mechanism to do this is the `sling:resourceType` property, since consumers (content nodes or other resource types) have then to
+explicitly mention the version expected to be executed.
+
+Scripts should not be considered content, since their only purpose is to actually generate the rendering for a certain content
+structure. They are not consumed by users, but rather by the Sling Engine itself and have very little meaning outside this
+context. As such, scripts should be handled like code:
+
+  1. they _provide an HTTP API_;

Review comment:
       _HTTP API_ is quite generic and should be clarified. _HTTP API_ in what sense? Examples?




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@sling.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org