Example from paper-styles

To make everything easy to load and navigate, we will write a custom Gulp task to generate a catalog JSON database starting with the catalog.json in the project root and decorating and adding to it from there. Here's a rough picture of how it should work:

• Read catalog.json
• For each entry in packages, take the name and look for a corresponding entry in the dependencies object in bower.json
• Parse the version number specified from the dependency and store it as the "version" key in the packages list.
• Load and parse the bower.json for the package (e.g. for core-elements look for bower_components/core-elements/bower.json
• Add "description" and "tags" from bower.json to the catalog metadata
• Find any dependencies of the package with the same dash prefix (i.e. core for core-elements).
• For each of these, append it to an "elements" array in the package's catalog metadata
• For each of these, load its bower.json
• Create a key in an elements object in the catalog metadata corresponding to the element name. It should include the name, description, tags, and parent package for the element
• For each of the element's tags, create or append a corresponding key in a tags object on the catalog metadata that is an array of elements that match the tag sorted alphabetically.
• Once you've parsed each package and built the metadata, pipe the output to .tmp/catalog.json and dist/catalog.json
• elements is an array sorted by name

Sample Source

{
  "packages": [
    {"name":"core-elements", "title":"Core Elements"}
  ]
}

Sample Result

{
  "packages": [
    {
      "name":"core-elements",
      "version":"1.0.0",
      "title":"Core Elements",
      "description":"The description from the bower.json for the package.",
      "elements":["core-example"]
    }
  ],
  "elements": {
    "core-example": {
      "name":"core-example",
      "package":"core-elements",
      "description":"The description from bower_elements/core-example/bower.json",
      "tags":["tags","from","bower_elements/core-example/bower.json"]
    }
  },
  "tags": {
    "tags": ["core-example"],
    "from": ["core-example"],
    "bower_elements/core-example/bower.json": ["core-example"]
  }
}

As an alternative to adding to cart and then downloading a bower.json, I'd like to just see the dependency line that I can copy and paste into my existing bower.json. A bower install command line would be nice too.

It would be nice to at a lance (either on the landing page, or inside a collection view) the number of elements in a collection.

Related: https://github.com/PolymerLabs/bowerzipper

@zgibson do you have a hero image for the using elements guide? @arthurevans is Using Elements the only guide that will be landed by I/O?

The toast is good, but it doesn't persist.

Discussion on Thursday led to conclusion that the homepage search should behave like Google Instant Search: you start typing and the search bar jumps to the sidebar and the filter view instantly (instead of displaying tiled elements in the home page view).

This needs to feel completely instantaneous and smooth, interesting UI challenge.

• Basic display of product lines based on catalog.json contents
• Fully styled display
• Animation on page load
• Animation on clicking through a line (maybe have it slide left while rest fade down and away since the details show up in the left sidebar?)

Could we add an (optional) section to the left sidebar for packages & elements showing the related guides. I'd like to have this below the Description but before the Tags.

Related guides

Using iron-icons

For extra credit, pluralize "Related guides" correctly :D

target="_blank"

To reproduce:

1. Select iron-elements
2. Scroll down
3. Select paper-elements

The paper-elements list should open at the top of the page, but it doesn't.

Let's keep it simple. Guides will be stored as .md files in a guides folder in the main project. They will have YAML frontmatter (like Jekyll) that contains metadata, starting with title, summary, tags, updated (date in form YYYY-MM-DD). Let's make a Gulp task that scans the guides directory and builds metadata to insert intocatalog.json`.

Example Markdown File (e.g. bower_components/gold-elements/guides/ecommerce.md)

---
title: How to Build an E-Commerce Site with Gold Elements
summary: "Learn how to add drop-in E-commerce components to quickly build a web presence for your business."
tags: ['ecommerce','beginner']
elements: ['gold-checkout','paper-input']
updated: 2015-04-10

---

Actual article content starts here.

## Example Section

Etc. etc.

Example catalog.json

{
  // guides with associated packages should also be referenced in the package metadata
  "packages": [
    {"name":"gold-elements","guides":["gold-elements/ecommerce"]}
  ],
  "guides": [
    {
      "name":"gold-elements/ecommerce",
      "title":"How to Build an E-Commerce Site with Gold Elements",
      "tags":["ecommerce","beginner"],
      "elements":["gold-checkout","paper-input"],
      "package":"gold-elements"
    }
  ],
  "elements": [
     {"name":"paper-input","guides":["gold-elements/ecommerce"]}
  ]
}

HTML Generation

In addition to parsing the metadata, the Markdown should be rendered into HTML and output into .tmp and dist at guides/<guide-name>.html

Guides in Other Repos

Guides can be added to package or individual element repositories as well. When scanning a package or element, the guides folder in the bower directory should be scanned as well. If there are any Markdown files, they should be parsed and aggregated but have the package or element key set in their metadata (depending on if it's a package or element repo you're exploring).

In addition, guides in other repos should have generated HTML placed in subdirectories named after them to avoid name conflicts. So a guide namedmy-guide.md in iron-elements should have generated HTML in app/iron-elements/my-guide.html.

Todo

• add guides to guide key in catalog.json
• add guides array to package listing in catalog.json
• convert markdown to html in .tmp and dist folders

I'd like to see the version of the component I'm viewing docs for:

This is happening when maximized on my MBP, so it's not an unreasonable screen size:

The mockups were in a bit of a transitional state and the big capsule design was decided against. instead tags should just be normal text-color bits of text that have a hover underline

Let's hook up a Travis CI deploy that runs Gulp and deploys to Divshot. For now let's have master deploy to development and put a password on it.

• travis file
• create app on Divshot
• protect environment

Should be able to easily manage layouts like these:

It's not obvious "google-sheets" is a dropdown that gives me more related elements. I'm worried many people will not ever see the extra elements.

https://github.com/PolymerElements/iron-flex-layout

Many people will deep link to these pages and not know about the list view

This prevents copying the command.

I selected paper-behavior from the list of "other elements" and was surprised to see it removed from the list.

Changing the list makes it hard to navigate by clicking down the list, because sometimes you don't move you cursor to select the next element and sometimes you do.

Are aggressive and make the docs hard to read .

This will be done by "seeding" one-off elements in catalog.json like so:

{
  "packages": [],
  "elements": [{"name":"one-off-element"}]
}

Elements must also be added to bower.json individually (since they aren't picked up by a meta package).

We need analytics on everything. Specifically, tracking page views on doc pages, element guides, and demo views

https://github.com/PolymerElements/iron-doc-viewer

Here we will do our best to approximate all of the same metadata we have about official packages and elements, but arbitrarily based off of a GitHub repository. The URL for these will be /community/:user/:repo/:version (where version is an optional GitHub ref that defaults to master) and there should be no required up-front processing to be able to display: using the GitHub API on the fly should be sufficient.

1. Grab the raw bower.json for the repo using the GitHub API. This tells us the name, description, tags, etc.
2. Use the main declaration to pick up which .html files should be parsed for docs.
3. Pull the raw contents of the indicated HTML files, parse them for docs, and display.

Unanswered Questions

1. How do we get around potential GitHub client-side rate limiting problems?
2. Should we require explicit declarations in bower.json for things that we can otherwise find by directory scanning to cut down on GitHub API requests?
3. Do we cache or otherwise index data that we've collected (maybe in Firebase)?
4. How do we handle demos and dependencies? Simplest possible is <iframe> to URL specified in element docs, but is there a better way?

During the catalog build process, each element should be analyzed with hydrolysis and the result stored in /data/docs/<element-name>.json. Note that you should use the clean option to make sure the output is serializable.

See this source for how to instantiate and run the analyzer.

The reason to do this is that then we have a static version of the docs and the analysis doesn't have to be run client-side each time you load.

Some exploring will need to be done as to best way to do this. Potential lib: https://github.com/GoogleChrome/sw-precache (and hey, Google made it)