generator-cacao-branchcms
Yeoman generator that scaffolds out a new BranchCMS(https://www.branchcms.com) website that uses the Cacao CSS framework(https://github.com/aptuitiv/cacao). Gulp(http://gulpjs.com/) is used for the build process.
Installation
If you don't have Yeoman already installed do that now.
We recommend npm and we assume you have pre-installed node.js. You can also use Yarn if you prefer.
npm install -g yo
If you have not yet installed generator-cacao-branchcms
do that now.
npm install -g generator-cacao-branchcms
Generate the project
Navigate in the command line to the folder that you want to set up the project in. You may want to go ahead and initialize git and add your repository.
git init
git remote add origin YOUR_GIT_ORIGIN_HERE
Or, you can use git clone
one directory up
git clone ssh://john@example.com/path/to/my-project.git
cd my-project
Then generate your new project:
yo cacao-branchcms
Follow the prompts and then the template files will be installed, packages will be installed with NPM or Yarn, and gulp build
will be run to initialize the project.
Set up your FTP settings and use the dist
folder as your base folder.
Setting up BranchCMS and files
Don't upload files via FTP yet. Certain things need to be set up in BranchCMS first.
Step 1
Disable the cache and CDN
- Go to Settings -> Cache and turn off the cache.
- Go to Settings -> CDN and make sure the CDN is turned off.
Step 2
Search
- Create a search form called "Search". Set it as the default form. It is used for the search and search result pages. Edit it's template and rename the key to "search".
- Create a search form called "Search Header". It's a search form to use in the header of a page. Edit it's template and rename the key to "search-header".
If you don't set those up first then the uploaded templates aren't always recognized correctly and aren't used.
Step 3
Update the theme configuration with the theme.json file. This will set up templates, site settings, content builder elements and content layouts.
- Upload the
dist\theme\custom\theme.json
file to the website. - Go to Design -> Themes -> View Themes
- Click on the
Update
button. - Because you just uploaded the
theme.json
file leave theUse Existing theme.json
value selected and click theNext
button. - Review the theme updates and click the
Next
button to finish.
Step 4
Upload the rest of the files in the dist
folder.
Step 5
Log into BranchCMS and go to the following sections to load the appropriate templates.
General Templates
- Design -> Themes (initializes the theme)
- Design -> Templates
- Design -> Snippets
- Design -> Navigation -> Templates
Forms
- Forms -> Templates
Search
- Site Manager -> Search -> Design -> Content Templates. Edit each template and set the correct type.
- Site Manager -> Search -> Design -> App Pages. Set up the "Search" and "Search Results" pages.
Don't forget to go to Site Manager -> Search -> Dashboard and enable search if the website will use it.
Step 6
Create a navigation menu called "Main". Choose the "main" template. Add at least a few items to it.
Step 7
Configure the rich text editor.
Go to Settings -> Rich Text Editor
Select the correct file for the "Import Stylesheets" section. It may be pre-filled in, but you should still click the Browse
button to select the theme\custom\css\main.css
file so that the correct S3 bucket path is set.
Step 8
Start Building!
Editing this Repository
Use npm link
to do local development with this repository so that you can test your changes before pushing to NPM.
Navigate to the folder for this repository on your computer. Run npm link
.
That will create a link between the repository folder and the global node_modules folder on your computer. You can now navigate to another folder outside this project and
run yo cacao-branchcms
and Yeoman will use the files from this project on your computer instead of package you may have installed globally from NPM.
You will want to avoid installing this package from NPM globally on your computer as it may create problems with the npm link
.
Editing package versions
If you need to update the packages in the package.json
file that is used in the templates then there are two places to update:
- Within
app/templates/_package.json
. Update it like you would with any otherpackage.json
file. - For
magnific-popup
andslick-carousel
update the versions inapp/config.js
.
Updating this repository on NPM
You should be working off of the develop
branch. If so, then start a new release branch with the version that you're updating to. The versioning should follow this pattern:
v1.7.0
Then update the package version number. Also see npm-version CLI documentation.
npm version <update_type>
<update_type>
could be one of patch
, minor
, major
, prepatch
, preminor
, premajor
, prerelease
.
Then finish the release branch. Don't tag the release branch because npm version
already did that. Push the develop
and main
branch to GitHub.
Then publish the package to NPM.
npm publish
License
MIT © Aptuitiv