diff --git a/docs/software_development/.pages b/docs/software_development/.pages index 813ffffb..96abe078 100644 --- a/docs/software_development/.pages +++ b/docs/software_development/.pages @@ -6,4 +6,4 @@ nav: - Languages - Version_Control - Remote_Development - - ... + - Web_Development diff --git a/docs/software_development/Web_Development/back-end/index.md b/docs/software_development/Web_Development/back-end/index.md new file mode 100644 index 00000000..40ebf732 --- /dev/null +++ b/docs/software_development/Web_Development/back-end/index.md @@ -0,0 +1,2 @@ +# Back-end +This section covers some core concepts, libararies, frameworks, and tools related to back-end web application development related to the lab. \ No newline at end of file diff --git a/docs/software_development/Web_Development/back-end/libraries_and_frameworks/expressjs.md b/docs/software_development/Web_Development/back-end/libraries_and_frameworks/expressjs.md new file mode 100644 index 00000000..731ea87f --- /dev/null +++ b/docs/software_development/Web_Development/back-end/libraries_and_frameworks/expressjs.md @@ -0,0 +1 @@ +# ExpressJS \ No newline at end of file diff --git a/docs/software_development/Web_Development/back-end/libraries_and_frameworks/index.md b/docs/software_development/Web_Development/back-end/libraries_and_frameworks/index.md new file mode 100644 index 00000000..e9c16c37 --- /dev/null +++ b/docs/software_development/Web_Development/back-end/libraries_and_frameworks/index.md @@ -0,0 +1,3 @@ +# Back-end Libraries and Frameworks + +This section of the handbook mainly focuses on the backend libraries and frameworks pertaining to API development. \ No newline at end of file diff --git a/docs/software_development/Web_Development/back-end/libraries_and_frameworks/nestjs.md b/docs/software_development/Web_Development/back-end/libraries_and_frameworks/nestjs.md new file mode 100644 index 00000000..2cf5be0f --- /dev/null +++ b/docs/software_development/Web_Development/back-end/libraries_and_frameworks/nestjs.md @@ -0,0 +1 @@ +# NestJS \ No newline at end of file diff --git a/docs/software_development/Web_Development/back-end/node/node.md b/docs/software_development/Web_Development/back-end/node/node.md new file mode 100644 index 00000000..50e596ed --- /dev/null +++ b/docs/software_development/Web_Development/back-end/node/node.md @@ -0,0 +1,46 @@ +# NodeJS + +[NodeJS](https://nodejs.org) is a runtime environment that allows you to run JavaScript code outside of a browser. By default all browsers have compilers that can interpret and execute JavaScript code, hence they can render web applications that are using React, Vue, Angular, or plain JS seamlessly. However, when running JavaScript code outside of a browser compiler, you will need to have NodeJS installed. + +Many different projects in the lab use different versions of Node so using a tool such as a NVM (Node Version Manager) is a must. A NVM allows you to install and toggle between different versions of Node which is important since different projects utilize different library/package versions only compatible with specific node versions. + +Most legacy projects in the lab use Node version 14-16. This includes projects like PharmacoDB, SynergxDB, ToxicoDB, KulGaP, XevaDB, PredictIO, cclid, and ORCESTRA. More recent projects like the Pmatch web-app, Science Portal, CoBE, lab website, and the new ORCESTRA rework fall into Node versions 18-22. If new applications are to be created in the lab it is recommended to adopt newer node versions (as of writing this that's 22) so we can ensure the Node versions and packages installed for them will be updated and maintained for many years to come and will not require manual package updates as frequently. + +## Installation (Mac/Linux and Windows) + +For Mac/Linux users you can install an NVM [here](https://github.com/nvm-sh/nvm?tab=readme-ov-file#install--update-script) + +For window users you will need to install a differerent NVM [here](https://github.com/coreybutler/nvm-windows) + +Both NVMs work very similarly and provide almost identical functionality for installing and toggling between Node versions. + +### Listing current versions: +``` Bash +nvm list + v16.20.1 + v16.20.2 + v18.16.0 +-> v18.19.1 + v20.17.0 + v22.21.1 + v24.12.0 +``` + +### Installing New Versions + +``` Bash +nvm install 21 +Downloading and installing node v21.7.3... +Downloading https://nodejs.org/dist/v21.7.3/node-v21.7.3-darwin-arm64.tar.xz... +########################################################### 100.0% +Computing checksum with shasum -a 256 +Checksums matched! +Now using node v21.7.3 (npm v10.5.0) +``` + +### Toggling New Versions + +``` Bash +nvm use 21.7.3 +Now using node v21.7.3 (npm v10.5.0) +``` \ No newline at end of file diff --git a/docs/software_development/Web_Development/back-end/node/npm.md b/docs/software_development/Web_Development/back-end/node/npm.md new file mode 100644 index 00000000..be1d8e53 --- /dev/null +++ b/docs/software_development/Web_Development/back-end/node/npm.md @@ -0,0 +1,81 @@ +# npm (Node Package Manager) + +npm is the default package manager bundled with Node when installing directly from [NodeJS](https://nodejs.org/) or via a [Node Version Manager (NVM)](./node.md#installation-maclinux-and-windows). npm consists of a CLI tool (primarily used for installing packages and executing code/tests) and it also has access to the largest online software registry (containing millions of different packages). + +Similarlily to Pixi, npm focuses on localized package management rather than global. Each project contains it's own package.json file which includes the following belonging to the respective project: + +- A list of packages and their versions +- Scripts +- Licenses +- Authors +- Project description +- ... + +The localized packages ensure the runtime Node environment has access **ONLY** to the packages needed for the current execution. This avoids environment managemenet and cross project dependency issues commonly faced using pip or conda for Python projects. + +By default the npm CLI has a baked in "install" command that will install all packages within the current working directory. For the project you are currently inside of, simply run `npm install`. This will search for a package.json file in the local directory and install the package versions listed there inside of a folder called `node_modules`. + +# Scripts +For any project there are usually several scripts (often referred to as tasks in other package managers) preconfigured for repeated processes. This usually includes building (build), start/dev (live executing the application), or test (live testing the application). These scripts live within your package.json and will look like each of the code blocks below. + +### Back-end + +#### Standard execution for ExpressJS +Any of these commands can be invoked by writing `npm`, then following with the script/task name Ex. `npm start`. + + +```JSON +"scripts": { + "start": "node app.js", + "devstart": "nodemon app.js", + "test": "mocha --exit" +}, +``` + +#### Standard execution for NestJS +Any of these commands can be invoked by writing `npm` or `npm run`, then following with the script/task name Ex. `npm run start`. + + +```JSON +"scripts": { + "build": "nest build", + "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"", + "start": "nest start", + "start:dev": "nest start --watch", + "start:debug": "nest start --debug --watch", + "start:prod": "node dist/main", + "lint": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix", + "test": "jest", + "test:watch": "jest --watch", + "test:cov": "jest --coverage", + "test:debug": "node --inspect-brk -r tsconfig-paths/register -r ts-node/register node_modules/.bin/jest --runInBand", + "test:e2e": "jest --config ./test/jest-e2e.json" +} +``` + + +### Front-end +#### Standard execution for [CRA (Create React App)](https://create-react-app.dev/) + +Any of these commands can be invoked by writing `npm`, then following with the script/task name Ex. `npm start`. + +```JSON +"scripts": { + "start": "react-scripts start", # Runs the project locally (typically executed for development) + "build": "react-scripts build", # Builds the project into a lightweight deployable format + "test": "react-scripts test", # Tests the app using integrated Jest test runner (not configured for most projects in the lab) +}, +``` + +#### Standard execution for [Vite](https://vite.dev/) + +Any of these commands can be invoked by writing `npm run`, then following with the script/task name Ex. `npm run dev`. + +```JSON +"scripts": { + "dev": "vite", + "build": "vite build", + "lint": "eslint . --ext js,jsx --report-unused-disable-directives --max-warnings 0", + "preview": "vite preview" +} +``` diff --git a/docs/software_development/Web_Development/back-end/tools/postman.md b/docs/software_development/Web_Development/back-end/tools/postman.md new file mode 100644 index 00000000..9b043ab8 --- /dev/null +++ b/docs/software_development/Web_Development/back-end/tools/postman.md @@ -0,0 +1,13 @@ +# Postman + +Postman is a free downloadable tool primarily used for testing API's or web sockets. Within Postman you can save collections of API routes and/or socket connections dedicated to a project and specific project functionality. + +![postman-collections-image](../../images/postman-collections.png){: style="height:100%;width:100%"} + +Where Postman is most useful: + +1. Constructing an API from the ground up. This is because you can quickly swap arugments, adjust headers, and retrigger the route frequently. +2. Testing queries of an external API. This is because errors are formatted which makes it easier to digest (errors are common when querying a new API), +3. Having the ability to share your created collections with new project members, new developers, or even external collaborators. +4. Being able to easily pick up where you left off years/months after working with an API. + diff --git a/docs/software_development/Web_Development/front-end/dom.md b/docs/software_development/Web_Development/front-end/dom.md new file mode 100644 index 00000000..bec7ebb6 --- /dev/null +++ b/docs/software_development/Web_Development/front-end/dom.md @@ -0,0 +1,60 @@ +# DOM + +!!! note + This isn't necessary information for software development in lab but it provides better rounded knowledge of web development. + +The DOM is the data representation of the objects that comprise the structure and contents of a document on the web. + +### What is a web document? + +A web document is simply a file you access through a web browser. This is typically written at it's core in HTML (HyperText Markup Language). It defines the structure and content of a web page. + +### What is the DOM + +In short, the DOM is a programming interface for all web documents. It represents the page so that programs can change the document structure, style, and content. The DOM is built using multiple APIs that work together. + +In most cases the DOM serves as a programmatic representation of an HTML document. It's how browsers internally structure your page in memory so that code such as JavaScript can interact with it. JavaScript will interact with the DOM to change things in memory to adjust the web document. + +### Why can't JavaScript directly interact with HTML instead of the DOM? + +JavaScript can't directly interact with raw HTML text because once a browser has loaded a page, that HTML text is no longer "alive". Once a browser page has loaded it has been parsed into a structured model (the DOM) that JavaScript can work with in memory to change the rendered page. + +To clarify this further, HTML lives on the server hosting a web page, whereas JavaScript lives in the browser, therefore allowing for constant manipulation of the web page by working with DOM in memory. + +If you make changes to an HTML document, you must reload the page to view the changes. If you manipulate the DOM, you can see those changes real-time, due to it living in memory. + +### Do browsers create their own DOM? + +Yes, all browsers build their own DOM from HTML. However, each browser uses the same specifications given by [W3C](https://www.w3.org/TR/WD-DOM/introduction.html) / [WHATWG](https://dom.spec.whatwg.org/) to ensure the JavaScript used to manipulate the DOM will act consistently across all. + +### HTML --> DOM --> JavaScript interactions simplified + +#### HTML + +Defines the structure and content of a web page. It is made up of just plane text. **Often thought of as the recipe or blueprint.** + +###### *Example* +```HTML +

Hello

+

This is a paragraph

+``` + +#### DOM + +Turns the plain text into a tree of objects in memory. **Often thought of as the ingredients or materials** + +###### *Example* + + Document + └── html + └── body + ├── h1 + └── p + +#### JavaScript + +Manipulates the in memory tree of objects. **Often thought of as the chef/laborer who works with the ingredients/materials** + +###### *Example* + + `document.querySelector("h1").textContent = "Goodbye";` \ No newline at end of file diff --git a/docs/software_development/Web_Development/front-end/index.md b/docs/software_development/Web_Development/front-end/index.md new file mode 100644 index 00000000..5f4d9a3f --- /dev/null +++ b/docs/software_development/Web_Development/front-end/index.md @@ -0,0 +1,2 @@ +# Front-end +This section covers some core concepts, libararies, and frameworks related to front-end web application development pertaining to the lab. \ No newline at end of file diff --git a/docs/software_development/Web_Development/front-end/libraries_and_frameworks/React/react.md b/docs/software_development/Web_Development/front-end/libraries_and_frameworks/React/react.md new file mode 100644 index 00000000..ade41ed6 --- /dev/null +++ b/docs/software_development/Web_Development/front-end/libraries_and_frameworks/React/react.md @@ -0,0 +1,45 @@ +# React + +React is a JavaScript library for building UIs. It follows a component-based architecture that allows for easy manipulation of the web browsers [virtual DOM](../../dom.md) for dynamic and interactive applications. + +React is the most crucial library used in the lab for front-end development. This library remains consistent across all web applications and will continue to be the case, versions do vary though. + +For the most part React applications are built as single-page applications, meaning a singular HTML page exists as a base that has it's contents translated to the DOM, which can be constantly manipulated using a mixture of JavaScript/React. + +For syntax sake, i like to think of React as a combination between JavaScript and HTML into a singular application workflow. React removes many complexities needed for JavaScript manipulation of the DOM and uses HTML(ish) syntax. + +### Ex: Pressing a button in JavaScript +In JavaScript you must add a listener to fetch the element in DOM. Then manipulate the DOM yourself. +```JS + + +``` + +### Ex: Pressing a button in React +In React you don't need to add listeners or even intentionally interact with the DOM. By simply talking React language, it'll work with the DOM for you. + +```JSX +function CounterButton() { + const [count, setCount] = useState(0); + return ( + + ); +} +``` + +**Note:** In the example above useState stores the current value of ***count*** and a function (***setCount***) to update it. Whenever the update function (***setCount***) is called, an automatic re-render is triggered so the UI can reflect the change. This completely removes the heavy lifting of needing to get the element by Id, add a click event listener, then manually update the text content when the count value changes. + +### Key Characteristics +- Reusability: Components/elements are designed to be used multiple times across multiple parts of an application. +- Modularity: Each component encapsulates it's own logic and styling. Making the code easier to manage, test, and debug. +- Encapsulation: Components tend to manage their own state and behavior, which avoids unintended behaviors in other parts of the app. + diff --git a/docs/software_development/Web_Development/front-end/libraries_and_frameworks/React/react_hooks.md b/docs/software_development/Web_Development/front-end/libraries_and_frameworks/React/react_hooks.md new file mode 100644 index 00000000..14142624 --- /dev/null +++ b/docs/software_development/Web_Development/front-end/libraries_and_frameworks/React/react_hooks.md @@ -0,0 +1,52 @@ +# React Hooks +React hooks are special functions that let you "hook into" React features. This includes things like state, lifecycle, and context, without writing classes. They were introduced in React 16.8 (2019) + +Before hooks came along, React components were either +- Class components (with this.state, componentDidMount, etc) +- Stateless functional components (no lifecycle or state) + +Hooks let you write everything as a simple function component, while still giving you: +- State (useState) +- Lifecycle effects (useEffect) +- Context (useContext) +- References (useRef) + +### useState +Stores local, reactive state in a function component. Calling the setter triggers a re-render. +Ex. + +```JSX +function CounterButton() { + const [count, setCount] = useState(0); + return ( + + ); +} +``` + +Same code functionality pre Hooks: +```JS +class CounterButton extends React.Component { + constructor(props) { + super(props); + this.state = { count: 0 }; + this.increment = this.increment.bind(this); + } + + increment() { + this.setState(prev => ({ count: prev.count + 1 })); + } + + render() { + return ( + + ); + } +} +``` + +TO BE CONTINUED... \ No newline at end of file diff --git a/docs/software_development/Web_Development/front-end/libraries_and_frameworks/index.md b/docs/software_development/Web_Development/front-end/libraries_and_frameworks/index.md new file mode 100644 index 00000000..129a90e8 --- /dev/null +++ b/docs/software_development/Web_Development/front-end/libraries_and_frameworks/index.md @@ -0,0 +1,2 @@ +# Libraries and Frameworks +This section focuses on libraries and frameworks used in the front-end development within the lab. It will mainly cover React and styling libraries used. \ No newline at end of file diff --git a/docs/software_development/Web_Development/front-end/libraries_and_frameworks/styling_libraries_and_frameworks/index.md b/docs/software_development/Web_Development/front-end/libraries_and_frameworks/styling_libraries_and_frameworks/index.md new file mode 100644 index 00000000..4aa16f12 --- /dev/null +++ b/docs/software_development/Web_Development/front-end/libraries_and_frameworks/styling_libraries_and_frameworks/index.md @@ -0,0 +1,3 @@ +# Styling Libraries and Frameworks + +A variety of styling libraries/frameworks have been used in the lab throughout the years. These include a mix of both [component libraries](https://prismic.io/blog/react-component-libraries#what-are-react-ui-component-libraries) and [utility-first frameworks](https://heydonworks.com/article/what-is-utility-first-css/) \ No newline at end of file diff --git a/docs/software_development/Web_Development/front-end/libraries_and_frameworks/styling_libraries_and_frameworks/primereact.md b/docs/software_development/Web_Development/front-end/libraries_and_frameworks/styling_libraries_and_frameworks/primereact.md new file mode 100644 index 00000000..9332b86d --- /dev/null +++ b/docs/software_development/Web_Development/front-end/libraries_and_frameworks/styling_libraries_and_frameworks/primereact.md @@ -0,0 +1,7 @@ +# PrimeReact + +[PrimeReact](https://primereact.org/) is a component library. Unlike TailwindCSS that deals with only styling components, PrimeReact provides premade components right out of the box. It is used in several projects and versions vary quite significantly. All of the new lab projects use version 10.9.7. + +PrimeReact really comes in handy for components that would take many hours to manually build to perfect functionality. This includes the [virtual scrollers](https://primereact.org/virtualscroller/), [accordions (dropdowns)](https://primereact.org/accordion/), [Toasts (popups)](https://primereact.org/toast/), [Dialog popups (modals)](https://primereact.org/dialog/), [tooltips](https://primereact.org/tooltip/), [calendars](https://primereact.org/calendar/), and [text editors](https://primereact.org/editor/). + +It is very good to use PrimeReact components where the engineering feat would be high but something out of the box would provide a good base component to work with. However, I would be weary on getting carried away with using PrimeReact premade components for everything. PrimeReact components can sometimes be very tricky to edit to your styling needs, so creating raw components using [TailwindCSS](./tailwindcss.md) is usually better if the component is not too much of a feat (since you will have much more styling control with TailwindCSS). \ No newline at end of file diff --git a/docs/software_development/Web_Development/front-end/libraries_and_frameworks/styling_libraries_and_frameworks/styled.md b/docs/software_development/Web_Development/front-end/libraries_and_frameworks/styling_libraries_and_frameworks/styled.md new file mode 100644 index 00000000..5e91dfd6 --- /dev/null +++ b/docs/software_development/Web_Development/front-end/libraries_and_frameworks/styling_libraries_and_frameworks/styled.md @@ -0,0 +1,27 @@ +# Styled-components + +[Styled-components](https://styled-components.com/) is another JavaScript library utilized for styling web applications components. It's frequently used in many of the legacy applications such as PharmacoDB, SynergxDB, ToxicoDB, KulGaP, XevaDB, PredictIO, cclid, ORCESTRA, and the lab website. So, for maintaing sake, it is good to have a good grasp on how styled-components works and how it differs from defining raw CSS or utilizing traditional utility-first styling (like [TailwindCSS](./tailwindcss.md)). + +When using styled-components, you don't directly create a classes, instead you create a new instance of a component, with the option of adding embedded classes afterwards. + +In the example below as you can see we define a new div component called "Wrapper" with it's own unique stylings. Within the "Wrapper" div component we also define a local classname called "title" which only exists in the scope of the component it is defined within. This does help significantly to keep styling local and not have too many spill over issues that occur when editing styling classes and having many cascading effects in the rest of your application where they are used. + +```JavaScript +const Wrapper = styled.div` + padding: 4em; + background-color: white; + .title { + font-size: 1.5em; + text-align: center; + color: #BF4F74; + } +`; + +return ( + +

+ Hello World! +

+ +); +``` \ No newline at end of file diff --git a/docs/software_development/Web_Development/front-end/libraries_and_frameworks/styling_libraries_and_frameworks/tailwindcss.md b/docs/software_development/Web_Development/front-end/libraries_and_frameworks/styling_libraries_and_frameworks/tailwindcss.md new file mode 100644 index 00000000..5fe1615d --- /dev/null +++ b/docs/software_development/Web_Development/front-end/libraries_and_frameworks/styling_libraries_and_frameworks/tailwindcss.md @@ -0,0 +1,99 @@ +# TailwindCSS + +[TailwindCSS](https://v3.tailwindcss.com/docs/installation) is a utility-first framework for styling components in React. In every new web application project within the lab Tailwind is installated and utilized for core styling. + +Due to our developer team being quite small in the lab, utilizing Tailwind is crucial when developing web applications in a timely manner because it removes several steps when styling components, hence saving a signficant amount of time. Traditionally, when styling a React component you must assign it a class, create a CSS file, create a new class in the CSS file that corresponds to the class given to your component, then write in your stylings. When Tailwind is installed and configured it has a large collection of preset classes (utility classes) that can be written inline on a component classname that will apply certain stylings to it. This means that you **NEVER** need to create extra CSS files and rarely define your own classes. + +Above the time saving aspect, Tailwind also ensures consistent styling (due to predefined utilities), easy to setup inline response designs utilizing media queries (this is not possible inline without Tailwind), and hover/focus, along with other state variants. + +In lab projects we primarily use v3.4.17 but v4 has been recently released, so newer applications can bump to take advantage of their new simplified setup, "high performance engine", larger colour palette, and new 3D transformations. + +## Tailwind Example + +If you want to add a `flex` display orientation to a div element, you would simply write it inline like such: + +```JavaScript +
+ . + . + . +
+``` + +This would apply the following classes manually without creating a css file for it + +```CSS +.flex { + display: flex; +} +.flex-row { + flex-direction: row; +} +``` + +## Robust Tailwind Comparison + +![tailwind-component](../../../images/tailwind-component.png) + +If you want to create the above component with raw CSS, you would need to define the following. + +```JavaScript +
+
+ +
+
+

ChitChat

+

You have a new message!

+
+
+ + +``` + +If you utilize Tailwind you can simply write the following: + +```JavaScript +
+
+ ChitChat Logo +
+
+
ChitChat
+

You have a new message!

+
+
+``` + +As you can see, once you are comfortable utilizing Tailwind styling, it will become significantly faster to develop core components of an application. \ No newline at end of file diff --git a/docs/software_development/Web_Development/images/postman-collections.png b/docs/software_development/Web_Development/images/postman-collections.png new file mode 100644 index 00000000..c6d76b85 Binary files /dev/null and b/docs/software_development/Web_Development/images/postman-collections.png differ diff --git a/docs/software_development/Web_Development/images/tailwind-component.png b/docs/software_development/Web_Development/images/tailwind-component.png new file mode 100644 index 00000000..b2b8f648 Binary files /dev/null and b/docs/software_development/Web_Development/images/tailwind-component.png differ diff --git a/docs/software_development/Web_Development/index.md b/docs/software_development/Web_Development/index.md new file mode 100644 index 00000000..5ce60102 --- /dev/null +++ b/docs/software_development/Web_Development/index.md @@ -0,0 +1,3 @@ +# Web Development + +This section of the handbook will focus on the core web development concepts, libraries, frameworks, and tools used in the lab. It is broken up into two main sections **back-end** and **front-end**. Back-end will discuss primarily API development, heavily focusing on frameworks, libraries, and tools used across the lab. Front-end cover UI development in the lab, also primarily focusing on frameworks, libraries, and tools needed and used. \ No newline at end of file