durbok/noodl-docs
1
0
Fork 0
mirror of https://github.com/noodlapp/noodl-docs.git synced 2026-01-11 23:02:54 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source 
Co-Authored-By: kotte <14197736+mrtamagotchi@users.noreply.github.com>
Co-Authored-By: mikaeltellhed <2311083+mikaeltellhed@users.noreply.github.com>
Co-Authored-By: Tore Knudsen <18231882+torekndsn@users.noreply.github.com>
Co-Authored-By: Michael Cartner <32543275+michaelcartner@users.noreply.github.com>
This commit is contained in:
Eric Tuvesson
2023-09-05 12:08:55 +02:00
commit 53f0d6320e
2704 changed files with 76354 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
javascript/extending/build-script/change-nodes-at-build-time.md Normal file
View File

@@ -0,0 +1,33 @@
---
title: Change nodes at build time
hide_title: true
---
<head>
<meta name="robots" content="noindex,nofollow,noarchive" />
</head>
# Change nodes at build time
:::note
This is recommended to only use in 2.7.x.
If using it in 2.6.x, you will change the current project
which will not be temporary during building.
:::
```js
module.exports = {
async onPreBuild(context) {
// Get all the "Function" nodes
const functionNodes = context.project.getNodesWithType('JavaScriptFunction');
functionNodes.forEach((node) => {
// Replace all "Hello World" to "Hello" in the scripts
node.parameters.functionScript = node.parameters.functionScript
.replace("Hello World", "Hello");
});
},
};
```

147
javascript/extending/build-script/overview.md Normal file
View File

@@ -0,0 +1,147 @@
---
title: Create a build script
hide_title: true
---
<head>
<meta name="robots" content="noindex,nofollow,noarchive" />
</head>
# Build scripts
Noodl has a way where you can hook into the different build events that
are triggered from the editor.
:::danger
This is an experimental feature, that might be changed in the future.
:::
### Where to use it?
- [Generate a Sitemap and static pages](/javascript/extending/build-script/sitemap-and-seo)
- [Change nodes at build time](/javascript/extending/build-script/change-nodes-at-build-time)
## Create a build script
To add a build script it has to be placed inside a folder in the project.
As long as the file ends with `.build.js` it will be picked up by Noodl.
The execution order of the build scripts are based on alphabetical order.
```
my-noodl-project/
.noodl/
build-scripts/
[HERE]
```
### Example
Here is an example of what kind of events you can listen to:
```js
module.exports = {
async onPreBuild(context) {
// Occurs before the build.
},
async onPostBuild(context) {
// Occurs after the build.
},
async onPreDeploy(context) {
// Occurs before the build is deployed.
},
async onPostDeploy(context) {
// Occurs after the build is deployed.
},
};
```
## What is Context?
Context is a little different in each method,
but generally have the same methods.
:::note
More documentation to come later!
:::
### General
```ts
workspaceId: string;
project: ProjectModel;
environment: {
name: string;
description: string;
masterKey: string;
appId: string;
} | undefined;
/**
*
* @param options
* @param callback
*/
activity(options: { message: string; successMessage?: string; }, callback: () => Promise<void>): Promise<void>;
/**
*
* @param type
* @param message
*/
notify(type: 'notice' | 'success' | 'error', message: string): void;
/**
* Returns a list of all the pages with absolute paths.
*
* @returns [
* {
* title: "page title",
* path: "/path-1/path-2",
* meta: {}
* },
* // ...
* ]
*/
getPages(options: {
expandPaths?: (route: RouteNode) => Promise<string[]>;
}): Promise<readonly PageObject[]>;
/**
* Create a index.html page similar to the one created for the web app.
*
* @returns a string containg the HTML code.
*/
createIndexPage(options: {
/**
* Override the title from project settings.
*
* Default: undefined
*/
title?: string;
/**
* Append the headcode from the project settings.
*
* Default: undefined
*/
headCode?: string;
}): Promise<string>;
/**
* Returns a traversal graph of the nodes.
*
* @param selector
* @returns
*/
graphTraverse(
selector: (node: NodeGraphModel.Node) => boolean,
options: NodeGraphTraverserOptions
): NodeGraphTraverser;
```

196
javascript/extending/build-script/sitemap-and-seo.md Normal file
View File

@@ -0,0 +1,196 @@
---
title: Build script that generate Sitemap and static pages
hide_title: true
---
<head>
<meta name="robots" content="noindex,nofollow,noarchive" />
</head>
# Generate a Sitemap and static pages
Having a `sitemap.xml` is very important for SEO,
so that search engines can build up a good map on the website.
With Noodl we can create build scripts that will alter the files after building.
What is really cool with this feature is that you can find all the information on
how the project is built, so we can find all the Pages nodes and generate a nice
sitemap and even create static index.html files to improve the SEO even more!
## Examples
Here are 2 examples of a script that generates a sitemap from all the pages.
### Static pages for Sitemap.xml
In case you don't have any dynamic pages, this script is really easy to use.
```js
const fs = require("fs");
/**
* Sitemap class that helps us build the sitemap XML.
*/
class Sitemap {
constructor() {
this.urls = [];
}
add(entry) {
this.urls.push(entry);
}
toXml() {
let xml = `<urlset
xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
xmlns:news="http://www.google.com/schemas/sitemap-news/0.9"
xmlns:xhtml="http://www.w3.org/1999/xhtml"
xmlns:image="http://www.google.com/schemas/sitemap-image/1.1"
xmlns:video="http://www.google.com/schemas/sitemap-video/1.1"
>`;
xml += this.urls
.map((item) => {
let entry = `<url>`;
Object.keys(item).forEach((key) => {
entry += `<${key}>${item[key]}</${key}>`;
});
return entry + `</url>`;
})
.join("");
return xml + `</urlset>`;
}
}
module.exports = {
async onPostBuild(context) {
/**
* this.getPages() returns a flat array of all the pages,
* like this:
*
* [
* {
* title: "page title",
* path: "/path-1/path-2",
* }
* ]
*
*/
const pages = await context.getPages();
// Create our Sitemap class
const sitemap = new Sitemap();
// Loop over all the pages
pages.forEach((page) => {
// Add the page to the sitemap with
// the sitemap tags we want to use.
//
// Here is what kind of tags there are:
// https://www.sitemaps.org/protocol.html
sitemap.add({
// NOTE: In this example the path is not an absolute URL, which is required to make sitemaps work correctly.
loc: page.path,
changefreq: "weekly",
priority: 0.5,
});
});
// Write our sitemap.xml to the outputPath
//
// if you are deploying via our cloud service
// this will also upload the file.
await fs.promises.writeFile(
`${context.outputPath}/sitemap.xml`,
sitemap.toXml()
);
},
};
```
### Dynamic pages for Sitemap.xml
To make this one work you have to provide the information required by Noodl
to understand what your dynamic pages have.
```js
// We can do that by sending more information to the "getPages" method.
const pages = await context.getPages({
// Async function that is called for each page that has variables.
async expandPaths(route) {
// Check the current page path.
if (route.current.path === "page-3/{id}") {
// Return a list of our expanded paths.
return [
{
title: "My custom title",
path: "page-3/0",
meta: {
description: "My description",
keywords: "",
},
},
{
path: "page-3/1",
},
{
path: "page-3/2",
},
];
}
// Return the default value.
// this will not be called unless there is a variable in the path.
// So we are returning an invalid path here.
return [
{
path: route.current.path,
},
];
},
});
// ...
// To access the meta data from the pages we can call
// pages[0].meta
```
### Generate static pages
We can expand on the previous example with dynamic pages for Sitemap.xml.
In this case we want to take all the information and write a index.html file
for each page.
```js
const fs = require('fs');
const path = require('path');
// ...
// Loop over all the pages
for (let index = 0; index < pages.length; index++) {
const page = pages[index];
// Create the filepath where we want to save the new index.html file.
const pageDir = path.join(context.outputPath, page.path);
// Generate a index.html file with our custom title and headcode.
const content = await context.createIndexPage({
title: page.title,
headCode: `
<meta name="description" content="${page.meta.description}">
<meta name="keywords" content="${page.meta.keywords}">
`,
});
// Create all the folders to the path.
await fs.promises.mkdir(pageDir, {
recursive: true,
});
// Save our new index.html file.
await fs.promises.writeFile(path.join(pageDir, "index.html"), content);
}
```

161
javascript/extending/create-lib.md Normal file
View File

@@ -0,0 +1,161 @@
---
hide_title: true
hide_table_of_contents: true
title: Create a new core node
---
# Create a new core node
Noodl is very extensible. As a developer you can add new modules with new capablities, create connections to data or make new visual components in your workspace. This guide gets us started by showing how the Noodl command line tool works and how to create an extension module with a single new node. This node will behave and appear just like the standard core nodes of Noodl.
:::note
This guide requires <a href="https://nodejs.org/en/download/" target="_blank">Node.js</a> and <a href="https://docs.npmjs.com/downloading-and-installing-node-js-and-npm" target="_blank">npm</a> installed.
:::
## Overview
This guide will walk you through how to create a **Noodl Module**. A Noodl Module can contain new core nodes to use in your projects. You can for example wrap an existing JavaScript library and expose it as a node in Noodl.
The general process works like this
* Set up a new **Module Project** where you can write the code for your module.
* Test your module in one of you projects while developing it.
* When you are done, build the module and deploy it to the projects you want to use it in.
## Install the Noodl CLI
First you need to install the Noodl command line interfaces. If you have not previously installed the CLI you can do so via npm.
```bash
npm install -g @noodl/noodl-cli
```
## Create a Module Project
With the CLI tool you can easily create a new Noodl module from a template:
```bash
noodl-cli new lib ./my-noodl-module
```
You need to specify a directory name that will be created. The directory will contain everything you need to get started. Using the command above, the directory _my-noodl-module_ will be created.
The newly created directory has the following structure:
```
my-noodl-module/
module/
project/
tests/
icon.png
module.json
```
First some notes on the content of a library module:
- The **module** directory contains the source code for the module as well as build scripts and any assets you might want, such as fonts, css etc.
- The **project** and **tests** folder can be ignored
First enter the **module** directory and install the needed dependencies:
```bash
cd module
```
```bash
npm install
```
If your module uses any other external libraries through NPM they will be installed as well.
## Developing your module
You develop your module mainly by editing the file ``module/src/index.js``. From start it contains some example code that you can use as a boiler plate. There is currently no official documenation of the Noodl module SDK but you can find the source code to a number of modules [here](https://github.com/noodlapp).
As you are developing your module you would want it packaged up and deployed in a Noodl project where you can test it. To do that you first have to create a new Noodl project that will be your test project. Once you've done that, find the local folder of that project by clickin the cogwheel ("Settings") and "Open project folder".
<div class="ndl-image-with-background m">
![](/javascript/extending/open-project-folder.png)
</div>
Copy the full path to that folder - you will need it in the next step.
Now open the file ``/module/src/webpack.config.js``. Among other things, this file specifies where to deploy the module. We want to make sure its deployed to our test project.
Update the row containing ``var outputPath = ...`` to the following
```javascript
var outputPath = path.resolve('<the absolute path that your project>', 'noodl_modules/' + pjson.name);
```
Now go back to your terminal window (that was located in the ``modules/`` folder) and write the following.
```bash
npm run dev
```
This will enter development mode where your module is automatically rebuilt and redeployed to your project when you make changes in the source code.
If you started from the boiler plate code in ``module/src/index.js`` you will already have a module now in your project. Reload the Noodl project by closing it and opening it again, or simply press ctrl+R (Windows) / cmd+R (Mac) when you are in the Node Editor. Then bring up the Node Picker and you should see your new core node under "External Libraries".
## Overview of the module code
The file _index.js_ contains the code for your nodes. Open it in your favorite editor and have a look. The file contains boilerplate code for a simple new core node, let's look at the different sections:
First you must import the Noodl SDK.
```javascript
const Noodl = require('@noodl/noodl-sdk');
```
Next you will define the code for the new node.
```javascript
const MyFullNameNode = Noodl.defineNode({
category: 'My Utils',
name: 'Full Name',
inputs: {
FirstName: 'string',
LastName: 'string',
},
outputs: {
FullName: 'string',
},
changed: {
FirstName: function () {
this.setOutputs({
FullName: this.inputs.FirstName + ' ' + this.inputs.LastName,
});
},
LastName: function () {
this.setOutputs({
FullName: this.inputs.FirstName + ' ' + this.inputs.LastName,
});
},
},
});
```
- You need to specify the **name** of the node, this is the name that shows up in the list when creating new nodes.
- you can optionally specify a **category**, this will also be used in the new node popup in Noodl.
Finally you need to define the specification of your module.
```javascript
Noodl.defineModule({
nodes: [MyFullNameNode],
setup() {
//this is called once on startup
},
});
```
Again, check out the [Noodl Repo](https://github.com/noodlapp) at GitHub for some module examples.
## Deploying your module
When you are happy with your module you can do a proper deploy. Go back to the terminal window (still in the ``modules/`` folder) and write.
```bash
npm run build
```
This deploys an optimized version of the module. If you want to use the module in a different project, just change the path in ``/module/src/webpack.config.js`` and do ```npm run build``` again.

117
javascript/extending/create-react-lib.md Normal file
View File

@@ -0,0 +1,117 @@
---
hide_title: true
hide_table_of_contents: true
title: Create a Visual node with React
---
# Create a Visual node with React
Noodl is built with React which makes it easy for you to add custom or community React components to your workspace. This guide will help you create a React library from scratch and push it to your Noodl workspace.
## Setup
In order to complete this guide you must install the _Noodl CLI_ and learn how to push the module to your workspace. Please review [this guide](/javascript/extending/create-lib) first.
With the CLI tool you can easily create a new react library module from a template:
```bash
noodl-cli new react-lib ./my-react-lib
```
You need to specify a directory name that will be created. The directory will contain everything you need to get started. Using the command above, the directory _my-react-lib_ will be created.
The newly created directory has the following structure:
```
my-react-lib/
module/
project/
tests/
icon.png
module.json
```
Just like in the introductory [guide](/javascript/extending/create-lib) the folder contains the **project** and **tests** subfolders that you may to import into Noodl. Especially the **tests** folder is a good place to play around with your library and create tests to make sure the component is working as expected.
:::note
It is important that you do not change the name of the **project** and **tests** folders. The build scripts in the _module_ folder is dependent on these names or it will not build the module properly and you cannot push to your workspace.
:::
## A tour of the code
Now you have created a new React library module from the template and you have pushed it to your Noodl workspace. Let's review the code a bit to get you up and running.
The react code can be found in the **module** directory.
```
my-react-lib/
module/
src/
index.js
assets/
manifest.json
package.json
webpack.config.js
project/
...
```
Open _index.js_ in your favorite editor. This file contains a simple React component and its export to Noodl. Each component that you want to be exposed in Noodl as a visual component, must be exported.
First a simple React component:
```javascript
function MyCustomReactComponent(props) {
const style = {
color: props.textColor,
backgroundColor: props.backgroundColor,
borderRadius: '10px',
padding: '20px',
marginBottom: props.marginBottom,
}
return (
<div style={style} onClick={props.onClick}>
{props.children}
</div>
)
}
```
Next the export of the component to Noodl:
```javascript
const MyCustomReactComponentNode = Noodl.defineReactNode({
name: 'Custom React Component',
category: 'Tutorial',
getReactComponent() {
return MyCustomReactComponent
},
inputProps: {
backgroundColor: { type: 'color', default: 'white' },
marginBottom: {
type: { name: 'number', units: ['px'], defaultUnit: 'px' },
default: 10,
},
},
outputProps: {
onClick: { type: 'signal', displayName: 'Click' },
},
})
```
In addition to how you would specify a simple Noodl node, as in the introductory [guide](/javascript/extending/create-lib), you must provide the _getReactComponent_ function that retuns the React component. You may also specify _inputProps_ and _outputProps_ that map to the properties of the React node and will become inputs and outputs of your Noodl node.
Outputs in React are typically done via callbacks. You can capture these callbacks and deliver them as outputs in Noodl.
Finally the component is provided as part of your module declaration. Here you need to put it under the _reactNodes_ section to make sure Noodl recognises it as a visual node.
```javascript
Noodl.defineModule({
reactNodes: [MyCustomReactComponentNode],
nodes: [],
setup() {
//this is called once on startup
},
})
```

36
javascript/extending/module/manifest.md Normal file
View File

@@ -0,0 +1,36 @@
# Module Manifest
:::note
WIP
:::
This document is all you need to know about what is required in the manifest.json file.
# React and Node Modules
```json
{
"name": "name",
"main": "index.js",
"dependencies": [
"http ..."
],
"runtimes": ["browser"]
}
```
## Iconset
```json
{
"name": "Material Icons",
"type": "iconset",
"browser":{
"stylesheets": ["https://fonts.googleapis.com/css2?family=Material+Icons"]
},
"iconClass": "material-icons",
"icons": ["10k", ...]
}
```

15
javascript/extending/overview.md Normal file
View File

@@ -0,0 +1,15 @@
---
hide_title: true
hide_table_of_contents: true
title: Extending Noodl
---
# Extending Noodl
One important aspect to improve productivity is extending your Noodl workspace with library modules that are tailored for your organizations needs.
[Create a new core node](/javascript/extending/create-lib)
This guide will show you how to install the Noodl CLI and create a single simple new core node in Noodl. This is a good starting point to cover before diving into the other guides.
[Create a React component](/javascript/extending/create-react-lib)
This guide will show you how to add React components to your Noodl workspace so that you can quickly build great front ends for your applications.