Iceberg, a block-based content editor
A content editor, with declaratively defined content blocks. Easily imports as a react component. Generates data in a simple JSON format.
Contents
- Iceberg element
- Block API
- Field API
- Sample setup with create-react-app
- Basic full example
- CSS
- Demo project
- Development
Iceberg element
<Iceberg.Editor = _state= = = />
Render an Iceberg editor.
blocks
: the set of editor blocks available in this editor (see Block API)data
: initialize the editor with some contentload_state
: one of the loading states (Loading
andError
are useful when loading content data asynchronously):Iceberg.State.Loading
Iceberg.State.Loaded
Iceberg.State.Error
delegate
: Iceberg calls theon_update()
method of your delegate object when data is saved:
const my_delagate = { // Kick-off a request to update the post data };
Block API
Iceberg.Blockset([ <block>, <block>, ... ]) -> blockset
- Define a blockset (a set of content blocks) for use in the editor.
- Returns the blockset object.
- Arguments:
[ <block>, <block>, ... ]
: an array of content block definitions
const text_blocks = Iceberg;
Methods
get(block_type) -> block
- Defined on a blockset created with
Iceberg.blockset()
. - Returns the requested block object from the blockset array.
Field API
A block contains one or more fields (see above).
<field>
:
name: 'content' description: 'Content' type: IcebergFieldsTextarea display_if: // To display this field only if a sibling has a value sibling: <sibling_name> equal_to: <value> // mutually exclusive not_equal_to: <value> //
(Note that display_if
can only operate on siblings of type Bool or Radio.)
Field types:
Iceberg.Fields.TextInput
- A simple text input.
Iceberg.Fields.TextArea
- A textarea for multiline, unstyled text.
Iceberg.Fields.TextEditor
- Multiline rich text editor.
Iceberg.Fields.Bool
- A yes/no toggle.
- Options:
text__yes: "Yes"
: label for the on state optiontext__no: "No"
: label for the off state option
Iceberg.Fields.Radios
- A set of radio buttons
- Options:
options: { value: "Label", ... }
: the set of radios
Iceberg.Fields.WPImage
- For wordpress integration: a wordpress media item. TBD.
Iceberg.Fields.SubBlock
- Embed another block into this block. Iceberg can compose blocks together recursively, allowing for complex content types, and aiding re-use of block definitions.
- Options:
description
: if supplied, used to title the wrapped subblock in the editorsubblock_type: MyTextBlock
: a block object (previously created withIceberg.Blockset()
) defining which subblock to embed.
Iceberg;
Iceberg.Fields.SubBlockArray
- Create a picker where the user can manage an array of subblocks, picking from types you predefine.
- Options:
description
: if suppied, used to title the wrapped subblock array in the editorsubblock_types: [ <block1>, <block2>, ... ]
: an array of block objects (previously created withIceberg.Blockset()
) defining what types of subblock the user can add to this subblock array.
Iceberg;
Sample setup with create-react-app
npx create-react-app my-appcd my-appnpm i -P iceberg-editor
To start:
- replace src/App.js with the demo App.js file
- run
npm run start
- visit
localhost:3000
Basic full example
;;;; // Define content blocks// ------------------------------- const blockset = Iceberg; // Handle updates// ------------------------------- const delegate = { console }; // Fetch some data & render// ------------------------------- { const data = __type: 'HeaderBlock' title: 'My article' author: 'Jane Smith' ; ReactDOM;} ;
CSS
The app needs to import the Iceberg CSS:
;
This currently includes bulma so at present weighs ~150kB. TBD: move to something more lightweight.
Demo project
/demo contains a minimal sample editor using Iceberg. Run npm run dev
to start webpack-dev-server, then visit http://localhost:3000
.
If prefer to use parcel (npm i -g parcel-bundler), you can instead run parcel demo/index.html
.
Development
Use the demo project and the dev
task.
To publish: npm publish
.
License
Iceberg is dual-licensed to enable Wordpress integration. The license is:
- GPLv2 for the purpose of embedding within Wordpress themes
- MIT for all other purposes
See LICENSE.md for details.