Snek Jaen-Template

Welcome to the official Jaen [ˈdʒæn] template, presented by snek-at. Discover Jaen, the sleek, free, and secure CMS framework designed for Gatsby.

"A bowl is most useful when it is empty." - Lao Tzu

Report bug · Request feature · Documentation

What’s In This Document

• 💪 Motivation
  • Features
  • Development Roadmap
  • Msg inspiring PPL
  • Disclaimer
• 🚀 Get Up and Running in 5 Minutes
  • Generate from template Generate Jaen on GitHub
  • First Deployment
  • Deployment Options
    • Codespace Setup
    • Local Setup
      • Troubleshooting
  • Editing
• 💻 How to Code
  • Overview
    • App Settings
    • Page Settings
    • Fields
  • App Settings
  • Page Settings
  • Fields
    • SimpleTextField
    • SimpleRichTextField
    • SimpleImageField
    • SimplePdfField
    • StreamField
    • IndexField
  • Blocks
• 🐞 How to Report a Bug or Request a Feature
• 🤝 How to Contribute
• 💚 Thanks
• 💼 Creators
• 🤔 FAQs
• 📝 Copyright and License

💪 Motivation

Your CMS should not dictate the identity of your webapp. It shouldn't be restricted by eCommerce or any third-party integration. At the heart of your webapp should be your code.

Jaen is designed with this philosophy:

• Jaen integrates seamlessly, without disturbing your user experience.
• Jaen respects and complements your application design.
• Jaen empowers you with control and flexibility.

Our focus is singular: provide a clean, well-documented interface that is customizable, extensible, and open-source.

Features

Jaen offers:

• A swift, user-friendly interface for authors
• Complete autonomy over front-end design and structure
• Quick and cache-friendly performance
• StreamField for flexible content management without compromising structure
• Comprehensive support for images and embedded content
• Powered by blockchain, offering a free-running option
• A simple, intuitive WYSIWYG (What You See Is What You Get) editing mode

Development Roadmap

Here is a quick overview of our progress:

Feature	Shipped	Coming Soon	In Development	Under Investigation
IndexField	✅️
RichTextField	✅️
Email Support	✅️
Fixed parent for IndexField	✅️
TextField	✅️
Dynamic Routes	✅️
PdfField	✅️
ImageField	✅️
StreamField	✅️
LinkField		✅️
Gatsby			✅️
Converter (HELMUT)				✅️
Smart Converter (SMARTMUT)				✅️
E-Commerce				✅️
User Management				✅️
Email Templates				✅️
Development Tools				✅️
Snek Editor				✅️
YT Tutorials				✅️

🌟 Msg inspiring PPL

Remember, merely going in circles is not inspiring. Aim for progress, not motion.

⚠️ Disclaimer

Jaen is not for the faint of heart. It's a tool for developers who aren't afraid to roll up their sleeves and dive into the details. Approach with curiosity and a readiness to learn.

🚀 Get Up and Running in 5 Minutes

Generate from template Generate Jaen on GitHub

Generate from template	Important public and no branches

First Deployment

The GITHUB_TOKEN has limitations for the first deployment so we have to select the GitHub Pages branch on the repository settings tab. After that follow the instrucions shown in the pictures below to deploy successfully.

First deployment failed	Go to the settings tab

Select branch	Deploying again and succeed

Deployment Options

We recomend to use vscode as IDE in either an codespace or local setup.

Codespace Setup

The easiest method is to use a GitHub Codespace (in beta). Just create a GitHub Codespace from the Code menu. Wait for the Codespace to complete provisioning. When the Codespace has completed provisioning open a terminal window (Ctrl-`, Control-backquote) and:

• Add GitHub npm registry npm login --registry=https://npm.pkg.github.com
• Create .env and set PUBLIC_URL
• Start a local copy of the docs site with npm start
• Or build a local copy of the library with npm run build

Local Setup

If you decide to set up locally, make sure you have the following prerequisites:

• Add GitHub npm registry npm login --registry=https://npm.pkg.github.com
• Use npm install to install all dependencies
• Start a local copy of the docs site with npm start
• Or build a local copy of the library with npm run build

The demo site will now be accessible at http://localhost:3000/.

Troubleshooting

If you are having trouble to get the template up and running there are a few things you can try:

• node-sass requires you to use node15. If you have node16 you can use nvm to get the repository running without having to downgrade

If you encounter any other issues getting this template to work we ask you to report it so that we can improve the documentation.

Editing

To edit the page you have to log into the CMS.
The standard user for this is snekman and the password for the account is ciscocisco.

💻 How to Code

Overview

App Settings

Field	Properties	Description	Wiki	Tutorial
CMSProvider	settings pages	The CMSProvider registers a Jaen application and provides a way to share values (e.g fields) between Jaen and the template pages.

Page Settings

Field	Type	Description	Wiki	Tutorial
PageType	string	The PageType defines the name of your page in the context of the CMS.
ChildPages	[Pages]	ChildPages is an array of pages in which you define what subpages can be added to a particular PageType.

Fields

Field	Properties	Description	Wiki	Tutorial
SimpleTextField	name	A SimpleTextField can be used to add short editable texts to your page.	✅️
SimpleRichTextField	name	SimpleRichtextField is used to provide an editable RichTextField to your page.	✅️
SimpleImageField	name	A SimpleImageField provides you with the option to embed a image of your choice.	✅️
ImageField	fieldOptions imageClassName imageStyle	The ImageField can is used to provide editable images that can also be passed an imageStyle parameter as well as an imageClassName parameter in order to style your images.	✅️
SimplePdfField	name pdfStyle	If you want to embed a PdfFile on your page you can use our SimplePdfField.	✅️
StreamField	name reverseOrder blocks	With a StreamField you can build your own React-Components with editable content and repeat them as often as you like.	✅️
IndexField	fixedSlug outerElement renderItem	The IndexField provides you with the oppertunity to easily build links, buttons and more pointing to your subpages. It is also useful for building cards that rely on content from childpages. With the fixedSlug property you can decide which page the childpages are pulled from.	✅️

App Settings

import {CMSProvider} from '@snek-at/jaen'

import {HomePage} from '...'
import ImprintPage from '...'

const App: React.FC = () => {
  return (
    <div style={{margin: 150}}>
      <CMSProvider
        settings={{gitRemote: process.env.REACT_APP_JAEN_GIT_REMOTE}}
        pages={[HomePage, ImprintPage]}></CMSProvider>
    </div>
  )
}
)

Page Settings

import ImprintPage from '...'

const HomePage: ConnectedPageType = () => {...}

HomePage.PageType = 'HomePage'
HomePage.ChildPages = [ImprintPage]

export default HomePage

Fields

Fields are data blocks that you can use to build React apps which the enduser is able to maintain. Fieldnames have to be unique when they are on the same page. It is advisable to give all the fields descriptive names.

SimpleTextField

The SimpleTextField is as the name implies quite simple. You just have to give the field a name.

Wiki 📖

import {SimpleTextField} from '@snek-at/jaen'

const HomePage: ConnectedPageType = () => {
  return (
    <SimpleTextField name="stffield" />
  )
}

[...]

export default HomePage

SimpleRichTextField

SimpleRichTextField is also a quite simple field that only requires a name.

Wiki 📖

import {SimpleRichTextField} from '@snek-at/jaen'

const HomePage: ConnectedPageType = () => {
  return (
    <SimpleRichTextField name="srtffield" />
  )
}

[...]

export default HomePage

SimpleImageField

If you want to add an image to your page you can use the SimpleImageField.
It works by embedding an image that is hosted on the ipfs by the CMS.

Wiki 📖

import {SimpleImageField} from '@snek-at/jaen'

const HomePage: ConnectedPageType = () => {
  return (
    <SimpleImageField
      name="siffield"
    />
  )
}

[...]

export default HomePage

ImageField

The ImageField is a more powerful version of the SimpleImageField. In addition to giving the field a name you also have the oppertunity to pass the field an imageClassName as well as an imageStyle property to fulfill your styling requirements.

Wiki 📖

import {ImageField} from '@snek-at/jaen'

const HomePage: ConnectedPageType = () => {
  return (
    <ImageField
      fieldOptions={{fieldName: "iffield"}}
      imageClassName="iffield"
      imageStyle={{width: '500px', height: '500px', objectFit: 'cover'}}
    />
  )
}

[...]

export default HomePage

SimplePdfField

SimplePdfFields as the name implies enables you to embed a PDF hosted on the ipfs.

Wiki 📖

import {SimplePdfField} from '@snek-at/jaen'

const HomePage: ConnectedPageType = () => {
  return (
     <SimplePdfField name="spffield" pdfStyle={{height: 1000, width: 1000}} />
  )
}

[...]

export default HomePage

StreamField

Jaen StreamFields enable you to integrate editable blocks and to use as many of them as you like. In order to use this field you are required to build a block. You can find an example of a block below.

Wiki 📖

import {StreamField} from '@snek-at/jaen'
import {CardBlock} from '...'

const HomePage: ConnectedPageType = () => {
  return (
    <div style={{width: '50%', display: 'table'}}>
      <StreamField
        reverseOrder={false}
        name={'timeline'}
        blocks={[CardBlock]}
      />
    </div>
  )
}

[...]

export default HomePage

IndexField

If you want to link to childpages of a slug the IndexField is your friend. The fixedSlug property is not required. When none is provided the children of the current page are used if you like it is possible to specify the parentpage, the outerElement is the wrapper for all your items and the renderItem property allows you to build cards, teasers, buttons and more to your subpages.

Wiki 📖

import {IndexField} from '@snek-at/jaen'

const HomePage: ConnectedPageType = () => {
  return (
    <IndexField
      fixedSlug={'home'}
      outerElement={() => <div />}
      renderItem={(item, key, navigate) => (
        <p key={key}>
          Slug: {item.slug} Title: {item.title}{' '}
          <button onClick={() => navigate()}>Goto</button>
        </p>
       )}
    />
  )
}

[...]

export default HomePage

Blocks

The Block is the keystone of the StreamField. With the help of blocks you can build complex React-Components with editable content.

Wiki 📖

import {
  BC,
  prepareBlocks,
  ImageField,
  EditableField,
  RichTextField
} from '@snek-at/jaen'

type BlockType = {
  title: string
  extra: string
  text: string
  }

const Block: BC<BlockType> = ({
  fieldOptions,
  streamFieldWidth
}) => {
  const blocks = prepareBlocks<BlockType>(Block, fieldOptions)

  return (
    <>
      <div className="card">
        <h1>{title}</h1>
        {blocks['text']}
        {blocks['image']}
        {blocks['extra']}
      </div>
    </>
  )
}

Block.BlockType = 'Block'
Block.BlockFields = {
  image: ImageField,
  title: EditableField,
  extra: EditableField,
  text: RichTextField
}

export default Block

🐞 How to Report a Bug or Request a Feature

Have a bug or a feature request? Please first search for existing and closed issues. If your problem or idea is not addressed yet, please open a new issue.

🤝 How to Contribute

Please read through our contributing guidelines. Included are directions for opening issues, coding standards, and notes on development.

All code should conform to the Code Guide, maintained by snek-at.

💚 Thanks

We do not have any external contributors yet, but if you want your name to be here, feel free to contribute to our project.

💼 Creators

Nico Schett	Florian Kleber	Daniel Petutschnigg

🤔 FAQs

Q: What do the roadmap categories mean?

• Shipped - Hopefully you are enjoying it! Give us feedback on how it is working!
• Almost There - We are applying the finishing touches. Things in this bucket you can expect to be shipped within 2-4 weeks.
• We're Writing the Code - Actively in development, we are trying to get this out to you in a good state as soon as we can.
• Investigating - We're thinking about it. This might mean we're still designing, or thinking through how this might work. This is a great phase to send how you want to see something implemented! We'd love to see your usecase or design ideas here.

Q: Why are there no dates on your roadmap?

A: Because we know things change and we want the room to do the right thing by fixing security issues as they come up or helping people out where they need. This means we might have to change our priorities and don’t want to let people down.

Q: How can I provide feedback or ask for more information?

A: Please open an issue in this repo! If the issue is a bug or security issue, please follow the separate instructions above.

Q: How can I request a feature be added to the roadmap?

A: Please open an issue! You can read about how to contribute here. Community submitted issues will be tagged "Proposed" and will be reviewed by the team.

📝 Copyright and License

Use of this source code is governed by an EUPL-1.2 license that can be found in the LICENSE file at https://snek.at/license