Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
334 lines (232 sloc) 9.74 KB

Papertrain

Papertrain

Papertrain is a framework designed to bring custom utilities and features to Craft CMS. Papertrain is built upon a Modular Design Pattern. Checkout this example to see how the modules work.

  1. Getting Started
  2. Creating Elements
  3. CSS Namespaces
  4. Deploying to Production
  5. Feedback
  6. License

Getting Started

When getting started you have two possible options. If you are starting a new project follow the New Project guide. If you're working with a project that has already been established follow the Existing Project guide.

Starting a New Project

1: Start by downloading the latest release 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)

npm install

3: Install Craft CMS by running the following command in your terminal: (requires composer)

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:

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:

git init

Followed by creating your first commit:

git commit -m "Initial commit"

Don't forget to set your remote:

git remote add origin <URL>

Then push your commit and master branch:

git push -u origin master

Joining an Existing Project

1: Start by cloning the project

git clone <URL>

2: Install the NPM dependencies by running the following command in your terminal: (requires Node.js)

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:

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:

npm run create

Globals

A Global is a unique style for a Basic 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

.g-button{
    border: 2px solid aqua;
    border-radius: 2px;
    padding: 0 16px;
    height: 36px;
    line-height: 36px;

    &.-solid{
        background-color: aqua;
    }
}

Incorrect Usage

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.

{% 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 naming methodology.

Namespace Format

The CSS namespace format will be as follows:

.p-primary-class-name_secondary_class_name -modifier -secondary-modifier
  1. Classes always begin with a prefix followed by a hyphen
  2. The primary class name will always be written in kebab-case
  3. The secondary class name will begin with an underscore and will always be written in snake_case
  4. 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.

<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>
.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 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

sudo apt-get install webp

2: Install Nodejs

sudo apt-get install nodejs

3: Install or Update NVM

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.34.0/install.sh | bash

4: Install version 10.13.0 of node

nvm install 10.13.0

5: Setup post-deployment commands

<path to npm-cli.js> ci
<path to npm-cli.js> run production

Feedback

Feel free to open an issue and report any bugs or request additional features.

License

Papertrain is licensed under the MIT license.

You can’t perform that action at this time.