Component API

This article will introduce you to components. Component are central in penguin.js. It's the only place where you can handle dynamic data.

A component is a JS file that lives in ./components. There is a naming convention: simpletext_editor.js will be exported with the component name "SimpletextEditor".

Usage of components: You can mount components on HTML elements. Mount a component by adding a data attribute data-component. E.g. <p data-component="SimpletextEditor">FooBar</p>.

The very basic structure of a component is explained below. It is important, that every component exports two functions - a render and a mount function.

• render(ctx, props)

  • Called on the server
  • Should return a string or an object:
  • Returning a string will set the content as innerHTML. Example: return "<p>example</p>"
  • Object must contain on or more of the following properties:
    • replace - A string as value that is used to replace the outerHTML of the html element
    • attrs - An object which gets merged into the attributes of the html element
    • Example cases:
      • Don't show element in the rendered HTML: return { replace: ''}
      • Don't change element in rendered HTML: return { attrs: {}}

• mount(ctx, props, el)

  • Called on the client
  • Should initialize el
  • Can return an object with hooks
    • save() - Is called before the page/object is saved (can update the state)
    • destroy() - Is called before the object is destroyed

• ctx Provides information and actions on the current page/object.

  • save([callback]) - Saves the page/object
  • publish([callback]) - Publishes the whole project (all pages/objects)
  • destroy([callback]) - Destroy the object (only valid for objects)
  • store - The redux store
  • language - The current language

• props Contains all props passed by the developer of the website (through data-props)

• el The dom element the component is mounted on

• Distinguish environments

  • Check for production (CDN) environment

    if (process.env.PENGUIN_ENV === 'production') { ... }

  • Check for development (Editing server) environment

    if (process.env.PENGUIN_ENV === 'development') { ... }