-
Notifications
You must be signed in to change notification settings - Fork 6
Home
Welcome to the link(-redux) reference, this document should provide an overview of how to achieve most common tasks while developing your application.
- Introduction
- Preparations
- IRI's
- Accessing the store
- Retrieving server data
- Querying local data
- Retrieving contextual information
- Rendering resources
- Rendering properties
- Rendering data types
- Actions, middleware and state changes
- Inheritance and reasoning
- Devtools
Link provides the functionality to build a fully-featured linked-data browser, it's also possible to just mix-and-match the functionality you need for your specific application.
Most tasks (e.g. data fetching) can be done in a number of ways, each with their own considerations. Link generally provides both imperative and declarative ways to attain the desired result. The imperative tools usually provide quick and easy results with a lot of flexibility, while the declarative tools provide a stable base for scaling and adapting to a variety of data sources.
Most applications will use both to achieve the best balance between performance, readability, scalability and maintainability.
Note: Link-redux has been through a lot of changes since its inception, the name implies the use of the popular Redux framework, while this was true in the past, link-redux has dropped its dependency and provides it's own middleware which is better adopted for processing linked data.
Use createStore to initialize a store to hold all data, and pass it to the RenderStoreProvider to provide your child components access;
const lrs = createStore()
ReactDOM.render(
(
<RenderStoreProvider value={lrs}>
// The rest of your app
</RenderStoreProvider>
)
document.getElementById('app')
)Linked data uses URL's for resources and properties. It can be tedious to write and instantiate those URL's, so the store provides a helper with some namespaces for that.
const lrs = createStore()
export const NS = lrs.namespacesUse NS.app('my/path') for all app-related things and when you're not sure. It is always relative to the domain your app is viewed on (github.com in the case of this documentation).
// The `app` namespace is relative, it uses window.location.origin (the current location)
NS.app('fletcher91/link-lib') // https://github.com/fletcher91/link-libA lot of popular namespaces are preconfigured (see the list)
NS.foaf('name')
NS.owl('sameAs')The following popular ontologies are available as plain objects as well;
Which can be called more easily;
NS.schema.name
NS.rdf.typeRetrieve the store in your component;
const MyComponent = () => {
const lrs = useLRS()
}const MyComponent = (props) => {
const lrs = props.lrs
}
const EnhancedComponent = withLRS(MyComponent)Mounting a LinkedResourceContainer will retrieve the resource passed as subject when it's not in the store yet.
<LinkedResourceContainer subject={NS.app('person/5')} />It's always possible to create a component which wraps an API;
const RestApiPerson = ({ id }) => (
<LinkedResourceContainer
subject={new NamedNode(`http://example.com/person/${id}`)}
/>
)
// And use it in your app
<RestApiPerson id={friends[0].id} />This is especially useful for API's which don't publish their data properly, i.e. 'RESTful API's' where an IRI has to be transformed before it can be fetched (x.com/api/v1/persons/5?type=linkedData while the IRI is just x.com/persons/5).
The simplest method to fetch data from a server is via getEntity, which returns a promise which will resolve once the resource has been fetched. The promise has no value, rather your component should re-render when it finishes loading.
await lrs.getEntity(NS.app('person/5'))Use queueEntity to let the store know it should be fetched in the near future. It is considerably more performant than getEntity since it doesn't create a promise and allows the store to batch data requests more efficiently.
lrs.queueEnitity(NS.app('person/5'))Not available at the time of writing
const MyComponent = (props) => {
return (
<div>
<h1>{props.name.value}</h1>
<p>{props.description.value}</p>
</div>
)
}
const EnhancedComponent = link({
name: NS.schema.name,
description: NS.schema.description,
})(MyComponent)If you pass your component to register, you can skip the link HOC and use the mapDataToProps static property, which does the call for you.
const Comp = ({ name }) => (
<div>{name.value}</div>
)
Comp.type = NS.schema.Thing
Comp.mapDataToProps = {
name: NS.schema.name,
}
export default register(Comp)Use tryEntity to retrieve actual data from the store. An empty array is returned when no data was found.
const data = lrs.tryEntity(NS.app('person/5'))const Comp () => {
const { subject, topology } = useLinkRenderContext()
return (
<p>Current subject: {subject.value} in topology {topology.value}</p>
)
}When mounting a LinkedResourceContainer, the resource will be fetched and if an accompanying view can be found that will be rendered.
<LinkedResourceContainer subject={resource} />You can pass a view implementation as a child when you only need to fetch the resource.
<LinkedResourceContainer subject={resource}>
<Property label={NS.schema.name} />
</LinkedResourceContainer>Mounting the Property component will render the best fitting view if present.
<Property label={NS.schema.name} />If the property is another resource and no view can be found, a LinkedResourceContainer will be mounted automatically rendering the containing resource. If it's a value (e.g. string, number, dollars, centimetres) and no view can be found the plain value will be displayed.
<Property label={NS.schema.name} /> // Will render e.g. "Bob's great adventure"
<Property label={NS.schema.author} /> // Will render the author mentioned in the propertyIn the example above, the author is a direct association on the surrounding resource. But oftentimes such associations are one-apart. When passing children to Property it will render those, but if the property is an association it will set that context first. This can be made use of to quickly render nested associations.
<Property label={NS.schema.name} /> // Will render the name of the book
<Property label={NS.schema.author}> // Will render its children if no property renderer for schema:author can be found
<Property label={NS.schema.name} /> // Will render the name of the author
<Property label={NS.schema.name}>
</Property>
</Property>If you need a (child resource) property within the context of the current view, you can use a render function to receive it without handing off control to a child component.
<Property label={NS.app.comments}> // Some ActivityStreams Collection
<Type /> // Will render view of the current subject, as if no children were passed here
<Property label={NS.as.totalItems}>
// The render function will recieve an array of all values for the given predicate
// We only use the first one here
{([count]) => {
<Link text={`Show all ${count.value} items`} />
}}
</Property>
</Property>Rendering the associated resource of a property is a good default in almost any case, but rendering a value as-is might not. See the rendering data types section for more info on how to customize the rendering behaviour.
Even if a resource has a property multiple times, it will render only one view by default. If you want to render the view multiple times, pass a custom limit.
// Will render the alternate name property at most 10 times
<Property label={NS.schema.alternateName} limit={10} />Using limit will render the entire view multiple times. If you need more than one value for a single view, you can request that in your view.
const CommentsRenderer = ({ linkedProp }) => (
<React.Fragment>
{linkedProp.map((name) => <p>{name.value}</p>)}
</React.Fragment>
);
CommentsRenderer.property = NS.schema.Person
CommentsRenderer.property = NS.schema.alternateName
CommentsRenderer.renderOpts = {
limit: 10,
}Most programming languages have certain built-in datatypes (e.g. string, bool, char, byte, longlong, etc), RDF has some built-in types as well (many from xsd such as string, boolean, or dateTime and from RDFS langstring), but it isn't limited to those types. Datatypes are just RDF resources and make sense to use for most quantities (e.g. expressing money like dollars, distance like centimetre, or volume like gallons) but also for more complex types (e.g. markdown formatted strings, DNA codon).
When the Property component terminates at a value (no view could be found), then it defaults to rendering the plain value. This works fine for (lang)strings, but when a datatype needs more formatting to be valuable to the user, a renderer for a class of data types can be registered.
const DollarRenderer = ({ linkedProp }) => (
<span>
${Number(linkedProp.value).toFixed(2)}
</span>
) // E.g. "2.5" => "$2.50"
DollarRenderer.type = NS.rdfs.Literal
DollarRenderer.property = new NamedNode("http://dbpedia.org/datatype/usDollar")TODO
If an ontology is loaded like any other resource it can be rendered, but it will not have any effect on how the engines view determination. If you want to add that information you have to use addOntologySchematics on the LinkedRenderStore. The statements added with addOntologySchematics will also be added to the main data store so they can be used by the views.
lrs.addOntologySchematics([
new Statement(s, p, o,g )
])The primary reason why these are separate is to prevent changing application behaviour when just browsing resources, possibly breaking the application when a server sends bad data.
It is strongly advised to use the experimental react devtools for chrome or firefox which has support for React hooks and other newer features (yes, the stable version doesn't have that yet at the time of writing...).
We also have some devtools internally which are planned to be published to npm, hit us up for them in the mean time.