Installation

BC Pie apps are installed as a bundle that appear together under "BC Pie" in the admin's side menu. The BC Pie bundle normally appears as the last item in the menu. Clicking on the item reveals its apps, which are currently Package Manager and App Builder

Installing BC Pie is easy. First, download the app. Then upload it to your site’s app folder (/_system/apps/).

Please Note:

  • BC Pie admin apps have only been tested on the latest versions of Chrome. It is not recommended to use the apps on other browsers at this time.

Package Manager

What's a Package?

A package is a group of one or more related files which offer additional functionality for your web site. Package Manager currently organizes packages into 6 catalogs:

  • Layouts
  • Tricks
  • Themes
  • Frameworks
  • Fonts
  • NPM

To get you started, BC Pie comes with several packages embedded in the app.

Settings

Package Manager is designed to alter files and folders on your site. That could obviously be dangerous to existing site content, so the Settings page gives you control over where certain assets are saved. The default settings are highly recommended for new sites, but for existing sites you may need to make adjustments to avoid potential conflicts.

Settings are divided by asset type. Within each type, you can specify the folder where files are saved to, and, where applicable, the filenames as well.

You will notice in Settings that file assets are divided into two categories: App-controlled and User-controlled.

App-controlled Files

These files are created and recreated by Package Manager whenever you perform a build. There are only a few of these files, and they are required, but Settings allows you to alter their folders and filenames to fit your needs. Do not modify these files outside of Package Manager!

User-controlled Files

These files are created by Package Manager during the build process only if they are missing from your filesystem. Package Manager will never overwrite the contents of these files, unless you explicitly tell it to do so. They are intended to be edited by you. From settings, you can change the names and locations of these files, as well as tell Package Manager to skip creating them altogether.

The only caveat with choosing not to create these files is that sometimes there are tags in them which are needed to make your build work on the frontend. One way or another, these tags need to be made available to your page templates. The following is a list of required tags:

Required Tag User File Description Requirement
{% include '/_System/Apps/bcpie-bcpie/public/globals.inc' -%} Page Templates Contains BC Pie global collections and variables. Must be the first item in each page template, before any html.
{{bcpie_head}} head.inc Contains BC Pie package assets which belong in the head element of the document. Should be the first item in the head element of the page.
{{bcpie_foot}} foot.inc Contains BC Pie package assets which belong in the foot of the document. Should be the first item in the foot of the page. The exception is if you have manually installed scripts which are required for some packages to run. In that situation, those scripts should precede this tag.

Installing Packages

Installing a package requires two steps: add to queue, and build.

Add to Queue

If this is your first time in the app, click on the Tricks catalog at the top, and follow along using the ActiveNav package.

The bottom of each package shows its current queue status. The initial status is “Not in Queue”. Click the plus icon to the right of the status to add that package to the build queue. If the package has dependencies which also need to be installed, an information dialog will popup letting you know about it. Clicking “Do It” will result in the current package and all its dependencies being added to the queue. You’ll notice that the package's status updates to "Added to Queue". The same will be true for each of its dependencies.

Build

The build queue can be found in the upper right corner of the app. The queue works a lot like a shopping cart on an ecommerce site. With a shopping cart, you add products you want to purchase, remove items you decided against purchasing, and finally checkout, completing your purchase.

While the queue also has that same basic cart functionality, it has some important differences as well. For example, in addition to packages that are queued for installation, it also shows items which are currently installed, queued to be uninstalled, and items which are marked as "Manually Installed". Also, the counter for the build queue doesn’t reflect how many items are in the queue. Rather, it shows the number of changes to the queue relative to the last build.

When you're ready to make changes to your site, you can press the “Build” button to have Package Manager install packages that were added to the queue, uninstall packages which were queued for removal, and reset the counter to zero. Package assets will be installed to your site in the locations specified in Settings.

Manually Installed Assets

When you install a package, all of its dependencies are included in the build. These dependencies could be common libraries, such as jQuery, that you already have on your site. It's bad practice to install multiple copies of the same library, especially when they are different versions. As such, you are presented with a choice in this scenario. You can choose to either remove your existing copy from your site and use the copy that Package Manager installs, or you can inform Package Manager that you have Manually Installed that asset. To do this, open the menu for that particular package and click the checkbox next to "Manually Installed". The package will thereafter show up in the build queue, but in italics, indicating that it will not be installed with the rest of the files.

App Builder

Coming February 2018!