examples/README.md
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.
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.
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.
Read the Templates Guideline for the detailed information about new code examples creation.
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.
Sometimes you want to edit existing code examples that is live in the /examples/<version_number> directory.
/examples/<version_number> directory.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).
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
To see code examples in action run these commands from the root of the repository (not the examples subdirectory):
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)
<sup> </sup>npm run examples:install <version_number> - will install the dependencies of all the examples matching the <version_number>, utilizing the examples' internal workspace logic.
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:
next examples require a local build of Handsontable, linked as handsontable.@handsontable/<framework_name>.examples/next/docs/<framework_name>/node_modules directory
node_modules directories inside the actual examples (pointing to node_modules a level higher).handsontable and @handsontable/angular in the node_modules directory of the angular-based examples (pointing to node_modules a level higher).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.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.
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.
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.
Each code example has its own test suites which you can run using a development server:
npm run start command.npm run test command which will launch tests specified to this code example.examples/<version_number> directory and be built using the command npm run examples:build <version_number>.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).