Branch issues/868-Spike_Investigate_editor_API_links_for_block-to-text created!

Spike: Investigate editor API links for block-to-text

Background

We have two ways of loading code into the editor, via a code prop or by passing in a project identifier identifier.

Our use case is we want the assets from one project, but with custom code, or code from another project.

Q. Can we obtain assets from the editor API using a project identifier?

• Yes, /api/projects/top-5-emoji-list-step-5 will return, amongst other things, the property image_list which will contain any assets.
• It's trivial to add a new route that just provides assets
  • e.g. /api/projects/top-5-emoji-list-step-5/images.
  • This has been done in about 10 minutes
  • Dev note: Just add show function to images_controller.rb

Q. Can we use the web components code attribute to run custom code against those assets? Or do we pull template code from the API too?

Template code can be stored in the API or through the code prop - this depends on the templating approaches spike outcome but both options can work.

If we store the template code in projects-admin, we may wish to optionally update the code styles so that any block sections are clear to the admins.

Separately, we will need to include options, e.g. if the code is There are {{}} apples on the {{}} we can use pipe separated blocks, which have comma separated options e.g. 1,2,3|left,right

Solutions

Pending on how we choose to template code, we may decide to allow simple string interpolation e.g. {{}} to signify a block in the code. This makes it possible to use the existing projects admin to define code.

1. Quick and dirty: Overwriting with the code prop

The quickest option if there's both an identifier and a code prop is to overwrite the loaded code with what's provided in the code prop.

Pros

• Less work - overwrite any code with whatever is in the code prop. Will need a prop with array of options.

Cons

• Overwriting the code can mean some projects appear different to how they are defined in projects-admin - as the overwriting code will be defined elsewhere.
• Where the code has selectable options, these will need overwriting with the new code. If forgotten, the wrong options could show and may not match with the overwriting code.

2. Split identifiers into asset and code identifiers

Assets are loaded by:

• asset identifier

Code is loaded by:

• code identifier, OR
• code prop, ELSE
• blank

This has been done by:

1. Update editor-ui to allow two identifiers: asset-identifier and code-identifier
2. Update editor-api to add endpoint for assets only (easy, as above)
3. Update editor-api to add endpoint for code only (easy)

Draft spike

This has been drafted out in the associated branch which splits out the asset loading from the project loading.

Using Redux devtools we can see the assets from the specified project are available to the user.

For HTML projects, as we can't provide the project type via props, this can be achieved loading a blank HTML project which will in turn set the project type.

You can preview this using these project identifiers:

  <editor-wc
    code_identifier="top-5-emoji-list-step-5" 
    class="c-editor__wc" 
    asset_identifier="anime-expressions"
    output_only
    data-editor-target="editor"
  >

Pros

• A comprehensive, robust, reliable option as it allows specific loading of different assets and code, without having to overwrite code. This should prevent mistakes or unstable situations.
• API work required is simple, just splitting the response into two endpoints, one for the assets and the other for the code
• Backwards compatible, the new assets and code props will supplement the existing identifier prop

Considerations

• There will be an increase in API calls, as a project with separate identifiers will now be making two calls.
• This is mitigated by preserving existing identifier prop and routes which will load both assets and code when they're the same, with the new props only being used when the code and assets are different.

3. Single identifier but have loading flags

Make no changes to the API and load everything with one API call, but instead specify in editor-ui which of assets or code it should load from the response: load-code and load-assets

We would forbid the use of the load-code and code - it makes it explicit that you can't overwrite code.

Examples would be:

• Load both from API
  • <editor-wc identifier="hello-world-example" load-code load-assets />
• Load assets with custom code
  • <editor-wc identifier="hello-world-example" load-assets code="..." />
• Just custom code
  • <editor-wc code="..." />

Pros

• A more explicit version of overwriting the provided code prop - instead of implicitly overwriting code when code prop is provided, we now explicitly require flags
• Very clear in the code what elements of a project get loaded in
• No API work needed.

Considerations

• Possibly breaking change - without the flags nothing loads, so where we currently load both assets and code (the default behaviour) we need to specify both flags.
• Could lead to confusion if developers don't know they need to specify a flag.

Q. Is there an alternative if images and other assets are used in the block-to-text project?

We could pass required assets into the web component as an assets prop, but these will need to be specified in such a specific manner as each asset requires a filename and url, e.g.

<editor-wc assets={[{filename: '', url: ''},{filename: '', url: ''}]} />

make a ticket for option 2

ticket generated from option 2 so marking this spike closed