layerjs / layerjs

layerJS: Javascript UI composition framework

Introduction

layerJS.org is an open source Javascript UI/UX library allowing intuitive, visually intense, mobile app-like experiences for web apps and websites.

UX patterns like menus, sliders, layers & light boxes, parallax effects, page-swipes, zoom effects, etc. are really just interactive animated layers. layerJS provides one simple universal concept to create such patterns in pure HTML: the Stage-Frame concept. Frames are containers that contain your content, e.g. sub pages, screens, menu panes, lightboxes, cards, slides, etc. Stages are viewports into which the frame content is dynamically fit. The root Stage is usually the browser window and its Frames represent sub pages or app screens. Frames can be exchanged within Stages using animated transitions like swipes, fades. Stages and Frames can be nested, so in an app screen(frame) a slider(stage) can exist which contains a set of slides (frames). Stages can have one or more overlapping layers with different frames, allowing effects like floating menus or parallax backgrounds.

layerJS’ concept resembles the principles of material design. In particular, layerJS’ frames are the papers/surfaces in material design. The stages are a convenient way to define the layout and the principal movements of the surfaces. With stages, animated transitions of the user interface can simply be defined by which frame should be shown in which stage in the next step.

Transitions are triggered through plain HTML links which simply name the frame which should be navigated to. layerJS also supports directional touch and touchpad gestures to trigger transitions. Use your fingers to pull down menus or swipe through a list of sub pages. Transitions can also be triggered through the API.

Watch this animation on how it works: https://layerjs.org/#explain-animation

Quickstart

layerJS can be included into your site from our CDN. Simply include the following tags into the head of your HTML document.

<script src="http://cdn.layerjs.org/libs/layerjs/layerjs-0.6.2.min.js"></script>
<link href="http://cdn.layerjs.org/libs/layerjs/layerjs-0.6.2.css" type="text/css" rel="stylesheet" />

In layerJS you will define stages, layers and frames simply by adding HTML-attributes to <div>s. Here is an example structure:

<div data-lj-type="stage">
    <div data-lj-type="layer" data-lj-default-frame="main" >
        <div data-lj-type="frame" >
            … your HTML code …
        </div>
    </div>
</div>

Find examples and live demos on our project website layerjs.org.

Check out the Wiki for more details.

Issues, bug reports and feature requests

If you experience any issues or bugs using layerJS or you would like to request features, please let us know through bitbucket issue tracking. This issue tracker is open to everyone so we encourage discussion on all issues.

How to contribute

Contributions to layerJS are more than welcome. Get in touch with us at [email protected] and discuss your ideas. You can also fork the repository and start building.

layerJS uses a contribution agreement to be able to republish code under future licenses if necessary: layerJS contribution agreement

Learn more about Harmony agreements.

layerjs's Issues

parse children identify method

this seems to be not correct:

1. why elem.nodeType !== 1 instead of elem.nodeType === 1?

2. "nodeType = pluginManager.identify(elem)" should be called only after identification through _wlView or type attribute. It should actually replace the "else if (undefined !== GroupView.getNodeType) “ clause.

3. Identify could also work for nodeType!=1
   
   Originally created at 2016-06-16 21:00:08+00:00 (UTC) by thomashandorf as a(n) major issue.

start position when swiping in same directions as scrolling

if for example the user swipes up to a frame that is a y-scroller, the start position should be automatically bottom. Now when swiping up it will scroll all the way up as the default start position is ‘top’

of course this should hold for all directions

should that one happen if the start position is the default? (e.g. manually setting start position to e.g. center will always scroll to center) NOTE: in particular if noScrolling is active and start position is center, the swipe should definitely go to center

Originally created at 2016-04-30 08:59:11+00:00 (UTC) by thomashandorf as a(n) major issue.

cannot select text

when dragging the mouse over text, sometimes text cannot be selected

Originally created at 2016-06-21 20:34:16+00:00 (UTC) by thomashandorf as a(n) major issue.

frame height is zero during setup when dimension derived from image

if a frame has no dimensions defined it will get it’s dimensions from the content. if this is an image of unknown dimension the frame height will be zero when the initial transform is calculated, hence creating a scroller of height zero

this is a minor problem as the frame dimension can be set.

best would be that the transition code reacts to size changes of the frames

Originally created at 2016-06-07 13:06:42+00:00 (UTC) by thomashandorf as a(n) major issue.

if no frame data-el-name is given layers fails

the following code fails:

<body data-wl-type="stage">
  <div data-wl-type="layer" data-wl-layout="canvas">
    <div data-wl-type="frame" data-wl-fit-to="width">
…

even though frames need names to be changeable there may be stages that have only one frame in which case no name is needed.

not sure what to do with this for now. A minor issue anyway

Originally created at 2016-06-07 12:53:53+00:00 (UTC) by thomashandorf as a(n) minor issue.

gesture manager: wheel gesture needs to detect x&y scrolling and save info into “shift” and “position"

• x & y scrolling needs to be detected
• this needs to be saved into position and shift to simulate a touch swipe
  
  
  Originally created at 2016-04-16 20:37:57+00:00 (UTC) by thomashandorf as a(n) major issue.

Filerouter does not transition to new state if the frames were already imported

if the router works w/o cache, the filerouter will detect that frames are already imported if navigating to the same state again.

However it will also not change the state (i.e. not transition to the new active frames)

Originally created at 2016-10-06 15:35:52+00:00 (UTC) by thomashandorf as a(n) minor issue.

testbug

A test

state gets confused when adding new text nodes

can be seen here:
http://layerjs-org.webflow.io/

preblem is that a mutation observer is fired as some script adds a text to the body elements which is a stage at the same time.

this fails in state.buildParent because it tries to reference parentElement which is not existing for textnodes (parentNode would be better here)

probably the whole state updating process should be stoped before anyway if the added node is not a layerjs relevant node

identify order

i don’t think identify order through the layers.js file do work

this is most likely not working reliably as some files may require groupview too early. I think there needs to be a special handling in pluginmanager
also "for (type in this.map)” doesn’t give a defined order. you need an array for a defined order

what about giving a priority value with each view registration with plugin manager?

Originally created at 2016-06-16 21:01:18+00:00 (UTC) by thomashandorf as a(n) major issue.

2x transitionTo lets all frames disappear

When calling transitionTo() a second time while the first transition is still running, the second transition will finish normally, but eventually all frames disappear (in plainLayout only)


Originally created at 2016-04-05 07:13:33+00:00 (UTC) by thomashandorf as a(n) major issue.

removeChild will not modify the View

when calling removeChild on an group (NodeData), the children list is correctly updated, but the View (which should listen to the change event) is not updating (e.g. removing the corresponding HTML from DOM)

Originally created at 2016-06-27 15:00:26+00:00 (UTC) by thomashandorf as a(n) major issue.

objects created from JSON seem Kern.Models not NodeData

data objects of views created in the importer example from the JSON objects transferred from the server seem to be of class Kern.Model rather then NodeData

Originally created at 2016-06-20 15:13:31+00:00 (UTC) by thomashandorf as a(n) major issue.

data-wl-width & height are not applied

layout.renderFramePosition() checks if width and height are in diff (which they are not) and hence does not set width and height of element

this has been observed in canvas layout, may also apply to other layouts

Originally created at 2016-06-07 15:28:59+00:00 (UTC) by thomashandorf as a(n) major issue.

removeChild will not modify the View

when calling removeChild on an group (NodeData), the children list is correctly updated, but the View (which should listen to the change event) is not updating (e.g. removing the corresponding HTML from DOM)

Originally created at 2016-06-27 15:00:26+00:00 (UTC) by thomashandorf as a(n) major issue.

identify nodeType!=1 nodes

in importer.js:
if (element.nodeType !== 1) {
nodeTag.content = element.data;
} else {

-> shouldn’t this be in the parser of nodeView?

Originally created at 2016-06-16 21:01:54+00:00 (UTC) by thomashandorf as a(n) major issue.

transitions for back button

when using the browsers back button, the previous frame / state will be transitioned to. layerJS will use the same transition type as used for the forward transition.

It would be great, if the transition could be inverted, e.g. if the original forward transition was a left, the backward transition would be right

Problems: not all transitions are investable;
how to define the inverted transition to a transition
how to make this configurable

Originally created at 2016-10-06 11:01:35+00:00 (UTC) by thomashandorf as a(n) major issue.

render resets style of frames

The new htmlAttributes will overwrite any transforms applied to frames if there was a style attribute during parsing.

hence in the example layerjs/test/html/scrolling.html initially all frames will be shown overlapping with no correct transform applied as the script in the site calls:

WL.select('[data-wl-name="main"]').data.set('neighbors',{l:'second',r:'second',t:'second',b:'second'});

which results in a render where style is set and hence transform and opacity / display are removed

Most likely solution:

do not set “style” for now from HTML attributes (we need to find a way later to deal with user provided style attributes - probably parsing them into the data.attributes.style block)

Originally created at 2016-06-07 14:19:40+00:00 (UTC) by thomashandorf as a(n) critical issue.

transitions for back button

when using the browsers back button, the previous frame / state will be transitioned to. layerJS will use the same transition type as used for the forward transition.

It would be great, if the transition could be inverted, e.g. if the original forward transition was a left, the backward transition would be right

Problems: not all transitions are investable;
how to define the inverted transition to a transition
how to make this configurable

Originally created at 2016-10-06 11:01:35+00:00 (UTC) by thomashandorf as a(n) major issue.

npm run buildexamples doesnt work for Windows

Description:
when running:
npm run buildexamples.

Result:
A failed err msg

*windows doesn't accept cp and rm commands that are in the build command

Originally created at 2016-10-31 15:49:07+00:00 (UTC) by GYoffe26 as a(n) major issue.

npm run buildexamples doesnt work for Windows

Description:
when running:
npm run buildexamples.

Result:
A failed err msg

*windows doesn't accept cp and rm commands that are in the build command

Originally created at 2016-10-31 15:49:07+00:00 (UTC) by GYoffe26 as a(n) major issue.

objects created from JSON seem Kern.Models not NodeData

data objects of views created in the importer example from the JSON objects transferred from the server seem to be of class Kern.Model rather then NodeData

Originally created at 2016-06-20 15:13:31+00:00 (UTC) by thomashandorf as a(n) major issue.

resize: scroll position lost

when resizing the stage (e.g. through window resize), the scroll position is set to the initial scroll position.

The easiest way would be to retain the current scroll position, which would mean that the upper border of the stage would be fixed.

scrollMax needs to be considered, but that may be already be included into the scrollTransformer.

Originally created at 2016-04-22 20:29:10+00:00 (UTC) by thomashandorf as a(n) major issue.

scrolling when fit-to=“cover"

should it scroll (maybe yes)
if not then we would need to disable scrolling also for native scroll
there seems to be a hick-up when scrolling in transform scrolling (jumps)
we need no-scrolling support for disabling scrolling

when layer does not contain frames it generates errors

when layer does not have any child frames and also no default frame specified it will break as currentframe and currentframetransform are not set.

The expected behaviour would be that it will react as if defaultframe where "none"

GroupView this_childView only keeps latest childview

The GroupView has a property _childViews with contains all the childViews in the group. This property is out of sync. It only keeps track of the last child in the groupView.

Maybe added childviews are getting overwritten. To verify.

slidelayout positioning of next frames incorrect

when swiping to the next frame, sometimes the next frame is not adjacent to current frame and the speed of the two frames may differ.

see attached screen cast

This seems to be related to shiftX/Y not correctly dealt with in pre placement of next frame (and /or post placement of current frame)

Originally created at 2016-05-23 10:32:50+00:00 (UTC) by thomashandorf as a(n) major issue.

router/filerouter does not work on file:// sites

when loading files from file system, AJAX requests are not possible so FileRouter will fail. In this case the router should go for the default / set window.location.href to the target url

Originally created at 2016-10-06 10:57:33+00:00 (UTC) by thomashandorf as a(n) major issue.

take id as frame name if lj-name is not given

when a frame has no given lj-name the layer will fail in the constructor as it will try to change to the current frame (which exists) by accessing currentframe.data.attributes.name
if no id is give either it should probably take frame[x] notation where x is the xth frame child

this most likely should be done in parse.

! this issue is on hold, because it will be solved differently after framework split

after the split it will be implemented in special getAttributes function

white space between frames when starting new transition while first is still running

see example.zip

i think i know why there is sometimes some white between the frames. In the above example click the right arrow and when the animation is still in progress, click on the left arrow. there will be a white area visible. this is because with the last click, the frame is positioned outside the screen so that it can come in from the left. I think in that case, the transition should not start from position (0,0) but rather from the current location of the frame.

also when your layer only has 2 frames (it is easier to explaine like this). you click to the left and during the transition you click again to the left? the exiting frame will disapaire and will be positoned at the right to come in from the right.

I think we should have some sort of mechanisme to combine or que the different transitions. Or know if a specific frame is still doing a transition.

This is also probably the reason why the scrolling sometimes feels jumpy (i think)

router initialisation does not consider current url

when loading an url like
file:///Users/handorf/tmp/xxx.html#frame2

where the default frame is frame1, frame1 is shown.

the router cache makes thinks worse since it would save the #frame2 url with frame1 being active

solution
the router needs to run once at startup with the current url to activate the correct state. Note: check how the cache needs to behave here AND use show instead of transition


Originally created at 2016-11-03 13:57:25+00:00 (UTC) by thomashandorf as a(n) critical issue.

frame.transformData.shift wrong

the shiftX and shiftY in the frame transformData are apparently wrongly treated. they are calculated in framespace in frameView.calculateTransformData but used as in stage space in layouts

I think they should be in stage space

(Note: scrollX/Y are in frame space)

Originally created at 2016-04-28 21:03:33+00:00 (UTC) by thomashandorf as a(n) major issue.

Filerouter does not transition to new state if the frames were already imported

if the router works w/o cache, the filerouter will detect that frames are already imported if navigating to the same state again.

However it will also not change the state (i.e. not transition to the new active frames)

Originally created at 2016-10-06 15:35:52+00:00 (UTC) by thomashandorf as a(n) minor issue.

transition type when doing direction swiping

currently when swiping left a transition of type “left” is triggered. This works currently as slidelayout only has 4 transition types and canvas layout ignores the type.

generally this decision should be done by the layout rather than the LayerView.

It should be configurable as there may be several left transitions. e.g. a left where the new frame zooms in.

Originally created at 2016-04-30 09:02:02+00:00 (UTC) by thomashandorf as a(n) major issue.

cannot select text

when dragging the mouse over text, sometimes text cannot be selected

Originally created at 2016-06-21 20:34:16+00:00 (UTC) by thomashandorf as a(n) major issue.

transition to currentFrame breaks swiping

when transitioning to same frame twice does not delete inTransition flag

Originally created at 2016-06-14 09:59:29+00:00 (UTC) by thomashandorf as a(n) major issue.

npm error message doesn't displaying LayerJS as Authur for the user to contact.

Gili Yoffe Today at 10:33am
status(23.12.16 - 10:24): Doesnt reproduce

scenario:

• downloaded zip from
  https://github.com/layerJS/layerJS
• ran : npm run build

expected result:
in a case of an error*
the info that is displayed to the user should
indicate the contactable author.
(reproduced once in the past and if this issue will get a higher priority - the next step would be to search for the specific scenario to reproduce the issue)
*sideNote: in this case, originally , wasn't expecting an err msg.

Actual result:
issue did not reproduce.

• received err msg that DOES contains layerjs as the Author that the user should contact.

attachments:
npm authur issue cmd log.txt
npm-debug.log as npm-debug.log.changeFileExtensionTo.log
because .log files are not possible to attach.

npm authur issue cmd log.txt

npm-debug.log.changeFileExtensionTo.log.txt

router/filerouter does not work on file:// sites

when loading files from file system, AJAX requests are not possible so FileRouter will fail. In this case the router should go for the default / set window.location.href to the target url

Originally created at 2016-10-06 10:57:33+00:00 (UTC) by thomashandorf as a(n) major issue.

using <!DOCTYPE html> will deactivate/breaks layerJS functionalities

Description:
*was reproduced with the nested example from the wiki.

• In the html file, insert at the first line.
• Save.
• Open the webpage in the browser (tested with chrome: Version 54.0.2840.71 m (64-bit))

Result:
Nothing is showing (no content?)

Originally created at 2016-11-03 08:21:57+00:00 (UTC) by GYoffe26 as a(n) major issue.

layerJS scope: make document and window as closure

when using jsdom in node environments it may be helpful to have document and window non-global

Originally created at 2016-05-23 19:22:07+00:00 (UTC) by thomashandorf as a(n) major issue.

frame width/height and box-sizing

the frame width is calculated wrongly if paddings and borders are applied. This could in principle be fixed by setting border-box on all frames but this may have impact on the users css code. so ideally calcFrameTransform will detect which box sizing is in effect and will use the right width/height anyway.

after each transition setLayerTransform is called

setLayerTransform may do a complete defender depending on how the layer layout is implemented. We should check whether a setLayerTransform is needed after the transition is done

router cache stores wrong state

when having the cache active and changing the state outside the router (gesture or api) the current caching mechanism will store the state only during the next routing event. So this will actually store the state after the gesture and api changes but not the state that was initally set during the former routing event

We need a way to store in the cache once the new state is set after an routing event

using <!DOCTYPE html> will deactivate/breaks layerJS functionalities

Description:
*was reproduced with the nested example from the wiki.

• In the html file, insert at the first line.
• Save.
• Open the webpage in the browser (tested with chrome: Version 54.0.2840.71 m (64-bit))

Result:
Nothing is showing (no content?)

Originally created at 2016-11-03 08:21:57+00:00 (UTC) by GYoffe26 as a(n) major issue.

router causes TWO clicks in case of a non-layers link

if a link is pressed and the routers do not react to it (non-layers link) the router will retrigger the click event.
However when other frameworks are listening to the click event they will be called twice in this way.

One way could be to use stopImmediatePropagation. This however ist not secure as it depends on layerjs being attached first.

The other way is not to retrigger the click event but work with setting window.location.href. Would that work or was there a reason for retriggering the event

resize events is bound to window

check if it is possible to bind to the stage instead

if not we need to go for mutation observers

Originally created at 2016-04-24 19:20:27+00:00 (UTC) by thomashandorf as a(n) major issue.

position of frames in “canvas” layout via CSS

it should be possible to position frames in canvas mode though top and left css properties.

the difficulty here is that this needs to be overwritten by the transform later on (or at least compensated)

Originally created at 2016-06-07 14:59:38+00:00 (UTC) by thomashandorf as a(n) major issue.

isRendered does not work

in render() isRendered is checked in order to decide if only the changedAttributes will be considered. There is

1. a spelling error “isRendererd”
2. isRendered is false when the View was initialized with an existing element (hence render() is never called) -> does that make sense or should a pre-rendered element have “isRendered=true”?

This has been observed in GroupView but may apply to other View Classes as well

(currently, after a render (e.g. after changing the data object) all properties will be rendered)

Originally created at 2016-06-07 14:14:51+00:00 (UTC) by thomashandorf as a(n) minor issue.

scroll through should stop at end of frame

when scrolling to the end of a frame where a neighbor frame is in the same direction, layerJS will directly continue from scrolling into the transition.

This is not what the user expects. The scrolling should stop there for a moment

Eventually it should depend on whether the scroll wheel / touch scrolling is in kinetic mode. So far this is not possible so currently there should be a pause and possibly a threshold for low wheel speeds.

Originally created at 2016-05-06 20:23:12+00:00 (UTC) by thomashandorf as a(n) major issue.

slidelayout: old frames stay until last transition ends

this is most likely related to transitionend only firing at the end. It’s unclear however why the frames disappear anyhow because only the last transitionend listener should fire anyhow.