From b8a5d5d087b05e45466f36e8d32e16ef817edea4 Mon Sep 17 00:00:00 2001 From: Eduard Heimbuch Date: Fri, 24 Apr 2020 10:17:18 +0200 Subject: [PATCH 1/4] add guide to prevent common pitfalls in ui development --- docs/common-pitfalls-ui-development.md | 32 ++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 docs/common-pitfalls-ui-development.md diff --git a/docs/common-pitfalls-ui-development.md b/docs/common-pitfalls-ui-development.md new file mode 100644 index 0000000000..38248a6808 --- /dev/null +++ b/docs/common-pitfalls-ui-development.md @@ -0,0 +1,32 @@ +# Common pitfalls ui development + +## Introduction +There are quite some common pitfalls which can cause an inconsistent or broken ui. +You can avoid most ugly ui glitches and broken surfaces or just improve your frontend code +by asking yourself some questions while building the components. + +## Design +There exists a scm styleguide which can support you build fitting and beautiful ui components. +Find the styleguide in "scm-ui/ui-styles". + +- Have I used the colors from the scm styleguide? +- Have I used familiar fonts which are already in use on this surface? +- Is my component scalable / resizeable? +- What happens if I insert very long / short content? +- Is my component mobile friendly (tablet / smartphone)? +- Does my component fit into the existing surface? +- Does the ui become confusing / overcrowded / ugly because of my component? +- Can I reduce the shown texts and use icons (tooltips) instead? +- Are there enough whitespaces in my component / around my component? +- Have I used translation keys and translated my content at least in german and english? + +## Small, reuseable components +The SCM-Manager provides a storybook which tests many reuseable components with usage examples. +You can also find some more ui components which doesn't have stories yet in "scm-ui/ui-components". +If a component which can be reused is missing, feel free to add it to ui-components. + +- Have I checked ui-components before creating an entirely new component? +- If creating a new component should it be added to ui-components? +- Have I written one or more stories which tests my new component in the storybook? +- Does my component have too much code / logic? Can it be cut down in some smaller components? +- Have I created the new component as a react functional component? From 374e9f7b0d5bdb52e625c4e2acac6e62e07e4462 Mon Sep 17 00:00:00 2001 From: Eduard Heimbuch Date: Fri, 24 Apr 2020 10:21:58 +0200 Subject: [PATCH 2/4] update CHANGELOG.md --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index ff7e4c3183..814d37c511 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Add iconStyle + onClick option and story shot for icon component ([#1100](https://github.com/scm-manager/scm-manager/pull/1100)) - Making WebElements (Servlet or Filter) optional by using the `@Requires` annotation ([#1101](https://github.com/scm-manager/scm-manager/pull/1101)) - Add class to manually validate rest data transfer objects with javax validation annotations ([#1114](https://github.com/scm-manager/scm-manager/pull/1114)) +- Add guide to prevent common pitfalls in ui development ([#1107](https://github.com/scm-manager/scm-manager/pull/1107)) ### Changed - Removed the `requires` attribute on the `@Extension` annotation and instead create a new `@Requires` annotation ([#1097](https://github.com/scm-manager/scm-manager/pull/1097)) From 1625cb386c2569fb0aa853cdcdbfa968b827581a Mon Sep 17 00:00:00 2001 From: Eduard Heimbuch Date: Fri, 24 Apr 2020 10:37:30 +0200 Subject: [PATCH 3/4] move common pitfall guide to existing common-pitfall.md --- CHANGELOG.md | 2 +- docs/common-pitfalls-ui-development.md | 32 --------------------- docs/en/development/common-pitfall.md | 40 +++++++++++++++++++++++--- 3 files changed, 37 insertions(+), 37 deletions(-) delete mode 100644 docs/common-pitfalls-ui-development.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 814d37c511..f1c7d9d86f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,10 +9,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Add iconStyle + onClick option and story shot for icon component ([#1100](https://github.com/scm-manager/scm-manager/pull/1100)) - Making WebElements (Servlet or Filter) optional by using the `@Requires` annotation ([#1101](https://github.com/scm-manager/scm-manager/pull/1101)) - Add class to manually validate rest data transfer objects with javax validation annotations ([#1114](https://github.com/scm-manager/scm-manager/pull/1114)) -- Add guide to prevent common pitfalls in ui development ([#1107](https://github.com/scm-manager/scm-manager/pull/1107)) ### Changed - Removed the `requires` attribute on the `@Extension` annotation and instead create a new `@Requires` annotation ([#1097](https://github.com/scm-manager/scm-manager/pull/1097)) +- Update guide to prevent common pitfalls in ui development ([#1107](https://github.com/scm-manager/scm-manager/pull/1107)) - Use os specific locations for scm home directory ([#1109](https://github.com/scm-manager/scm-manager/pull/1109)) - Use Library/Logs/SCM-Manager on OSX for logging ([#1109](https://github.com/scm-manager/scm-manager/pull/1109)) - Cleanup outdated jaxb annotation in scm-core ([#1136](https://github.com/scm-manager/scm-manager/pull/1136)) diff --git a/docs/common-pitfalls-ui-development.md b/docs/common-pitfalls-ui-development.md deleted file mode 100644 index 38248a6808..0000000000 --- a/docs/common-pitfalls-ui-development.md +++ /dev/null @@ -1,32 +0,0 @@ -# Common pitfalls ui development - -## Introduction -There are quite some common pitfalls which can cause an inconsistent or broken ui. -You can avoid most ugly ui glitches and broken surfaces or just improve your frontend code -by asking yourself some questions while building the components. - -## Design -There exists a scm styleguide which can support you build fitting and beautiful ui components. -Find the styleguide in "scm-ui/ui-styles". - -- Have I used the colors from the scm styleguide? -- Have I used familiar fonts which are already in use on this surface? -- Is my component scalable / resizeable? -- What happens if I insert very long / short content? -- Is my component mobile friendly (tablet / smartphone)? -- Does my component fit into the existing surface? -- Does the ui become confusing / overcrowded / ugly because of my component? -- Can I reduce the shown texts and use icons (tooltips) instead? -- Are there enough whitespaces in my component / around my component? -- Have I used translation keys and translated my content at least in german and english? - -## Small, reuseable components -The SCM-Manager provides a storybook which tests many reuseable components with usage examples. -You can also find some more ui components which doesn't have stories yet in "scm-ui/ui-components". -If a component which can be reused is missing, feel free to add it to ui-components. - -- Have I checked ui-components before creating an entirely new component? -- If creating a new component should it be added to ui-components? -- Have I written one or more stories which tests my new component in the storybook? -- Does my component have too much code / logic? Can it be cut down in some smaller components? -- Have I created the new component as a react functional component? diff --git a/docs/en/development/common-pitfall.md b/docs/en/development/common-pitfall.md index a226bdd4ed..f9b74cfc41 100644 --- a/docs/en/development/common-pitfall.md +++ b/docs/en/development/common-pitfall.md @@ -2,19 +2,51 @@ title: Common pitfall occurred while developing the SCM V2 --- -## React Component is loaded unexpectedly +## Introduction +There are quite some common pitfalls which can cause an inconsistent or broken ui. +You can avoid most ugly ui glitches and broken surfaces or just improve your frontend code +by asking yourself some questions while building the components. -### Bug +## Design +There exists a scm styleguide which can support you build fitting and beautiful ui components. +Find the styleguide in "scm-ui/ui-styles". + +- Have I used the colors from the scm styleguide? +- Have I used familiar fonts which are already in use on this surface? +- Is my component scalable / resizeable? +- What happens if I insert very long / short content? +- Is my component mobile friendly (tablet / smartphone)? +- Does my component fit into the existing surface? +- Does the ui become confusing / overcrowded / ugly because of my component? +- Can I reduce the shown texts and use icons (tooltips) instead? +- Are there enough whitespaces in my component / around my component? +- Have I used translation keys and translated my content at least in german and english? + +## Small, reuseable components +The SCM-Manager provides a storybook which tests many reuseable components with usage examples. +You can also find some more ui components which doesn't have stories yet in "scm-ui/ui-components". +If a component which can be reused is missing, feel free to add it to ui-components. + +- Have I checked ui-components before creating an entirely new component? +- If creating a new component should it be added to ui-components? +- Have I written one or more stories which tests my new component in the storybook? +- Does my component have too much code / logic? Can it be cut down in some smaller components? +- Have I created the new component as a react functional component? + +## Other common errors +### React Component is loaded unexpectedly + +#### Bug A react component is updated without any changes in the props or states. -### Fix +#### Fix Use the [why-did-you-update](https://github.com/maicki/why-did-you-update) library to analyze the causes of the updates. A common cause is the definition of [new functions in render()](https://github.com/maicki/why-did-you-update#changes-are-in-functions-only). -### Example +#### Example ```javascript class Main extends React.Component { From d6b1292102aec4a42cf48b9627c74ab13b188917 Mon Sep 17 00:00:00 2001 From: Eduard Heimbuch Date: Fri, 24 Apr 2020 10:41:49 +0200 Subject: [PATCH 4/4] rename common-pitfalls file --- docs/en/development/{common-pitfall.md => ui-common-pitfall.md} | 0 docs/en/navigation.yml | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename docs/en/development/{common-pitfall.md => ui-common-pitfall.md} (100%) diff --git a/docs/en/development/common-pitfall.md b/docs/en/development/ui-common-pitfall.md similarity index 100% rename from docs/en/development/common-pitfall.md rename to docs/en/development/ui-common-pitfall.md diff --git a/docs/en/navigation.yml b/docs/en/navigation.yml index a406038586..045f97f29e 100644 --- a/docs/en/navigation.yml +++ b/docs/en/navigation.yml @@ -16,7 +16,7 @@ entries: - /development/intellij-idea-configuration/ - /development/build-from-source/ - - /development/common-pitfall/ + - /development/ui-common-pitfall/ - /administration/permission-concept/ - /development/error-handling/ - /development/i18n/