Getting started

It is an alternative to x-editable. Written in pure JavaScript.

Here's a quick demo on jfiddle to give you some example of how it works.

Quick start

You can install via npm
``
npm i dark-editable
`
or manually:

Required
- Bootstrap 5
- Popper
- Moment.js
1. Include it on your page.
`



`

2. Download corresponding dark-editable build and include it on your page:
`

`

If you can import then use:
`
dist/dark-editable.js
`
If you just want to connect globally to the page then use:
`
dist/dark-editable.iife.js
`

3. Markup elements that should be editable. Usually it is `` element with additional `data-*` attributes

`
superuser
`
Main attributes you should define are:
- `type` - type of input (text, textarea, select, etc)
- `url` - url to server-side script to process submitted value (/post, post.php etc)
- `pk` - primary key of record to be updated (ID in db)
- `id` or `name` - name of field to be updated (column in db). Taken from `id` or `data-name` attribute
- `value` - initial value. Usefull for select, where value is integer key of text to be shown. If empty - will be taken from element html contents
4. Enable popovers via JavaScript:
`
const usernameEl = document.getElementById('username');
const popover = new DarkEditable(usernameEl);
`
Alternatively, you can set all options via javascript
`
superuser
`
`
const usernameEl = document.getElementById('username');
const popover = new DarkEditable(usernameEl, {
type: 'text',
pk: 1,
url: '/post',
title: 'Enter username'
});
`
5. Frontend ready!\
Open your page and click on element. Enter new value and submit form. It will send ajax request with new value to `/post`.\
Request contains name, value and pk of record to be updated:
`
POST /post
{
name: 'username', //name of field (column in db)
pk: 1 //primary key (record id)
value: 'superuser!' //new value
}
`
6. Write backend part: \
X-editable has no limitation to server-side part: you can write it on any language you prefer.\
For example, you want to validate submitted value on server:
- If value is valid, you should return HTTP status 200 OK. Element on page will be updated automatically. No response body required.
- If value is not valid, you should return HTTP status != 200 (e.g. 400 Bad request) with error message in response body. Element on page will not be updated and editable form will display error message.

JSON response:\
If your server returns JSON, you can always send HTTP status 200 with error flag in response body.\
To process it use success handler:

response - Fetch Response
`
const usernameEl = document.getElementById('username');
const popover = new DarkEditable(usernameEl, {
...
success: async function(response, newValue) {
const res = await response.json();
if(res.error == 'error') return res.msg; //msg will be shown in editable form
}
});
`
Work LOCALLY:\
If you don't want to send value on server, just keep empty url option. You can process value in success handler:
`
const usernameEl = document.getElementById('username');
const popover = new DarkEditable(usernameEl, {
type: 'text',
title: 'Enter username',
});
`


Options

Options can be defined via javascript or via data-* html attributes.

| Name | Type | Default | Description |
|--------------|-----------------|----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
| ajaxOptions | object | {} | empty |
| disabled | boolean | false | Sets disabled state of editable |
| emptytext | string | 'Empty' | Text shown when element is empty. |
| error | function | null | |
| success | function | null | |
| name | string | null | Name of field. Will be submitted on server. Can be taken from `id` attribute |
| pk | string | null | Primary key of editable object (e.g. record id in database). |
| send | boolean | true | Strategy for sending data on server. When `true` data will be sent on server only if pk and url defined, otherwise new value will be stored locally. |
| showbuttons | boolean | true | Form without buttons is auto-submitted. |
| type | string or Class | 'text' | Type of input. Can be text/textarea/select/date and more |
| url | string | null | Url for submit, e.g. `'/post'` |
| value | mixed | element's text | Initial value of input. If not set, taken from element's text. |
| mode | string | 'popup' | Mode of editable, can be popup or inline. |
| popoverOptions | object | {} | Bootstrap Popover Options |


Methods

| Method | Parameters | Description |
|------------------|---------------------------------|---------------------------------------------|
| disable() | none | Disables editable |
| enable() | none | Enables editable |
| getValue() | none | Returns current values of editable elements |
| setValue(value) | - value Mixed new value | Sets new value of editable |
| getOption(value) | - value Mixed name option | Returns option value of editable elements |

Events

`
document.getElementById("username").addEventListener("save", function(e){
alert('Saved value');
})
`
| Event | Callback parameters | Description |
|--------|-----------------------------------|--------------------------------------------------------------------------------------------------------------|
| show | - event Object event object | Fired when container is show and form is rendered. |
| shown | - event Object event object | Fired when container is shown and form is rendered. |
| hide | - event Object event object | Fired when container was hide. It occurs on both save or cancel. |
| hidden | - event Object event object | Fired when container was hidden. It occurs on both save or cancel. |
| init | - event Object event object | Fired when element was initialized. Please note that you should setup init handler before applying editable. |
| save | - event Object event object | Fired when new value was submitted. |

Inputs

There are several input types supported by library. Each type may have additional configuration options.\
Currently supported:
- text
- textarea
- select
- date
- datetime
- html5types

text

Text input

| Name | Type | Default | Description |
|-------------|--------|---------|------------------------------------------------------------|
| placeholder | string | null | Placeholder attribute of input. Shown when input is empty. |

textarea

Textarea input

| Name | Type | Default | Description |
|-------------|--------|---------|------------------------------------------------------------|
| placeholder | string | null | Placeholder attribute of input. Shown when input is empty. |

select

Select (dropdown)

| Name | Type | Default | Description |
|--------|-------|---------|----------------------------------------------------------------------------------------------------------------------|
| source | array | [] | Source data for list. If array - it should be in format: [{value: 1, text: "text1"}, {value: 2, text: "text2"}, ...] |

date

Textarea input

| Name | Type | Default | Description |
|------------|--------|------------|---------------------------------------------------------------------------------------------------------------------|
| format | string | YYYY-MM-DD | Format used for sending value to server. Also applied when converting date from data-value attribute. Use moment.js |
| viewformat | string | YYYY-MM-DD | Format used for displaying date. Also applied when converting date from element's text on init. Use moment.js |

datetime

Textarea input

| Name | Type | Default | Description |
|------------|--------|------------------|---------------------------------------------------------------------------------------------------------------------|
| format | string | YYYY-MM-DD HH:mm | Format used for sending value to server. Also applied when converting date from data-value attribute. Use moment.js |
| viewformat | string | YYYY-MM-DD HH:mm | Format used for displaying date. Also applied when converting date from element's text on init. Use moment.js |

html5types

HTML5 input types. Following types are supported:
- password
- email
- url
- tel
- number
- range
- time

| Name | Type | Default | Description |
| ----------- | ------ | ------- | ---------------------------------------------------------- |
| attributes | object | {} | A map of HTML5 input attributes to apply on the input. |

$3

`js
const popover = new DarkEditable(el, {
type: 'number',
attributes: {
placeholder: 'Enter age',
min: 0,
max: 120,
step: 1,
required: true
}
});
``