From 7af96f225bc5525f114b60a85d1076f846fd8ed1 Mon Sep 17 00:00:00 2001 From: Marco La Rosa Date: Sat, 29 Jun 2024 10:23:51 +1000 Subject: [PATCH] update component docs --- src/docs/component/advanced-usage.md | 55 +++++++++++++++---- src/docs/component/usage-and-configuration.md | 20 ++----- 2 files changed, 48 insertions(+), 27 deletions(-) diff --git a/src/docs/component/advanced-usage.md b/src/docs/component/advanced-usage.md index 2382337..484ce0f 100644 --- a/src/docs/component/advanced-usage.md +++ b/src/docs/component/advanced-usage.md @@ -30,27 +30,29 @@ import DescriboCrateBuilder from ... const describo = ref() - // console.log(describo.value) -// { -// cm: function(), -// refresh: function(), -// setCurrentEntity: function({ id }), -// setTab: function(tabName) -// } ``` If you connect to the component via a reference, you will get access to an object with the following properties: -- cm: the internal CrateManager instance that the component uses to manipulate the data; -- pm: the internal ProfileManager instance; makes handling profiles/schema.org classes easy; -- refresh: a method to tell the current entity to refresh its display; -- setCurrentEntity({ id }): a method to set the enity to display; -- setTab(tabName): a method to display the selected tab. +- `cm`: the internal CrateManager instance that the component uses to manipulate the data; +- `pm`: the internal ProfileManager instance; makes handling profiles/schema.org classes easy; +- `state`: the internal state manager instance with controls to navigate back and forth and patch + the current state; +- `refresh`: a method to tell the current entity to refresh its display; +- `setCurrentEntity({ id })`: a method to set the enity to display; +- `setTab(tabName)`: a method to display the selected tab; +- `toggleReverseLinkBrowser`: a method to open / close the reverse link browser. Following are some examples of how you can use these methods. +## jsdoc docs + +You should also consult the documentation for Crate Manager (cm), Profile Manager (pm) and Editor +State (state) @ +[https://describo.github.io/crate-builder-component/](https://describo.github.io/crate-builder-component/) + ## Add data to the crate; modify the root dataset and refresh the display ::: warning NOTE! @@ -81,6 +83,35 @@ cm.linkEntity({ refresh(); ``` +## Add a fully resolved file or folder path to the crate + +As the component is embdeded into another application, it's likely the outer application will want +to add files and folders to the crate. This can be done easily with cm from your application. + +```JS +cm.addFile('/a/b/c/file.txt') +``` + +This will create the full path hierarchy of the file, starting from the root dataset and connected +via hasPart (as required by the spec) with the folders as type Dataset and finally linking the file. + +```JS +cm.addFolder('/a/b/c') +``` + +As described above but with only the folder paths. + +## Interact with the internal editor state + +The component maintains an internal editor state that has the history of paths taken through the +crate. You can access that via `state.editorState`, e.g.: + +```JS +// navigate back and forward through the history +state.editorState.back() +state.editorState.forward() +``` + ## Change the tab being displayed This assumes you've loaded a profile with tabbed grouping. diff --git a/src/docs/component/usage-and-configuration.md b/src/docs/component/usage-and-configuration.md index 5e27ad5..d875a0a 100644 --- a/src/docs/component/usage-and-configuration.md +++ b/src/docs/component/usage-and-configuration.md @@ -49,7 +49,6 @@ let crate = mintNewCrate() :enable-crate-preview="true" :enable-browse-entities="true" :enable-template-save="true" - :enable-internal-routing="true" :enable-reverse-link-browser="true" :enable-url-markup="true" :enable-entity-timestamps="true" @@ -57,8 +56,6 @@ let crate = mintNewCrate() :readonly="false" :web-component="false" :tab-location="'left'" - :reset-tab-on-entity-change="true" - :reset-tab-on-profile-change="true" :show-controls="true" :language="language" @ready="ready" @@ -138,13 +135,12 @@ for an example. In fact, you probably want to start from there. control - `enable-template-save`: true | false: `(default: false)` : enable / disable the entity and crate template saving controls -- `enable-internal-routing`: true | false: `(default: false)`: enable / disable the internal - router which updates the location whenever an entity is selected. If no router is found (ie - inside a web component or just not used), routing is turned off anyway. Most likely you want to - leave the component to deal with this or listen out for the `navigation` event and handle it - yourself if the component can't. - `enable-reverse-link-browser`: true : false: `(default: true)`: enable / disable the reverse - link browser. If enabled, it can be shown as a right sidebar as required. + link browser on the right of the main metadata editor. This is useful if you want to disable the + component controls bar but still have access to the reverse link browser. If enabled, it can be + shown as a right sidebar as required. If you connect to the component via a ref (see + [/docs/component/advanced-usage](/docs/component/advanced-usage)), you can also control the + reverse link browser in code. - `enable-url-markup`: true : false: `(default: true)`: When describo detects that a string is a URL, it will store an entity of type URL in the crate. If you would rather just have these as strings, set this to false (note that the URL primitive still outputs a URL entity) @@ -159,12 +155,6 @@ for an example. In fact, you probably want to start from there. some components when the crate builder is used as a web component. - `tab-location`: left | top | right | bottom: `(default: left)` : Specify where the tabs are shown when profiles define grouping. -- `reset-tab-on-entity-change`: true | false: `(default: true)` : When true, if a layout is - applied and the entity changes, the UI will navigate to the about tab. If false, that doesn't - happen. -- `reset-tab-on-profile-change`: true | false: `(default: true)` : When true, if a layout is - applied and the profile changes, the UI will navigate to the about tab. If false, that doesn't - happen if there is a matching tab. Otherwise it will go back to the about tab. - `show-controls`: true | false: `(default: true)` : Show or hide the controls bar. Useful if you want to provision those controls in your own application. - `language`: en | hu `(default: en)` : Sets the component's localization to the given language.