coze_demo/socket/node_modules/pillarjs/docs

PillarJS is a "batteries included" JavaScript library for writing smart reusable Web Components in a modern way.

Inspired by React components PillarJS provides familiar state management mechanisms and Virtual DOM, while also providing all of the sweetness of Web Components like Shadow DOM, "by-definition" server side rendering and ability to render from template tags and strings.

Shortcuts

1. Getting started
2. Using stateless components
3. Options
4. Using JSX
5. Browser support
6. FAQ

Getting Started

Getting started is simple:

Step 1. Import PillarJS:

import Pillar from 'pillarjs';

Step 2. Create your component:

class SuperHeader extends Pillar {
	render(props) {
		return (
			<div>
				<h1>{props.text}</h1>
				<h3>It's Superpowered!</h3>
			</div>
		);
	}
}

Looks familiar? Pillar components are written in the exact same way as React components.

Note: Because Pillar uses Preact for rendering JSX, props and state are passed as arguments to the render() method for convenient destructuring. You can still use this.props and this.state if you want to, but it's not required.

Step 3. Register your custom tag:

Pillar.register(SuperHeader, 'super-header');

Second argument is an optional tag name. If not set, component name converted to dash-case will be used.

Step 4. Use it!

<div id="main">
	<super-header text="This is not a simple header!"></super-header>
</div>

And you're good to go! Custom tag's attributes will be passed to this.props in your component and resulting HTML on the page will be:

<div>
	<h1>This is not a simple header!</h1>
	<h3>It's Superpowered!</h3>
</div>

Can I use stateless components?

Yes, you can! The above class example can be trimmed down to this:

const SuperHeader = ({ text }) => (
	<div>
		<h1>{text}</h1>
		<h3>It's Superpowered!</h3>
	</div>
);

Options

A third argument passed to Pillar.register is an options object:

{
	useShadow: 'open' || 'closed',
	allowScripts: true // Template render only
}

useShadow option enables Shadow DOM. Pass open for open mode and closed for closed. See the difference here.

allowScripts By default, all <script> tags will be removed from the content of the template tag before rendering. This option re-enables them and permits executing any JavaScript code within template tag. Be careful with this option.

Notes on JSX

There are 3 ways to enable JSX with Pillar:

1. Using a Babel preset (easiest)

   // .babelrc
   {
   	"presets": ["pillar"]
   }
   

   ``

2. By adding:

   /** @jsx Pillar.h */
   

   ``

   on top of the file containing JSX. This will tell Babel to turn all JSX calls into Pillar.h calls. This is useful if for instance you already have React in your project and don't wan't to overwrite all of JSX behavior.

3. In .babelrc:

   {
   	"presets": [...],
   	"plugins": [
           "transform-react-jsx",
           {
               "pragma": "h" // default pragma is React.createElement
           }
   	]
   }
   

   ``

What browsers are supported?

Pillar is written with the web platform in mind. According to WebComponents.org, the current support for platform features is as follows:

Browser Support
Template Tags	❇️ Stable	❇️ Stable	❇️ Stable	❇️ Stable	❇️ Stable
Custom Elements	❇️ Stable	❇️ Stable	❇️ Stable	🛠 Developing	🤔 Considering
Shadow DOM	❇️ Stable	❇️ Stable	❇️ Stable	🛠 Developing	🤔 Considering
Module Scripts	❇️ Stable	❇️ Stable	❇️ >10.1	🏁 Flag in 54	🏁 Flag in 15
HTML Imports	❇️ Stable	❇️ Stable	⏱ On Hold	⏱ On Hold	🤔 Considering

And this is what the support looks like with the polyfill:

Polyfill Support
Template Tags	❇️ Stable	❇️ Stable	❇️ Stable	❇️ Stable	❇️ Stable
Custom Elements	❇️ Stable	❇️ Stable	❇️ Stable	☘️ Polyfill	☘️ Polyfill
Shadow DOM	❇️ Stable	❇️ Stable	❇️ Stable	☘️ Polyfill	☘️ Polyfill
Module Scripts	❇️ Stable	❇️ Stable	❇️ >10.1	☘️ Polyfill	☘️ Polyfill
HTML Imports	❇️ Stable	❇️ Stable	☘️ Polyfill	☘️ Polyfill	☘️ Polyfill

Note: Pillar does not include any polyfills. You are responsible for pollyfilling for your target browsers.

FAQ

Q: I am morally opposed to JSX! How can I use this?

Pillar also supports rendering from string and template tags. We'll get to explaining those in a bit.

However using JSX provides a whole lot of awesome features that you'll be missing out on otherwise.

Q: I'm morally opposed to Webpack and bundling! How can I use this?

Pillar doesn't impose any build systems on you. All you need to get started is drop a script tag on the page.

The downside of not using a build system is unavailability of JSX via Babel. But you can still use string render and template tags and get all benefits of Virtual DOM.

Q: I am morally opposed to HTML Imports!

We are too. Safari and Firefox aren't going to implement them, and they are just generally weird. Pillar doesn't rely on them and we suggest not to use them.

Q: Do I need React to use this?

Nope. Pillar is inspired by React components approach and uses Preact under the hood for features like Virtual DOM and linkState but it's not React nor does it require it.

Q: Can I have content inside of my custom elements?

Yes! By default all elements inside your custom tag will be passed to this.props.children. There's a flag to disable that behavior.

Q: I am morally supportive of imperative DOM manipulations. Will this still work?

Pillar is your friend! If outside forces like jQuery decide to change your element's attributes, changes will be passed down to this.props and componentWillReceiveProps will be called as you would expect.

Q: Can I use React library XYZ to do ZYX?

No idea. Pillar doesn't use React, it only uses JSX via Preact, so if library XYZ just does some JSX stuff and doesn't heavily depend on React core, it might work, but no promises.

Q: How do I port my single page app to Pillar?

Whoa whoa, hold your horses. Pillar serves different purpose than React or Angular or Vue or what have you. You're not supposed to be building an SPA with this.

Pillar is not a framework, it's a Web Components library.

Web components are a set of web platform APIs that allow you to create new custom, reusable encapsulated HTML tags to use in web pages and web apps.

What Pillar does is allows you to create componens that are smarter than just a collection of tags and styles and allow you to do things like interactivity, networking, etc.

If you want to build a dynamic single page app, this library is probably not the tool you're looking for.

Next: Lifecycle Methods →