search

contao / docs

Contao Documentation
https://docs.contao.org
Other
31 stars 141 forks source link

Add helper tools #1382

Closed zoglo closed 2 months ago

zoglo commented 2 months ago

[!NOTE]
This PR also introduces a config.toml file that embeds the styles into the head for the manual pages as <style> is not valid HTML within <body>. The config.toml is documented here: https://learn.netlify.app/en/basics/configuration/

Description

This PR addresses the issue of people having to encode/decode their parameters within dotenv and yaml files and not trusting any source to do that for them.

This also adds the first tools into the docs and can be used by normal users without relying on support.

Converting database parameters

image

The first tool introduced is the same as the database parameter tool within the contao-manager. It's rewritten in native JavaScript and works within the docs. You are able to either use your database credentials to create the DATABASE_URL or copy it to create the credentials.

Temporary example:

https://sebastian.oveleon.com/manual/en/system/settings/#convert-your-database-parameters

Converting mail parameters

image

The second tool introduces normal url-encoding for the .env setting MAILER_DSN and the double encoded config.yml variant for setting up your e-mail parameters.

Temporary example:

https://sebastian.oveleon.com/manual/en/system/settings/#convert-your-mail-parameters

fkaminski commented 2 months ago

Great idea, especially for a MAILER_DSN tool, as this is currently not done within the manager (For all those who do not like to use e.g. urlencoder.org).

Furthermore, possibly also for the "Different e-mail configurations and sender addresses" chapter (config.yml - the smtp://... or smtps://... part)? Because of this:

When using config.yaml, the respective encoding of a special character must be prefixed with %: So e. g. %%40 for the special character @.

fkaminski commented 2 months ago

The temporary example does not take all special characters, for example * or !, into account - compared to urlencoder.org usage

Test: +-@-$-#-/-:-%-&-*-!

fritzmg commented 2 months ago

@fkaminski that's fine, you don't need raw URL encoding.

zoglo commented 2 months ago

Should the css be included separately or be included in the theme_contao.css? /cc @fritzmg

fritzmg commented 2 months ago

I would prefer separate.

zoglo commented 2 months ago

Can we also integrate the JavaScript externally? This way we wouldn't need to copy the code. Or may be integrate it as a short code instead.

Sounds good to me - could just add it into the custom-header.html

zoglo commented 2 months ago

Done @fritzmg :) - I added a tools.js and am loading that via the custom-header