The web-illinois Github organization is meant for developers to share code. The traditional way to share client-side (JS and CSS) code is to create and publish an NPM package. However, creating a package requires some skill on both the developer (to create the package) and the end user (to consume the package). You can also take your code on Github and host your code on a cPanel instance. However, this requires some additional work to create the cPanel instance and copy the code from Github to cPanel, and there's no guarantee that the code on Github is the same as on the cPanel instance.
This shared components repository is a low-effort way to put files in Github, and these files will be pushed to a Tech Services AWS S3 bucket. Unlike Illinois Toolkit and the formal WIGG groups, this is distributed and "bottom-up" -- a way to crowdsource and share solutions without having to combine the code into a single monolithic javascript and CSS file.
An end user can then consume your code by adding HTML tags like the following (using ils-input as an example):
<script src="//contrib.webtheme.illinois.edu/ils-input/input.min.js"></script>
<link rel="stylesheet" href="//contrib.webtheme.illinois.edu/ils-input/input.min.css" media="all">
Each folder in this repository is independent of each other. This may mean that using multiple components is "chatty" and requires multiple calls to the contrib.webtheme.illinois.edu URL, but that is the trade-off of using this method.
Despite this being called "shared components", this isn't limited to web components. Contents may include (but are not limited to)
- Formal web components
- Vanilla JavaScript files
- jQuery files
- CSS files
- Images and other resources
- JSON data files
- Everything is use as is. There are no code review process in terms of accessibility, security, cross-platform use, or usability.
- Authors are responsible for their own components inside this github repository.
- If an author is going to pull or drastically change a component, they need to contact everyone listed on the component's README.md file.
- Users are responsible for keeping current the list of components they are using (via the components' README.md files)
First check to see if someone else wants or has it! Go to the "Need Component" issue section and the "Have Component" issue section and scan if something there meets your needs. If nothing there works, then post an issue and give it the "Need Component" label.
Again, first check to see if someone else wants it or if someone else built it already. Go to the "Need Component" issue section and scan if something there meets your needs. If no one needs it, create an issue and give it the "Have Component" label.
You can either access the files directly on https://contrib.webtheme.illinois.edu, or copy the files and host them on your website. Contact the owner first so they can add you to the README.md of the component, or add your area to the component README.md file.
For example, the component does 95% of what you want it to do, or there's a bug that prevents you from using it. Contact the owner before making any changes.
The shared-components uses NPM and package.json to manage the build process. You are not required to any existing packages. If you need to add additional packages, feel free. Ensure that any packages that are added don't interfere with other components, and try to use existing packages when possible.
Any changes to the main branch gets pushed to the https://contrib.webtheme.illinois.edu site. Please make sure you create a branch, then merge to main. Do not make changes directly to the main branch.
If you need the continuous integration to build your code, modify the package.json to add a script and deploy_main.yml to include your npm script in the build process.
It's tempting, but do not contribute something just because it is cool. This is for collaboration, so make sure that another college or department needs the component you are committing. If you aren't sure, post an issue with the "Have Component" label and see if someone else requests it.
I recommend that shared components have a namespace of "ils-{xxxxxxxx}" for their web component, data tags, or CSS classes. All components, data tags, and CSS classes should use this namespace.
customElements.define('ils-contentslider', Slider);
<div class="ils-twitter"><div class="ils-twitter-block-flex"><div class="ils-twitter-item">...</div></div></div>
<div class="ils-contact-info" data-ils-contact-info-name="EducationHR">...</div>
customElements.define('il-contentslider', Slider);
<div class="ils-twitter"><div class="block-flex"><div class="item">...</div></div></div>
<div class="ils-contactinfo" data-name="EducationHR">...</div>
Shared components should have a README.md file at their root directory.
- The namespace of this component (ils-{xxxxxxxxxxx}).
- The author of this component.
- The state of the project. The available states are:
- Development on xx/yy/zzzz: Use at your own risk; things may change without warning.
- Production on xx/yy/zzzz: This is stable and can be used. The interface to this will not change drastically.
- Depreciated on xx/yy/zzzz: This is no longer supported. This may be because it has been transferred to a campus service, it is no longer used, or a newer version has been developed.
- Abandoned on xx/yy/zzzz: This never met production status and should not be used.
- Any dependencies this component needs (a specific version of the Illinois Toolkit, bootstrap, jQuery, etc.).
- Examples or information on how to use this. Include code snippets of what files need to be included.
- A userlist of other areas on campus that use this.
If you run into any problems, please post a message to the WIGG discussion on Teams