FOAM Metaprogramming Framework

Common errors

• Error: Cannot find module 'foam-framework'

  cause Attempting to import or require `foam-framework` as a CommonJS or ESM module.
  fix FOAM is not designed for module imports. Load it via a script tag in HTML (`<script src="path/to/foam.js"></script>`) or use its dedicated build tools to generate deployable files.

• ReferenceError: FOAM is not defined

  cause The `FOAM` global object is not available because the framework's script was not loaded, or it was loaded incorrectly, or code is trying to access it before the script has executed.
  fix Ensure the `foam.js` script is correctly linked in your HTML (`<script src="path/to/foam.js"></script>`) and that any code accessing `FOAM` runs *after* the script has fully loaded and executed. Verify the path to `foam.js` is correct.

• SyntaxError: Unexpected token '...' (or other modern JavaScript syntax errors)

  cause Running FOAM's codebase or generated output in an environment (e.g., an older Node.js version or specific browser) that does not support the JavaScript features it uses, or conversely, running old FOAM code in a new environment without proper transpilation.
  fix Ensure the environment's JavaScript engine (browser or Node.js) is compatible with the version of JavaScript FOAM was written in. If using a newer environment, be aware that FOAM's code might contain deprecated patterns or lack support for modern syntax.

Warnings

• breaking FOAM is likely incompatible with modern JavaScript syntax (ES2015+) and recent Node.js versions. Its development predates many contemporary language features and runtime advancements, potentially leading to syntax errors or runtime issues.
  Fix: This framework is generally not recommended for new projects. For existing projects, consider a full migration to a modern framework or extensive polyfilling and environment setup if strict compatibility is required.
• gotcha The framework operates by exposing itself globally (e.g., `window.FOAM`) when loaded via script tags. This can lead to global scope pollution and potential conflicts with other libraries or scripts that might use similar global variable names.
  Fix: Carefully manage the order of script loading and be aware of potential global namespace clashes. Isolate FOAM usage where possible or wrap it within an immediately invoked function expression (IIFE) if supported, though the latter might interfere with its internal bootstrapping.
• gotcha FOAM does not support modern JavaScript module systems (CommonJS, ESM). Attempts to `import` or `require` modules from the `foam-framework` npm package will fail, as it expects direct script inclusion or use of its build tools.
  Fix: Utilize the intended method of inclusion via `<script>` tags in HTML or by running its dedicated build tool (`nodejs tools/foam.js`) to generate bundled files. Do not try to integrate it directly into projects using `import` or `require`.
• gotcha The project appears to be abandoned or no longer actively maintained, given its low version number (0.5.0), outdated documentation references (Google Groups), and absence of recent updates. This implies a lack of security patches, bug fixes, or compatibility updates for newer environments.
  Fix: Avoid using FOAM for new development. For critical legacy applications, be aware of the inherent risks related to unpatched vulnerabilities and potential instability in modern environments. Plan for eventual migration.
• gotcha The build process, described using a `nodejs tools/foam.js` command, is not integrated with modern front-end build pipelines (e.g., Webpack, Rollup, Vite). This can complicate integration into contemporary development workflows and dependency management.
  Fix: The build tool must be run separately as a command-line script. Integrating its output into modern build systems might require custom asset pipelines or manual steps to include the generated `foam.js` and `foam.html` files.

Install

• npm install foam-framework npm
• yarn add foam-framework yarn
• pnpm add foam-framework pnpm

Imports

• FOAM
  wrong:

  import { FOAM } from 'foam-framework';
  const FOAM = require('foam-framework');

  correct:

  <!-- Load foam.js into an HTML page -->
  <script src="path/to/foam.js"></script>
  <!-- FOAM will then be available globally, e.g., window.FOAM -->

  FOAM is primarily designed for global script inclusion in HTML environments, making the `FOAM` object available on the `window` object. It does not support modern JavaScript module systems like CommonJS or ESM for direct programmatic imports from the npm package.

Quickstart

Demonstrates how to use the framework's `foam.js` build tool to generate a bundled application from a specified controller model for deployment.

nodejs tools/foam.js foam.build.BuildApp controller=my.controller.Model targetPath=. 

// This command runs the FOAM build tool to generate a bundled application. 
// 'my.controller.Model' should be replaced with the actual path to your application's main controller model. 
// The 'targetPath' specifies where the output (e.g., foam.js and foam.html) will be placed.