Simpla-article lets you write longform, rich-media articles seamlessly inline with a single HTML element. It's built on the Simpla content system.
<simpla-article path="/article"></simpla-article>- Installation and setup
- Writing articles
- Saving articles
- Styling article content
- Initializing with static content
- Custom placeholders
- Typographer
- Readonly
- Contributing
Install simpla-article with Bower (Yarn support coming soon)
$ bower i simpla-article --saveSetup Simpla on your page, then import simpla-article into your <head>
<link rel="import" href="/bower_components/simpla-article/simpla-article.html">Use the <simpla-article> element wherever you want to create a new article. Give each article a unique path, where it will store its content in your project
<simpla-article path="/article"></simpla-article>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.
// Enter edit mode
Simpla.editable(true);<!-- Make only this article editable -->
<simpla-article path="/article" editable></simpla-article>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.
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
Save a simpla-article by calling Simpla's save() method, which saves all modified content on the page. It returns a promise.
// Save all modified content on page
Simpla.save();You must be authenticated with Simpla before saving 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.
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
<p> - Bold text is wrapped in
<strong> - Italic text is wrapped in
<em> - Links are wrapped in
<a> - Blockquotes are wrapped in
<blockquote> - Headings are wrapped in
<h1>or<h2> - Lists use standard list elements (
<ul>,<ol>,<li>) - Embedded images use standard
<img>
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.
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.
<simpla-article path="/article">
<h1>Simpla Article</h1>
<p>Write longform, rich-media articles seamlessly inline</p>
</simpla-article>Initializing with static content is useful for converting existing sites to Simpla, or bootstrapping a project with predefined content. By putting markup inside <simpla-article> 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
<simpla-article>in production. If newer content gets saved you will experience FOUC (Flash Of Unformatted Content) when the static content is overwritten
You can set custom placeholders (displayed when simpla-article is editable and doesn't have content) with a placeholder attribute
<simpla-article
path="/article"
placeholder="Tell your story">
</simpla-article>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
<simpla-article
path="/article"
no-typographer>
</simpla-article>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.
<simpla-article path="/article" readonly></simpla-article>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