Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/simplajs/simpla-collection

Create editable collections of content straight in HTML
https://github.com/simplajs/simpla-collection

collection content-management custom-element simpla web-components

Last synced: about 2 months ago
JSON representation

Create editable collections of content straight in HTML

Awesome Lists containing this project

README 

        
# Simpla Collection

[![Build status][travis-badge]][travis-url] ![Size][size-badge] ![Version][bower-badge] [![Published][webcomponents-badge]][webcomponents-url]



Simpla-collection lets you create dynamic collections of content in HTML. It consumes a HTML template, which users can add, remove, and reorder instances of inline on your page. It's built on the [Simpla][simpla] content system.



```html



  

    

  



```



### Contents



- [Installation and setup](#installation-and-setup)

- [Editing a collection](#editing-a-collection)

- [Saving collections](#saving-collections)

- [Using simpla-paths](#using-simpla-paths)

- [Custom item names](#custom-item-names)

- [Collection data model](#collection-data-model)

- [Readonly](#readonly)

- [Contributing](#contributing)



### Resources



- [API reference][api]

- [Demo][demo]

- [License][license]



## Installation and setup



Install simpla-collection with Bower (Yarn support coming soon)



```sh

$ bower i simpla-collection --save

```



[Setup Simpla][simpla-setup] on your page, then import simpla-collection into your ``



```html



```



Use `` wherever you want to create a collection of items. Define the item template in a `` inside simpla-collection. Give each collection a unique `path`, where it will store its content in your project. Simpla-collection also exposes an `[item]` key to use in the paths of Simpla elements inside your template.



```html



  

    

  



```



## Editing a collection



Manage the items in your collection by entering edit mode with Simpla (which makes all Simpla elements on a page editable) or setting the `editable` property directly on the element.



```js

// Enter edit mode

Simpla.editable(true);

```



```html



  ...



```



Entering edit mode with Simpla is the recommended way to edit collections. It ensures all elements on a page remain in sync and updates Simpla's public `'editable'` state, which other elements may rely on.



## Saving collections



Save a `simpla-collection` by calling Simpla's `save` method, which will save all modified content on the page. It returns a promise.



```js

// Save all modified Simpla content

Simpla.save();

```



> You must be authenticated with Simpla before saving content



## Using simpla-paths



Simpla-collection works with [simpla-paths](https://github.com/SimplaElements/simpla-paths), which lets you build content paths for Simpla elements declaratively with HTML attributes. This is useful for creating more complex collection items



```html



  

    


       

       

    


  



```



## Custom item names



You can change the default item name used by simpla-collection with the `as` property. Setting a custom item name changes the key used for templating Simpla paths, as well as labels throughout simpla-collection's edit UI. It doesn't effect the data saved by the colleciton.



```html



  

    

  

 

```



## Collection data model



Simpla-collection stores meta information about its items on Simpla's API and in its `items` property as an ordered Array:



```js

[

  { id: 'dwubz' },

  { id: 'h3sqb' },

  ...

]

```



The order of the items objects in the `items` array determines the order of the items rendered in the collection.



Each item has a unique ID, which is generated for the `[item]` templating key in the item template. A single item ID can map to several paths of content. For example, given the following template:



```html



  

    

    

  

 

```



A single item ID (eg: `'dbuwz'`) would map to the following paths:



```

/gallery/dbuwz/img

/gallery/dbuwz/caption

```



## Readonly



Simpla-collection 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-collection to purely consume and display content from Simpla's API.



```html



  ...



```



## Contributing



If you find any issues with simpla-collection 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](https://slack.simpla.io). 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-collection/page/API.md

[demo]: https://www.webcomponents.org/element/simplaio/simpla-collection/demo/demo/index.html

[license]: https://github.com/simplaio/simpla-collection/blob/master/LICENSE



[bower-badge]: https://img.shields.io/bower/v/simpla-collection.svg

[bowerlicense-badge]: https://img.shields.io/bower/l/simpla-collection.svg

[travis-badge]: https://img.shields.io/travis/simplaio/simpla-collection.svg

[travis-url]: https://travis-ci.org/simplaio/simpla-collection

[size-badge]: http://img.badgesize.io/simplaio/simpla-collection/master/simpla-collection.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-collection