Skip to content
Permalink
Browse files

Updates readme to incldue links to new documentation

  • Loading branch information...
codewithkyle committed Aug 2, 2019
1 parent 65fad77 commit 807a048bd4cb66c3460adfdf848e428188c31959
Showing with 79 additions and 315 deletions.
  1. +2 −1 CHANGELOG.md
  2. +5 −312 README.md
  3. +70 −0 _papertrain/papertrain-craft-0.2.md
  4. +2 −2 package.json
@@ -4,7 +4,8 @@

- Adds: updated project setup section of the readme
- Adds: updated IE 11 polyfills to use `nomodule` attribute instead of wrapping the `document.write()` method in a render blocking script
- Adds: papertrain v0.1.x documentation
- Adds: papertrain v0.1 documentation
- Adds: papertrain v0.2 documentation

## 0.2.3 - 2010-07-25

317 README.md
@@ -1,9 +1,9 @@
<p align="center">
<a href="http://papertrain.io"><img alt="Papertrain" src="_papertrain/papertrain-logo.png"/></a><br/>
<img style="display:inline-block;" src="https://img.shields.io/badge/CMS-Craft%203.1-ff69b4.svg?style=flat-square"/>
<img style="display:inline-block;" src="https://img.shields.io/badge/CMS-Craft%203.2-ff69b4.svg?style=flat-square"/>
<img style="display:inline-block;" src="https://img.shields.io/badge/templating%20engine-Twig-orange.svg?style=flat-square"/>
<img style="display:inline-block;" src="https://img.shields.io/badge/style-SASS-blue.svg?style=flat-square"/>
<img style="display:inline-block;" src="https://img.shields.io/badge/typescript-3.4-yellow.svg?style=flat-square"/>
<img style="display:inline-block;" src="https://img.shields.io/badge/typescript-3.5-yellow.svg?style=flat-square"/>
<img style="display:inline-block;" src="https://img.shields.io/badge/bundler-webpack-5299c8.svg?style=flat-square"/>
<a style="display:inline-block;" href="https://github.com/AndrewK9/papertrain/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-lightgray.svg?style=flat-square"/></a>
</p>
@@ -12,317 +12,10 @@
Papertrain is a framework designed to bring custom utilities and features to Craft CMS. Papertrain is built upon a [Modular Design Pattern](https://github.com/Pageworks/modular-design-pattern). Checkout this [example](https://github.com/codewithkyle/modular-design-pattern-javascript-example) to see how the modules work.
1. [Getting Started](#getting-started)
- [New Project](#starting-a-new-project)
- [Existing Project](#joining-an-existing-project)
1. [Creating Elements](#creating-elements)
- [Globals](#globals)
- [Objects](#objects)
- [Components](#components)
- [Templates](#templates)
- [Loading Styles and Scripts](#loading-styles-and-scripts)
1. [CSS Namespaces](#css-namespaces)
- [Namespace Format](#namespace-format)
- [Prefixes](#prefixes)
- [Example](#example)
1. [Deploying to Production](#deploying-to-production)
1. [Feedback](#feedback)
1. [License](#license)
# Getting Started
When getting started you have two possible options. If you are starting a new project follow the [New Project](#starting-a-new-project) guide. If you're working with a project that has already been established follow the [Existing Project](#joining-an-existing-project) guide.
## Starting a New Project
1: Start by downloading the [latest release](https://github.com/Pageworks/papertrain/releases) of Papertrain and extracting the files into your projects root directory.
2: Install the NPM dependencies by running the following command in your terminal: (requires [Node.js](https://nodejs.org/en/))
```script
npm install
```
3: Install Craft CMS by running the following command in your terminal: (requires [composer](https://getcomposer.org/download/))
```script
composer install
```
4: Set your Apache server to point to the projects `/public` directory.
5: Create a new empty database for the project.
6: Run the setup script by running the following command in your terminal:
```script
npm run dev && npm run setup
```
To finish follow the Craft CMS installation in the browser. If the browser doesn't automatically open navigate to the `/webmaster` route.
### Additional Steps
After Craft is installed you may need to navigate to the Utility -> Updates section and update Craft or any of the plugins.
If you're using a Git repository run the following command in your terminal:
```script
git init
```
Followed by creating your first commit:
```script
git commit -m "Initial commit"
```
Don't forget to set your remote:
```script
git remote add origin <URL>
```
Then push your commit and master branch:
```script
git push -u origin master
```
## Joining an Existing Project
1: Start by cloning the project
```script
git clone <URL>
```
2: Install the NPM dependencies by running the following command in your terminal: (requires [Node.js](https://nodejs.org/en/))
```script
npm ci
```
3: Set your Apache server to point to the projects `/public` directory.
4: Create a new empty database for the project.
5: Run the setup script by running the following command in your terminal:
```script
npm run dev && npm run setup
```
To finish follow the Craft CMS installation in the browser. If the browser doesn't automatically open navigate to the `/webmaster` route.
# Creating Elements
New elements can easily be created by using the CLI based element generator. To run the generation tool enter the following command into your terminal:
```script
npm run create
```
## Globals
A Global is a unique style for a [Basic HTML Element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element). Globals will **NEVER** apply the style to the raw HTML element and they **DO NOT** inherently have any functionality but can be assigned functionality by a Component.
Globals are defined as a single Style file.
File: `Button.scss`
**Correct Usage**
```scss
.g-button{
border: 2px solid aqua;
border-radius: 2px;
padding: 0 16px;
height: 36px;
line-height: 36px;
&.-solid{
background-color: aqua;
}
}
```
**Incorrect Usage**
```scss
button{
border: 2px solid aqua;
border-radius: 2px;
padding: 0 16px;
height: 36px;
line-height: 36px;
}
```
## Objects
Objects can exists anywhere within the page as visual elements. Objects **DO NOT** inherently have any functionality but can be assigned functionality by a Component.
Objects can be composed of Globals and other Objects.
Objects are defined as a combination of the following files:
- HTML
- Style
## Components
A Component is similar to an Object except that is has a uniquely defined piece of functionality.
Components can be composed of Objects and Globals.
Components are defined as a combination of following files:
- HTML
- Style
- Script
## Templates
Templates are single template pages within Craft. They usually have a unique style, custom fields, or unique layout compared to the standard pages.
Templates can be composed of Globals, Objects, and Components.
Templates are defined as a combination of the following files:
- HTML
- Style (optional)
- Script (optional)
## Loading Styles and Scripts
To load custom scripts and styles use the `getAssetPaths` method avilable via the Papertrain module. Pass in the kebab-case filenames of any module, css, or package that you need. Then use Crafts `view.registerCssFile` or `view.registerJsFile` to have the files automagically included for you.
```twig
{% set assetPaths = craft.papertrain.getAssetPaths(['asset-file-name', 'npm-package-name']) %}
{% do view.registerCssFile(assetPaths['asset-file-name'].css) %}
{% do view.registerJsFile(assetPaths['asset-file-name'].module) %}
{% do view.registerJsFile(assetPaths['npm-package-name'].package) %}
```
# CSS Namespaces
Papertrain follows a simplified version of the [BEM](https://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/) naming methodology.
## Namespace Format
The CSS namespace format will be as follows:
```script
.p-primary-class-name_secondary_class_name -modifier -secondary-modifier
```
1. Classes always begin with a prefix followed by a hyphen
1. The primary class name will always be written in [kebab-case](http://wiki.c2.com/?KebabCase)
1. The secondary class name will begin with an underscore and will always be written in [snake_case](https://en.wikipedia.org/wiki/Snake_case)
1. Modifiers will always be additional/optional classes that begin with a hyphen and are written in kebab-case
## Prefixes
Classes will use a prefix to declare what type of element is being used.
- `g-` will be used for globals
- `o-` will be used for objects
- `c-` will be used for components
- `t-` will be used for templates
- `u-` will be used for utility classes
- `js-` will be used as a selector hook for JavaScript query selectors
- `is-` when something is in a specific state such as `is-open`
- `has-` when something has something such as `has-focus`
## Example
Some elements may contain other elements, in the example below the card will contain a heading, image, and link.
```html
<div class="o-card">
<img src="img.jpg" alt="Lorem ipsum">
<h3>Lorem Ipsum Dolor</h3>
<a href="#" class="o-card_button">Button 1</a>
<a href="#" class="o-card_button -alt">Button 2</a>
</div>
```
```scss
.o-card{
width: 256px;
height: 512px;
border-radius: 8px;
background-color: #ffffff;
box-shadow: 0 2px 4px rgba(41,41,41,0.1);
padding: 16px;
img{
object-fit: cover;
width: 100%;
height: 158px;
}
h3{
font-size: 24px;
color: cyan;
}
.o-card_button{
height: 36px;
line-height: 36px;
font-size: 18px;
text-transform: uppercase;
padding: 0 16px;
border-radius: 2px;
background-color: cyan;
color: #ffffff;
&.-alt{
color: rgb(41,41,41);
background-color: transparent;
border: 2px solid cyan;
}
}
}
```
# Deploying to Production
Papertrain uses server-side compiling via [Nodejs](https://nodejs.org/en/) for the CSS and JavaScript modules/packages. Follow these steps to setup the server-side compiling. If you don't want server side compiling update the `.gitignore` file by removing the `/public/assets` line. This guide will assume you're server is running Ubuntu Server.
1: Install cwebp
```script
sudo apt-get install webp
```
2: Install Nodejs
```script
sudo apt-get install nodejs
```
3: Install or Update [NVM](https://github.com/nvm-sh/nvm)
```script
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.34.0/install.sh | bash
```
4: Install version 10.13.0 of node
```script
nvm install 10.13.0
```
5: Setup post-deployment commands
```script
<path to npm-cli.js> ci
<path to npm-cli.js> run production
```
[Papertrain v0.1 Documentation](https://github.com/Pageworks/papertrain/blob/develop/_papertrain/papertrain-craft-0.1.x.md)
[Papertrain v0.2 Documentation](https://github.com/Pageworks/papertrain/blob/develop/_papertrain/papertrain-craft-0.2.md)
If you are unsure about what version of Papertrain you are using please check the `package.json` file located in the root project directory.
# Feedback

0 comments on commit 807a048

Please sign in to comment.
You can’t perform that action at this time.