cedar-embeddable-editor 0.9.0

package/.browserslistrc

@@ -0,0 +1,18 @@
+# This file is used by the build system to adjust CSS and JS output to support the specified browsers below.
+# For additional information regarding the format and rule options, please see:
+# https://github.com/browserslist/browserslist#queries
+
+# For the full list of supported browsers by the Angular framework, please see:
+# https://angular.io/guide/browser-support
+
+# You can see what browsers were selected by your queries by running:
+#   npx browserslist
+
+last 1 Chrome version
+last 1 Firefox version
+last 2 Edge major versions
+last 2 Safari major versions
+last 2 iOS major versions
+Firefox ESR
+not IE 9-10 # Angular support for IE 9-10 has been deprecated and will be removed as of Angular v11. To opt-in, remove the 'not' prefix on this line.
+not IE 11 # Angular supports IE 11 only as an opt-in. To opt-in, remove the 'not' prefix on this line.

package/.editorconfig

@@ -0,0 +1,16 @@
+# Editor configuration, see https://editorconfig.org
+root = true
+
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.ts]
+quote_type = single
+
+[*.md]
+max_line_length = off
+trim_trailing_whitespace = false

package/README.md

@@ -0,0 +1,302 @@
+# Cedar Embeddable Editor (CEE)
+
+The CEDAR Embeddable Editor is as a web component that implements the functionality of the CEDAR Metadata Editor.
+
+It takes CEDAR JSON Schema templates as input, and produces CEDAR JSON-LD metadata.
+
+## Running as a standalone application
+
+You can run CEE as a standalone application. This is helpful for developers to see changes to the code reflected immediately in the application. To run CEE in the standalone mode (NOT as a Webcomponent), proceed with the following steps:
+
+### Clone the repository
+
+Clone this repository onto a local directory of your choice:
+
+```shell
+git clone https://github.com/metadatacenter/cedar-embeddable-editor.git
+```
+
+### Edit configuration
+
+1. Open the file ```cedar-embeddable-editor/src/app/app.component.dev.ts``` in your favorite editor.
+2. Edit configuration parameters based on your local environment (see section [Configuration](https://github.com/metadatacenter/cedar-embeddable-editor/tree/develop#configuration) for details).
+
+### Build the project and start the server
+
+1. Navigate to the CEE directory:
+```shell
+$cd <...>/<clone directory>/cedar-embeddable-editor/
+```
+2. Run these commands:
+```shell
+cedar-embeddable-editor$ npm install
+cedar-embeddable-editor$ ng serve
+```
+3. In your browser, navigate to `http://localhost:4200/`. The app will automatically reload if you change any of the source files.
+
+## Running as a Webcomponent
+
+This method creates a single Javascript (JS) file that encapsulates all the functionality of CEE. The JS file can be embedded in any application or HTML page. To build a CEE Webcomponent, proceed with these steps: 
+
+### Build and copy the Webcomponent JS file
+
+1. Run the build command:
+```shell
+cedar-embeddable-editor$ ng build --configuration production --output-hashing=none
+```
+2. Combine the generated files into a single file and copy the final JS to the sample application:
+```shell
+cedar-embeddable-editor$ cat dist/cedar-embeddable-editor/{runtime,polyfills,main}.js > "/dev/cedar/cedar-cee-demo-generic/assets/js/cedar-embeddable-editor.js"
+```
+
+## Configuration
+
+### Configuration file
+
+The CEE configuration file format and storage location depends on the application and the mode in which CEE is being used.
+
+* When running CEE in the standalone mode (developer mode), the configuration parameters are stored in and read from the file: `src/app/app.component.dev.ts`.
+* When running CEE as a generic Webcomponent, the configuration parameters can be stored in any `.json` file that is visible to the application that embeds CEE Webcomponent. CEE Webcomponent API provides a method for loading the configuration file from its path at runtime. For example:
+```javascript
+document.addEventListener('WebComponentsReady', function () {
+  const cee = document.querySelector('cedar-embeddable-editor');
+  cee.loadConfigFromURL('assets/data/cee-config.json');
+});
+```
+* When using the Angular 2 sample application (https://github.com/metadatacenter/cedar-cee-demo-angular), the configuration is stored in the file: `assets/data/appConfig.json`. 
+
+### Metadata save endpoint
+
+CEE offers the functionality to save user metadata using a custom remote endpoint. If you plan to enable this feature, you will need to set the following configuration:
+
+```json
+"showDataSaver": true,
+"dataSaverEndpointUrl": "http://localhost:8000/datasave.php",
+```
+Replace `dataSaverEndpointUrl` with a URL pointing to the endpoint that will handle metadata submissions.
+
+The endpoint can be implemented using any REST-enabled framework/programming language. CEE makes a POST call to the endpoint specified in the configuration file, including the metadata in JSON-LD format in the body of the request.
+
+* Request format:
+```json
+{
+  "metadata": {__contents of meatadata__},
+  "info": {__optional info object that can be passed in and out of CEE__}
+}
+```
+
+CEE allows custom data to be passed to the Webcomponent, which then becomes available to your Metadata save endpoint. The custom data is passed to the Webcomponent via an API call and is propogated to the Metadata save endpoint using the `info` attribute.
+
+Example:
+
+```javascript
+function getCustomTemplateInfo() {
+  return {
+    mycustomtitle: 'ACME Template',
+    mycustomurl: 'https://doi.org/10.15468/9vuieb',
+    mycutomdataattribute1: 'Hello World',
+    mycutomdataattribute2: {name: 'John Doe', age: 35}
+  };
+}
+
+document.addEventListener('WebComponentsReady', function () {
+  const cee = document.querySelector('cedar-embeddable-editor');
+  cee.templateInfo = getCustomTemplateInfo();
+});
+```
+
+When a user pushes the **Save** (metadata) button, these custom attributes are propagated to the Metadata save endpoint.
+
+Example:
+
+```json
+{
+  "metadata": {__contents of metadata__},
+  "info": {
+    "mycustomtitle": "ACME Template",
+    "mycustomurl": "https://doi.org/10.15468/9vuieb",
+    "mycutomdataattribute1": "Hello World",
+    "mycutomdataattribute2": {
+      "name": "John Doe",
+      "age": 35
+    }
+  }
+}
+```
+
+If the metadata was created successfully, the response received from the server returns `201 Created` status code.
+
+The response must include a JSON object with the following attributes:
+* **id:** identifier of the created resource in the target database.
+* **title:** title of the resource that has been created (corresponds to the value of schema:name in the metadata)
+* **links:**
+  * **self:** If the resource is publicly available, an URL identifying the location of the newly created resource. Otherwise, null.
+
+Example:
+
+```json
+{
+  "id": "010a261f12b3efc4",
+  "title": "single field",
+  "links": {
+    "self": "http://localhost:8000/metadata/010a261f12b3efc4.json"
+  }
+}
+```
+
+If there was an error,  the corresponding error code and a JSON object with the following attributes:
+* **status:** the HTTP status code applicable to this problem, expressed as a string value.
+* **title:** a short, human-readable summary of the problem that should not change from occurrence to occurrence of the problem.
+* **detail:** a human-readable explanation specific to this occurrence of the problem.
+
+Example:
+
+```json
+{
+  "status": "500",
+  "title": "Internal Error",
+  "detail": "Error connecting to database server (invalid credentials)"
+}
+```
+
+### Template upload endpoint
+
+CEDAR Embeddable Editor includes an optional feature that allows uploading a template source file and creating metadata for that template.
+
+If you plan to enable that functionality, you will need to set up two endpoints in your configuration file:
+
+```json
+"showTemplateUpload": true,
+"templateUploadBaseUrl": "http://localhost:8000",
+"templateUploadEndpoint": "/upload.php",
+"templateDownloadEndpoint": "/download.php",
+```
+Replace `templateUploadBaseUrl` with a URL pointing to the root of the server on which the endpoints reside. Configure `templateUploadEndpoint` and `templateDownloadEndpoint` to their respective paths from the `templateUploadBaseUrl`.
+
+### Required configuration parameters
+
+* **sampleTemplateLocationPrefix:** The base URL that contains the sample CEDAR templates
+* **terminologyProxyUrl:** The URL of the proxy endpoint that communicates with BioPortal
+
+```json
+{
+  "sampleTemplateLocationPrefix": "https://component.metadatacenter.orgx/cedar-embeddable-editor-sample-templates/",
+  "terminologyProxyUrl": "https://terminology.metadatacenter.org/bioportal/integrated-search"
+}
+```
+
+### Optional configuration parameters
+
+The are other optional configuration parameters available for controlling various aspects of the CEE user interface. Most of these are self-explanatory. The example below includes the default values in cases, where the parameter isn't explicitly declared.
+
+```json
+{
+  "showSampleTemplateLinks": true,
+  "loadSampleTemplateName": "19",
+  "expandedSampleTemplateLinks": false,
+  "showTemplateRenderingRepresentation": true,
+  "expandedTemplateRenderingRepresentation": false,
+  "showInstanceDataCore": true,
+  "expandedInstanceDataCore": true,
+  "showInstanceDataFull": false,
+  "expandedInstanceDataFull": false,
+  "showMultiInstanceInfo": false,
+  "expandedMultiInstanceInfo": false,
+  "showTemplateSourceData": true,
+  "expandedTemplateSourceData": false,
+  "showHeader": true,
+  "showFooter": true,
+  "collapseStaticComponents": true
+}
+```
+
+## Metadata API
+
+CEE Webcomponent includes APIs for exporting metadata externally and importing metadata into CEE.
+
+### Metadata Export
+
+The metadata currently being edited inside CEE can be exported at anytime by making this API call:
+
+```javascript
+const meta = cee.currentMetadata;
+```
+
+In the example below, the metadata is sent to an external endpoint every 15 seconds:
+
+```javascript
+document.addEventListener('WebComponentsReady', function () {
+  const cee = document.querySelector('cedar-embeddable-editor');
+  cee.loadConfigFromURL('assets/data/cee-config.json');
+  const saveTime = 15000; // 15 seconds
+
+  setInterval(() => {
+    const meta = cee.currentMetadata;
+
+    const xhr = new XMLHttpRequest();
+    xhr.open("POST", "http://localhost:8001/metadatasave.php");
+    xhr.setRequestHeader("Accept", "application/json");
+    xhr.setRequestHeader("Content-Type", "application/json");
+    xhr.send(JSON.stringify(meta, null, 2));
+    console.log('Saved metadata after ' + saveTime / 1000 + ' seconds');
+  }, saveTime);
+});
+```
+
+### Metadata Import
+
+You can import your metadata into CEE Webcomponent, provided it matches the template currently being edited. To import your metadata, execute this API call:
+
+```javascript
+cee.metadata = yourCustomMetadataJson
+```
+
+In the example below, the metadata is fetched from a remote URL and imported into CEE:
+
+```javascript
+function restoreMetadataFromURL(metaUrl, cee, successHandler = null, errorHandler = null) {
+  const xhr = new XMLHttpRequest();
+  xhr.onreadystatechange = () => {
+    if (xhr.readyState === XMLHttpRequest.DONE) {
+      if (xhr.status === 200) {
+        const jsonMeta = JSON.parse(xhr.responseText);
+        cee.metadata = jsonMeta;
+
+        if (successHandler) {
+          successHandler(jsonMeta);
+        }
+      } else {
+        if (errorHandler) {
+          errorHandler(xhr);
+        }
+      }
+    }
+  };
+  xhr.open('GET', metaUrl, true);
+  xhr.send();
+}
+
+document.addEventListener('WebComponentsReady', function () {
+  const cee = document.querySelector('cedar-embeddable-editor');
+  cee.loadConfigFromURL('assets/data/cee-config.json');
+  restoreMetadataFromURL('uploads/metadata-for-restore.json', cee);
+});
+```
+
+To reiterate, the metadata being imported **MUST** match the template currently being edited and open in your browser window.
+
+## Example Applications
+
+There are two sample applications you can use to demonstrate how to embed and use CEE. Follow the links below to the demo application of your choice. The documentation for each demo application can be found in the README file of the corresponding application.
+
+### CEE Demo Generic
+
+This demo uses a generic HTML page with the CEE Webcomponent embedded in it. It runs standalone, with no dependency on any web framework.
+
+https://github.com/metadatacenter/cedar-cee-demo-generic
+
+### CEE Demo Angular
+
+This demo is written in Angular 2 and requires that framework to run properly.
+
+https://github.com/metadatacenter/cedar-cee-demo-angular

package/angular.json

@@ -0,0 +1,153 @@
+{
+  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
+  "version": 1,
+  "newProjectRoot": "projects",
+  "projects": {
+    "cedar-embeddable-editor": {
+      "projectType": "application",
+      "schematics": {
+        "@schematics/angular:component": {
+          "style": "scss"
+        }
+      },
+      "root": "",
+      "sourceRoot": "src",
+      "prefix": "app",
+      "architect": {
+        "build": {
+          "builder": "@angular-devkit/build-angular:browser",
+          "options": {
+            "allowedCommonJsDependencies": [
+              "moment-timezone"
+            ],
+            "outputPath": "dist/cedar-embeddable-editor",
+            "index": "src/index.html",
+            "main": "src/main.ts",
+            "polyfills": "src/polyfills.ts",
+            "tsConfig": "tsconfig.app.json",
+            "assets": [
+              "src/favicon.ico",
+              "src/assets"
+            ],
+            "styles": [
+              "src/styles.scss",
+              "src/styles-own.scss"
+            ],
+            "scripts": [
+              "node_modules/@webcomponents/custom-elements/src/native-shim.js"
+            ],
+            "allowedCommonJsDependencies": [
+              "moment",
+              "moment-timezone"
+            ],
+            "aot": false,
+            "vendorChunk": true,
+            "extractLicenses": false,
+            "buildOptimizer": false,
+            "sourceMap": true,
+            "optimization": false,
+            "namedChunks": true
+          },
+          "configurations": {
+            "production": {
+              "fileReplacements": [
+                {
+                  "replace": "src/environments/environment.ts",
+                  "with": "src/environments/environment.prod.ts"
+                }
+              ],
+              "optimization": true,
+              "outputHashing": "none",
+              "sourceMap": false,
+              "namedChunks": false,
+              "aot": true,
+              "extractLicenses": true,
+              "vendorChunk": false,
+              "buildOptimizer": true,
+              "budgets": [
+                {
+                  "type": "initial",
+                  "maximumWarning": "3mb",
+                  "maximumError": "5mb"
+                },
+                {
+                  "type": "anyComponentStyle",
+                  "maximumWarning": "500kb",
+                  "maximumError": "3mb"
+                }
+              ]
+            }
+          },
+          "defaultConfiguration": ""
+        },
+        "serve": {
+          "builder": "@angular-devkit/build-angular:dev-server",
+          "options": {
+            "browserTarget": "cedar-embeddable-editor:build",
+            "port": 4400
+          },
+          "configurations": {
+            "production": {
+              "browserTarget": "cedar-embeddable-editor:build:production"
+            }
+          }
+        },
+        "extract-i18n": {
+          "builder": "@angular-devkit/build-angular:extract-i18n",
+          "options": {
+            "browserTarget": "cedar-embeddable-editor:build"
+          }
+        },
+        "test": {
+          "builder": "@angular-devkit/build-angular:karma",
+          "options": {
+            "main": "src/test.ts",
+            "polyfills": "src/polyfills.ts",
+            "tsConfig": "tsconfig.spec.json",
+            "karmaConfig": "karma.conf.js",
+            "assets": [
+              "src/favicon.ico",
+              "src/assets"
+            ],
+            "styles": [
+              "src/styles.scss",
+              "src/styles-own.scss"
+            ],
+            "scripts": [
+              "node_modules/@webcomponents/custom-elements/src/native-shim.js"
+            ]
+          }
+        },
+        "lint": {
+          "builder": "@angular-devkit/build-angular:tslint",
+          "options": {
+            "tsConfig": [
+              "tsconfig.app.json",
+              "tsconfig.spec.json",
+              "e2e/tsconfig.json"
+            ],
+            "exclude": [
+              "**/node_modules/**"
+            ]
+          }
+        },
+        "e2e": {
+          "builder": "@angular-devkit/build-angular:protractor",
+          "options": {
+            "protractorConfig": "e2e/protractor.conf.js",
+            "devServerTarget": "cedar-embeddable-editor:serve"
+          },
+          "configurations": {
+            "production": {
+              "devServerTarget": "cedar-embeddable-editor:serve:production"
+            }
+          }
+        }
+      }
+    }
+  },
+  "defaultProject": "cedar-embeddable-editor",
+  "cli": {
+    "analytics": false
+  }
+}

package/e2e/protractor.conf.js

@@ -0,0 +1,36 @@
+// @ts-check
+// Protractor configuration file, see link for more information
+// https://github.com/angular/protractor/blob/master/lib/config.ts
+
+const { SpecReporter, StacktraceOption } = require('jasmine-spec-reporter');
+
+/**
+ * @type { import("protractor").Config }
+ */
+exports.config = {
+  allScriptsTimeout: 11000,
+  specs: [
+    './src/**/*.e2e-spec.ts'
+  ],
+  capabilities: {
+    browserName: 'chrome'
+  },
+  directConnect: true,
+  baseUrl: 'http://localhost:4200/',
+  framework: 'jasmine',
+  jasmineNodeOpts: {
+    showColors: true,
+    defaultTimeoutInterval: 30000,
+    print: function() {}
+  },
+  onPrepare() {
+    require('ts-node').register({
+      project: require('path').join(__dirname, './tsconfig.json')
+    });
+    jasmine.getEnv().addReporter(new SpecReporter({
+      spec: {
+        displayStacktrace: StacktraceOption.PRETTY
+      }
+    }));
+  }
+};

package/e2e/src/app.e2e-spec.ts

@@ -0,0 +1,23 @@
+import { AppPage } from './app.po';
+import { browser, logging } from 'protractor';
+
+describe('workspace-project App', () => {
+  let page: AppPage;
+
+  beforeEach(() => {
+    page = new AppPage();
+  });
+
+  it('should display welcome message', () => {
+    page.navigateTo();
+    expect(page.getTitleText()).toEqual('cedar-embeddable-editor app is running!');
+  });
+
+  afterEach(async () => {
+    // Assert that there are no errors emitted from the browser
+    const logs = await browser.manage().logs().get(logging.Type.BROWSER);
+    expect(logs).not.toContain(jasmine.objectContaining({
+      level: logging.Level.SEVERE,
+    } as logging.Entry));
+  });
+});

package/e2e/src/app.po.ts

@@ -0,0 +1,11 @@
+import { browser, by, element } from 'protractor';
+
+export class AppPage {
+  navigateTo(): Promise<unknown> {
+    return browser.get(browser.baseUrl) as Promise<unknown>;
+  }
+
+  getTitleText(): Promise<string> {
+    return element(by.css('app-cedar-embeddable-editor .content span')).getText() as Promise<string>;
+  }
+}

package/e2e/tsconfig.json

@@ -0,0 +1,14 @@
+/* To learn more about this file see: https://angular.io/config/tsconfig. */
+{
+  "extends": "../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "../out-tsc/e2e",
+    "module": "commonjs",
+    "target": "es2018",
+    "types": [
+      "jasmine",
+      "jasminewd2",
+      "node"
+    ]
+  }
+}

package/karma.conf.js

@@ -0,0 +1,32 @@
+// Karma configuration file, see link for more information
+// https://karma-runner.github.io/1.0/config/configuration-file.html
+
+module.exports = function (config) {
+  config.set({
+    basePath: '',
+    frameworks: ['jasmine', '@angular-devkit/build-angular'],
+    plugins: [
+      require('karma-jasmine'),
+      require('karma-chrome-launcher'),
+      require('karma-jasmine-html-reporter'),
+      require('karma-coverage-istanbul-reporter'),
+      require('@angular-devkit/build-angular/plugins/karma')
+    ],
+    client: {
+      clearContext: false // leave Jasmine Spec Runner output visible in browser
+    },
+    coverageIstanbulReporter: {
+      dir: require('path').join(__dirname, './coverage/cedar-embeddable-editor'),
+      reports: ['html', 'lcovonly', 'text-summary'],
+      fixWebpackSourcePaths: true
+    },
+    reporters: ['progress', 'kjhtml'],
+    port: 9876,
+    colors: true,
+    logLevel: config.LOG_INFO,
+    autoWatch: true,
+    browsers: ['Chrome'],
+    singleRun: false,
+    restartOnFileChange: true
+  });
+};

package/license.txt

@@ -0,0 +1,26 @@
+Copyright (c) 2023, The Board of Trustees of Leland Stanford Junior University
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are
+permitted provided that the following conditions are met:
+
+   1. Redistributions of source code must retain the above copyright notice, this list of
+      conditions and the following disclaimer.
+
+   2. Redistributions in binary form must reproduce the above copyright notice, this list
+      of conditions and the following disclaimer in the documentation and/or other materials
+      provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY The Board of Trustees of Leland Stanford Junior University
+''AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
+EVENT SHALL The Board of Trustees of Leland Stanford Junior University OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
+IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+The views and conclusions contained in the software and documentation are those of the
+authors and should not be interpreted as representing official policies, either expressed
+or implied, of The Board of Trustees of Leland Stanford Junior University.