diff --git a/README.md b/README.md index 4dd6b3e..4e881a6 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,99 @@ For reference have a look at [public/logo.svg](./public/logo.svg). To change the index.html, create a public folder in your application and put your index.html in it. For reference have a look at [public/index.html](./public/index.html). +### Add social links to the footer and sidebar +To add social links, create a public folder in your application and put a messages.json in it. +```json +{ + "socialLinks": [ + { "href": "https://www.facebook.com/aoepeople", "iconName": "facebook" }, + { "href": "https://twitter.com/aoepeople", "iconName": "twitter" }, + { "href": "https://www.linkedin.com/company/aoe", "iconName": "linkedIn" } + ] +} +``` + +> For more information and the possible icon names see the source code of the [SocialLink Component](./src/components/SocialLink/SocialLink.tsx). + +### Add a legal information link to the footer and sidebar +To add a link to legal information, create a public folder in your application and put a messages.json in it. +```json +{ + "legalInformationLink": "https://www.aoe.com/en/imprint.html" +} +``` + +### Add a footnote with the logo to the footer +To add a footnote to the footer, create a public folder in your application and put a messages.json in it. +```json +{ + "footerFootnote": "AOE is a leading global provider of services for digital transformation and digital business models. AOE relies exclusively on established Enterprise Open Source technologies. This leads to innovative solutions, digital products and portals in agile software projects, and helps build long-lasting, strategic partnerships with our customers." +} +``` + +### Add a help page with explanations +To add a help page, create a public folder in your application and put a messages.json in it. +```json +{ + "pageHelp": { + "paragraphs": [ + { + "headline": "Introduction", + "values": [ + "Technology is moving fast and new technologies and innovations appear continuously.", + "It's essential for a development and technology company such as AOE to constantly improve and keep track with the latest useful innovations. It is important to openly look for innovations and new technologies and to question established technologies and methods every now and then.", + "But, it is also important to wisely choose which technologies to use in our daily work and in the different projects we are carrying out. As we all know: There is no silver bullet." + ] + }, + { + "headline": "What is the AOE Technology Radar", + "values": [ + "The Tech Radar is an overview of different technologies - from languages, frameworks, tools and patterns to platforms - that we consider \"new or mentionable\". The radar therefore doesn't provide an overview of all established technologies - but it focuses on items that have recently gained in importance or changed." + ] + } + ], + "quadrants": [ + { + "name": "Languages and Frameworks", + "description": "We've placed development languages (such as Scala or Golang) here, as well as more low-level development frameworks (such as Play or Symfony), which are useful for implementing custom software of all kinds." + }, + { + "name": "Tools", + "description": "Here we put different software tools - from small helpers to bigger software projects" + }, + { + "name": "Methods and Patterns", + "description": "Patterns are so important, and a lot of them are valid for a long time (compared to some tools or frameworks). So, this is the category where we put information on methods and patterns concerning development, continuous x, testing, organization, architecture, etc." + }, + { + "name": "Platforms and Operations", + "description": "(including AOE internal Services): Here we include infrastructure platforms and services. We also use this category to communicate news about AOE services that we want all AOE teams to be aware of." + } + ], + "rings": [ + { + "name": "Adopt", + "description": "We can clearly recommend this technology. We have used it for longer period of time in many teams and it has proven to be stable and useful." + }, + { + "name": "Trial", + "description": "We have used it with success and recommend to have a closer look at the technology in this ring. The goal of items here is to look at them more closely, with the goal to bring them to the adopt level." + }, + { + "name": "Assess", + "description": "We have tried it out and we find it promising. We recommend having a look at these items when you face a specific need for the technology in your project." + }, + { + "name": "Hold", + "description": "This category is a bit special. Unlike the others, we recommend to stop doing or using something. That does not mean that they are bad and it often might be ok to use them in existing projects. But we move things here if we think we shouldn't do them anymore - because we see better options or alternatives now." + } + ] + } +} +``` + +> For more information see the source code of the [Messages Context](./src/context/MessagesContext/index.tsx). + ## Use and build the radar > Set the environment variable `PUBLIC_URL` properly. For more information see [Host the application under a sub path](#host-the-application-under-a-sub-path) @@ -115,7 +208,8 @@ You can integrate images in your markdown. Put the image files in your public fo ``` ## Development -For local development you need a `rd.json` in the public folder. You can use `rd_example.json`. +For local development you need a `rd.json` in the public folder. You can use [rd_example.json](./rd_example.json). +For several customizations you need a `messages.json` in the public folder. You can use [messages_example.json](./messages_example.json). Then simply start the dev server ``` diff --git a/public/messages.json b/messages_example.json similarity index 52% rename from public/messages.json rename to messages_example.json index 0db0afa..2e14576 100644 --- a/public/messages.json +++ b/messages_example.json @@ -10,23 +10,37 @@ { "href": "https://github.com/aoepeople", "iconName": "github" } ], "pageHelp": { - "introduction": [ - "Technology is moving fast and new technologies and innovations appear continuously.", - "It's essential for a development and technology company such as AOE to constantly improve and keep track with the latest useful innovations. It is important to openly look for innovations and new technologies and to question established technologies and methods every now and then.", - "But, it is also important to wisely choose which technologies to use in our daily work and in the different projects we are carrying out. As we all know: There is no silver bullet." - ], - "whatIsTheRadar": [ - "The Tech Radar is an overview of different technologies - from languages, frameworks, tools and patterns to platforms - that we consider \"new or mentionable\". The radar therefore doesn't provide an overview of all established technologies - but it focuses on items that have recently gained in importance or changed." - ], - "howItIsCreated": [ - "The items in the technology radar are raised by the different teams and therefore a lot of the items are related to the work and challenges the teams face in the different projects. In fact, we don't include anything on the radar, which we haven't already tried ourselves at least once.", - "There have been a lot of valuable discussions in different expert groups about the classification and details of each of technologies and innovations. And the result of all this can be found in the latest technology radar." - ], - "howShouldItBeUsed": [ - "The radar acts as an overview of technologies that we think everyone in the teams should currently know about.", - "Its goal is to act as a guide and inspiration for the daily work in the teams. Its purpose is also to provide helpful information and a bird's-eye perspective - so that decisions can be taken with a much deeper understanding of the subject matter. This results in more-informed and better-aligned decisions.", - "We also hope that developers outside of AOE find the information in our technology overview inspirational.", - "We group or categorize the items in 4 quadrants - (sometimes, when it's not 100% clear where a item belongs, we choose the best fit)." + "paragraphs": [ + { + "headline": "Introduction", + "values": [ + "Technology is moving fast and new technologies and innovations appear continuously.", + "It's essential for a development and technology company such as AOE to constantly improve and keep track with the latest useful innovations. It is important to openly look for innovations and new technologies and to question established technologies and methods every now and then.", + "But, it is also important to wisely choose which technologies to use in our daily work and in the different projects we are carrying out. As we all know: There is no silver bullet." + ] + }, + { + "headline": "What is the AOE Technology Radar", + "values": [ + "The Tech Radar is an overview of different technologies - from languages, frameworks, tools and patterns to platforms - that we consider \"new or mentionable\". The radar therefore doesn't provide an overview of all established technologies - but it focuses on items that have recently gained in importance or changed." + ] + }, + { + "headline": "How it is created", + "values": [ + "The items in the technology radar are raised by the different teams and therefore a lot of the items are related to the work and challenges the teams face in the different projects. In fact, we don't include anything on the radar, which we haven't already tried ourselves at least once.", + "There have been a lot of valuable discussions in different expert groups about the classification and details of each of technologies and innovations. And the result of all this can be found in the latest technology radar." + ] + }, + { + "headline": "How should it be used", + "values": [ + "The radar acts as an overview of technologies that we think everyone in the teams should currently know about.", + "Its goal is to act as a guide and inspiration for the daily work in the teams. Its purpose is also to provide helpful information and a bird's-eye perspective - so that decisions can be taken with a much deeper understanding of the subject matter. This results in more-informed and better-aligned decisions.", + "We also hope that developers outside of AOE find the information in our technology overview inspirational.", + "We group or categorize the items in 4 quadrants - (sometimes, when it's not 100% clear where a item belongs, we choose the best fit)." + ] + } ], "quadrants": [ { @@ -63,6 +77,12 @@ "name": "Hold", "description": "This category is a bit special. Unlike the others, we recommend to stop doing or using something. That does not mean that they are bad and it often might be ok to use them in existing projects. But we move things here if we think we shouldn't do them anymore - because we see better options or alternatives now." } - ] - } + ], + "sourcecodeLinks": { + "href": "https://github.com/AOEpeople/aoe_technology_radar", + "name": "AOE Tech Radar on Github", + "description": "Contributions and source code of the AOE Tech Radar are on github:" + } + }, + "legalInformationLink": "https://www.aoe.com/en/imprint.html" } diff --git a/src/components/App.tsx b/src/components/App.tsx index c3e4053..6f374f0 100644 --- a/src/components/App.tsx +++ b/src/components/App.tsx @@ -18,10 +18,25 @@ interface Params { page: string; } -const useQuery = () => { - return new URLSearchParams(useLocation().search); +const useFetch = (url: string): D | undefined => { + const [data, setData] = React.useState(); + + React.useEffect(() => { + fetch(url) + .then((response) => response.json()) + .then((data: D) => { + setData(data); + }) + .catch((error) => { + console.error(`fetch ${url} failed. Did the file exist?`, error); + }); + }, []); + + return data; }; +const useQuery = () => new URLSearchParams(useLocation().search); + const RouterWithPageParam = ({ items, releases, @@ -60,30 +75,12 @@ interface Data { } export default function App() { - const [data, setData] = React.useState(); - const [messages, setMessages] = React.useState(); + const data = useFetch(`${process.env.PUBLIC_URL}/rd.json`); + const messages = useFetch( + `${process.env.PUBLIC_URL}/messages.json` + ); - React.useEffect(() => { - fetch(`${process.env.PUBLIC_URL}/rd.json`) - .then((response) => response.json()) - .then((data: Data) => { - setData(data); - }) - .catch((error) => { - console.error("fetch data", error); - }); - - fetch(`${process.env.PUBLIC_URL}/messages.json`) - .then((response) => response.json()) - .then((messages: Messages) => { - setMessages(messages); - }) - .catch((error) => { - console.error("fetch messages", error); - }); - }, []); - - if (data && messages) { + if (data) { const { items, releases } = data; return ( diff --git a/src/components/Footer/Footer.tsx b/src/components/Footer/Footer.tsx index 47ba59a..6ca1fdb 100644 --- a/src/components/Footer/Footer.tsx +++ b/src/components/Footer/Footer.tsx @@ -22,14 +22,22 @@ const Footer: React.FC = ({ items, pageName }) => { !isMobileViewport() && getItemPageNames(items).includes(pageName), })} > - - } - > - {footerFootnote} - + {footerFootnote && ( + + } + > + {footerFootnote} + + )} + ); diff --git a/src/components/FooterEnd/FooterEnd.tsx b/src/components/FooterEnd/FooterEnd.tsx index 1a97312..ae2c922 100644 --- a/src/components/FooterEnd/FooterEnd.tsx +++ b/src/components/FooterEnd/FooterEnd.tsx @@ -1,6 +1,6 @@ import React from "react"; import classNames from "classnames"; -import SocialIcon from "../SocialIcon/SocialIcon"; +import SocialLink from "../SocialLink/SocialLink"; import "./footerend.scss"; import { useMessages } from "../../context/MessagesContext"; @@ -9,7 +9,7 @@ interface Props { } const FooterEnd: React.FC = ({ modifier }) => { - const { socialIcons } = useMessages(); + const { socialLinks, legalInformationLink } = useMessages(); return (
= ({ modifier }) => { })} >
-
-

Follow us:

-
-
- {socialIcons.map(({ href, iconName }) => ( - - ))} -
-
-
-

- - Legal Information - -

+ {socialLinks && ( + <> +
+

Follow us:

+
+
+ {socialLinks.map(({ href, iconName }) => ( + + ))} +
+ + )}
+ + {legalInformationLink && ( + + )}
); }; diff --git a/src/components/Header/Header.tsx b/src/components/Header/Header.tsx index 61438c6..fa5825f 100644 --- a/src/components/Header/Header.tsx +++ b/src/components/Header/Header.tsx @@ -7,10 +7,12 @@ import Search from "../Search/Search"; import { radarNameShort } from "../../config"; import { useHistory } from "react-router-dom"; import qs from "query-string"; +import { useMessages } from "../../context/MessagesContext"; export default function Header({ pageName }: { pageName: string }) { const [searchOpen, setSearchOpen] = useState(false); const [search, setSearch] = useState(""); + const { pageHelp } = useMessages(); const history = useHistory(); const searchRef = useRef(null); @@ -49,12 +51,14 @@ export default function Header({ pageName }: { pageName: string }) { return ( }>
-
- - - How to Use {radarNameShort}? - -
+ {pageHelp && ( +
+ + + How to Use {radarNameShort}? + +
+ )}
diff --git a/src/components/PageHelp/PageHelp.tsx b/src/components/PageHelp/PageHelp.tsx index 0c25994..859c90c 100644 --- a/src/components/PageHelp/PageHelp.tsx +++ b/src/components/PageHelp/PageHelp.tsx @@ -3,141 +3,68 @@ import HeroHeadline from "../HeroHeadline/HeroHeadline"; import Fadeable from "../Fadeable/Fadeable"; import SetTitle from "../SetTitle"; import { radarName } from "../../config"; +import { useMessages } from "../../context/MessagesContext"; -export default function PageHelp({ - leaving, - onLeave, -}: { +interface Props { leaving: boolean; onLeave: () => void; -}) { - return ( - - - How to use the {radarName} -
-

Introduction

-

- Technology is moving fast and new technologies and innovations appear - continuously. -

-

- It's essential for a development and technology company such as AOE to - constantly improve and keep track with the latest useful innovations. - It is important to openly look for innovations and new technologies - and to question established technologies and methods every now and - then. -

-

- But, it is also important to wisely choose which technologies to use - in our daily work and in the different projects we are carrying out. - As we all know: There is no silver bullet. -

-

What is the {radarName}

-

- The Tech Radar is an overview of different technologies - from - languages, frameworks, tools and patterns to platforms - that we - consider "new or mentionable". The radar therefore doesn't provide an - overview of all established technologies - but it focuses on items - that have recently gained in importance or changed. -

-

How it is created

-

- The items in the technology radar are raised by the different teams - and therefore a lot of the items are related to the work and - challenges the teams face in the different projects. In fact, we don't - include anything on the radar, which we haven't already tried - ourselves at least once. -

-

- There have been a lot of valuable discussions in different expert - groups about the classification and details of each of technologies - and innovations. And the result of all this can be found in the latest - technology radar. -

-

How should it be used

-

- The radar acts as an overview of technologies that we think everyone - in the teams should currently know about. -

-

- Its goal is to act as a guide and inspiration for the daily work in - the teams. Its purpose is also to provide helpful information and a - bird's-eye perspective - so that decisions can be taken with a much - deeper understanding of the subject matter. This results in - more-informed and better-aligned decisions. -

-

- We also hope that developers outside of AOE find the information in - our technology overview inspirational. -

-

- We group or categorize the items in 4 quadrants - (sometimes, when - it's not 100% clear where a item belongs, we choose the best fit). -

-

The quadrants are:

-
    -
  • - Languages and Frameworks: We've placed development - languages (such as Scala or Golang) here, as well as more low-level - development frameworks (such as Play or Symfony), which are useful - for implementing custom software of all kinds. -
    • -
  • - Tools: Here we put different software tools - from - small helpers to bigger software projects -
    • -
  • - Methods and Patterns: Patterns are so important, - and a lot of them are valid for a long time (compared to some tools - or frameworks). So, this is the category where we put information on - methods and patterns concerning development, continuous x, testing, - organization, architecture, etc. -
    • -
  • - Platforms and Services (including AOE internal - Services): Here we include infrastructure platforms and services. We - also use this category to communicate news about AOE services that - we want all AOE teams to be aware of. -
    • -
-

Each of the items is classified in one of these rings:

-
    -
  • - Adopt: We can clearly recommend this technology. We - have used it for longer period of time in many teams and it has - proven to be stable and useful. -
    • -
  • - Trial: We have used it with success and recommend - to have a closer look at the technology in this ring. The goal of - items here is to look at them more closely, with the goal to bring - them to the adopt level. -
    • -
  • - Assess: We have tried it out and we find it - promising. We recommend having a look at these items when you face a - specific need for the technology in your project. -
    • -
  • - Hold: This category is a bit special. Unlike the - others, we recommend to stop doing or using something. That does not - mean that they are bad and it often might be ok to use them in - existing projects. But we move things here if we think we shouldn't - do them anymore - because we see better options or alternatives now. -
    • -
-

- Contributions and source code of the radar are on github:{" "} - - AOE Tech Radar on Github - -

-
- - ); } + +const PageHelp: React.FC = ({ leaving, onLeave }) => { + const { pageHelp } = useMessages(); + + if (pageHelp) { + const { paragraphs, quadrants, rings, sourcecodeLink } = pageHelp; + return ( + + + How to use the {radarName} +
+ {paragraphs.map(({ headline, values }) => ( + +

{headline}

+ {values.map((element, index) => ( +

{element}

+ ))} + + ))} + +

The quadrants are:

+
    + {quadrants.map(({ name, description }) => ( +
  • + {name}: {description} +
    • + ))} +
+ +

Each of the items is classified in one of these rings:

+
    + {rings.map(({ name, description }) => ( +
  • + {name}: {description} +
    • + ))} +
+ + {sourcecodeLink && ( +

+ {`${sourcecodeLink.description} `} + + {sourcecodeLink.name} + +

+ )} +
+ + ); + } + + return null; +}; + +export default PageHelp; diff --git a/src/components/SocialIcon/SocialIcon.tsx b/src/components/SocialLink/SocialLink.tsx similarity index 82% rename from src/components/SocialIcon/SocialIcon.tsx rename to src/components/SocialLink/SocialLink.tsx index 124a406..1c1d98b 100644 --- a/src/components/SocialIcon/SocialIcon.tsx +++ b/src/components/SocialLink/SocialLink.tsx @@ -24,7 +24,7 @@ export interface Props { iconName: keyof typeof icons; } -const SocialIcon: React.FC = ({ href, iconName }) => { +const SocialLink: React.FC = ({ href, iconName }) => { const Icon = icons[iconName]; if (Icon) { @@ -39,8 +39,8 @@ const SocialIcon: React.FC = ({ href, iconName }) => { ); } - console.log(`The icon is unknown: ${iconName}`); + console.error(`The iconname is unknown: ${iconName}`); return null; }; -export default SocialIcon; +export default SocialLink; diff --git a/src/context/MessagesContext/index.tsx b/src/context/MessagesContext/index.tsx index 5e86984..6d35e7f 100644 --- a/src/context/MessagesContext/index.tsx +++ b/src/context/MessagesContext/index.tsx @@ -1,5 +1,5 @@ import { createContext, FC, useContext } from "react"; -import { Props as SocialIcon } from "../../components/SocialIcon/SocialIcon"; +import { Props as SocialLink } from "../../components/SocialLink/SocialLink"; interface Quadrant { name: string; @@ -11,24 +11,32 @@ interface Ring { description: string; } +interface Paragraph { + headline: string; + values: string[]; +} + interface PageHelp { - introduction: string[]; - whatIsTheRadar: string[]; - howItIsCreated: string[]; - howShouldItBeUsed: string[]; + paragraphs: Paragraph[]; quadrants: Quadrant[]; rings: Ring[]; + sourcecodeLink?: { + href: string; + name: string; + description: string; + }; } export interface Messages { - footerFootnote: string; - socialIcons: SocialIcon[]; - pageHelp: PageHelp; + footerFootnote?: string; + socialLinks?: SocialLink[]; + legalInformationLink?: string; + pageHelp?: PageHelp; } const MessagesContext = createContext(undefined); -export const MessagesProvider: FC<{ messages: Messages }> = ({ +export const MessagesProvider: FC<{ messages?: Messages }> = ({ messages, children, }) => ( @@ -42,5 +50,5 @@ export const useMessages = () => { if (context === undefined) { throw new Error("useMessages must be used within a MessagesProvider"); } - return context; + return context || {}; };