Hercules pxScene / Spark - Initial markdown support

Challenge Objectives

• Target: pxScene / Spark (http://pxscene.org) using Javascript

• Requirements: Implement MIME dispatcher and basic Markdown parsing / rendering

• Note  A custom build of pxScene is used for this challenge that only supports macOS.  You will need macOS to compete in this challenge.

 

Project Background

• “Sparkdown” refers to the processing and rendering of Markdown in Spark.  This will allow the customer to quickly prototype new screens or help files that render on low-powered devices.

• This challenge is the first of at least 2 challenges in this project.  We will add more advanced features and integrate client feedback in a second challenge, and possibly more depending on what the client requires.

Technology Stack

• "Spark" is the new name for the pxScene project we've done work for in the past.  The links below offer a lot more details on these particular technologies. pxCore is a C++ graphics library that is used on a wide variety of embedded devices that the client distributes.  pxScene is a wrapper application around pxCore that exposes the drawing APIs to Javascript through Node and V8.

• This challenge will be in Javascript as much as possible.  We don’t want to change any native code.

• A special build of macOS pxScene / Spark will be provided that handles image processing and drag and drop.

• Quirks:  Note that there are plenty of third party Markdown processors.  For this challenge, we aren’t going to be able to use those directly.  You can use BSD licensed code as reference, but the overall implementation will need to be separate.

 

Code access

Pxscene is a platform independent drawing platform / app that will be used on a wide variety of embedded devices for the Hercules client.  You can find more information here, and you can download the regular app to be used for testing: http://www.pxscene.org/.  Note that you should target the custom build provided in the forum - this information is just provided for reference.

The code for pxCore / pxscene is available in Github here: https://github.com/pxscene/pxCore

Build instructions can be found here:  

https://github.com/pxscene/pxCore/blob/master/examples/pxScene2d/README.md

 

Individual requirements

1. MIME dispatcher (major requirement)

For this challenge, we are going to build a recursive MIME dispatcher that can handle detecting the MIME type of a given file or artifact and then dispatching it to a concrete renderer instance to render the specific MIME type.

In a simple example, if we drag and drop a PNG file onto the pxScene app, the MIME dispatcher will detect an image/png MIME type and will dispatch the rendering to a PNG renderer.

1.1 Recursive:

In a more complex example, we can look to markdown, which can contain images inside the markdown, or even other embedded markdown.  We want the markdown renderer to be able to leverage the MIME rendering of embedded images and files to cut down on redundancy. The individual renderers should be able to recursively call the dispatcher to render sub-items.

It's important that the rendering interface and concrete implementations be well designed, encapsulated, and extensible.  Please make sure to use design patterns, namely the strategy and factory design patterns, in your implementation.

 

1.2 Shell.js vs. browser.js:

Note that currently the URL handling and processing is done in browser.js for the example given in the forum.  The client would prefer this to happen in shell.js instead. You can see this by right clicking on the app and choosing “Show package contents”.

1.3 Unsupported file:

If a user drops on a file of an unsupported file type, we will just render a simple message in the window that says “Unsupported file type: <MIME type>”, like “Unsupported file type: video/mp4”.  The message should be readable and should go away when the user drops on a new file instead.

2. Markdown (major requirement)

Another major requirement for this challenge is the ability to drag and drop and render markdown formatted files.  Markdown can be a complex format, so we are going to focus on a subset that can hopefully cover a good number of use cases.

The requirements list below will refer to specific sections here that we want to cover:  https://guides.github.com/features/mastering-markdown/

If you have questions about specifics on any item, please ask in the forum.

2.1 Required elements

• Emphasis
• Ordered lists
• Unordered lists
• Headers
• Images (using the MIME dispatcher)
• Blockquotes
• Inline code (code coloring not required at this time)

Note that pxScene has some limitations with regards to fonts, specifically bold and italics.  For this challenge, it's acceptable to use a different font or manually adjust to simulate bold and italics, if necessary.  We're open to suggestions on how this might be accomplished.

2.2 Allowed features of pxScene

If you would like to use any of the free Google fonts, that is allowed:  http://fonts.google.com

In addition, SVG is a supported file format that can be used in pxScene.  Just note that embedded JPG and other images inside of SVG will not work.

3. Theming (minor requirement)

We will likely want to adjust how the markdown is rendered and displayed based on client feedback.  Please make sure that you support reasonable configuration values so we can properly adjust things like font, font sizes, and colors of things, including the default background.  By default, the background colour should be white, with black text.

The theme should be a separate file that is easily editable and packaged with the app.  JSON format is fine, but other formats are acceptable as well, if something would work better.  Please just make sure to get approval in the forum if you use something other than JSON.

4. Resizing (minor requirement)

The pxScene window can be resized manually by the user.  We want to support re-rendering markdown and having it fill available space as the window is resized.

As a hint, look at the text box in pxScene - xStartPos, xStopPos.  This will give access to pixel coordinates as start and end of text box.

 

Deployment guide and validation document

You must provide A README.md that covers:

• Deployment:  How do we deploy the custom Javascript you create for both the MIME dispatcher and the Markdown processing?  Ideally, this would just be an edited executable that can be double-clicked to run, with the edited shell.js and other files that support the required features.

• Configuration:  How do we theme the Markdown rendering?

 

You must provide a Validation.md that covers:

• MIME dispatcher validation:  What files can be dragged and dropped that the dispatcher can handle and render?  You should provide reasonable samples here to make review easy.

• Markdown processing:  Provide at least a couple markdown files that show the required features working properly.
   

Validation video / screencast

• Please provide a short video / screencast that shows the drag and drop and markdown processing working.  Make sure to include the resizing functionality..

 

What To Submit

• The updated app with new JS embedded in it

• A README.md

• A Validation.md

• A screencast or a link to the screencast showing the functionality working

Final Submission Guidelines

Please see above