Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/simplajs/simpla-article
Write longform, rich-media articles seamlessly inline
https://github.com/simplajs/simpla-article
article content-management custom-element richtext simpla web-components
Last synced: 2 months ago
JSON representation
Write longform, rich-media articles seamlessly inline
- Host: GitHub
- URL: https://github.com/simplajs/simpla-article
- Owner: simplajs
- License: mit
- Created: 2017-05-23T16:23:11.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2017-12-15T05:55:17.000Z (about 7 years ago)
- Last Synced: 2024-11-11T23:51:45.141Z (3 months ago)
- Topics: article, content-management, custom-element, richtext, simpla, web-components
- Language: HTML
- Homepage: https://www.simplajs.org
- Size: 169 KB
- Stars: 8
- Watchers: 6
- Forks: 0
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Simpla Article
[![Build status][travis-badge]][travis-url] ![Size][size-badge] ![Version][bower-badge] [![Published][webcomponents-badge]][webcomponents-url]
Simpla-article lets you write longform, rich-media articles seamlessly inline with a single HTML element. It's built on the [Simpla][simpla] content system.
```html
```
### Contents
- [Installation and setup](#installation-and-setup)
- [Writing articles](#writing-articles)
- [Editing inline](#editing-inline)
- [Saving articles](#saving-articles)
- [Styling article content](#styling-article-content)
- [Initializing with static content](#initializing-with-static-content)
- [Custom placeholders](#custom-placeholders)
- [Typographer](#typographer)
- [Readonly](#readonly)
- [Contributing](#contributing)
### Resources
- [API reference][api]
- [Demo][demo]
- [License][license]
## Installation and setup
Install simpla-article with Bower (Yarn support coming soon)
```sh
$ bower i simpla-article --save
```
[Setup Simpla][simpla-setup] on your page, then import simpla-article into your ``
```html
```
Use the `` element wherever you want to create a new article. Give each article a unique `path`, where it will store its content in your project
```html
```
## Writing articles
Write and edit articles by entering edit mode with Simpla (which makes all Simpla elements on a page editable) or setting the `editable` property directly on an article element.
```js
// Enter edit mode
Simpla.editable(true);
```
```html
```
Entering edit mode with Simpla is the recommended way to edit articles. It ensures all elements on a page remain in sync and updates Simpla's public `editable` state, which other elements may rely on.
### Editing inline
Simpla-article supports the following content types:
- Formatted text (Bold/Italic)
- Links
- Headings
- Blockquotes
- Lists (ordered and unordered)
- Embedded images
To format text and apply links, headings, and blockquotes, highlight the text you want to modify and use the appropriate tool from the toolbar.
To embed an image, focus on an empty line and tap the camera icon that appears to the left of the cursor. Once the image has been embedded select it to change its alignment.
Write lists inline, and they will be automatically converted to HTML lists by simpla-article.
```
Unordered list:
- Item
- Item 2
Ordered list:
1. Item
2. Item 2
```
## Saving articles
Save a simpla-article by calling Simpla's `save()` method, which saves all modified content on the page. It returns a promise.
```js
// Save all modified content on page
Simpla.save();
```
> You must be authenticated with Simpla before saving content
## Styling article content
Simpla-article doesn't style your content, and generates the same clean, semantic markup you would write if you were to code the content yourself.
```css
simpla-article h1 {
font-size: 1.8em;
font-weight: 400;
}
```
These are the only HTML elements allowed by simpla-article's content model:
- Paragraphs are wrapped in `
`
- Bold text is wrapped in ``
- Italic text is wrapped in ``
- Links are wrapped in ``
- Blockquotes are wrapped in ``
- Headings are wrapped in `` or ``
- Lists use standard list elements (``, ``, `- `)
- Embedded images use standard `![]()
`
Embedded images have a `data-alignment` attribute with the image's current alignment (eg: `data-alignment="left"`). You can use this attribute to customize how aligned images behave.
## Initializing with static content
You can write HTML content inside simpla-article just like you would with any other element. The HTML you insert will be parsed and sanitized into simpla-article's content model when you enter edit mode. If content for an article's `path` exists on Simpla's API any static content will be overwritten.
```html
Simpla Article
Write longform, rich-media articles seamlessly inline
```
Initializing with static content is useful for converting existing sites to Simpla, or bootstrapping a project with predefined content. By putting markup inside `` and then calling `Simpla.save()` you can easily set static content directly to Simpla's API.
> Since static content is overwritten by remote data, you should not have content inside `` in production. If newer content gets saved you will experience FOUC (Flash Of Unformatted Content) when the static content is overwritten
## Custom placeholders
You can set custom placeholders (displayed when simpla-article is editable and doesn't have content) with a `placeholder` attribute
```html
```
## Typographer
Simpla-article applies 'smart typography' rules to its content, including:
- Smart quotes (`"` to `“`)
- Automatic em dashes (`--` to `—`)
- Automatic ellipses (`...` to `…`)
You can disable the smart typographer by giving simpla-article a `noTypographer` property
```html
```
## Readonly
Simpla-article has a `readonly` property that stops it from becoming editable, even if Simpla is in edit mode or you try to set `editable` on the element directly. This is useful for using simpla-article to purely consume and display content from Simpla's API.
```html
```
## Contributing
If you find any issues with simpla-article please report them! If you'd like to see a new feature in supported file an issue or let us know in Simpla's public [Slack group][slack-url]. We also happily accept PRs.
***
MIT © [Simpla][simpla]
[simpla]: https://www.simpla.io
[simpla-setup]: https://docs.simpla.io/guides/get-started.html
[api]: https://www.webcomponents.org/element/simplaio/simpla-article/page/API.md
[demo]: https://www.webcomponents.org/element/simplaio/simpla-article/demo/demo/index.html
[license]: https://github.com/simplaio/simpla-article/blob/master/LICENSE
[bower-badge]: https://img.shields.io/bower/v/simpla-article.svg
[travis-badge]: https://img.shields.io/travis/simplaio/simpla-article.svg
[travis-url]: https://travis-ci.org/simplaio/simpla-article
[size-badge]: http://img.badgesize.io/simplaio/simpla-article/master/simpla-article.html?compression=gzip&label=render_bundle_%28gzip%29
[webcomponents-badge]: https://img.shields.io/badge/webcomponents.org-published-blue.svg
[webcomponents-url]: https://www.webcomponents.org/element/simplaio/simpla-article