# Introduction

Pitcherify is a component library and a customization package for Vuetify (opens new window). The package includes many custom components created for Pitcher applications and written with the help of Vuetify components. In the background, Vuetify customizations are kept in multiple SCSS files, and overrides Vuetify framework values/styles on the fly with the help of pitcherify-cli-plugin. This means, Pitcherify changes default look and feel of Vuetify even if you use default Vuetify components. To see how Vuetify components looks like with Pitcherify customizations, take a look at Vuetify Components page. These customizations are based on Pitcher design requirements.

# Dependencies

@pitcher/pitcherify package simply depends 4 other packages:

  "@pitcher/core": "^0.1.1",
  "@pitcher/vue-cli-plugin-pitcherify": "~0.1.2", (needed for Vuetify customizations)
  "@vue/composition-api": ">= 1.0.0-rc.1",
  "sass": "^1.32.11",
  "sass-loader": "^10.1.1",
  "vue": ">= 2.6.12",
  "vuetify": ">= 2.4.2",

WARNING

If you are installing pitcherify through Vue CLI, you don't need to install dependencies manually.

# Installation with Vue CLI

To install Pitcherify through Vue CLI:

run this in the command line, in your project root:

vue add @pitcher/pitcherify

Select pitcherify & core packages in the menu with space bar
The CLI will ask you the following questions:
- @vue/composition-api is not installed in your project. Do you want to add it? - Yes
- Vuetify is not installed in your project. Do you want to add it? - Yes
And thats it! You should now have Pitcherify installed in your project. Keep in mind that the generator will change some of your files and create example files app.example.vue to lead you for initializing your project properly.

Migration

If you are migrating from a Fomantic based project, the CLI might ask if it should migrate. In this case, you can select Yes to migrate, but keep in mind that you will need to replace:

@pitcher/vue-sdk imports with @pitcher/core imports
i18n related imports from @pitcher/vue-sdk to @pitcher/i18n imports

WARNING

This command will make changes to your project template files, components folder, vue.config.js, etc. If you are installing Pitcherify via Vue CLI, make sure you commit your code to avoid any potential data loss.

# Usage with CDN

IMPORTANT NOTE

If you already have a project with build process (webpack/vue-cli based project), this approach is NOT RECOMMENDED. CDN usage is helpful when you have a legacy project without a build process, e.g. building parts of a PHP application that works without webpack/vue-cli, or simply need to use it in plain HTML/JS application.

To use Pitcherify without installing it through the Vue CLI, copy the code below into your index.html file. This will pull the latest version of Vue, Vuetify and Pitcherify, allowing you to start playing with components. While not recommended, if you need to utilize the CDN packages in a production environment, it is recommended that you scope the versions of your assets.

Note: Even if you use Pitcherify through CDN, you still need to use Vue and Vuetify also. This because of Pitcherify is based on Vue and Vuetify and in the background they are used.

Example HTML (Required lines are highlighted)

<!DOCTYPE html>
<html>
  <head>
    <link href="https://fonts.googleapis.com/css?family=Roboto:100,300,400,500,700,900" rel="stylesheet" />
    <link href="https://ui.pitcher.com/libs/fontawesome-pro/5.12.1/css/fontawesome.min.css" rel="stylesheet" />
    <link href="https://ui.pitcher.com/libs/fontawesome-pro/5.12.1/css/solid.min.css" rel="stylesheet" />
    <link href="https://ui.pitcher.com/libs/fontawesome-pro/5.12.1/css/regular.min.css" rel="stylesheet" />
    <link href="https://ui.pitcher.com/libs/fontawesome-pro/5.12.1/css/light.min.css" rel="stylesheet" />
    <!-- Enable if needed -->
    <!-- <link href="https://ui.pitcher.com/libs/fontawesome-pro/5.12.1/css/brands.min.css" rel="stylesheet"> -->
    <!-- <link href="https://ui.pitcher.com/libs/fontawesome-pro/5.12.1/css/duotone.min.css" rel="stylesheet"> -->
    <link href="https://ui.pitcher.com/libs/pitcherify/pitcherify.min.css" rel="stylesheet" />
    <meta
      name="viewport"
      content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no, minimal-ui"
    />
  </head>
  <body>
    <div id="app">
      <v-app>
        <v-main>
          <v-card class="ma-8">
            <v-card-title>{{ state.cardTitle }}</v-card-title>
            <v-card-text>{{ state.cardText }}</v-card-text>
          </v-card>
        </v-main>
      </v-app>
    </div>

    <script src="https://cdn.jsdelivr.net/npm/vue@2.x/dist/vue.js"></script>
    <script src="https://cdn.jsdelivr.net/npm/@vue/composition-api@1.0.0-rc.10"></script>
    <script src="https://cdn.jsdelivr.net/npm/vuetify@2.x/dist/vuetify.js"></script>
    <script src="https://ui.pitcher.com/libs/pitcherify/pitcherify.min.js"></script>
    <script>
      const vuetifyInstance = new Vuetify({
        theme: {
          options: {
            customProperties: false,
          },
          themes: {
            light: {
              primary: '#c00',
            },
          },
        },
      })
      // Required
      Vue.prototype.$vuetify = vuetifyInstance

      new Vue({
        el: '#app',
        vuetify: vuetifyInstance,
        setup() {
          const state = VueCompositionAPI.reactive({
            cardTitle: 'Hello World',
            cardText: 'Welcome to Pitcherify CDN',
          })

          return { state }
        },
      })
    </script>
  </body>
</html>

# Using different versions

If you need to use a specific version of Pitcherify, you can check out the example below to use the version you need.

Example

<link href="https://ui.pitcher.com/libs/pitcherify/pitcherify@0.2.2.min.css" rel="stylesheet" />
<script src="https://ui.pitcher.com/libs/pitcherify/pitcherify@0.2.2.min.js"></script>

# My Vue application is not in the root folder

If your application is not in the root folder for any reason e.g. your application is actually in a subfolder of a php project, you will probably have problems with transpiling your Vue project. This issue is related to @pitcher/vue-cli-plugin-pitcherify plugin as pitcherify-cli-plugin is working integrated with vue-cli-service to load your style files under project_root/src/styles. In this case you would need to define the styles folder path and this you can do through vue.config.js file. Let's assume your project is inside a subfolder of a PHP project as below:

├── controllers/
├── docker/
├── views/
├── ...
├── my-vue-app/
│   ├── assets/
│   ├── components/
│   ├── router/
│   ├── store/
│   ├── views/
│   ├── styles/
│   ├── App.vue
│   └── main.js
├── package.json
├── vue.config.js

In this case, you can simply configure vue.config.js as below to get it work.

// vue.config.js
module.exports = {
  ...
  ...,
  pluginOptions: {
    pitcherify: {
      stylesPath: 'my-vue-app/styles'
    }
  },
}

Pitcherify Components (all) →