Instructions (#4)

Esri · Jan 10, 2025 · cbe887d · cbe887d
1 parent 237761a
commit cbe887d
Show file tree

Hide file tree

Showing 58 changed files with 512 additions and 471 deletions.
diff --git a/README.md b/README.md
@@ -1 +1,48 @@
 # ArcGIS REST JS Samples
+
+This repository contains a variety of samples of different ways to use [ArcGIS REST JS](https://github.com/Esri/arcgis-rest-js). Please see the [samples folder](samples/) for the entire list. Each sample has a README file to explain how to run the sample.
+
+## Local ArcGIS REST JS
+
+If you'd like to use a local version of ArcGIS REST JS while running one of the samples, follow these steps.
+
+### Local ArcGIS REST JS (NPM)
+
+For samples that use NPM to install ArcGIS REST JS as a dependency, follow these steps.
+
+1. In the ArcGIS REST JS repo run any relevant build commands for the packages with which you are working.
+1. In the terminal, `cd` onto the package you want to link. E.g. `cd packages/arcgis-rest-request`.
+1. Run `npm link`.
+1. In this repo, `cd` into the demo you want to run and run the `npm link` command for the package you want to link. `npm link @esri/arcgis-rest-request`
+
+Remember that you must run `npm run build` in the ArcGIS REST JS repository after making changes to see those changes when running the sample.
+
+To remove the link and use the package from NPM instead of the local one, run `npm install` in the sample folder again.
+
+### Local ArcGIS REST JS (Browser)
+
+For samples that use a `<script>` tag to reference ArcGIS REST JS in the browser, follow these steps.
+
+1. In the ArcGIS REST JS directory, run these commands. This will run a local server hosting ArcGIS REST JS.
+
+   ```bash
+   npm install
+   npm run build
+   node .\scripts\run-demo-server.js
+   ```
+
+2. In this sample's directory, in the HTML file code, change the `<script>` tag(s) from `https://unpkg.com` to `https://localhost:8080` (or whatever port is used in step 1). For example, change this:
+
+   ```html
+   <script src="https://unpkg.com/@esri/arcgis-rest-feature-service/dist/bundled/feature-service.umd.js"></script>
+   ```
+
+   ... to this:
+
+   ```html
+   <script src="https://localhost:8080/@esri/arcgis-rest-feature-service/dist/bundled/feature-service.umd.js"></script>
+   ```
+
+## Sample Repository Maintenance
+
+In order to not need to constantly update the packages, we are not including `package-lock.json` files within samples the use NPM to install dependencies. See [.gitignore](.gitignore).
diff --git a/samples/attachments-browser/README.md b/samples/attachments-browser/README.md
@@ -1,7 +1,15 @@
-# Running this demo
+# Attachments Browser
 
-1. Make sure you run `npm run build` in the root folder to setup the dependencies
-1. `npm start`
-1. Visit http://localhost:8080
+## Running this sample
 
-**Note:** The server starts with a special configuration to serve URLs starting with `@esri/arcgis-rest-*` from their respective packages. In your application you will need to change these URLs to point to their respective locations.
+For this sample, you do not need to install any dependencies - it uses ArcGIS REST JS from the Unpkg CDN. To run this sample, you just need to host the `index.html` file. There are a variety of ways to do that; one simple way is to use the [serve](https://www.npmjs.com/package/serve) package:
+
+```bash
+npx serve
+```
+
+### Local ArcGIS REST JS
+
+If you'd like to use a local version of ArcGIS REST JS, follow the [steps in the parent README](../README.md#local-arcgis-rest-js-browser), updating the script tags in these files as necessary:
+
+- `index.html`
diff --git a/samples/attachments-browser/index.html b/samples/attachments-browser/index.html
@@ -1,8 +1,15 @@
 <!DOCTYPE html>
 <html>
-<title>Attachments</title>
+  <head>
 
-<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css" integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u" crossorigin="anonymous">
+    <title>Attachments</title>
+
+    <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css" integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u" crossorigin="anonymous">
+
+    <script src="https://rawgit.com/kriszyp/put-selector/master/put.js"></script>
+    <script src="https://unpkg.com/@esri/arcgis-rest-request/dist/bundled/request.umd.js"></script>
+    <script src="https://unpkg.com/@esri/arcgis-rest-feature-service/dist/bundled/feature-service.umd.js"></script>
+  </head>
 
 <div class="container-fluid">
   <div class="row">
@@ -15,7 +22,7 @@ <h3>Attachments</h3>
         </div>
         <div class="form-group">
           <label for="featureId">Feature ID</label>
-          <input type="number" min="0" step="1" id="featureId" name="featureId" class="form-control" value="8254973" required>
+          <input type="number" min="0" step="1" id="featureId" name="featureId" class="form-control" value="21502403" required>
         </div>
         <div class="form-group">
           <button type="submit" class="btn"><span class="glyphicon glyphicon-paperclip" aria-hidden="true"></span> Get Attachments</button>
@@ -53,10 +60,6 @@ <h3>Attachments</h3>
   </div>
 </div>
 
-<script src="https://rawgit.com/kriszyp/put-selector/master/put.js"></script>
-<script src="@esri/arcgis-rest-request/dist/bundled/request.umd.js"></script>
-<script src="@esri/arcgis-rest-feature-service/dist/bundled/feature-service.umd.js"></script>
-
 <script>
   let serviceUrl, featureId;
 

diff --git a/samples/attachments-browser/package.json b/samples/attachments-browser/package.json
diff --git a/samples/attachments-node/README.md b/samples/attachments-node/README.md
@@ -1,4 +1,13 @@
 # Native JavaScript Modules in Node.js
 
-1. Run `npm run build` in the root directory
-1. Run `npm start` to make a require and log output.
+## Running this sample
+
+1. Run `npm install` to install the dependencies.
+2. Run `npm start` to make a require and log output.
+
+### Local ArcGIS REST JS
+
+If you'd like to use a local version of ArcGIS REST JS, follow the [steps in the parent README](../README.md#local-arcgis-rest-js-npm), referencing these packages that this sample uses as necessary:
+
+- `arcgis-rest-request`
+- `arcgis-rest-feature-service`
diff --git a/samples/attachments-node/package.json b/samples/attachments-node/package.json
@@ -12,6 +12,7 @@
   },
   "dependencies": {
     "@esri/arcgis-rest-request": "^4.0.0",
+    "@esri/arcgis-rest-feature-service": "^4.0.0",
     "fetch-blob": "^3.1.2",
     "mime": "^2.5.2",
     "mime-types": "^2.1.32"

diff --git a/samples/batch-geocoder-node/README.md b/samples/batch-geocoder-node/README.md
@@ -1,6 +1,8 @@
-# Running this demo
+# Batch Geocoder (Node)
 
-1. Make sure you run `npm run build` in the root folder to setup the dependencies
+## Running this sample
+
+1. run `npm install` to install the dependencies.
 2. Create and register a [new application](https://developers.arcgis.com/documentation/core-concepts/security-and-authentication/accessing-arcgis-online-services/).
 3. Replace values in [config-template.js](/demos/batch-geocoder-node/config-template.js) and rename to `config.js`
    1. `"clientId"`: ArcGIS ClientId
@@ -11,3 +13,10 @@
 4. `npm start`
 
 Sample Restaurant Inspections adapted from a DOHMH dataset available [online](https://data.cityofnewyork.us/Health/DOHMH-New-York-City-Restaurant-Inspection-Results/xx67-kt59/data)
+
+### Local ArcGIS REST JS
+
+If you'd like to use a local version of ArcGIS REST JS, follow the [steps in the parent README](../README.md#local-arcgis-rest-js-npm), referencing these packages that this sample uses as necessary:
+
+- `arcgis-rest-request`
+- `arcgis-rest-geocoding`
diff --git a/samples/browser-es-modules/README.md b/samples/browser-es-modules/README.md
@@ -1,7 +1,15 @@
 # ArcGIS REST JS + Native Browser Modules
 
-1. Run `npm run build` in the root directory
-1. Run `npm start` to spin up the development server.
-1. Visit [http://localhost:8080](http://localhost:8080).
+## Running this sample
 
-**Note:** The server starts with a special configuration to serve URLs starting with `@esri/arcgis-rest-*` from their respective packages. In your application you will need to change these URLs to point to their respective locations.
+For this sample, you do not need to install any dependencies - it uses ArcGIS REST JS from the Unpkg CDN. To run this sample, you just need to host the `index.html` file. There are a variety of ways to do that; one simple way is to use the [serve](https://www.npmjs.com/package/serve) package:
+
+```bash
+npx serve
+```
+
+### Local ArcGIS REST JS
+
+If you'd like to use a local version of ArcGIS REST JS, follow the [steps in the parent README](../README.md#local-arcgis-rest-js-browser), updating the script tags in these files as necessary:
+
+- `index.html`
diff --git a/samples/browser-es-modules/index.html b/samples/browser-es-modules/index.html
@@ -1,38 +1,42 @@
 <!DOCTYPE html>
 <html lang="en">
-
-<head>
-  <meta charset="utf-8">
-  <title>ArcGIS REST JS Browser w/ Modules</title>
-  <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css"
-    integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u" crossorigin="anonymous">
-
-</head>
-
-<body>
-  <!-- Load the ES Modules Polyfill so we can use importmap in FF and Safari -->
-  <script async src="https://unpkg.com/[email protected]/dist/es-module-shims.js"></script>
-
-  <!-- Map package imports to URLS starting with @esri/... which will get served from the local build of the modules -->
-  <script type="importmap">
-  {
-    "imports": {
-      "@esri/arcgis-rest-request": "/@esri/arcgis-rest-request/dist/bundled/request.esm.js",
-      "@esri/arcgis-rest-portal": "/@esri/arcgis-rest-portal/dist/bundled/portal.esm.js"
-    }
-  }
-  </script>
-
-  <script type="module">
-    import { searchItems } from "@esri/arcgis-rest-portal";
-
-    let element = document.createElement("pre");
-    document.body.appendChild(element);
-
-    searchItems("water").then((response) => {
-      element.textContent = JSON.stringify(response, null, 2); // false
-    });
-  </script>
-</body>
-
-</html>
+  <head>
+    <meta charset="utf-8" />
+    <title>ArcGIS REST JS Browser w/ Modules</title>
+    <link
+      rel="stylesheet"
+      href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css"
+      integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u"
+      crossorigin="anonymous"
+    />
+  </head>
+
+  <body>
+    <!-- Load the ES Modules Polyfill so we can use importmap in FF and Safari -->
+    <script
+      async
+      src="https://unpkg.com/[email protected]/dist/es-module-shims.js"
+    ></script>
+
+    <!-- Map package imports to URLS starting with @esri/... which will get served from the local build of the modules -->
+    <script type="importmap">
+      {
+        "imports": {
+          "@esri/arcgis-rest-request": "https://unpkg.com/@esri/arcgis-rest-request/dist/bundled/request.esm.js",
+          "@esri/arcgis-rest-portal": "https://unpkg.com/@esri/arcgis-rest-portal/dist/bundled/portal.esm.js"
+        }
+      }
+    </script>
+
+    <script type="module">
+      import { searchItems } from "@esri/arcgis-rest-portal";
+
+      let element = document.createElement("pre");
+      document.body.appendChild(element);
+
+      searchItems("water").then((response) => {
+        element.textContent = JSON.stringify(response, null, 2); // false
+      });
+    </script>
+  </body>
+</html>
diff --git a/samples/browser-es-modules/package.json b/samples/browser-es-modules/package.json
diff --git a/samples/deno/README.md b/samples/deno/README.md
@@ -1,9 +1,33 @@
 # ArcGIS REST JS + Deno
 
-ArcGIS REST JS is fully compatible with Deno. You can import the packages from the [esm.run CDN](https://www.jsdelivr.com/esm) for the easiest use. This demo shows importing from a local install with an import map.
+## Running this sample
 
-You can run this demo with:
+ArcGIS REST JS is fully compatible with Deno. You can run this demo with:
 
 ```
-deno run --allow-net --import-map ./import_map.json index.js
+deno run --allow-net --allow-import --import-map ./import_map.json index.js
+```
+
+### Local ArcGIS REST JS
+
+If you'd like to use a local version of ArcGIS REST JS, follow these steps.
+
+1. In the ArcGIS REST JS directory, run these commands. This will run a local server hosting ArcGIS REST JS.
+
+```bash
+npm install
+npm run build
+node .\scripts\run-demo-server.js
+```
+
+2. In this sample's directory, update `import_map.json` with relative paths to the files on your computer. For example replace this:
+
+```json
+"https://esm.run/@esri/arcgis-rest-form-data/browser-ponyfill.mjs"
+```
+
+... with this:
+
+```json
+"../../path/to/arcgis-rest-js/packages/arcgis-rest-form-data/browser-ponyfill.mjs"
 ```
diff --git a/samples/deno/import_map.json b/samples/deno/import_map.json
@@ -1,8 +1,8 @@
-  {
-    "imports": {
-      "@esri/arcgis-rest-form-data": "../../packages/arcgis-rest-form-data/browser-ponyfill.mjs",
-      "@esri/arcgis-rest-fetch": "../../packages/arcgis-rest-fetch/browser-ponyfill.mjs",
-      "@esri/arcgis-rest-request": "../../packages/arcgis-rest-request/dist/esm/index.js",
-      "@esri/arcgis-rest-portal": "../../packages/arcgis-rest-portal/dist/esm/index.js"
-    }
-  }
+{
+  "imports": {
+    "@esri/arcgis-rest-form-data": "https://esm.run/@esri/arcgis-rest-form-data/browser-ponyfill.mjs",
+    "@esri/arcgis-rest-fetch": "https://esm.run/@esri/arcgis-rest-fetch/browser-ponyfill.mjs",
+    "@esri/arcgis-rest-request": "https://esm.run/@esri/arcgis-rest-request/dist/esm/index.js",
+    "@esri/arcgis-rest-portal": "https://esm.run/@esri/arcgis-rest-portal/dist/esm/index.js"
+  }
+}
diff --git a/samples/dev-credentials-client/README.md b/samples/dev-credentials-client/README.md
@@ -2,33 +2,25 @@
 
 This page will show API key and OAuth 2.0 app CRUD demo with help of `arcgis-rest-developer-credentials` package. First
 step requires a user to log in
-via [Authenticate with an ArcGIS identity](https://developers.arcgis.com/arcgis-rest-js/authentication/tutorials/authenticate-with-an-arcgis-identity-rest-js-browser/).
+via [Authenticate with an ArcGIS identity](https://developers.arcgis.com/arcgis-rest-js/authentication/tutorials/sign-in-with-user-authentication-browser/).
 Then you can use the form to create an API key or switch to the OAuth 2.0 form to create an OAuth 2.0 app.
 Once you've created an API key or OAuth 2.0 app, you can click on the item in the table below the form to edit it.
 
-## Running this demo
+## Running this sample
 
-1. Run `npm run build` in the repository's root directory.
-2. Go into `demos/dev-credentials-client` and run `npm start` to spin up the development server.
-3. Visit [http://localhost:8080](http://localhost:8080).
+First run `npm install` to install the dependencies.
+
+### Local ArcGIS REST JS
+
+If you'd like to use a local version of ArcGIS REST JS, follow the [steps in the parent README](../README.md#local-arcgis-rest-js-npm), referencing these packages that this sample uses as necessary:
+
+- `arcgis-rest-request`
+- `arcgis-rest-developer-credentials`
 
 ## Additional tools used
 
-<table>
-  <tr>
-    <th>Description</th>
-    <th>Tool</th>
-  </tr>
-  <tr>
-    <td>Enhanced Multi-Select</td>
-    <td><a href="https://select2.org/">Select2</a></td>
-  </tr>
-  <tr>
-    <td>Table</td>
-    <td><a href="https://datatables.net/">jQuery Data Table</a></td>
-  </tr>
-  <tr>
-    <td>Others</td>
-    <td>jQuery 3, Bootstrap 5</td>
-  </tr>
-</table>
+| Description           | Tool                                        |
+| --------------------- | ------------------------------------------- |
+| Enhanced Multi-Select | [Select2](https://select2.org)              |
+| Table                 | [jQuery Data Table](https://datatables.net) |
+| Others                | jQuery 3, Bootstrap 5                       |