Add documentation for state.source.url

[juanmaguitar]

As per https://github.com/frontity/docs/issues/245

[michalczaplinski]

Hey @juanmaguitar in addition to the comments I was wondering if you would like to add:

• Examples of usage for each of the properties.
• Information about what the "suggested" usage is for each scenario:
  • Free WP.com
  • Personal and Premium WP.com
  • WP.org and Business WP.com
  • for each of the above, whether it's running in decoupled or embedded mode.

I'm going to approve the PR in any case as you have the last word on how to document this. Those are my suggestions 🙂

[michalczaplinski]

Hey @juanmaguitar I've pushed my version of the docs here. Hope it clears things up a bit.

A couple of things:

• I've mentioned the Embedded Mode when talking about state.source.url which is important information, but I don't know if you have already documented the fact that there exist a decoupled and embedded modes since they are not "officially" released. So, I ll let you decide if you want to keep that bit.
• I've mentioned WP Engine and Pantheon by name when talking about state.source.api just to clarify. It's obviously not an endorsement and but I don't know if you have a policy about mentioning other companies by name.

If you are self-hosting your WordPress
installation or using a third party hosting like WP Engine, Pantheon, etc.,
the value would be https://my-awesome-site.com/wp-json.

• I did not see any place in the api-reference where you specify that state.frontity.url has to be set to a particular valve. I think previously it was not strictly necessary, but now we absolutely require it to be set by the user in order for a Frontity site to run. I think that you should add such a section to the docs.

I think that the part that was difficult to distill from the Feature Discussion was to document which settings are required for which kind of hosting. I've tried to summarize it here: https://community.frontity.org/t/make-the-backend-url-a-global-setting/2381/59

[juanmaguitar]

@michalczaplinski Regarding this...

I did not see any place in the api-reference where you specify that state.frontity.url has to be set to a particular valve. I think previously it was not strictly necessary, but now we absolutely require it to be set by the user in order for a Frontity site to run. I think that you should add such a section to the docs.

What is the purpose of this `state.frontity.url value?

• Should it contain the URL of the final deployed Frontity site?
• Should it contain the URL of the WordPress backend installation?
• Is it also required if state.source.url is set?

[michalczaplinski]

What is the purpose of this `state.frontity.url value?

• Should it contain the URL of the final deployed Frontity site?

correct! Take mars.frontity.org for example.

The state.frontity.url is simply "https://mars.frontity.org" and state.source.url is "https://test.frontity.org" (the URL of the WP backend)

Should it contain the URL of the WordPress backend installation?

Nope. This is what state.source.url is for.

Is it also required if state.source.url is set?

Yes! It's explained in some more detail in the community thread. To quote from there:

Only in Embedded mode, where both Frontity and the backend are in the same domain, you can omit state.source.url and if you do, it will take the value of state.frontity.url as a fallback.

[juanmaguitar]

@michalczaplinski

I've mentioned the Embedded Mode when talking about state.source.url which is important information, but I don't know if you have already documented the fact that there exist a decoupled and embedded modes since they are not "officially" released. So, I ll let you decide if you want to keep that bit.

Yes, there's this thread opened in the Community Forum for this conversation. I'd like we wrap what we have about Embedded Mode in some way and start documenting it (even if it's with the tag. "Experimental")

I've mentioned WP Engine and Pantheon by name when talking about state.source.api just to clarify. It's obviously not an endorsement and but I don't know if you have a policy about mentioning other companies by name.

No rule against this for now

I did not see any place in the api-reference where you specify that state.frontity.url has to be set to a particular valve. I think previously it was not strictly necessary, but now we absolutely require it to be set by the user in order for a Frontity site to run. I think that you should add such a section to the docs.

I've opened this thread in the Community Forum to gather feedback about the documentation of @fronitty/core. That could be a good place to document the frontity namespace and its related settings

Besides this, a more practical approach of these setting will be covered in the "A Frontity project" section

There's also this related issue which may be solved with the @fronitty/core documentation idea

I think that the part that was difficult to distill from the Feature Discussion was to document which settings are required for which kind of hosting. I've tried to summarize it here: https://community.frontity.org/t/make-the-backend-url-a-global-setting/2381/59

I think this table is covered w/ the current status of the page. Please, have a look and share your feedback in case you think some more explanations are needed regarding this

[michalczaplinski]

Ok, thanks JuanMa, I ll check it out the threads you linked and add my comments there 🙂.

I think this table is covered w/ the current status of the page. Please, have a look and share your feedback in case you think some more explanations are needed regarding this

Yes, I think that the docs are covering it - I just added it in the community thread for completeness.