Developing with ENgrid
Developing with ENgrid
Setting up a local environment
Prerequisites:
- Your ENgrid template code. You can find this on your Github repository.
- If you’re starting a fresh project, use this template repo to get started.
- Node.js (latest LTS) https://nodejs.org/en/download/
- An IDE or text editor, such as VSCode, with support for Prettier for code formatting.
- If you’re using VSCode you can support Prettier with this extension
- A method of locally serving your ENgrid assets from https://your-repo-name.test
- There are many ways to do this but one of the simplest is to use a tool such as Laravel Valet or Herd.
One you have that set up, and you have your ENgrid project code, you can get started:
- Install your dependencies
npm install
- Activate automatic compiling of your assets on save
npm install
- Build your assets for production
npm run build
Upgrading the core ENgrid Scripts Package
Your ENgrid theme gets the vast majority of its functionality from the engrid package, which is used by your theme code.
That code is hosted on Github here and in 2 NPM packages here and here.
To bring in new features, you can run this command to upgrade the engrid-script package to the latest version and rebuild your assets:
npm run rebuild
If you need to use a specific engrid version you can run:
npm uninstall @4site/engrid-styles @4site/engrid-scripts
npm install @4site/engrid-styles@your-version-number
npm install @4site/engrid-scripts@your-version-number
You can always view your current ENgrid version in the banner at the start of your compiled JS and CSS assets.
Making changes to the SCSS or JS files
For SCSS you’ll find the majority of your code in the /src/sass/page-template-styles.scss
file.
The majority of styles can be customized via CSS custom properties.
You should know!
These properties are named with the convention: {component__name}-{property_name}_{modifier}
For JS your theme will contain a /src/scripts/main.js
file. Here you can add any extra JavaScript customizations you might need. /src/index.ts
is the entry point for loading the ENgrid application. You can modify the Options here to customize the ENgrid components loaded and their functionality.
Refer to the engrid source for more information.
Previewing your changes
When working localling your can add ?assets=local
to your URL and ENgrid will load your local assets from https://your-repo-name.test
.
To preview remote changes on a Github repository, first create a Git branch with your changes on it and push that to Github.
Then, you can use the assets URL parameter ?assets=your-branch-name
to load in those assets from Github without needing to deploy them elsewhere.
Building and deploying production files
Once you’re happy with everything, you can compile the final assets with
npm run build
Then, upload the engrid.min.css and engrid.min.js
files from your /dist
folder to Engaging Networks, overwriting the existing assets.
You should know!
Before doing this you should thoroughly test your changes using a Github branch, especially if you’re upgrading engrid versions.
It may take some time for Engaging Network to refresh its cached assets. Until then, you can preview the changes by using the ?assets=flush URL parameter
, which will apply cache-busting to the assets.
Advanced Development Techniques with ENgrid for Engaging Networks
?assets=local
- Loads the uncompressed ENgrid CSS and JS from
https://engrid-wwf.test/dist/engrid.[file-extension]
?assets=[branch-name]
- Loads the uncompressed ENgrid CSS and JS from the Client Repo's feature branch
https://github.com/4site-interactive-studios/engrid-[client-name]/[branch-name]
?engridcss=false
- Unloads the ENgrid CSS and applies some base styles to make the ENgrid sections appear in a column?engridjs=false
- Unloads the ENgrid JS
Engaging Networks Buildout
Page Template Reference
Variables Reference
Advanced "Row"
1. page-alert
2. content-header
3. body-headerOutside
4. body-header
5. body-title
6. body-banner
7. body-bannerOverlay
8. body-top
9. body-main
10. body-bottom
11. body-footer
12. body-footerOutside
13. body-footerSpacer
14. content-preFooter
15. content-footer
16. page-backgroundImage
17. page-backgroundImageOverlay
18. page-customCode
Global Variables
EngridAmounts
With that variable you can set dynamic amounts at the page level.
Example:
window.EngridAmounts = {
"onetime": {
amounts: {
"10": 10,
"30": 30,
"50": 50,
"100": 100,
"Other": "other",
},
default: 30,
},
"monthly": {
amounts: {
"5": 5,
"15": 15,
"25": 25,
"30": 30,
"Other": "other",
},
default: 15,
},
};
When you're using the window.EngridAmounts
option, the user-selected amount will persist when changing frequencies if:
- We're coming from a backend error.
- We have an amount defined via URL.
- The user selected a non-default amount.
Known Limitations
- This option does not work with NSG or other similar native EN features
- You need to remove any Swap List from the donation amount field. If you don't there will be race conditions between the swap list and our code which will create unpredictable and inconsistent behaviors.