search

OpenWaterFoundation / owf-app-viz-demo-ng

Open Water Foundation application to test different visualizations in Angular
0 stars 0 forks source link

Add Showdown menu and examples #12

Open smalers opened 3 years ago

smalers commented 3 years ago

The InfoMapper is using Showdown integration to implement content. However, there are some issues that need to be resolved, such as verifying that advanced Markdown is working. Figuring out how to open links in Markdown in a tab (so that using "back" does not reload the Angular application, etc. I recommend the following:

  1. Add a Showdown menu with demonstrations relevant to Angular application integration.
  2. The Resources menu can have a link to Showdown and the OWF repo focusing on that.
  3. If the HashLocationStrategy is implemented, the markdown pages as URLs can be standardized in the routing.
  4. Any application content that is currently hard-coded as HTML can be moved to Markdown.
smalers commented 3 years ago

The ShowndownJS menu needs to be updated as per the hash approach and move the instructions to a README file. The information for developers is good but the demo should behave as it would for users. The ShowdownJS menu should have sub-menus with demonstration of the following. Each demonstration should have README content somewhere. It may be necessary to go back to the owf-lib-showdown-js repository to test these examples external to Angular, and then implement similarly in Angular.

Menu Description
Standard Markdown Typical Markdown that demonstrates all Markdown elements. Questions: How are internal and external links handled in the page? Does the page behave like a normal web page?
Custom CSS Need an example that shows how to implement custom CSS for style. We will need to use this to extend Markdown, such as coloring text.
Popup Instead of showing the HTML in a page that takes over the application, show in a popup. All the normal questions apply as to whether the HTML is fully-navigable. See also the next item.
Open Links in Tab In the InfoMapper we have information icons that need to display text content. In many cases we don't want the content to take over the application but instead want to show Markdown in a popup, or open a new browser tab. It may be that we want to default to a popup but if user does CTRL-click on an icon or link, it will show in a tab. This example will show a page with links that are formatted to open a tab.

For the above, need to consider the following:

  1. How is a markdown page uniquely identified so that it uniquely matches a hash URL? Applications that implement showdown need a way to read the markdown from a path, convert to HTML, and display with an appropriate URL.
  2. How robust is the HTML viewer once displayed? Can ANY valid HTML be used? This is a question of how robust is the Angular HTML component. Does the Angular HTML viewer behave differently if an Angular page or popup?
  3. How are links handled, both for internal page navigation links (# links), links to other pages in the application, and external links. Need examples of these working.
  4. CSS file needs to be configurable. For example, for InfoMapper a general design is to allow configuration to specify a path, and then the application finds that in assets/app. Therefore, could have an assets/app/css folder where CSS is found. The page should allow indicating which CSS file (files?0 to use. The documented examples for this need to be clear.
  5. In general, how are links handled when viewed in application page and popup and when links refer to application and external page URLs, and # links in a page?
gsofia23 commented 3 years ago

Demo shows a file with various examples. Demonstrating how the raw Markdown appears in the input box, as well as how it is configured to HTML using showdown below it. Provide feedback on whether this is an acceptable demo approach or if separate menu's are still preferred for demo application.

gsofia23 commented 3 years ago

Custom CSS examples still needed for showdown

smalers commented 3 years ago

The point of the demonstrations is to show how to integrate Showdown in an application, not to demonstrate Showdown's basic features. I would like to see the Markdown example used in each of the examples. Showing the original markdown source in the first menu item would be helpful.

We generally try to avoid a linked page taking over the Angular application window because then "back" is needed and reloads the entire application. Josh and I will discuss what we are doing.