Adding Create From URL documentation

[rhamilto]

• Adding "Configuring the Create From URL Namespace Whitelist" to web_console_customization and fixing heading semantics on that page (several headings were improperly declared
  as h3s or h4s when they should have been h2s or h3s).
• Adding "Create from URL" page to the developer guide describing the "API" for create from URL.

[jwforres]

@sspeiche @luciddreamz any thoughts on where in the docs we should put the information for the API for "Run on OpenShift" it doesn't really go in the console customization docs because that is for cluster administrators.

[luciddreamz]

Put it in the developers section as it's own page.

[rhamilto]

ALL: Thoughts on this [initial draft of the new Create from URL page]

[rhamilto]

@sspeiche, @luciddreamz: what do we want to call this feature? The card describes it as "Run on OpenShift", but I've been referring to it as "Create from URL" as that arguably better describes the functionality. I completely defer to y'all.

[luciddreamz]

Create from URL sounds like a better description - that or Deploy on OpenShift Button.

[sspeiche]

I like what you have, I'd suggest a few updates:

• not sure users would know what you mean by a preordained namespace
• do we need to talk about parameter encoding?
• an example or two would be helpful, using something like the ever helpful numbered items pointing to it which each part does
• any value in showing screenshot or two?

[rhamilto]

not sure users would know what you mean by a preordained namespace

good point. i've eliminated "from a preordained namespace" since the next paragraph explains about namespace whitelisting.

do we need to talk about parameter encoding?

i don't think so. @jwforres or @spadgett?

an example or two would be helpful, using something like the ever helpful numbered items pointing to it which each part does

i'm guessing you didn't notice the examples since they weren't in the original screenshot? i've corrected that by adding a second screenshot with the rest of the page.

any value in showing screenshot or two?

it might be confusing since the page displays the title and description of the image stream or template being used?

[rhamilto]

^ bump @jwforres, @spadgett

[jwforres]

this description is really confusing, particularly 'value key value'. Also an example is probably helpful here.

[jwforres]

nevermind on the example part, i see it below. This description could still be improved though

[rhamilto]

I struggled with this description and agree it's confusing. Ideas on how to more clearly state?

[spadgett]

@rhamilto I would mention that the parameter values need to be correctly encoded. If you're passing things like URLs, it's likely they'll have special characters (like their own query parameters) that need to be URL escaped.

[jwforres]

seems redundant to say that it defaults to openshift when you have a whole column dedicated to the Default values

[rhamilto]

Fair point. Will remove the two instances.

[rhamilto]

@rhamilto I would mention that the parameter values need to be correctly encoded. If you're passing things like URLs, it's likely they'll have special characters (like their own query parameters) that need to be URL escaped.

Based on my own testing and this comment, I don't think we need to do any encoding given these URLs will be included in HTML.

[spadgett]

@rhamilto I'm not sure I follow what the comment is saying, but for some values, it's not possible for the browser to automatically encode them for you. For instance, a source URL that contains query parameters like

http://example.com/code?branch=master&name=myname

Using that as the sourceURI in your example without escaping will pass two different name parameters. The trailing &name=myname will be treated as a different query parameter, not part of sourceURI. (The ? might also be a problem.)

This could a problem with JSON template parameter values that could have characters like & in them. The parameters MUST be encoded if they contain certain characters.

[spadgett]

Another example: Source URLs with a # like

http://example.com/code#master

will cause anything from the # in the URL to be ignored. The value needs to be encoded.

[rhamilto]

Ah. Thanks for clarifying, @spadgett! I completely overlooked the parenthesis in your initial comment. Apologies.

[rhamilto]

@jwforres, @spadgett Comments addressed. PTAL.

[rhamilto]

@ahardin-rh, please put this on your radar for 3.5. This PR is probably ok as is, but could probably benefit from a writer's touch.

[ahardin-rh]

[rev_history]
|xref:../dev_guide/create_from_url.adoc#dev-guide-create-from-url[Create from URL]
|New topic on Create from URL, a function that allows you to construct a URL from an image stream, image tag, or template.
%