Custom-Header-Plan.md

Overview

Using the existing curation endpoint, we can save/load a CustomHeader item that will be used to store the attributes that can be consumed at page render to create the desired customized header look.

The CustomHeader item could look something like this:

{
    "itemType": "CustomHeader",
    "itemData": {
        "backgroud": {
            "type": "color",
            "value": "#509b22"
        },
        "primary": {
            "type": "text",
            "value": "This is a text headline"
            // possibly color? 
        },
        "secondary": {
            "type": "text",
            "value": "this is some paragraph text I suppose"
        },
        "tertiary": {
            "type": "links",
            "value": [
                {
                    "text": "Season 1",
                    "url": "/c/tv-shows/season-1"
                },
                {
                    "text": "Season 2",
                    "url": "/c/tv-shows/season-2"
                }
            ]
        }
    }
}

/*  potentially in the future we add additional content "types" and the types in each slot would be interchangeble.  
(ie:  "primary": {"type": "links", "value"...)
*/            

Time-frame

I feel like a basic MVP is achievable by 9/30. That basic MVP would allow for:

• Custom background color
• Non-formated text in both the primary (heading) & secondary (text) slots
• Image in the primary (heading) slot
• Ability to set the background to an image
• Up to 4 links in the tertiary slot
• overhang the curation module (see second image)
• look like:

Once this is released, we can look to expand the functionality by order of importance and add things like:

• Addition of a "Sponsor Badge" slot
• Formatted and/or colored text in both the primary (heading) & secondary (text) slots

Ultimately arriving at something like this:

Pros/Cons

Pros

• Custom header functionality can be added to any place a curation module currently lives.
• Using the existing curation module endpoints means that new api/backend work should be required and also means that...
• only a single call needs to be made to retrieve the data for both the curation module and the custom header, rather than 2 separate calls.
• Potentially makes doing curation/header integrations easier in the future.

Cons

• Every place the curation module possibly could live needs to be touched to ensure that it can properly handle the possibly of the new CustomHeader item type.
• Making updates to either a custom header or a curation module on a page means that both parts need to be "Saved"
• Custom header functionality can't easily live on pages were curation module can't/doesn't exist
  (ie: "Uncategorized" category/subcategory pages & permalink pages)
• Potentially adds confusion/complexity around using the "Delete" endpoints as they would now remove both the data responsible for rendering the curation module and the custom header. Currently no client functionality exists utilizing this endpoint.

To Do

Rendering

Allow for a CustomHeader item

Make sure the page render and the curation module component can handle the new CustomHeader item. Update:
kinja-magma/client/controllers/categorization/category-page.js and/or
kinja-magma/utils/prepareCurationProps.js

Create CustomHeader Component

Build a custom component that consumes a CustomHeader item and renders it correctly on the page.

Editor

Update curation module with an "Empty" layout

To allow for instances were someone wants a custom header but no curation module.

This is option can be utilized via the "Remove curation module" button shown in this mock

in kinja-components/components/curation-layout/default-layouts-stub.js add to getDefaultLayouts

{
    group: 'None',
    cardinality: 1,
    zones: [
        {
            dimension: '1fr',
            numberOfItems: 0
        }
    ]
}

Add editor functionality

When the curation module edit "Pin" is clicked, the custom header component becomes editable.
On pages that don't currently have any custom header content, an empty editable header is displayed.

Update the curation module "Save" functionality so that it takes the values set in that editable header and bundles them into a CustomHeader item that is included in the existing curation save flow prior to POST.

"Background Color" would be set using a system color picker similar to special sections.

"Background Image" would be set via the same sort of functionality that is used on special sections.

"Links" would open a simple modal similar to what currently exists when adding a link on a special sections.

Fully completed editor mock

Notes/Links

In-vision Designs

schema.json

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title" : "Custom Header",
    "description" : "Defines the structure of the data used to customizable the header of story type and category pages",

    "type": "object",

    "properties": {
        "background": {
            "type": "object",
            "properties": {
                "type":  { "type": "string", "enum": ["color", "image"]  }
            },
            "allOf":[
                {
                    "if": { "properties": {"type": {"const":"color"}} },
                    "then": {"properties": {"value": {"$ref": "#color"}} }
                },
                {
                    "if": {"properties": {"type": {"const": "image"}} },
                    "then": {"properties": {"value": {"$ref": "#image"}} }
                }
            ]

        },
        "primary": {
            "type": "object",
            "properties": {
                "type":  { "type": "string", "enum": ["plainText", "image"]  }
            },
            "allOf":[
                {
                    "if": { "properties": {"type": {"const":"plainText"}} },
                    "then": {"properties": {"value": {"type": "string"}} }
                },
                {
                    "if": {"properties": {"type": {"const": "image"}} },
                    "then": {"properties": {"value": {"$ref": "#image"}} }
                }
            ]
        },
        "secondary": {
            "type": "object",
            "properties": {
                "type":  { "type": "string", "enum": ["plainText"]  }
            },
            "allOf":[
                {
                    "if": { "properties": {"type": {"const":"plainText"}} },
                    "then": {"properties": {"value": {"type": "string"}} }
                }
            ]
        },
        "tertiary": {
            "type": "object",
            "properties": {
                "type":  { "type": "string", "enum": ["links"]  },
                "items": {
                    "type": "array",
                    "items": { "$ref": "#link" }
                }
            }
        }
    },

    "typeDefinitions": {
        "color": {
            "$id": "#color",
            "type": "string",
            "pattern": "^#([a-f]|[A-F]|[0-9]){3}(([a-f]|[A-F]|[0-9]){3})?$"
        },
        "image": {
            "$id": "#image",
            "properties":{
                "format" : {
                    "type":"string",
                    "enum": ["jpg" , "png" , "gif" , "bmp" , "svg"]
                },
                "id": { "type": "string" },
                "altText": {"type": "string"}
            },
            "required":["format","id"]
        },
        "link": {
            "$id": "#link",
            "type": "object",
            "properties": {
                "text": { "type": "string"},
                "url": { "type": "string", "pattern": "https?:\\\/\\\/[\\w\\-_]+(\\.[\\w\\-_]+)+([\\w\\-\\.,@?^=%&:\/~\\+#]*[\\w\\-\\@?^=%&\/~\\+#])?"}
            },
            "required":["text","url"]
        }
    }
}

@BriceShatzer

• Yes, I meant an image in every position would have the type on the same level as its other fields. That's similar to how block nodes work for example. I don't think it's a big issue if it's ugly in this particular schema description format, if it's easily typeable both in Flow and Scala we should be fine.
• Yeah I agree with tertiary being a container just like the others. Tbh I wasn't planning to restrict primary/secondary/tertiary/background to their specific content types on the backend, instead letting each be a color | image | plaintext | links, at least in the first iteration.
• Yeah, the ids should be a part of this. I propose to have those in an outer layer though, that way I could store the content part in one field in the database and later changes (e.g. we want to drop tertiary or add a new one) are just a code change, not a database change.

So I'm thinking about a model like this in flow syntax, let me know what you think:

// This is what the API takes/returns:
type CustomHeaderJSON = {
  storyTypeId?: StoryTypeId,
  categoryId?: CategoryId, // Either storyTypeId or categoryId must be defined
  content: CustomHeaderContent
  // The backend also stores the last update time and the user who did it on this level, but probably the frontend won't need that.
};

type CustomHeaderContent = {
  background?: CustomHeaderColor | CustomHeaderImage,
  primary?: CustomHeaderPlainText | CustomHeaderImage,
  secondary?: CustomHeaderPlainText,
  tertiary?: CustomHeaderLinks
};

type CustomHeaderColor = {
  type: 'color',
  value: string
};

type CustomHeaderImage = {
  type: 'image',
  id: string,
  format: ImageFormat,
  altText?: string
};

type CustomHeaderPlainText = {
  type: 'plainText',
  value: string
};

type CustomHeaderLinks = {
  type: 'links',
  value: [{ text: string, url: string }]
};

Yep that all looks good.
And yeah, I think having multiple different content types that can be interchangeable into any of the different "containers" is where I figured we would eventually end up.