Simpla Collection

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 content system.

<simpla-collection path="/collection">
  <template>
    <img is="simpla-img" path="/collection/[item]">
  </template>
</simpla-collection>

Installation and setup
Editing a collection
Saving collections
Using simpla-paths
Custom item names
Collection data model
Readonly
Contributing

Resources

Installation and setup

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

$ bower i simpla-collection --save

Setup Simpla on your page, then import simpla-collection into your <head>

<link rel="import" href="/bower_components/simpla-collection/simpla-collection.html">

Use <simpla-collection> wherever you want to create a collection of items. Define the item template in a <template> 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.

<simpla-collection path="/collection">
  <template>
    <img is="simpla-img" path="/collection/[item]">
  </template>
</simpla-collection>

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.

// Enter edit mode
Simpla.editable(true);

<!-- Make only this collection editable -->
<simpla-collection path="/collection" editable>
  <template>...</template>
</simpla-collection>

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.

// 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, which lets you build content paths for Simpla elements declaratively with HTML attributes. This is useful for creating more complex collection items

<simpla-colleciton sid="faqs">
  <template>
    <div sid="[item]">
      <simpla-text sid="question"></simpla-text> 
      <simpla-text sid="answer"></simpla-text> 
    </div>
  </template>
</simpla-colleciton>

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.

<simpla-collection path="/gallery" as="image">
  <template>
    <img is="simpla-img" path="/gallery/[image]">
  </template>
</simpla-collection>

Collection data model

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

[
  { 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:

<simpla-collection path="/gallery">
  <template>
    <img is="simpla-img" path="/gallery/[item]/img">
    <simpla-text path="/gallery/[item]/caption"></simpla-text>
  </template>
</simpla-collection>

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.

<simpla-collection path="/collection" readonly>
  <template>...</template>
</simpla-collection>

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. We also happily accept PRs.

simplajs/simpla-collection