ceri

1.0.26 • Public • Published

ceriJS

You love reusable web-components, but googles polymer just doesn't look right to you? Then you have come to the right place.

The aim of CeriJS is to make development and maintenance of custom elements v1 as easy as possible.

Ecosystem

cerijs - core and tooling
ceri-comps - simple components built with ceri
ceri-widgets - complex components built with ceri and other ceri-components

Features

  • incoperates many concepts of VueJS
  • declarative instead of imperative
  • not monolithic
  • a component only loads what it needs
  • endless backwards compatibility, new API is delivered alongside old one
  • not limited to help only in "common" use cases
  • tooling for building, testing and publishing

I want to use a component built with ceri

I want to build a component with ceri

I want to build a mixin for ceri

When should you want to build a component with ceri?

Lets face it, the API of your framework of love will change - if its vue, react or angular. Within a single project this is no problem, but as soon as you have several projects with sharing code, maintenance caused by API change can get tedious.

So as a rule of thumb: use ceri if you plan to use your component across projects, if it is project specific, use the framework of the project and keep it homogenous.

I want to use a component built with ceri

Custom elements aren't widely adopted, yet. So you have to use the lightweight custom-element polyfill:

npm install --save-dev document-register-element

then call it somewhere in your app

// always load the polyfill
require("document-register-element")
 
// load the polyfill only when needed - with the help of webpack
function polyfillCE() {
  require.ensure([], require => {
    require("document-register-element")
    startupApp() // your startup code depending on window.customElements
  },"cePoly")
}
if !window.customElements
  polyfillCE()
else
  startupApp() // your startup code depending on window.customElements

To register a component:

// the name should contain at least one hyphen
window.customElements.define("ceri-component", require("ceri-component"))
// and create a element programatically
el = document.createElement("ceri-component")

or use it in your markup

<ceri-component></ceri-component>

The native customElements implementation depends on ES6 classes, this requires some setup of webpack when using the UglifyJSPlugin:

npm install --save-dev uglifyjs-webpack-plugin git://github.com/mishoo/UglifyJS2#harmony

then use it in your webpack.config

UglifyJSPlugin = require("uglifyjs-webpack-plugin")
plugins: [new UglifyJSPlugin()]

I want to build a component with ceri

  • ATTENTION: ALL API IS STILL IN BETA AND CAN CHANGE ANYTIME

Getting started

first have a look at ceri-boilerplate

Install

npm install --save-dev ceri

Usage

# the wrapper creates a ES6 or ES5 class, depending if the polyfill is loaded, and calls ceri on it 
ceri = require "ceri/lib/wrapper"
# the component 
module.exports = ceri
  mixins: [
    require "ceri/lib/watch"
    require "ceri/lib/structure"
  ]
  structure: template 1"""
    <div :text="textprop"></div>
    <slot></slot>
    """
  data: ->
    textprop: "someText"
  watch:
    textprop: -> console.log "textprop changed"

Guideline for building a component

  • Required style for features should be managed in style attributes
  • Optional style should be delivered in one or multiple "theme" css files alongside your component
  • Use a mixin only if it helps to reduce complexity in your use-case. They don't come for free
  • HTMLElement has a lot of properties, try to not conflict with them

Reactions

All official reactions of all mixins will be merged into your component, with exception of constructor.

For setup code use created instead. All created callbacks will be called in the constructor

List of mixins

Name Links Short description
class doc src helper functions to interact with element classes
classes doc src manage the classes of your element structure
combined doc src helper function to create a computed property which combines a prop, data and computed obj
computed doc src adds computed property
events doc src adds basic events management
path doc src helper functions to move on objects
props doc src adds props with attributes reflection
structure doc src adds core element structure creation
style doc src helper functions to interact with element style
styles doc src manage the styles of your element structure
svg doc src adds svg creation to structure
tests doc src call unit test on ceri-views
util doc src some basic helper functions
watch doc src adds reactive data

List of directives

Name Links Short description
#ref doc src saves the element on your instance
#text, :text doc src sets the textContent of the element
#if doc src toggle element
#show doc src toggle visibility of an element

Template attributes

Used with structure mixins and template compiler of ceri-compiler or ceri-loader.

<!-- as expected -->
<div attr="value"></div> 
 
 
<!-- binds attr to the reactive prop @propName -->
<div :attr="propName"></div>
 
 
<!-- binds the property prop of the div to the reactive prop @propName -->
<div $prop="propName"></div>
 
 
<!-- adds an eventListener on the div which will call the fn @fnName-->
<div @click="fnName"></div>
<!-- use capture mode -->
<div @click.capture="fnName"></div>
<!-- only when target == @ -->
<div @click.self="fnName"></div>
<!-- only when not prevented -->
<div @click.notPrevented="fnName"></div>
<!-- call preventDefault() -->
<div @click.prevent="fnName"></div>
<!-- call stopPropagation() -->
<div @click.stop="fnName"></div>
<!-- remove eventListener once it got called -->
<div @click.once="fnName"></div>
 
 
<!-- adds an function @focusDiv which will call focus on the div -->
<div ~focus="focusDiv"></div>
<!-- emit an event "focus" instead -->
<div ~focus.event="focusDiv"></div> 

Mixins

Class

Helper functions to interact with element classes

mixins: [ require("ceri/lib/class") ]
# usage 
@$class.set(el{someClass: true}) # set class on el to "someClass", el defaults to @ 
@$class.strToObj("someClass") # {someClass: true} 
@$class.objToStr({someClass: true}) # "someClass" 
@$class.setStr(el"someClass") # set class on el to "someClass" 

Classes

Manage the classes of multiple elements, imperativly and declerativly

mixins: [ require("ceri/lib/classes") ]
# usage with structure & props 
props: class: 
  type: String
  name: "_class" #rename prop, as class is already taken on HTMLElement 
structure: template(1,"""<div #ref="someDiv"></div>""")
data: -> @classToggled: true
classes:
  this: # to target the instance 
    computed: -> someClass: @classToggled # someClass will be removed on @classToggled = false 
    data: -> someOtherClass: true # can be accessed: @classes.this.someOtherClass = false 
    prop: "_class" # bind to a prop to pass through a user given class 
  someDiv: # to target a ref 
    data: -> classForSomeDiv: true

Combined

Helper function to create a computed property which combines a prop, data and computed obj into one.

mixins: [ require("ceri/lib/combined") # used in classes and styles 
# usage 
@$combined({
  path: "somePath"
  value:
    someName:
      data: -> # should return object, will be accessible under @somePath.someName 
      computed: -> # should return object 
      prop: # name of a prop to watch 
  parseProp: (propValue) -> # optional, should convert the value to an object 
  normalize: (obj) -> # optional, should return a normalized object 
  cbFactory: (name) -> [(val) ->
    # name will be "someName" 
    # the cbs will be called whenever the combined object changes 
  ]
})

Computed

Used to lazily recompute a value whenever a dependend, reactive value changes

mixins: [ require("ceri/lib/computed") 
# usage 
data: -> someDependency: true
computed:
  # @computed.someData will be updated when @someDependency changes and its getter is called 
  someData: ->
    return @someDependency*1
# when a callback is attached, the computed property will be evaluated 
# as soon as a dependency changes 
# to attach a callback: 
@$watch.path path:"computed.someData"initial: truecbs: [(newVal) ->
  # do something with newVal 
  ]

Events

adds basic events management

mixins: [ require("ceri/lib/events") 
# usage 
events:
  someEvent: (e) -> # attaches an eventListener on @ 
#to issue a custom event 
@$emit el"someEvent""someOptions" # el defaults to @ 
@$emit "someEvent""someOptions" # options will be accessible on e.detail 

Path

helper functions to move on objects

mixins: [ require("ceri/lib/path") ]
# usage 
data: -> some: path: true
@$path.toValue(path:"some.path") # {path:"some.path",value:true} 
@$path.setValue(path:"some.path",value:false) # @some.path == false 
@$path.toNameAndParent(path:"some.path") # {path:"some.path",name:"path",parent:@some} 

Props

adds props with attributes reflection.

mixins: [ require("ceri/lib/props") ]
# usage 
props:
  someProp: String # will be connected with "some-prop" attribute 
  someProp2:
    type: Boolean # will be casted to boolean 
    name: "_someProp2" # will be accessible as @_someProp2 instead of @someProp2 
  someProp3: Number # will be casted to number 
watch:
  someProp: (val, old) -> # props are reactive 

Structure

adds core element structure creation. Looks for directives.

mixins: [ require("ceri/lib/structure") ]
# usage 
# adds <div attr=value><p></p></div> 
# as a child of your custom element 
structure: ->
  return @$el "div"{"":{attr:"value"}}[@$el "p"]
# alternative with ceri-compiler / ceri-loader 
structure: template 1"""<div attr=value><p></p></div>"""

Style

Helper functions to interact with element styles

mixins: [ require("ceri/lib/style") ]
# usage 
@$style.set(el{position:"absolute"}) # el defaults to @ 
@$style.normalize("position") # will find vendor prefixes 
@$style.normalizeObj({position:"absolute"}) # normalize all keys 
@$style.setNormalized(el{position:"absolute"}) # same as set, but will not call normalize on obj 

Styles

Manage the styles of multiple elements, imperativly and declerativly

mixins: [ require("ceri/lib/styles") ]
# usage with structure & props 
props: style: 
  type: String
  name: "_style" #rename prop, as style is already taken on HTMLElement 
structure: template(1,"""<div #ref="someDiv"></div>""")
data: -> height: 10
styles:
  this: # to target the instance 
    computed: -> height: @height + "px"
    data: -> position: "absolute"  # can be accessed: @styles.this.position = "relative" 
    prop: "_style" # bind to a prop to pass through user given style 
  someDiv: # to target a ref 
    data: -> position: "absolute"

Svg

adds svg creation to structure

mixins: [ require("ceri/lib/svg") ]
# allows this: 
structure: template 1"""<svg></svg>"""

Tests

Unit test within a ceri view. This shouldn't be used in your component.

mixins: [ require("ceri/lib/tests") ]
# usage 
tests: (el) ->
  describe "your compontent"->
    it "should exist"->
      should.exist(el)

Util

Some basic helper functions

mixins: [ require("ceri/lib/util") ]
# usage 
@util.noop #empty function 
# returns an array wrapping the argument, if it isn't already one 
@util.arrayize({}) # [{}] 
@util.isString
@util.isArray
@util.isObject
@util.isFunction
@util.isElement
@util.camelize("test-test") # testTest 
@util.capitalize("test") # Test 
@util.hyphenate("testTest") # test-test 

Watch

Adds reactive data

mixins: [ require("ceri/lib/watch") ]
# usage 
data: -> someData: true
watch:
  someData: (val,old) -> # will be called when @someData is set 

Directives

#ref

saves the element on your instance

mixins: [ require("ceri/lib/structure") ]
# usage 
structure: template 1"""<div #ref="someDiv"></div>"""
# accessible under @someDiv 

#text, :text

sets the textContent of the element

mixins: [ require("ceri/lib/structure") ]
# usage 
structure: template 1"""<div #text="someText"></div>"""
# will result in <div>someText</div> 
# use :text to bind to a reactive var instead 
structure: template 1"""<div :text="someText"></div>"""
data: ->
  someText: "content"
# will result in <div>content</div> and will be updated on change of @someText 

#if

toggle an element

mixins: [ require("ceri/lib/#if") ]
# usage with structure and watch 
structure: template 1"""<div #if=visible></div>"""
data: -> visible: true

#show

toggle visibility of an element

mixins: [ require("ceri/lib/#show") ]
# usage with structure and watch 
structure: template 1"""<div #show=visible></div>"""
data: -> visible: true

I want to build a mixin for ceri

All sorts of mixins can be submitted, make sure to include a unit test and a proper documentation.

Try to restrict your mixin to a namespace with the help of _rebind.

# simple example 
module.exports =
  _name: "someMixin"
  _v: 1
  _rebind: "$someMixin"
  mixins: [
    # add the mixins you depend on 
    # these will be flattend on runtime 
  ]
  methods:
    $someMixin:
      anArray: [# will be cloned to the instance 
      anObject: {} # shallow cloned to the instance 
      aFunction: -> # will be bound to the instance 
 

License

Copyright (c) 2017 Paul Pflugradt Licensed under the MIT license.

Readme

Keywords

none

Package Sidebar

Install

npm i ceri

Weekly Downloads

31

Version

1.0.26

License

MIT

Last publish

Collaborators

  • paulpflug