Merge pull request #1 from DriveWorks/develop

Initial release (1.0.0)

Author: ConnorDriveWorks

LICENSE

@@ -0,0 +1,7 @@
+Copyright (C) 2021 DriveWorks Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this example and associated documentation files (the "Example"), to deal in the Example without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Example, and to permit persons to whom the Example is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Example.
+
+THE EXAMPLE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE EXAMPLE OR THE USE OR OTHER DEALINGS IN THE EXAMPLE.

LICENSE.md

@@ -1 +1,90 @@
-# IntegrationThemeExample-StylingWithCSS
+# Integration Theme Example:  Styling with CSS
+### Version: 1.0.0
+#### Minimum DriveWorks Version: 18.0
+
+A distributable example that demonstrates how to style DriveWorks controls using CSS.
+
+Please note: DriveWorks are not accepting pull requests for this example.  
+Join our [online community](https://my.driveworks.co.uk) for discussion, resources and to suggest other examples.
+
+### This example:
+- Demonstrates using basic metadata & CSS selectors, and further advanced styling that CSS enables.
+- Provides 2 DriveWorks Packages (.drivepkg), each containing an example Project that demonstrate use of the Metadata property and styling various properties.
+    - **BasicStyles18.drivepkg** - Demonstrates using metadata & basic CSS selectors to target DriveWorks controls (see also: /basic-styles/style.css)
+    - **AdvancedStyles18.drivepkg** - Demonstrates some possibilities for advanced styling made available via CSS (see also: /advanced-styles/advanced-styles.css)
+
+The CSS selectors/styles demonstrated can be viewed without installing the provided Projects, for quick reference. Simply open the included `.css` files.
+
+### /basic-styles
+
+![Basic Example](/images/basic.png)
+
+- Creates a new Specification
+- Loads in a custom stylesheet (/basic-styles/style.css)
+- Styles a single button control - using the Project 'BasicStyles18'
+- Demonstrates:
+    - Targeting controls with the `Metadata` property (data-metadata)
+    - Using CSS Attribute Selectors
+    - Rounded Corners (border-radius)
+    - Shadows (box-shadow)
+    - Animating styles (transition)
+    - Rotate and Scale (transform)
+    - Gradients (linear-gradient)
+    - Hover styles (:hover)
+    - Styling child elements
+
+### /advanced-styles
+
+![Advanced Example](/images/advanced.png)
+
+- Creates a new Specification
+- Loads in an alternate custom stylesheet (/advanced-styles/advanced-styles.css)
+- Styles multiple controls - using the Project 'AdvancedStyles18'
+- Demonstrates:
+    - Various button styles
+    - CSS Transforms (rotate/scale/skew)
+    - CSS Filters (blur, grayscale)
+    - Animating position changes
+
+### To use:
+1. Clone this repository, or download as a .zip
+
+2. Extract each of the supplied .drivepkg files using the DriveWorks Package Wizard to access the included Project files.
+
+3. Open the extracted Groups in DriveWorks Administrator and use 'Form Design' to view each Controls and its properties.
+    * Most importantly: the 'Metadata' properties that are targeted via CSS.
+
+4. In `DriveWorksLiveConfigUser.xml`, add a new Group Alias for the each new Group containing the example Projects.
+    * See [Integration Theme Settings](https://docs.driveworkspro.com/Topic/IntegrationThemeSettings) for additional guidance.
+
+5. Open the extracted Groups in DriveWorks Live and start the Integration Theme.
+    * See [Selecting the Integration Theme](https://docs.driveworkspro.com/Topic/IntegrationThemeSelect) for additional guidance.
+
+6. Enter your Integration Theme details into `config.js` for each example.
+    * `serverUrl` - The URL that hosts your Integration Theme, including any ports.
+    * `groupAlias` - The public alias created for the Group containing the DriveApps to render - as configured in DriveWorksConfigUser.xml.
+        * This *must* be specified for each Group you wish to use.
+        * This allows you to mask the true Group name publicly, if desired.
+        * See [Integration Theme Settings](https://docs.driveworkspro.com/Topic/IntegrationThemeSettings) for additional guidance.
+    * `projectName` - The name of the Project to render a Specification from.
+        * These are pre-filled with supplied Project names, but can be changed if required.
+
+7. Open the example HTML files locally (localhost) or on a remote server.
+    * Ensure `<corsOrigins>` in DriveWorksConfigUser.xml permits request from this location.
+    See [Integration Theme Settings](https://docs.driveworkspro.com/Topic/IntegrationThemeSettings) for additional guidance.
+
+8. If encountering any issues, check the browser's console for error messages (F12)
+
+### Potential Issues:
+* When serving this example for a domain different to your DriveWorks Live server, e.g. api.my-site.com from company.com, 'SameSite' cookie warnings may be thrown when the Client SDK attempts to store the current session id.
+    * This appears as "Error: 401 Unauthorized" in the browser console, even with the correct configuration set. 
+    * To resolve:
+        * Ensure you are running DriveWorks 18.2 or above, HTTPS is enabled in DriveWorks Live's settings and a valid SSL certificate has been configured via DriveWorksConfigUser.xml.
+        * See [Integration Theme Settings](https://docs.driveworkspro.com/Topic/IntegrationThemeSettings) for additional guidance.
+
+---
+
+This source code has been made available to demonstrate how you can integrate with DriveWorks using the DriveWorks Live API.
+This code is provided under the MIT license, for more details see LICENSE.md.
+
+The example requires that you have the latest DriveWorks Live SDK installed, operational and remotely accessible.

README.md

@@ -0,0 +1,133 @@
+/* 
+
+  Example Styles
+  --------------
+
+  This example demonstrates further styling opportunities when using the "Metadata" property in DriveWorks.
+  These styles can be combined, tweaked and removed - this aims only to provide inspiration.
+
+  IMPORTANT NOTE: CSS styles should be seen as a 'progressive enhancement'.
+  Your Forms should function fully without these additional styles, as they may not be loaded in all environments the Integration is accessed.
+
+  For more detailed information on these selectors, see: https://developer.mozilla.org/en-US/docs/Web/CSS/Attribute_selectors
+
+  ## Note: the use of !important allows the default inline styles to be overwritten (style="...") - and should be used carefully.
+  For more information, see: https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity#The_!important_exception
+
+*/
+
+/* Set re-usable colours - update in one central location, apply to many rules */
+:root {
+  --color-brand-primary: #4299e1;
+  --color-brand-secondary: #48bb78;
+}
+
+/* Global button default style */
+[data-metadata*="button"] button {
+  background: none !important; /* ## See note above when using !important */
+  border: none !important;
+  cursor: pointer !important;
+}
+
+/* Background color */
+[data-metadata*="button"] {
+  background-color: var(--color-brand-primary);
+}
+
+/* Text color */
+[data-metadata*="button"] [data-id*="CaptionElement"] {
+  color: #fff !important;
+}
+
+/* Rounded Button */
+[data-metadata*="rounded"] {
+  border-radius: 5px;
+}
+
+/* 'Pill' Button */
+[data-metadata*="pill"] {
+  border-radius: 100em;
+}
+
+/* Inactive Button */
+[data-metadata*="inactive"] {
+  opacity: 50% !important;
+}
+[data-metadata*="inactive"] button {
+  cursor: not-allowed !important;
+}
+
+/* Change color on hover, with ease */
+[data-metadata*="hover-green"]:hover {
+  background-color: var(--color-brand-secondary);
+}
+
+/* Lighten on hover */
+[data-metadata*="hover-light"]:hover {
+  filter: brightness(115%);
+}
+
+/* Darken on hover */
+[data-metadata*="hover-dark"]:hover {
+  filter: brightness(85%);
+}
+
+/* Circle */
+[data-metadata*="circle"] {
+  border-radius: 50%;
+}
+
+/* Border Styles */
+[data-metadata*="border-dashed"] {
+  border: 1px dashed #aaa !important;
+}
+
+/* Drop Shadow */
+[data-metadata*="shadow"] {
+  box-shadow: 0 2px 10px rgba(0,0,0,.5);
+}
+
+/* Background Gradient */
+[data-metadata*="gradient"] {
+  background: linear-gradient(45deg, #833ab4 0%, #4299e1 100%);
+}
+
+/* Custom Shape (clip-path) */
+[data-metadata*="shaped"] {
+  clip-path: polygon(5% 0, 100% 0%, 95% 100%, 0% 100%);
+}
+
+/* Blur */
+[data-metadata*="blur"] {
+  filter: blur(3px);
+}
+
+/* Rotate */
+[data-metadata*="rotate"] {
+  transform: rotate(10deg);
+}
+
+/* Scale */
+[data-metadata~="scale"] {
+  transform: scale(0.5);
+}
+
+/* Skew */
+[data-metadata*="skew"] {
+  transform: skewX(-15deg);
+}
+
+/* Grayscale */
+[data-metadata*="grayscale"] {
+  filter: grayscale(1);
+}
+
+/* Animate background color */
+[data-metadata*="animate-background"] {
+  transition: background-color .5s ease;
+}
+
+/* Animate position */
+[data-metadata*="animate-position"] {
+  transition: left .5s ease;
+}

advanced-styles/AdvancedStyles18.drivepkg

@@ -0,0 +1,6 @@
+// Config
+const config = {
+    serverUrl: "",
+    groupAlias: "",
+    projectName: "AdvancedStyles18",
+};

advanced-styles/advanced-styles.css

@@ -0,0 +1,61 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Advanced Styling with CSS | DriveWorks</title>
+
+    <!-- Comment/remove the line below to view the Form in it's original state -->
+    <link rel="stylesheet" href="advanced-styles.css" />
+</head>
+
+<body>
+
+    <div id="form-output">
+        Advanced styles example loading...
+    </div>
+
+    <script src="config.js"></script>
+    <script>
+        const output = document.getElementById("form-output");
+
+        // Run on client load
+        async function dwClientLoaded() {
+            try {
+
+                // Create DriveWorks API client
+                const DW_CLIENT = new window.DriveWorksLiveClient(config.serverUrl);
+
+                // Login to group
+                await DW_CLIENT.loginGroup(config.groupAlias);
+
+                // Create Specification
+                const specification = await DW_CLIENT.createSpecification(config.groupAlias, config.projectName);
+
+                // Render Specification
+                output.innerHTML = "";
+                await specification.render(output);
+
+            } catch (error) {
+                console.log(error);
+                output.innerHTML = error;
+            }
+        }
+    </script>
+
+    <!-- Option A) Directly load Client Library -->
+    <!-- <script src="https://YOUR-THEME-SERVER.COM/DriveworksLiveIntegrationClient.min.js" onload="dwClientLoaded()"></script> -->
+
+    <!-- Option B) Inject Client Library dynamically from server url in config file -->
+    <script>
+        (function(doc, script) {
+            script = doc.createElement("script");
+            script.src = config.serverUrl + "/DriveWorksLiveIntegrationClient.min.js";
+            script.onload = () => dwClientLoaded(); // Custom local function run when client has loaded
+            doc.body.appendChild(script);
+        }(document));
+    </script>
+
+</body>
+</html>

advanced-styles/config.js

@@ -0,0 +1,6 @@
+// Config
+const config = {
+    serverUrl: "",
+    groupAlias: "",
+    projectName: "BasicStyles18",
+};

advanced-styles/index.html

@@ -0,0 +1,59 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Basic Styling with CSS | DriveWorks</title>
+
+    <!-- Comment/remove the line below to view the Form in it's original state -->
+    <link rel="stylesheet" href="style.css" />
+</head>
+
+<body>
+
+    <div id="form-output">
+        Basic styles example loading...
+    </div>
+
+    <script src="config.js"></script>
+    <script>
+        const output = document.getElementById("form-output");
+
+        // Run on client load
+        async function dwClientLoaded() {
+            try {
+                // Create DriveWorks API client
+                const DW_CLIENT = new window.DriveWorksLiveClient(config.serverUrl);
+
+                // Login to group
+                await DW_CLIENT.loginGroup(config.groupAlias);
+
+                // Create Specification
+                const specification = await DW_CLIENT.createSpecification(config.groupAlias, config.projectName);
+
+                // Render Specification
+                output.innerHTML = "";
+                await specification.render(output);
+            } catch (error) {
+                console.log(error);
+                output.innerHTML = error;
+            }
+        }
+    </script>
+
+    <!-- Option A) Directly load Client Library -->
+    <!-- <script src="https://YOUR-THEME-SERVER.COM/DriveworksLiveIntegrationClient.min.js" onload="dwClientLoaded()"></script> -->
+
+    <!-- Option B) Inject Client Library dynamically from server url in config file -->
+    <script>
+        (function(doc, script) {
+            script = doc.createElement("script");
+            script.src = config.serverUrl + "/DriveWorksLiveIntegrationClient.min.js";
+            script.onload = () => dwClientLoaded(); // Custom local function run when client has loaded
+            doc.body.appendChild(script);
+        }(document));
+    </script>
+
+</body>
+</html>