Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/simplajs/simpla-paths
Structure Simpla content in code with new HTML attributes
https://github.com/simplajs/simpla-paths
content-management custom-attributes data-structure simpla web-components
Last synced: about 2 months ago
JSON representation
Structure Simpla content in code with new HTML attributes
- Host: GitHub
- URL: https://github.com/simplajs/simpla-paths
- Owner: simplajs
- License: mit
- Created: 2017-02-21T01:56:25.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2017-12-15T05:56:28.000Z (about 7 years ago)
- Last Synced: 2024-11-19T04:28:35.188Z (about 2 months ago)
- Topics: content-management, custom-attributes, data-structure, simpla, web-components
- Language: JavaScript
- Homepage: https://www.simplajs.org
- Size: 145 KB
- Stars: 7
- Watchers: 3
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Simpla Paths
[![Build status][travis-badge]][travis-url] ![Size][size-badge] [![NPM][npm-badge]][npm-url]
Simpla-paths maps [Simpla][simpla] content paths to the DOM with new HTML attributes. This allows you to structure your content declaratively in code.
### Installation & usage
Simpla-paths is available on NPM/Yarn, Bower, and the Unpkg CDN
```sh
$ npm i simpla-paths --save
```
```sh
$ bower i simpla-paths --save
```
```
https://unpkg.com/simpla-paths@^1.0.0
```
[Setup Simpla][setup-simpla] on your page, then include simpla-paths in your ``. Simpla-paths is distributed as both an HTML import (`simpla-paths.html`) and a JavaScript file (`simpla-paths.min.js`). You can include either, but make sure you only include one of them.
```html
```
```html
```
Simpla-paths will automatically begin observing its attributes and constructing paths (except inside Shadow DOM - see [observing shadow roots](#observing-shadow-roots)).
## Constructing paths
Simpla-paths creates paths for elements by stringing together IDs used in new HTML attributes. For example, this markup
```html
```
Creates the path `/page/section/element` for the ``` element.
Simpla-paths exposes two new HTML attributes:
- `sid`: Scoped ID
- `gid`: Global ID
Every element with either of these attributes will get a `path` property set on it by simpla-paths.
### Scoped IDs
Scoped IDs (the `sid` attribute) are the building blocks of structured content. They are namespaced to any parent element with a path ID attribute. To created nested paths, just nest HTML elements with `sid` attributes
```html
```
### Global IDs
Global IDs (the `gid` attribute) always create new paths regardless of where they are used. When applied to Simpla elements, they are equivelant to specifying `path="/[gid]"`.
They are useful for creating reusable chunks of content that always have consistent data, regardless of where they appear on your site.
```html
```
## Dynamically reloading paths
Changing any ID in a chain of IDs recalculates the entire path. This means you can easily make your content react to changes in DOM.
```html
document.querySelector('#page').setAttribute('sid', 'about');
```
> Read more about [structuring data with simpla-paths](https://www.simpla.io/docs/guides/structuring-data)
## Observing shadow roots
Simpla-paths automatically observes IDs and constructs paths in the main document. To use `sid` and `gid` attributes in Shadow DOM you will need to tell simpla-paths to observe your shadow root manually.
Do this with the `observe()` method on the `SimplaPaths` global. It takes two arguments, the shadow tree to observe, and an optional base path (defaults to `'/'`).
```js
SimplaPaths.observe(el.shadowRoot, el.path);
```
## API
### Custom attributes
Attribute | Description
--------- | -----------
`sid` | Scoped ID, appended to parent IDs to create nested paths
`gid` | Global ID, creates a new root path
### Events
Events are fired on elements that `sid` or `gid` attributes set
Event | Detail | Description
-------------- | ------------------ | ------------
`path-changed` | `{ path: String }` | Fired whenever an element's path changes
## Contributing
If you find any issues with simpla-paths please report them! If you'd like to see a new feature in supported file an issue. We also happily accept PRs.
***
MIT © [Simpla][simpla]
[simpla]: https://www.simpla.io
[setup-simpla]: https://docs.simpla.io/guides/get-started.html
[npm-badge]: https://img.shields.io/npm/v/simpla-paths.svg
[npm-url]: https://www.npmjs.com/package/simpla-paths
[travis-badge]: https://img.shields.io/travis/simplaio/simpla-paths.svg
[travis-url]: https://travis-ci.org/simplaio/simpla-paths
[size-badge]: https://badges.herokuapp.com/size/github/simplaio/simpla-paths/master/simpla-paths.min.js?gzip=true