# j-Paper

> Edit rich content as a list of widgets.

Framework: jcomponent20
Product: jComponent 20 (jcomponent@20)
Language: en
Content-SHA256: 27be8a8200fd381bf1d9ecd1c1215b31459d0476bb1e402451936dd3e34484f7
Snapshot: c0700e321579725c5cf4f5ace1ad7d2866d1b4f93c24a63c0b41b6b7998e976c
Sources: components@910ed1a86f6e72b4f031d3ad0dc7844f9fc5cb8e
Review: usage-reviewed

The component edits a document as an array of widget objects. Bind a model path to that array, configure the widget repository, and use autosave to write edits back to the model.

- output is a simple `Object Array` structure:
	- `[{ id: String, widget: String, newbie: Boolean, changed: Boolean, config: Object }]`
- widgets repository: https://github.com/totaljs/parts/tree/main/paper

__Configuration__:

- `readonly {Number}` enables/disables readonly mode `0=disabled`, `1=partially enabled`, `2=fully enabled`
- `parent {String}` optional, a parent element for min-height (default: `null`)
- `margin {Number}` additional margin for min-height (default: `0`)
- `autosave {Boolean}` changes are serialized according to the path automatically
- `widgets {String}` a link to the widgets (default: Componentator CDN)
	- it can contain multiple addresses divided by the comma `mywidget1.html,/mywidget2.html,etc..`
	- or you can keep [CDN structure](https://github.com/totaljs/parts/blob/main/cdn/paper/db.json)
- `icon {String}` a link to the `function(opt, callback)`
	- `opt.element {jQuery element}`
	- __IMPORTANT__: call the `callback` argument if the icon has been changed in the element
- `link {String}` a link to the `function(opt)`
	- `opt.element {jQuery element}`
	- `opt.href {String}`
	- `opt.target {String}`
	- `opt.widget {Object}` a widget instance
- `command {String}` a link to the `function(cmd)`
	- `cmd.widget {Object}` a temporary widget instance
	- `cmd.widgets {Array}` a list of registered widgets
	- `cmd.remove() {Function}` removes widget
	- `cmd.append(name)` replaces the current temporary widget with a new widget (`name` name of widget)
- `format {String}` a link to the `function(toolbar)`
	- `toolbar` can be `null`
	- `toolbar.element {jQuery element}` a current element
	- `toolbar.node {HTML element}` a current element
	- `toolbar.widget {Object}` a widget instance
	- `toolbar.style {Object}` contains a current style e.g. `bold: 1, link: 1`
- `upload {String}` a link to the `function(opt, callback)`
	- `opt.accept {String}` optional
	- `opt.files {FileList}` optional
	- `opt.multiple {Boolean}` optional, default: `false`
	- `opt.width {Number}` optional
	- `opt.height {Number}` optional
	- __IMPORTANT__: `callback` argument must be executed after upload with the `files {Array}` argument
- `change {String}` a link to the `function(change)`
	- `change.id {String}` identifier
	- `change.block {String}` a block identifier
	- `change.blockprev {String}` a previous block identifier
	- `change.widget {String}` a widget id
	- `change.type {String}` operation type (insert, update, remove)
- `contextmenu {String}` a link to the `function(widget)` when the user pressed the right mouse button on the widget
- `check {String}` a link to the `function(widget)` that decides whether to enable editing or not
- `placeholder {String}` a placeholder for the default HTML widget (default: `Press / for adding rich content`)

__Methods__:

- `component.save(function(data, ischange) {` for saving content
- `component.import(url or url_array, [callback])` for importing additional widgets
- `component.notify(event, [a], [b], [c], [d])` emits event in every widget

__Good to know__:

The component creates a global variable called `window.papercache {Object}` used by all `j-Paper` instances.

- the component compares the content when you change data, so you can change data in real-time
- the component assigns (in the form) `paper-yourwidgetname` class to every widget element
- reserved HTML classes `readonly`, `widget`, `selected`
	- readonly usage: `.readonly .paper-yourwidgetname { ... }`
- `htmlelement.$widget {Object}` contains a widget instance
	- `widget.remove()` method will remove the widget

__Shortcuts in text edit__:

- `CMD + m` highlights text
- `CMD + l` creates a link
- `CMD + p` adds an icon
- `CMD + b` bold
- `CMD + i` italic
- `CMD + u` underline

__Good to know__:

- `[data-prevent]` attribute can prevent click event in the widget

## Usage

```html
<ui-component name="paper" path="form.widgets"
  config="autosave:true;widgets:/paper/db.json"></ui-component>
<script>
  SET('form.widgets', []);
  function saveDocument() {
    SETTER('paper/save', function(widgets) {
      console.log(widgets);
    });
  }
</script>
```

Serve the widget index at /paper/db.json and its widget files from your application. The save callback receives the serialized widget array.

Source: [Total.js components](https://github.com/totaljs/components/tree/910ed1a86f6e72b4f031d3ad0dc7844f9fc5cb8e/j-Paper). Copyright Peter Širka and contributors. [MIT license](/knowledge-licenses.json).