Skip to content

Commit

Permalink
Merge branch 'main' into a11y/add-icon-img-alt
Browse files Browse the repository at this point in the history
  • Loading branch information
@TimidRobot
TimidRobot committed Apr 12, 2024
2 parents e8d2cf2 + c37acc1 commit 22b3a91
Show file tree
Hide file tree
Showing 29 changed files with 9,944 additions and 5,705 deletions.
6 changes: 3 additions & 3 deletions .gitignore
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
/tests/e2e/reports/
/chromedriver.log
.idea/
dist/
chromedriver.log
coverage/
dist/
node_modules/
tests/e2e/reports/
yarn.lock
13 changes: 0 additions & 13 deletions CODE_OF_CONDUCT.md
View file

This file was deleted.

34 changes: 0 additions & 34 deletions CONTRIBUTING.md
View file

This file was deleted.

186 changes: 145 additions & 41 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,47 +8,149 @@
![GitHub Repo stars](https://img.shields.io/github/stars/creativecommons/chooser?style=social)
![GitHub forks](https://img.shields.io/github/forks/creativecommons/chooser?style=social)


# Chooser

The Creative Commons License Chooser is meant to help people learn about CC licenses, and select the license that best fits their needs. The new version in this repo places greater importance on usability, and an educational experience of the six CC licenses.


## About

Repository containing the source code for the new Creative Commons License Chooser. The new chooser is still in beta, and a beta deployment can be found [here](https://chooser-beta.creativecommons.org/).

This site is built using [Vue.js](https://vuejs.org/) (and vue-cli).


### Roadmap

Tasks, issues, and discussion related to the release of the new chooser are tracked with the [`Launch Milestone`](https://github.com/creativecommons/chooser/milestone/1).

## Getting Started

### Prerequisite
[nodeJS](https://nodejs.org/en/blog/release/v14.17.3) version 14 or below, as the version above 14 may give error.
## Code of conduct

### Commands
Run the following commands in order to have the code up and running on your machine:
[`CODE_OF_CONDUCT.md`][org-coc]:
> The Creative Commons team is committed to fostering a welcoming community.
> This project and all other Creative Commons open source projects are governed
> by our [Code of Conduct][code_of_conduct]. Please report unacceptable
> behavior to [[email protected]](mailto:[email protected])
> per our [reporting guidelines][reporting_guide].
``` bash
# install dependencies
npm install
```
[org-coc]: https://github.com/creativecommons/.github/blob/main/CODE_OF_CONDUCT.md
[code_of_conduct]: https://opensource.creativecommons.org/community/code-of-conduct/
[reporting_guide]: https://opensource.creativecommons.org/community/code-of-conduct/enforcement/


## Contributing

See [`CONTRIBUTING.md`][org-contrib].

[org-contrib]: https://github.com/creativecommons/.github/blob/main/CONTRIBUTING.md


## Using Docker


### Containers

The [`docker-compose.yml`](docker-compose.yml) file defines the following
containers:
1. **chooser-web** - simple NGINX container serving [`docs/`](docs)
- [localhost:8888](http://localhost:8888/)
2. **chooser-node** - Node14 container
- [localhost:8080](http://localhost:8080/)
- (requires **Run Node development server**, below)


### Docker desktop required

Before proceeding, ensure you have Docker installed on your local machine. If
not, download and install Docker Desktop by visiting [Docker's official
website](https://www.docker.com/products/docker-desktop) and follow the
installation instructions.


### Run Node development server

1. Perform a clean install of NPM packages from `package-lock.json`
```shell
docker compose exec chooser-node npm ci
```
- (this initial step can be skipped if previously completed)
2. Run Node development server
```shell
docker compose exec chooser-node npm run serve
```
- [localhost:8080](http://localhost:8080/)

```bash
# Build and serve assets with hot-reload
npm run serve

### Create production (standalone) build

1. Perform a clean install of NPM packages from `package-lock.json`
```shell
docker compose exec chooser-node npm ci
```
- (this initial step can be skipped if previously completed)
2. Run Node development server
```shell
docker compose exec chooser-node npm run build
```
- (this automatically copies the generated files from [`dist/`](dist) to
[`docs/`](docs))

The chooser is deployed to GitHub Pages. The source files for the beta
deployment are contained in the `./docs/` dir, and are live. Any changes to
this directory's contents will be automatically deployed, so please take care
when making modifications to this location.
### Create standalone (production) build
1. Perform a clean install of NPM packages from `package-lock.json`
```shell
docker compose exec chooser-node npm ci
```
- (this initial step can be skipped if previously completed)
2. Run Node development server
```shell
docker compose exec chooser-node npm run build
```
- (this automatically copies the generated files from [`dist/`](dist) to
[`docs/`](docs))
The chooser is deployed to GitHub Pages. The source files for the beta
deployment are contained in the `./docs/` dir, and are live. Any changes to
this directory's contents will be automatically deployed, so please take care
when making modifications to this location.

For an embedded standalone build (no header nor footer), run:
```shell
docker compose exec chooser-node VUE_APP_CC_OUTPUT=embedded npm run build
```
**(please _don't_ commit embedded builds to `docs/`)**
You should now have the application running and accessible at <http://localhost:8080> (note: will run on a different port if 8080 is occupied, most common alternative port is 8081).
## Building as web component
### Create a web component build
To build the project as a web component, run the command `npm run build-component`. This will create a file in the `dist` folder named `license-chooser.min.js`. It can be used to load the web-component in any JS project. There is also a sample `demo.html` created.
1. Perform a clean install of NPM packages from `package-lock.json`
```shell
docker compose exec chooser-node npm ci
```
- (this initial step can be skipped if previously completed)
2. Run Node development server
```shell
docker compose exec chooser-node npm run build-component
```
To be able to use the file it should either be rendered statically from the integrater's web-app or be published on a CDN. Following code can be used to integrate this in other apps.
This will create a file in the [`dist/`](dist) folder named
`license-chooser.min.js`. It can be used to load the web-component in any JS
project. There is also a sample `demo.html` created.
Note: the Chooser component depends on Vue 2.x, as can be seen in the following example.
To be able to use the file it should either be rendered statically from the
integrater's web-app or be published on a CDN. Following code can be used to
integrate this in other apps.

Note: the Chooser component depends on Vue 2.x, as can be seen in the following
example.

```
<script src="https://cdn.jsdelivr.net/npm/[email protected]"></script>
Expand All @@ -57,44 +159,46 @@ Note: the Chooser component depends on Vue 2.x, as can be seen in the following
<license-chooser></license-chooser>
```

If the web component is intended to be built without header and footer, run `VUE_APP_CC_OUTPUT=embedded npm run build-component`

## Contributing

For information on contributing, please see [Creative Commons' Contribution Guidelines](https://opensource.creativecommons.org/contributing-code/)

If you create a PR for your work, but you are not finished yet, please include `WIP:` in the beginning of your PR title. When your work on your PR is completed, and you are ready for a final review, please remove the `WIP:` prefix from the title to indicate that your work is done.

Here's a [handy link](https://github.com/creativecommons/chooser/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22help+wanted%22+-label%3A%22in+progress%22) that will show you all open issues in this repo that have the `help wanted` tag, but do not have the `in progress` tag.
All issues in this list are up for grabs!
If it says "No results matched your search", then there are no issues currently up for grabs.
For an embedded web component build (no header nor footer), run:
```shell
docker compose exec chooser-node VUE_APP_CC_OUTPUT=embedded npm run build-component
```

*If no progress has been made on an issue for seven days after assignment, the assignment will be removed to allow others to contribute.*

## Running Tests

You can run tests by executing:

```bash
npm run test
```shell
docker compose exec chooser-node npm run test
```
For running tests on a web-component build, run `npm run test-component`. It starts a server with the `dist/demo.html` on which tests can be run.

For running tests on a web-component build, run:
```shell
docker compose exec chooser-node npm run test-component
```

## CSS Build
It starts a server with the `dist/demo.html` on which tests can be run.

The Chooser uses PostCSS plugin for PurgeCSS to make CSS bundle size smaller. It automatically removes unused CSS based on the classes found in the final built bundle. Some styles for dynamic components or dynamically-imported files can also be removed. If you find that the built site misses some styles, you can manually add the necessary classes or Regex expressions to the `safelist` array in the `postcss.config.js` file.

## Deployment
## CSS Build

The chooser is deployed to GitHub Pages. The source files for the beta deployment are contained in the `./docs/` dir, and are live. Any changes to this directory's contents will be automatically deployed, so please take care when making modifications to this location.
The Chooser uses PostCSS plugin for PurgeCSS to make CSS bundle size smaller.
It automatically removes unused CSS based on the classes found in the final
built bundle. Some styles for dynamic components or dynamically-imported files
can also be removed. If you find that the built site misses some styles, you
can manually add the necessary classes or Regex expressions to the `safelist`
array in the `postcss.config.js` file.

To update the dist bundle, run ```$ npm run build```. This will also automatically copy the generated files from `./dist/` to `./docs/`.

## Output Modes
## Embedded screenshot

The site can be built in two different modes: `embedded` and `standalone`. `Embedded` mode removes the header and footer from the application, resulting in the following appearance:
The site can be built in two different modes: `embedded` and `standalone`.
`Embedded` mode removes the header and footer from the application, resulting
in the following appearance:

<img src="static/embedded-screenshot.png" alt="Application built in embedded mode">

To build into embedded mode, set the environment variable `VUE_APP_CC_OUTPUT=embedded` on your server before building. If `VUE_APP_CC_OUTPUT` is unset or set to a different value, the app will build in the default `standalone` mode, with its own header and footer.
To build into _embedded_ mode, set the environment variable
`VUE_APP_CC_OUTPUT=embedded` on your server before building. If
`VUE_APP_CC_OUTPUT` is unset or set to a different value, the app will build in
the default _standalone_ mode, with its own header and footer.
28 changes: 28 additions & 0 deletions docker-compose.yml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
# Use docker compose v2 for non swarm deployments
# https://docs.docker.com/compose/compose-file/compose-file-v2/
version: '2.4'

services:

chooser-web:
# https://hub.docker.com/_/nginx/
image: 'nginx:latest'
ports:
- '8888:80'
restart: on-failure
volumes:
- './docs:/usr/share/nginx/html:ro'

chooser-node:
# continue running until shutdown (allows docker compose exec which is much
# faster than docker compose run) per https://serverfault.com/a/1084975
command: sh -c 'trap "exit" TERM; while true; do sleep 1; done'
image: 'node:14'
ports:
- '8080:8080'
restart: on-failure
stdin_open: true
tty: true
volumes:
- '.:/app'
working_dir: /app
Loading

0 comments on commit 22b3a91

Please sign in to comment.