Declaratively contribute components to the parent layout

Preact is beautiful and pure. Literally, because with Preact we mostly write pure functions that take properties and render markup, possibly including child components that we control via their props. Information flows one way and everything is good.

But I just want to set the title of the page in the header. Do I really have to make the root component aware of the title of each page? What if I need something in the footer as well? Or in some sidebar? I want my Page component to contribute these components to it's parent, without it knowing about the parent and without the parent component knowing about the Page component... Is it even possible?

preact-layout does not only make this possible, it makes it simple!

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

• Define contribution functions
• Create a layout
• Use the contribution functions in your components
• Nest the component inside the layout

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(){}

Create a layout with sections for the Header and Footer:

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>

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.