diff --git a/README.md b/README.md index c1d431a..74cd397 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,6 @@ # linkedart.js -[Docs](http://linkedartjs.org/) | -[Contributing](https://github.com/thegetty/linkedart.js/blob/master/.github/CONTRIBUTING.md) +[Docs](http://linkedartjs.org/) | [Contributing](https://github.com/thegetty/linkedart.js/blob/master/.github/CONTRIBUTING.md) | [NPM](https://www.npmjs.com/package/@thegetty/linkedart.js) ## What is LinkedArt? @@ -11,8 +10,8 @@ LinkedArt is a Linked Open Data model which is used to describe cultural heritag This library includes a set of methods for working with [linked.art](https://linked.art) data. Easily manipulate and access rich, complexly nested linked data from any LinkedArt source. This library includes different types of functions or methods: -- _Basic Helpers_: for things like getting the Title, Name, Identifier, or other common properties from a LinkedArt Object. Please see the helpers, or examples in our tests. -- _Document Navigation and Filters_: to use when building custom functions and queries -- this includes filtering data by multiple classifications, traversing the JSON-LD structure, and working with languages. +- _Accessors_: Helpers for common use cases like getting the Title, Name, Identifier, or other common properties from a LinkedArt Object. Please see the helpers, or examples in our tests. +- _Document Navigation and Filters_: For building custom functions and queries -- this includes filtering data by multiple classifications, traversing the JSON-LD structure, and working with languages. ## Why did we create this? @@ -281,6 +280,15 @@ const result = getClassifiedAs( // result should equal: "Young Woman Picking Fruit" ``` +## List of Files + +To better manage the functions into logical groups, this library breaks them into files (described below). + +- **Basic Helpers**: Commonly used and shared helpers across the library, mainly for unifying or normalizing the LinkedArt document structure +- **Language Helpers**: Functions for filtering and managing data in multiple languages +- **LinkedArt Helpers**: Mainly low-level accessors and filter logic for working with LinkedArt Document Structure, but also includes some higher-level functions such as getPrimaryName (for getting the title). +- **Object Helpers**: High-level functions for accessing common fields in documents. + ## License This software is licensed under the [BSD-3](https://opensource.org/licenses/BSD-3-Clause) license. diff --git a/jsdoc-config.json b/jsdoc-config.json index 8167837..c5a0be7 100644 --- a/jsdoc-config.json +++ b/jsdoc-config.json @@ -31,7 +31,7 @@ "destination": "jsdoc", "recurse": true, "template": "node_modules/better-docs", - "readme": "src/docs/jsdoc_home.md" + "readme": "./README.md" }, "markdown.hardwrap": true, "markdown": { diff --git a/src/docs/jsdoc_home.md b/src/docs/jsdoc_home.md deleted file mode 100644 index 4bc0a66..0000000 --- a/src/docs/jsdoc_home.md +++ /dev/null @@ -1,72 +0,0 @@ -## About LinkedArt.js - -This library includes a set of methods for working with [linked.art](https://linked.art) data. Easily manipulate and access rich, complexly nested linked data from any Linked.Art source. This library includes two different types of methods: - -Basic Helpers for things like getting the Title, Name, Identifier, or other common properties from a Linked.Art Object. Please see the helpers, or examples in our tests. -It also includes a more robust set of tools for navigating the Linked.Art JSON-LD to create custom functions and queries -- this includes filtering data by multiple classifications, traversing the JSON-LD structure, and working with languages. - -## What is Linked.Art? - -You probably know this if you’ve made it this far but just in case: Linked.Art is a Linked Open Data model which is used to describe cultural heritage materials. Much more information about the model, and the community that is building it, can be found at [https://linked.art/](https://linked.art/) - -## How Does it Work? - -The library includes a number of helpers for working with Linked.Art’s basic JSON-LD patterns. You can do basic things like getting values based on a classification or set of classifications, as well as more advanced tasks like working with languages and other elements of the Linked.Art model. Want to know more, take a look at the [examples below](#examples). - -## Contributing - -We know this library does not include every use-case, or a simple helper for accessing every Linked.Art property. We’d love feedback or pull-requests to continue to broaden and deepen the library to better support the community. - -## What Do I Need to Use It? - -You will need to be comfortable with javascript and npm (Node Package Manager). You will also need data that is formatted to the Linked.Art model. Example sets you can work with can be found at [https://linked.art/cookbook/data-sources/](https://linked.art/cookbook/data-sources/) - -## How do I install it? - -Using npm: - -```shell -$ npm install @thegetty/linkedart.js --save -``` - -## Examples - -Below is a simple example of how to use the LinkedArt library, for more examples, please see the tutorials [Working with Linked Art](https://observablehq.com/@jrladd/linked-art-2), [Understanding Linked Art](https://observablehq.com/@jrladd/linked-art-1), [Exploring Linked Art](https://observablehq.com/@jrladd/linked-art-3) for using Linked.Art with the Getty Museum’s linked open data APIs. - -### A Simple Example to get the title of an object: - -```js -// import a single helper -import { getClassifiedAs, getPrimaryName } from "@thegetty-private/linkedart"; - -const linkedArtObject = { - identified_by: [ - { - type: "Name", - content: "Young Woman Picking Fruit", - classified_as: [ - { - id: "http://vocab.getty.edu/aat/300404670", - _label: "preferred terms", - type: "Type" - } - ] - } - ] -}; - -// get the title using the built-in helper -const title = getPrimaryName(linkedArtObject); - -// get the title using the lower-level methods which allow you to specify a different classification, or other settings -const result = getClassifiedAs( - linkedArtObject["identified_by"], - "http://vocab.getty.edu/aat/300404670" -); - -// result should equal: "Young Woman Picking Fruit" -``` - -## License - -This software is licensed under the [BSD-3](https://opensource.org/licenses/BSD-3-Clause) license. diff --git a/src/helpers/BasicHelpers.js b/src/helpers/BasicHelpers.js index ba92921..cb205cd 100644 --- a/src/helpers/BasicHelpers.js +++ b/src/helpers/BasicHelpers.js @@ -1,7 +1,8 @@ /** * @file BasicHelpers * @author Adam Brin, Pamela Lam, Alyx Rossetti, Charles Webb, Selina Zawacki - * @category Basic + * @module BasicHelpers + * @category Files * @description This file contains helpers for working with LinkedArt JSON-LD data */ @@ -84,7 +85,7 @@ export function normalizeAatId(id) { * @category Basic Helpers * @description Some of the fields in LinkedArt may be (but sometimes dont) include parts. * For example, `produced_by` which may have a production, or that production may contain multiple - * parts. This method returns an array with the single or all parts + * parts. This function returns an array with the single or all parts * * @param {Object} object - the JSON-LD object (or sub-bart) * @param {String} field - the field to look for/in diff --git a/src/helpers/LanguageHelpers.js b/src/helpers/LanguageHelpers.js index 838f87e..4eb106d 100644 --- a/src/helpers/LanguageHelpers.js +++ b/src/helpers/LanguageHelpers.js @@ -1,5 +1,6 @@ /** * @file LanguageHelpers + * @category Files * @author Adam Brin, Pamela Lam, Alyx Rossetti, Charles Webb, Selina Zawacki * @module LanguageHelpers * @description This file contains helpers for working with Languages in Linked.art diff --git a/src/helpers/LinkedArtHelpers.js b/src/helpers/LinkedArtHelpers.js index 82afd79..cec0377 100644 --- a/src/helpers/LinkedArtHelpers.js +++ b/src/helpers/LinkedArtHelpers.js @@ -2,6 +2,7 @@ * @file LinkedArtHelpers * @author Adam Brin, Pamela Lam, Alyx Rossetti, Charles Webb, Selina Zawacki, Nabil Kashyap * @module LinkedArtHelpers + * @category Files * @description This file contains helpers for working with LinkedArt JSON-LD data */ @@ -241,6 +242,7 @@ export function getObjectsClassifiedByWithClassification( /** * Gets the primary name of the JSON-LD object based on an AAT value or other qualifier, uses the AAT value of Preferred Term as the default * + * @category Accessors * @param {Object} submittedResource - the JSON-LD object * @param {Object} options - additional options * @param {String|Array} options.requestedClassifications - the requested classifications (default is aat.PRIMARY_TERM) @@ -273,6 +275,7 @@ export function getPrimaryName( /** * Gets the primary names of the JSON-LD object based on an AAT value or other qualifier, uses the AAT value of Preferred Term as the default * + * @category Accessors * @param {Object} submittedResource - the JSON-LD object * @param {Object} options - additional options * @param {String|Array} options.requestedClassifications - the requested classifications (default is aat.PRIMARY_TERM) diff --git a/src/helpers/ObjectHelpers.js b/src/helpers/ObjectHelpers.js index 68dbcbd..f7d518d 100644 --- a/src/helpers/ObjectHelpers.js +++ b/src/helpers/ObjectHelpers.js @@ -2,6 +2,7 @@ * @file LinkedArtHelpers * @author Adam Brin, Pamela Lam, Nabil Kashyap * @module ObjectHelpers + * @category Files * @description This file contains convenience helpers for working with LinkedArt objects */ diff --git a/src/index.js b/src/index.js index 0ab6d60..f1f5247 100644 --- a/src/index.js +++ b/src/index.js @@ -1,5 +1,5 @@ /** - * This is the main entrypoint for the module. We import the methods we want to expose + * This is the main entrypoint for the module. We import the functions we want to expose * from the appropriate helper and then export them as part of the module. */ import {