Giter Club home page Giter Club logo

simpla-paths's Introduction

Simpla Paths

Build status Size NPM

Simpla-paths maps 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

$ npm i simpla-paths --save
$ bower i simpla-paths --save
https://unpkg.com/simpla-paths@^1.0.0

Setup Simpla on your page, then include simpla-paths in your <head>. 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.

<!-- As HTML import -->
<link rel="import" href="/bower_components/simpla-paths/simpla-paths.html">
<!-- As Javascript file -->
<script src="/node_modules/simpla-paths/simpla-paths.min.js"></script>

Simpla-paths will automatically begin observing its attributes and constructing paths (except inside Shadow DOM - see observing shadow roots).

Constructing paths

Simpla-paths creates paths for elements by stringing together IDs used in new HTML attributes. For example, this markup

<div sid="page">
  <div sid="section">
    <simpla-text sid="element"></simpla-text>
  </div>
</div>

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

<div sid="nested">
  <!-- path = /nested/path -->
  <simpla-text sid="path"></simpla-text>
</div>

<!-- path = /path -->
<simpla-text sid="path"></simpla-text>

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.

<div sid="page">

  <!-- path = /page/title -->
  <simpla-text sid="title"></simpla-text>

  <div gid="footer">

    <!-- path = /footer/company -->
    <simpla-text sid="company"></simpla-text>  

  </div>

</div>

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.

<div id="page" sid="page">
  <div sid="section">
    <simpla-text sid="title"></simpla-text>
  </div>
</div>

<!-- simpla-text path = /page/section/title -->

<script>
  document.querySelector('#page').setAttribute('sid', 'about');
</script>

<!-- simpla-text path = /about/section/title -->

Read more about structuring data with simpla-paths

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 '/').

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-paths's People

Contributors

bedeoverend avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar

simpla-paths's Issues

Use Symbols for path prop

Right now we're just setting the path property on any element that has an sid / gid property. This is a risk if the user wants to use these attributes on elements that already have a path property that's used for something else. There's no standard HTML path property, but users could have a custom-element that adds it.

This could be resolved by using a Symbol, rather than a String as the property. This would protect for unknown elements.

From a simpla element's perspective, to keep the regular path property on them, as well as getting the value from simpla-paths, it would have to import the Symbol used by simpla-paths (not much weight given tree-shaking), and pass the value set by paths to it's own path property. e.g.

import { PathSymbol } from 'simpla-paths';

class SimplaText extends HTMLElement {
  set [ PathSymbol ](value) {
    this.path = value;
  }

  get [ PathSymbol ](value) {
    return this.path;
  }
}

A Symbol polyfill would also have to be bundled somewhere, as Symbols aren't supported at all by IE, AFAIK the polyfill is relatively lightweight e.g. are used by SkateJS.

Data traversal?

Allow simpla-paths to traverse up/down the tree in attributes, using dot notation inside SIDs/GIDs. Fixes the use-case where markup structure doesn't perfectly match content structure, especially with shared code and complex content models

  • foo.bar to traverse down a tree

  • ..baz to traverse up a tree (additional dot for each level up)

  • Can combine patterns, eg: ..baz.qux

  • Can traverse in both SIDs and GIDs (obvs GIDs can only traverse down, useful for removing unecssary nesting)

  • If the key accessed with traversing doesn’t exist, it is created as per usual

Sanitize basePath

The basePath argument to SimplaPaths.observe() is confusing - intuitively you specify a leading slash, like /base/path, but that results in the following //base/path which is invalid. Likewise I was just guessing whether I should include a trailing slash or not, if I had it would have resulted in /base/path//sid which is also invalid.

I think the fix for this is for observe() just to sanitize whatever it gets in basePath (within limits), particular in regard to leading and trailing slashes.

Investigate perf issues

Very unscientiffic test, but ran Fetch as Google on simplajs.org, and the only thing that rendered was the one bit that isn't using simpla-paths (the footer)

screen shot 2017-12-16 at 4 26 36 pm

Might be worth profiling, and maybe even suggesting to deprecate this in favour of build-time path construction. Or, add a prerender buildstep to simpla-paths, so you can maintain easy clientside path recalculation

Should fire event on path change

Right now it's impossible to observe path changes on builtins, because simpla-paths doesn't fire any events to let us know when things change.

Should fire a path-changed event originating from the element set that looks something like

{
  detail: {
    path: ...
   }
}

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.