Code examples

This folder contains all code examples, that Handsontable uses for a myriad of reasons, such as documentation, blog, etc. Each code example is a separate project that uses Handsontable to present certain features.

Code examples are structured by Handsontable version. Inside the version directory, examples are grouped by category, which can be anything. The most important category is "docs", which is used in the Handsontable documentation website.

To see a deployed code example you can visit its URL. See Live on production section to learn about the URL structure.

To run arbitrary code example locally on your machine see How to run the arbitrary code example section.

Contents

• Folder structure
• Live on production
• Creating new examples
• Deployment
• Editing existing examples
• Copying an example to a separate repo
• Development
  • How to run the arbitrary code example
• Testing
  • How to tun tests for arbitrary code example
  • How to run tests for the versioned code examples locally

Folder structure

Within the /examples directory, there are all the code examples created for specific Handsontable version and the templates folder, which contains base projects for creating new code examples. A path to the example follow the undermentioned convention:

/examples/<version_number>/<category>/<framework>/<example_path>

• <version_number> - the destributed version of the Handsontable and Handsontable's wrapper or next - the value provided to the NPM scripts as the last argument.
• <category> - category of the code examples. The main category is docs which means: code examples from the documentation.
• <framework> - any supported framework's name (react, angular, vue, js).
• <example_path> - path to the specific code example. A folder name of the code example will identify that code example - it will be used as a URL further. The folder name of the code example should be the same across all the frameworks.

An example path to the code example: examples/8.1.0/docs/angular/custom-id

It's worth noting, that the examples directory is defined as a npm workspace, as well as each of the <framework> directories within it. This allows installing shared dependencies for all the framework-specific examples.

Dependency sharing is defined by a shared lockfile (/examples/<version_number>/<category>/<framework>/package-lock.json) for all examples of each framework. The examples:install script bumps the dependency versions in shared lockfiles. A single example's lockfile (e.g. /examples/<version_number>/<category>/<framework>/<example_path>/package-lock.json) can still be created when you run npm install inside the example's folder, but is ignored in /examples/.gitignore.

Live on production

All code examples are available online. The base URL for the code examples is https://examples.handsontable.com/examples/ with the path to the built project after the slash.

URL to the specific project follow the undermentioned convention:

<version_number>/<category>/<framework>/<example_path>

An example URL to the live example: https://examples.handsontable.com/examples/11.1.0/docs/js/basic-example/

For more details see the Folder structure section.

Note: The https://examples.handsontable.com/examples/ URL is not CORS-enabled. If that poses a problem, you can use the GitHub-based, CORS-enabled direct equivalent: https://handsontable.github.io/handsontable.

Creating new examples

Read the Templates Guideline for the detailed information about new code examples creation.

Deployment of the new code examples

After new code examples are merged into master branch and the new version of the Handsontable has been released to the NPM, you can safely deploy new examples.

In Github Actions do a manual dispatch of the "Code Examples Deployment" workflow with the <version_number> input set as the Handsontable version you want to deploy. A new folder will be created: /examples/<version_number>, containing the new code examples with Handsontable version fixed to the <version_number>.

The new code snippets will be deployed to the Github Pages and will be available under URL mentioned in the "Live on production" section section.

Editing existing examples

Sometimes you want to edit existing code examples that is live in the /examples/<version_number> directory.

1. Edit code examples within the /examples/<version_number> directory.
2. Commit and push the code examples to the repo.
3. After merging your feature branch to the develop branch, the code examples will be deployed to the Github Pages and will be available under their already-existing URL.

You can also deploy examples without committing anything by using the "Code Examples Deployment" workflow. See the Deployment of the new code examples section for more details.
Note that dispatching the workflow will overwrite the already-existing examples from the gh-pages branch (even when they're based on a branch different from develop).

Copying an example to a separate repo

It is possible to copy an example into a new Git repo. Doing it is as simple as making a copy of the example folder.

When making a copy, keep in might that the node_modules folder in our monorepo workspace might contain symbolic links. For a clean slate, it is a good idea to remove this folder altogether it and regenerate it in the copied folder.

The below commands present how to copy an example with the above advice in mind:

# make a local clone of the repo, if you haven't already
git clone https://github.com/handsontable/handsontable.git

# verify that you are in the folder of the example by checking that the README.md file is the one that you are reading right now
cat README.md

# if it exists, delete the "node_modules" folder of the example, because our NPM workspace sets it up as a symlink in the monorepo (which will not be useful in your fork)
rm -rf node_modules

# copy the example into a new folder called "forked-example" that is a sibling folder of the monorepo
cp -r . ../../../../../../forked-example

# go to your fork
cd ../../../../../../forked-example

# if you want, initiate a new Git repo there
git init
git add .
git commit -m "initial commit in my fork of the Handsontable example"

# install dependencies and start the example
npm install
npm run start

Development

To see code examples in action run these commands from the root of the repository (not the examples subdirectory):

0. npm run examples:version <version_number> - will create a new directory at examples/<version_number> and fill it with code examples based on the examples/next directory, with the handsontable and @handsontable/<framework_name> dependencies updated with the provided <version_number>.
   (This step is optional - done only when creating a new set of examples based on a new version of Handsontable)
    
1. npm run examples:install <version_number> - will install the dependencies of all the examples matching the <version_number>, utilizing the examples' internal workspace logic.
   • If the next version of the examples is being installed, after the dependencies are all in place the script will symlink the local dependencies needed for the examples to work as expected:
     • All the next examples require a local build of Handsontable, linked as handsontable.
     • The framework-based examples required their respective wrapper builds, linked as @handsontable/<framework_name>.
     • All the required symlinks are created in the examples/next/docs/<framework_name>/node_modules directory
       • Additionally, the Angular examples require creating additional symlinks in the node_modules directories inside the actual examples (pointing to node_modules a level higher).
   • When installing a semver-based version of the examples, the only thing being symlinked are handsontable and @handsontable/angular in the node_modules directory of the angular-based examples (pointing to node_modules a level higher).
2. npm run examples:build <version_number> - will build each code example in the /examples/<version_number> directory then copy each example's production output to the /examples/tmp/<version_number>. The path to the code example in the /examples/tmp follows the Folder structure convention.
3. npm run examples:start - it will start the http-server right in the /examples/tmp on PORT 8080. So the URL to the specific code example would be http://localhost:8080/8.1.0/docs/angular/custom-context-menu/. The URL follows the same convention as mentioned in the Live on production section.

Important: As the next directory of the examples uses the local builds of handsontable and the wrappers, for the next build process to work, all the root-level packages need to be built (for example, bu running npm run all build) before running the examples build script.

How to run the arbitrary code example

To launch only one code example, go to the project directory, run npm install and npm run start. This will instal all the project dependencies and start a development server. After this command is called visit http://localhost:8080.

Testing

Each code example has its own test specs, which lives in the spec directory.

Templates have one failing test, which has been added to force developers to write passing tests for the next code examples.

How to tun tests for arbitrary code example

Each code example has its own test suites which you can run using a development server:

1. Run the npm run start command.
2. After the app is launched on a server, run the npm run test command which will launch tests specified to this code example.

How to run tests for the versioned code examples locally

1. Code examples must exist in the examples/<version_number> directory and be built using the command npm run examples:build <version_number>.
2. npm run examples:test <version_number>. This command will run npm run test for each code example (to know what the npm run test command does check out the section above).