MILESTONE: introducing v2

Suppenhuhn79 · Apr 25, 2024 · 71e7934 · 71e7934
1 parent d9a0893
commit 71e7934
Show file tree

Hide file tree

Showing 5 changed files with 769 additions and 9 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1 +1,2 @@
 _config.yml
+~*
diff --git a/README.md b/README.md
@@ -10,7 +10,7 @@ pageSnippets is a JavaScript tool for dynamically and easily creating complex HT
 
 This short example to gives you a glimpse how easy it is to use pageSnippets.
 
-1) Compose your snippets as an XML file:
+1. Compose your snippets as an XML file:
 
 ```xml
 <?xml version="1.0" encoding="utf-8" standalone="yes"?>
@@ -21,25 +21,30 @@ This short example to gives you a glimpse how easy it is to use pageSnippets.
 </ps:pagesnippets>
 ```
 
-2) Include `pageSnippets.js` in your HTML file.
+2. Include `pageSnippets2.js` in your HTML file. (Note that the previous version 'pageSnippets.js' is deprecated and will be discontinued.)
+
 ```html
 <!DOCTYPE html>
 <html xmlns="http://www.w3.org/1999/xhtml">
-  <head>
-    <title>pageSnippets Demo</title>
-    <meta charset="utf-8" />
-    <script src="https://suppenhuhn79.github.io/pagesnippets/pagesnippets.js"></script>
-  </head>
+	<head>
+		<title>pageSnippets Demo</title>
+		<meta charset="utf-8" />
+		<script src="https://suppenhuhn79.github.io/pagesnippets/pagesnippets2.js"></script>
+	</head>
+</html>
 ```
-3) Have a short script that imports the snippet file. Produce the snippet and place it in the document.
+
+3. Have a short script that imports the snippet file. Produce the snippet and place it in the document.
+
 ```html
   <body>
     <script>
-      pageSnippets.import("snippet.xml").then(() => document.body.appendChild(pageSnippets.hello.produce()));
+      pageSnippets.import("snippet.xml").then(() => document.body.appendChild(pageSnippets.produce("hello")));
     </script>
   </body>
 </html>
 ```
+
 You're done.
 
 Of course there's more! Unleash its full power with [placeholders](https://github.com/Suppenhuhn79/pagesnippets/wiki/Placeholders), [conditions](https://github.com/Suppenhuhn79/pagesnippets/wiki/Conditions), [lists](https://github.com/Suppenhuhn79/pagesnippets/wiki/Lists) and much more. Find a full
@@ -48,3 +53,4 @@ reference in the [wiki](https://github.com/Suppenhuhn79/pagesnippets/wiki).
 ## Licence
 
 pageSnippets is licensed under the [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0).
+
diff --git a/pagesnippets.js b/pagesnippets.js
@@ -4,6 +4,9 @@ Copyright 2021 Christoph Zager, licensed under the Apache License, Version 2.0
 See the full license text at http://www.apache.org/licenses/LICENSE-2.0
  */
 
+/**
+ * @deprecated Use pagesnippets2.js instead.
+ */
 const pageSnippets =
 {
 	NAMESPACE_URI: "https://github.com/suppenhuhn79/pagesnippets",

diff --git a/pagesnippets2.d.js b/pagesnippets2.d.js
@@ -0,0 +1,25 @@
+/**
+ * @typedef PageSnippetsProductionData
+ * Data record that is used for producing a page snippet or any of a page snippets elements.
+ * @type {{[key: string]: any}}
+ *
+ * @callback PageSnippetsProductionCallback
+ * Function type that is used as callback in `ps:postproduction` attributes and `<ps:call-function>` nodes.
+ * @param {Element} element Currently processed target element.
+ * @param {PageSnippetsProductionData} data Data provided to build the target element.
+ *
+ * @typedef PageSnippetsMeta
+ * A page snippets meta data.
+ * @property {string} key Identifier key (including path) of that snippet.
+ * @property {string} source URL from which this snippet was loaded.
+ * @property {string} namespace Namespace URI of this snippets root node.
+ * @property {Element} data XML source data of that snippet.
+ *
+ * @callback PageSnippetsProductionFunction
+ * Function type used in production methods. This does not return any value but manipulate the `targetElement`object.
+ * @param {Element} sourceNode Source that defined the element that is currently build.
+ * @param {Element} targetElement Currently processed target element.
+ * @param {PageSnippetsProductionData} data Data provided to build the target element.
+ * @param {string} origin Listing of source document nodes that lead to this function call.
+ * @returns {void}
+ */