add an example illustrating how to integrate a dynamic react component

Author: lovasoa

examples/official-site/sqlpage/migrations/01_documentation.sql

@@ -378,6 +378,8 @@ INSERT INTO parameter(component, name, description, type, top_level, optional) S
     ('title', 'The title of your page. Will be shown in a top bar above the page contents. Also usually displayed by web browsers as the name of the web page''s tab.', 'TEXT', TRUE, TRUE),
     ('description', 'A description of the page. It can be displayed by search engines when your page appears in their results.', 'TEXT', TRUE, TRUE),
     ('link', 'The target of the link in the top navigation bar.', 'URL', TRUE, TRUE),
+    ('css', 'The URL of a CSS file to load and apply to the page.', 'URL', TRUE, TRUE),
+    ('javascript', 'The URL of a Javascript file to load and execute on the page.', 'URL', TRUE, TRUE),
     ('image', 'The URL of an image to display next to the page title.', 'URL', TRUE, TRUE),
     ('icon', 'Name of an icon (from tabler-icons.io) to display next to the title in the navigation bar.', 'TEXT', TRUE, TRUE),
     ('menu_item', 'Adds a menu item in the navigation bar at the top of the page. The menu item will have the specified name, and will link to as .sql file of the same name.', 'TEXT', TRUE, TRUE),

examples/using react and other custom scripts and styles/README.md

@@ -0,0 +1,19 @@
+# Custom javascript and CSS
+
+This example shows how to use custom javascript and CSS in your application.
+
+It integrates a simple [react](https://reactjs.org/) component and loads it with properties coming from a SQL query.
+
+## Screenshots
+
+![example SQLPage application with a custom style](screenshot-css.png)
+
+![example client-side reactive SQLPage application with React](screenshot-react.png)
+
+## Notes
+
+This example relies on a CDN to load the react library, and the example component is written in plain Javscript, not JSX.
+
+You can also use include a local copy of react, and write your components in JSX/TSX,
+you will simply need to add a build step to your application to compile the JSX/TSX files into plain JS,
+and then include that build result in your application.

examples/using react and other custom scripts and styles/index.sql

@@ -0,0 +1,7 @@
+SELECT 'shell' AS component,
+    'SQLPage with a frontend component' as title,
+    'style.css' as css,
+    'settings' as icon;
+
+SELECT 'text' AS component, 'funky_text' AS id;
+SELECT 'Try my react component !' AS contents, 'react.sql' AS link;

examples/using react and other custom scripts and styles/my_react_component.js

@@ -0,0 +1,17 @@
+// Here we are using React and ReactDOM directly, but this file could be a compiled
+// version of a React component written in JSX.
+
+function RootComponent({ greeting_name }) {
+    const [count, setCount] = React.useState(0);
+    return React.createElement(
+        'button',
+        { onClick: () => setCount(count + 1), className: 'btn btn-primary' },
+        `Hello ${greeting_name}, you clicked me ${count} times!`
+    );
+}
+
+for (const container of document.getElementsByClassName('react_component')) {
+    const root = ReactDOM.createRoot(container);
+    const props = JSON.parse(container.dataset.props);
+    root.render(React.createElement(RootComponent, props, null));
+}

examples/using react and other custom scripts and styles/react.sql

@@ -0,0 +1,14 @@
+SELECT 'shell' AS component,
+    'SQLPage with a frontend component' AS title,
+    'settings' AS icon,
+
+    -- Including react from a CDN like that is quick and easy, but if your project grows larger,
+    -- you might want to use a bundler like webpack, and include your javascript file here instead
+    'https://cdn.jsdelivr.net/npm/[email protected]/umd/react.production.min.js' AS javascript,
+    'https://cdn.jsdelivr.net/npm/[email protected]/umd/react-dom.production.min.js' AS javascript,
+    'my_react_component.js' AS javascript;
+
+SELECT 'react_component' AS component,
+    JSON_OBJECT(
+        'greeting_name', 'World'
+    ) AS props;

examples/using react and other custom scripts and styles/screenshot-css.png

@@ -0,0 +1,3 @@
+<div class="react_component" data-props="{{props}}">
+  Dynamic component is loading...
+</div>

examples/using react and other custom scripts and styles/screenshot-react.png

@@ -0,0 +1,33 @@
+#funky_text {
+  font-family: Arial, sans-serif;
+  font-size: 36px;
+  color: white;
+  background: linear-gradient(45deg, #ff4e00, #ec9f05);
+  padding: 10px;
+  border-radius: 10px;
+  box-shadow: 0 2px 5px rgba(0, 0, 0, 0.3);
+  transition: transform 0.3s ease-in-out;
+}
+
+#funky_text:hover {
+  transform: scale(1.1);
+  background: linear-gradient(45deg, #e5004d, #7a0180);
+  box-shadow: 0 4px 8px rgba(0, 0, 0, 0.5);
+}
+
+@keyframes neon-glow {
+  0%, 100% {
+    text-shadow: 0 0 10px #fa2dd1, 0 0 20px #b30890, 2px 3px 30px #ff00cc;
+  }
+  50% {
+    text-shadow: 0 0 1px #e48fd3, 0 0 2px #ca28aa, 0 0 8px #ff00cc;
+  }
+}
+
+#funky_text:hover {
+  animation: neon-glow .5s ease-in-out infinite;
+}
+
+#funky_text * {
+    color: inherit;
+}