in with the new

src/plugins/add-plugin.md

@@ -0,0 +1,127 @@
+# Add a plugin
+
+### Swagger-UX relies on plugins for all the good stuff.
+
+Plugins allow you to add
+- `statePlugins`
+  - `selectors` - query the state
+  - `reducers` - modify the state
+  - `actions` - fire and forget, that will eventually be handled by a reducer. You *can* rely on the result of async actions. But in general its not reccomended
+  - `wrapActions` - replace an action with a wrapped action (useful for hooking into existing `actions`)
+- `components` - React components
+- `fn` - commons functions
+
+To add a plugin we include it in the configs...
+
+```js
+SwaggerUI({
+  url: 'some url',
+  plugins: [ ... ]
+})
+```
+
+Or if you're updating the core plugins.. you'll add it to [src/js/bootstrap-plugin](https://github.com/SmartBear/swagger-ux/blob/master/src/js/bootstrap-plugin.js)
+
+Each Plugin is a function that returns an object. That object will get merged with the `system` and later bound to the state.
+Here is an example of each `type`
+
+```js
+// A contrived, but quite full example....
+
+export function SomePlugin( toolbox ) {
+
+  const UPDATE_SOMETHING = "some_namespace_update_something" // strings just need to be uniuqe... see below
+
+  // Tools
+  const fromJS = toolbox.Im.fromJS // needed below
+  const createSelector = toolbox.createSelector // same, needed below
+
+  return {
+    statePlugins: {
+
+      someNamespace: {
+        actions: {
+          actionName: (args)=> ({type: UPDATE_SOMETHING, payload: args}), // Synchronous action must return an object for the reducer to handle
+          anotherAction: (a,b,c) => (system) => system.someNamespaceActions.actionName(a || b) // Asynchronous actions must return a function. The function gets the whole system, and can call other actions (based on state if needed)
+        },
+        wrapActions: {
+          anotherAction: (oriAction, system) => (...args) => {
+            oriAction(...args) // Usually we at least call the original action
+            system.someNamespace.actionName(...args) // why not call this?
+            console.log("args", args) // Log the args
+            // anotherAction in the someNamespace has now been replaced with the this function
+          }
+        },
+        reducers: {
+          [UPDATE_SOMETHING]: (state, action) => { // Take a state (which is immutable) and an action (see synchronous actions) and return a new state
+            return state.set("something", fromJS(action.payload)) // we're updating the Immutable state object... we need to convert vanilla objects into an immutable type (fromJS)
+            // See immutable about how to modify the state
+            // PS: you're only working with the state under the namespace, in this case "someNamespace". So you can do what you want, without worrying about /other/ namespaces
+          }
+        },
+        selectors: {
+          // creatSelector takes a list of fn's and passes all the results to the last fn.
+          // eg: createSelector(a => a, a => a+1, (a,a2) => a + a2)(1) // = 3
+          something: createSelector( // see [reselect#createSelector](https://github.com/reactjs/reselect#createselectorinputselectors--inputselectors-resultfunc)
+            getState => getState(), // This is a requirement... because we `bind` selectors, we don't want to bind to any particular state (which is an immutable value) so we bind to a function, which returns the current state
+            state => state.get("something") // return the whatever "something" points to
+          ),
+          foo: getState => "bar" // In the end selectors are just fuctions that we pass getState to
+        }
+      }
+
+      ... // you can include as many namespaces as you want. They just get merged into the 'system'
+
+    },
+
+    components: {
+      foo: ()=> <h1> Hello </h1> // just a map of names to react components, naturally you'd want to import a fuller react component
+    },
+
+    fn: {
+      addOne: (a) => a + 1 // just any extra functions you want to include
+    }
+  }
+}
+```
+
+>The plugin factory gets one argument, which I like to call `toolbox`.
+This argument is the entire plugin system (at the point the plugin factory is called). It also includes a reference to the `Immutable` lib, so that plugin authors don't need to include it.
+
+
+### The Plugin system
+
+Each plugin you include will end up getting merged into the `system`, which is just an object.
+
+Then we bind the `system` to our state. And flatten it, so that we don't need to reach into deep objects
+
+> ie: spec.actions becomes specActions, spec.selectors becomes specSelectors
+
+You can reach this bound system by calling `getSystem` on the store.
+
+`getSystem` is the heart of this whole project. Each container component will receive a spread of props from `getSystem`
+
+here is an example....
+```js
+class Bobby extends React.Component {
+
+  handleClick(e) {
+    this.props.someNamespaceActions.actionName() // fires an action... which the reducer will *eventually* see
+  }
+
+  render() {
+
+    let { someNamespaceSelectors, someNamespaceActions } = this.props // this.props has the whole state spread
+    let something = someNamespaceSelectors.something() // calls our selector, which returns some state (either an immutable object or value)
+
+    return (
+      <h1 onClick={this.handleClick.bind(this)}> Hello {something} </h1> // render the contents
+    )
+
+  }
+
+}
+```
+
+TODO: a lot more elaboration
+`

src/plugins/configs/index.js

@@ -0,0 +1,88 @@
+import YAML from "js-yaml"
+import yamlConfig from "../../../swagger-config.yaml"
+
+const CONFIGS = [ "url", "spec", "validatorUrl", "onComplete", "onFailure", "authorizations", "docExpansion",
+    "apisSorter", "operationsSorter", "supportedSubmitMethods", "highlightSizeThreshold", "dom_id",
+    "defaultModelRendering", "oauth2RedirectUrl", "showRequestHeaders" ]
+
+const parseYamlConfig = (yaml, system) => {
+    try {
+        return YAML.safeLoad(yaml)
+    } catch(e) {
+        if (system) {
+            system.errActions.newThrownErr( new Error(e) )
+        }
+        return {}
+    }
+}
+
+const parseSeach = () => {
+    let map = {}
+    let search = window.location.search
+
+    if ( search != "" ) {
+        let params = search.substr(1).split("&");
+
+        for (let i in params) {
+            i = params[i].split("=");
+            map[decodeURIComponent(i[0])] = decodeURIComponent(i[1]);
+        }
+    }
+
+    return map;
+}
+
+
+export default function configPlugin (toolbox) {
+    let { fn } = toolbox
+
+    const actions = {
+        downloadConfig: (url) => () => {
+            let {fetch} = fn
+            return fetch(url)
+        },
+
+        getConfigByUrl: (callback)=> ({ specActions }) => {
+            let config = parseSeach()
+            let configUrl = config.config
+            if (configUrl) {
+                return specActions.downloadConfig(configUrl).then(next, next)
+            }
+
+            function next(res) {
+                if (res instanceof Error || res.status >= 400) {
+                    specActions.updateLoadingStatus("failedConfig")
+                    console.log(res.statusText + " " + configUrl)
+                } else {
+                    callback(parseYamlConfig(res.text))
+                }
+            }
+        }
+
+    }
+
+    const selectors = {
+        getLocalConfig: () => {
+            return parseYamlConfig(yamlConfig)
+        }
+    }
+
+    return {
+        statePlugins: {
+            spec: { actions, selectors }
+        }
+    }
+}
+
+
+export function filterConfigs (configs) {
+    let i, filteredConfigs = {}
+
+    for (i in configs) {
+        if (CONFIGS.indexOf(i) !== -1) {
+            filteredConfigs[i] = configs[i]
+        }
+    }
+
+    return filteredConfigs
+}

src/plugins/index.js

@@ -0,0 +1,17 @@
+import { pascalCaseFilename } from "js/utils"
+
+const request = require.context(".", true, /\.jsx?$/)
+
+request.keys().forEach( function( key ){
+  if( key === "./index.js" ) {
+    return
+  }
+
+  // if( key.slice(2).indexOf("/") > -1) {
+  //   // skip files in subdirs
+  //   return
+  // }
+
+  let mod = request(key)
+  module.exports[pascalCaseFilename(key)] = mod.default ? mod.default : mod
+})

src/plugins/topbar/index.js

@@ -0,0 +1,9 @@
+import Topbar from './topbar.jsx'
+
+export default function () {
+  return {
+    components: {
+      Topbar
+    }
+  }
+}

src/plugins/topbar/topbar.jsx

@@ -0,0 +1,62 @@
+import React, { PropTypes } from "react"
+
+//import "./topbar.less"
+import Logo from "./logo_small.png"
+
+export default class Topbar extends React.Component {
+
+  constructor(props, context) {
+    super(props, context)
+    this.state = { url: props.specSelectors.url() }
+  }
+
+  componentWillReceiveProps(nextProps) {
+    this.setState({ url: nextProps.specSelectors.url() })
+  }
+
+  onUrlChange =(e)=> {
+    let {target: {value}} = e
+    this.setState({url: value})
+  }
+
+  downloadUrl = () => {
+    this.props.specActions.updateUrl(this.state.url)
+    this.props.specActions.download(this.state.url)
+  }
+
+  render() {
+    let { getComponent, specSelectors } = this.props
+    const Button = getComponent("Button")
+    const Link = getComponent("Link")
+
+    let isLoading = specSelectors.loadingStatus() === "loading"
+    let isFailed = specSelectors.loadingStatus() === "failed"
+
+    let inputStyle = {}
+    if(isFailed) inputStyle.color = "red"
+    if(isLoading) inputStyle.color = "#aaa"
+    return (
+        <div className="topbar">
+          <div className="wrapper">
+            <div className="topbar-wrapper">
+              <Link href="#" title="Swagger UX">
+                <img height="30" width="30" src={ Logo } alt="Swagger UX"/>
+                <span>swagger</span>
+              </Link>
+              <div className="download-url-wrapper">
+                <input className="download-url-input" type="text" onChange={ this.onUrlChange } value={this.state.url} disabled={isLoading} style={inputStyle} />
+                <Button className="download-url-button" onClick={ this.downloadUrl }>Explore</Button>
+              </div>
+            </div>
+          </div>
+        </div>
+
+    )
+  }
+}
+
+Topbar.propTypes = {
+  specSelectors: PropTypes.object.isRequired,
+  specActions: PropTypes.object.isRequired,
+  getComponent: PropTypes.func.isRequired
+}

src/plugins/topbar/topbar.less

@@ -0,0 +1,53 @@
+.swagger-ui {
+
+  .topbar {
+    background-color: #89bf04;
+  }
+
+  .topbar-wrapper {
+    padding: 0.7em
+  }
+
+  .topbar-logo__img {
+    float: left;
+  }
+
+  .topbar-logo__title {
+    display: inline-block;
+    color: #fff;
+    font-size: 1.5em;
+    font-weight: bold;
+    margin: 0.15em 0 0 0.5em;
+  }
+
+  .download-url-wrapper {
+    text-align: right;
+    float: right;
+  }
+
+  .topbar .download-url__text {
+    width: 28em;
+    height: 2em;
+    margin-right: 0.5em;
+  }
+
+  .download-url__btn {
+    background-color: #547f00;
+    border-color: #547f00;
+    text-decoration: none;
+    font-weight: bold;
+    padding: 0.2em 0.3em;
+    color: white;
+    border-radius: 0.1em;
+
+    &:hover {
+      &:extend(.download-url__btn);
+    }
+  }
+
+  .center-700 {
+    display: block;
+    margin: 0 auto;
+    width: 45em;
+  }
+}