Proposal: Support Content Collection API

[mantaroh]

What is this feature?

This PR make spear to support content API feature:

• Support this API that how spear collect the content.
  • API can allow to specify how tool collect the content from CMS. (e.g., Contentful / microCMS / etc....)
  • API can allow to specify how collect the content from local files. (e.g., markdown, yaml)
• User can specify this plugin which contain these API via spear.config.js
  • contentCollectionPlugin key
  • Value is objects:

{
  "contentCollectionPlugin": {
    "getCollection": function() {
       return [{
        ....<Abstracted Content Object>...
       }];
    },
    "getContent": function(contentName) {
        return {
          ....<Abstracted Content Object>...
        };
    },
  }
}

Note that:

• We SHOULD DEFINE Abstracted Content Object

Why do we need this feature?

At the moment, spear is specialized Spearly CMS. So we might need to support other CMS or local files.
Especially, If we provide spear docs, contributor CAN NOT have the way to contribute for documentation.

[mantaroh]

We SHOULD DEFINE Abstracted Content Object

our Spearly CMS Response data is depend on each content type, however this response includes the basic information of content. So we specify the following abstract structure of content:

// Spear support the following fields.
export type FieldInputType = 'text' | 'number' | 'rich_text' | 'image' | 'calendar' | 'map' | 'content_type' | 'tags'

export type FieldType<T> = {
  id: string
  type: 'field'
  attributes: {
    identifier: string
    inputType: FieldInputType
    value: T
  }
}

export type MapValue = {
  preferredFormat: string
  address: string
  latitude: number
  longitude: number
}

export type FieldTypeText = FieldType<string>
export type FieldTypeNumber = FieldType<number>
export type FieldTypeRichText = FieldType<string>
export type FieldTypeImage = FieldType<string>
export type FieldTypeCalendar = FieldType<Date>
export type FieldTypeMap = FieldType<MapValue>
export type FieldTypeTags = FieldType<string[]>
export type FieldTypeContentType = FieldType<
  (
    | FieldTypeText
    | FieldTypeNumber
    | FieldTypeRichText
    | FieldTypeImage
    | FieldTypeCalendar
    | FieldTypeMap
    | FieldTypeTags
  )[]
>

export type FieldTypeAll =
  | FieldTypeText
  | FieldTypeNumber
  | FieldTypeRichText
  | FieldTypeImage
  | FieldTypeCalendar
  | FieldTypeMap
  | FieldTypeTags
  | FieldTypeContentType

export type ServerFieldTypeCalendar = FieldType<string>

export type ServerFieldTypeAll =
  | FieldTypeText
  | FieldTypeNumber
  | FieldTypeRichText
  | FieldTypeImage
  | ServerFieldTypeCalendar
  | FieldTypeMap
  | FieldTypeTags
  | FieldTypeContentType

// Spear's Content has the following attributes
export type Content = {
    attributes: {
      contentAlias: string  // 
      createdAt: Date
      fields: {
        data: FieldTypeAll[]
      }
      nextContent: Content | null
      previousContent: Content | null
      publicUid: string
      publishedAt: Date
      updatedAt: Date
    }
    id: string
    type: 'content'
    values: {
      [key: string]: unknown
    }
  }
  
  export type ServerContent = {
    attributes: {
      createdAt: string
      publishedAt: string
      updatedAt: string
    } & Omit<Content['attributes'], 'createdAt' | 'publishedAt' | 'updatedAt'>
  } & Omit<Content, 'attributes'>
  

[mantaroh]

I implementing the prototype of this content collection. Then we might need to the following case:

cms-optionn-

If the source embed syntax use the cms-option- attribute, this option effect to content collection since we switch return value in this attribute value.

cms-loop and cms-item

There are two pattern which getting the content:

1. Fetch the single content.
2. Fetch all of contents.

An above pattern, we need to switch the return value.

[mantaroh]

At the moment spear use the spearly-cms-js-core library internally:

sequenceDiagram
    Spear->>Spear: Initialize
    Spear->>+cms-core: instanize
    Spear->> Spear : parseElements
    Spear->>+cms-core: generateList(w/ DOM and content-type)
    cms-core->>+SpearlyCMS: get content list
    SpearlyCMS-->cms-core : response
    cms-core->>cms-core: generate list html
    cms-core-->Spear: Response(Embed HTML)

Loading

So I guess cms-core should have the feature generating content with a passed API response mode.

[mantaroh]

So I guess cms-core should have the feature generating content with a passed API response mode.

Ah, we can inject alternative sdk-js which getting data from markdown.