BE WARNED THIS IS NOT PRODUCTION READY, UNLESS YOU HAVE PLANS TO HELP ITS NOT WORTH DOWNLOADING, IT'S VERY MUCH A LIVING DOCUMENT!
A generator for the Alchmy ecosystem that makes it easy to add components from the ecosystem onto a webpage. Making it trivial to create beautiful webpages. Moreover, Alchmy is designed to be decentralized, so that the individual components can be downloaded separately, which, at scale, means that much of the data from many websites will already be cached. Reusable, fast, easy-to-use, easy-to-maintain.
alchmy-cli is a cli tool for quickly adding and creating webcomponents from different libraries. For adding prebuilt components quickly, it uses the related github polymer_web_components. That library contains the official Polymer elements as well as some other custom components and some elements based on typical implementations from some popular styling frameworks or component libraries listed below.
The cli is usable without reference to these libraries to help you create the boiler code for new custom elements and convert markdown to clean HTML5 code. The cli tool is a useful way to install components quickly, rapidly speeding development, but it is also designed to be used with IPFS peers. Thus, if a significant number of people use this project, your website resources should load faster as each element could be downloaded from peers within your neigbourhood.
- Polymer Elements - Official Polymer components of Google.
- simplajs - Clean, prebuilt components for user live editing. Helpful for forms, Social media, CMSs.
- Material Design Components - Official Google Components based on Material Design. Though called components, without Angular or Polymer it's more a styling framework or a framework for building components. See more.
- Semantic-ui - Clean, modern, easier to use than MDC as there is less to include in the modules.
- Materialize - Easy to use Material Design based css framework.
- MUI - Lightweight framework based on Googles Material Design.
- Material Bootstrap - Perhaps implemented later.
- Bootstrap - Perhaps implemented later.
- Foundation - Perhaps implemented later.
- Building the App
curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.8/install.sh | bash source ~/.bashrc nvm install node nvm use node mkdir myproject cd myproject
npm init -y npm install pine-cli --save npm install pine-cli --global wget --output-document=index.html https://ipfs.io/ipfs/QmWckGtnq3dnFWuJUqqwPQ7HWH28SA31RWN7VZREGStgFR mkdir -p src/components
There are two main commands to be used to build a website. You can stick with one method, or you can do a little of each.
Building Method 1 - Adding prebuilt elements using
pine-cli add prebuilt-component-name
Building Method 2 - building your own components using
pine-cli new my-custom-component-name
These two methods can be combined on the same project. If you want a simple introduction, choose Building Method 1
pine-cli add materialize-navbar pine-cli add mui-grid-fluid-1-2 pine-cli add materialize-footer
<materialize-footer> above will probably be exactly what you expect. The first word of the tag name is the css styling framework that is used, and the following words are a description of the tags content. The
<mui-grid-fluid-1-2> is a grid for placing other elements inside. The
1-2 at the end represents the basic layout of the site. Which means the right section is twice the width of the left section.
Once each component has been added, a reference to the component will be inserted into your
index.html file. At this point, you should be able to use the webcomponents within your
index.html just like you would use any other html tag. For example, you could use the elements you added above like this:
<body> <header> <materialize-navbar></materialize-navbar> </header> <main> <mui-grid-fluid-1-2></mui-grid-fluid-1-2> </main> <footer> <materialize-footer></materialize-footer> </footer> </body>
pine-cli new my-custom-navbar -s materialize pine-cli new my-custom-grid pine-cli new my-custom-table -h html_template_url pine-cli new materialize-footer -b polymer_component_url
This code shows you how to create your own polymer web components. These components will be placed into a
components folder. Note the options that can be used with this tag.
-s you can add the name of one of the supported frameworks listed in the introduction and it will include links to the libraries in your polymer component. Note, this may use a lot of unnecessary code, as it includes the libraries separately for each element. This might be a problem, but your browser also might solve this automatically with cacheing. Also note, styles do leak out of Web Components in Firefox, but they don't in Chrome. It is better at this stage to stick with using one styling framework. I hope to include tools in this
pine-cli later that will make it easier to treeshake. Until then, stick with one styling framework or deal with the consequences.
-b tag allows you to choose a base component to use, which will use the path/url given but it will give the component the name you specify. This is useful for modifying existing prebuilt components. The downside is that these will not exist on IPFS peer hosting and you will have to link to these components locally or add the component to IPFS and host the component from there(you will be your own peer).
The following options can be used to specify a download source when youWhen the
--local tags are implemented with the , they will specify where the component should be hosted.
This hasn't been started, but will be implemented eventually. It will have a bunch of examples, and users can submit their prebuilt templates.The github repo and documentation will be the first instance of this.
You can serve the web components of this app through any method you like, the built-in methods are local, ipfs, and github, but with an option of serving from arbitrary links. Any custom components need to be served by something that you set up. You can set up local hosting, your own link, or an IPFS server(this is the recommended method, and the inspiration of this project). Since your html file is edited by you, it will need to set up by you.
Any non-modified components can be downloaded from IPFS(I am hosting the components, in time, I hope others will join me hosting these components in IPFS, so it will be fast for all of us :) ), or you could download them yourself and make your
index.html references to your components local.
- Serving Method 1 - (Recommended when developed) IPFS
- Serving Method 2 - Github
- Serving Method 3 - CDN
- Serving Method 4 - (Recommended) Local
Serving Method 1 - (Use local until this is completed, local is default) IPFS
pine-cli add materialize-navbar --ipfs
pine-cli new my-custom-tabs --ipfs
To start your own IPFS server, see the video linked under this paragraph. More information will be written about this soon. This is the recommended method. It is experimental, but the hope is that the components should be loaded quickly if a lot of people use them. And components are incredibly reusable as they are so modular and self-contained, and the styles are not supposed to leak outside of the component itself(The Shadow DOM), although they do leak in Firefox 52.6!
pine-cli add materialize-navbar --github
pine-cli new my-custom-tabs --github
See my Github https://github.com/musicsmithnz/polymer_web_components for the location of the development Github of the polymer web components. This will be updated frequently, but if you are downloading the versions from IPFS, it wont update, as any new files saved to IPFS gets saved based on its files hash. This means that if two files have the same content, but a different name, they are still the same file to IPFS. Files saved to IPFS are referenced according to their content.
pine-cli add materialize-navbar --vendor
pine-cli new my-custom-tabs --vendor
Use this if you want to use a custom styling Library that isn't supported. But to my knowledge, there is no easy way to use a CDN to deliver components to the user. Generally Polymer expects you to have the Library installed.
pine-cli add materialize-navbar --local
pine-cli new my-custom-tabs --local
Presently only this method is working. The imports need to be changed in the other models to be hostable from a remote source.
The Following standards will be perused, but not necessarliy followed completely, we will specify in each case the extent to which it is followed
I am seeking to apply this style guide to all of the code. It has not been implemented yet.
[Web Components and Style]
We have some unique ideas about styling that we have not yet been implemented or even crystalized in our own minds. In a word, it's about applying mathematics and the science of perception to Material Design, and the concept of an n-dimensional visual space. We will seek to study and understand the following style guides, and if possible, we will be a superset of these standards, applying these rules and more.
- U.S. Web Design System
- We are still looking for good resources to include to apply the Mathematics :-)
[Style](my custom url for my new standard based on MD). We are working on a new Standard which extends Googles Material Design that adds more algorithmic exactness to color and distance css generation based on the science of perception, as well as an n-dimensional concept of webpages. 3 for Space, 1 for Time, and an extra n-4 dimensions for data that changes upon clicks or other interactive activity. Generic elements like div should be used as much as possible only for styling. More specific and semantic elements should be used as much as possible. Custom elements are encouraged to use these HTML tags, custom html elements should be named semantically.
a templating engine like jade or perhaps even yaml, will give you the opportunity to quickly write website with custom elements. Pug should work very well, and it could use the mixin syntax to add custom elements, this way we can get custom elements by prepending + to a custom element-name. Otherwise, they could just be treated as a replacement for the mixin syntax, this might be preferable, as it would probably make it more portable. One suggested naming convention for your components is to have the designer name, framework, or organization as the first word, and the top-level Tag of your custom component as the second word. For example, materialize might decide to make a custom component like so:
If this element is then styled with the materialize framework, the most appropriate name according to this standard would me
Generic elements like
<div> should be used as little as possible and primarily for styling.