With just 2 components, the API is very simple to learn, yet powerful.

• Layout to define layouts
• Section to divide the layout into multiple sections

preact-layout allows you to define contribution functions that are used as JSX tags that signal that the components contained in those tags should be contributed to another section of the parent layout.

For example, for a simple layout with a header and a footer around some main content block, we might define these functions:

function Header(){}
function Footer(){}

Then, create a layout with Header and Footer sections:

function MyLayout({children}) {return (
	<Layout>
		<div>
			<header>
				<Section type={Header}><b>header</b></Section>
			</header>

			<Section>{children}</Section>

			<footer>
				<Section type={Footer}><i>footer</i></Section>
			</footer>
		</div>
	</Layout>
)}

Now, we can build components that use the contribution functions to contribute components to the related sections of the layout:

function MyPage(){return (
	<div>
		<Header><h1>my page</h1></Header>
		<article>main article</article>
		<Footer>goodbye</Footer>
	</div>
)}

Finally, render the component nested within the layout:

render(
	<MyLayout>
		<MyPage />
	</MyLayout>
	,
	document.getElementsByTagName('body')[0]
)

This will result in:

<div>
	<header>
		<h1>my page</h1>
	</header>
	<div>
		<article>main article</article>
	</div>
	<footer>
		goodbye
	</footer>
</div>

You can now change the layout completely separate from the component. As long as both refer to the same contribution functions Header and Footer (which you create and are custom to your app), things will work as expected.

You can reuse those contribution functions across multiple layouts:

function ReversedLayout({children}) {return (
	<Layout>
		<div>
			<footer>
				<Section type={Footer}><i>footer</i></Section>
			</footer>

			<Section>{children}</Section>

			<header>
				<Section type={Header}><b>header</b></Section>
			</header>
		</div>
	</Layout>
)}

Note how ReversedLayout also uses Footer and Header contribution functions

We can now simply render MyPage with this new ReversedLayout and get a completely different end result without changing one line of code in the MyPage component:

render(
	<ReversedLayout>
		<MyPage />
	</ReversedLayout>
	,
	document.getElementsByTagName('body')[0]
)

Renders:

<div>
	<footer>
		goodbye
	</footer>
	<div>
		<article>main article</article>
	</div>
	<header>
		<h1>my page</h1>
	</header>
</div>

Getting started with preact-layout:

• Setup - Add preact-layout to your project
• Basic Usage - Using Layout, Section and contribution functions
• Examples - Learn by example!

• Layout - Create layouts using Layout
• Section - Divide your layout into named Sections
• contribution functions - Defining conribution functions

When collecting contributions, preact-layout peeks ahead at the elements that the child components will produce by rendering those child components. The resulting elements could itself again contain components, which would need to be rendered as well, leading to recursive rendering that of course comes at a performance cost. You can tune this cost by setting the recurse attribute on the Layout to some positive number. It defaults to 9.

Add an issue in this project's issue tracker to let me know of any problems you find, or questions you may have.

Copyright 2016 by Stijn de Witt. Some rights reserved.

Licensed under the Creative Commons Attribution 4.0 International (CC-BY-4.0) Open Source license.