Generic Card Schema vs a Seperate Schema for each Card Type

[carlyleec]

I'm wondering if makes more sense to extend the the schema of each card to include a set custom attributes for each card type. So that you have some more like this:

{
"_id": "1234",
"title" : "The Card's Title",
"type": "question-and-answer-card",
"attributes": [
{ "question" : "What's up?"},
{"answers": [
  {"text" : "Not Much", "link" : "http://some-other-card"},
  {"text" : "Nothing", "link" : "http://some-other-card"}
  ]
}
],
"permalink": "link to card",
"meta" : ["content type", "preprocessors", "variables", "custom CSS" ],
"group_tag": "thing to group cards by"
}

or this...

{
"_id": "1234",
"title" : "The Card's Title",
"type": "info-card",
"attributes": [
{ "body" : "<html/>"},
{"links": [
  {"text" : "Next Action", "link" : "http://some-other-card"},
  {"text" : "Another Action", "link" : "http://some-other-card"}
  ]
}
],
"permalink": "link to card",
"meta" : ["content type", "preprocessors", "variables", "custom CSS" ],
"group_tag": "thing to group cards by"
}

Thoughts?

[ejaxon]

I am pretty convinced that this is the right idea, mostly because I think it provides a mechanism for a Flow tool that uses that information to generate UI for linking sequences to card controls (or any external tool that uses cards for that matter, e.g., the CBE).

Here's where I'm struggling a bit ...

A question-and-answer card is pretty straightforward - it obviously involves an array of answers that can be tied to either general links or special links (enabled by the flow system) to cards/flow sequences. The length of the list is variable, but the structure of the attributes is fixed.

However, where things get more complicated is when the content of a card just includes in the HTML links to other sequences. The example we came up with in the brainstorming session is exactly this. We'll have a card which is mid-way through the main sequence with, e.g., a pie chart with areas that link to sequences about particular categories of projects (actually they'll probably initially link just to project listing pages, but as the story-telling content around the categories is developed, we can replace with links to the corresponding sequences).

We also have the issue of output controls, which tie into variables that are stored in the Flow structure state.

There are a couple different approaches to dealing with all this.

1. Let the flow tool read information from the controls themselves. In this case, we don't need the attributes at all - everything is included in the controls themselves. The disadvantage is that the Flow tool needs to parse and interpret the content of a card. Not a good idea, I think.
2. Have the card "publish" all relevant information to its attributes. This is a bit messier than encoding it strictly through card "type". For example, you could have a question-and-answer-card with the answers array in attributes, but with HTML text that also includes a couple of embedded links to other parts of the flow. In this case the links in the body should be actual controls that refer to information in the attributes.

To implement the second approach we either need a card editor that knows to create, say, a general links attribute with as many entries as there are instances of controls that use them, or we have a postprocessor on the editor output that generates the appropriate attributes when the card is saved. The latter is simpler and, even though we still have to write something that interprets the content, it's associated with the cards system, not the flow system.

Reactions?

[carlyleec]

Could you explain what output controls are in a little more detail? I just want to make sure that we are speaking the same language.

Are they just links within a block of html? If so, we could just do what WordPress does. When some clicks on the "Add Link" button in TinyMCE, they get a modal window with a list valid locations to link to. Like this:

This would require the card editor WYSIWYG component to be aware of the Flow Sequence and potentially/probably aware of all other sequences accessible by that user.

Alternatively, we could do some sort of Short Code thing.

As far as the Pie Chart example you mentioned above, I think that this could a "pie-chart" or "data-viz" card type where links are attached to data being visualized.

[ejaxon]

Re: output controls, the simplest example would be a prompt in a sequence asking the user for their name (input control) and then inserting it into various places in the text in later cards (output control). The example in the case of the CIP project is asking them for the value of their property or amount of taxes (input control) and then using it later to present information in terms of their contribution (i.e., rather than outputting the number itself, we'd provide it to some visualization or other output control).

Basically, then, output controls generically refer to anything that pulls a value from the Flow application state and uses it in the content.

Re: the Wordpress example, I think that's right, but the way I see it happening is that we have the base card editor, which works completely independently of the Flow application, but then have plugins to the editor that are associated with the Flow piece (I'm assuming that we'll use TinyMCE since it's open source and free, but the research I've done indicates that any of the candidate editors have the capability of adding plugins).

[carlyleec]

awww...I get it now.. input controls input values into the flow state, and output controls output values from the flow state into the content of the card... very cool!

And I get the idea of plugins for the card editor now too...Thanks!

[ejaxon]

Ok, I'll make a stab at revising the documentation to reflect all this, if you and I are more or less aligned on all the issues so far.

[ejaxon]

I've updated the Cards page to reflect this discussion. I went a bit further, moving several fields (title, image, link and group) into attributes. These are common attributes, but the more I thought about it the less they seemed to belong as first-class fields of a card.

I've made you a collaborator on the project - feel free to close issues that you think are now fully addressed.

Feel free to write the code too, while you're at it :).