Open Budget Grand Rapids
Open Budget Grand Rapids intends to promote a deeper understanding of the City of Grand Rapids Budget. We believe that this project will allow citizens, officials, and other stakeholders to engage in more informed dialogue about how the City of Grand Rapids currently works and how it should in the future.
Use the following documentation to help you get started developing with this project.
These next items listed are necessary to develop this project on your local machine.
This project uses Yarn package manager to install dependencies.
You can install Yarn on mac using the command below or by going to the Yarn website.
brew install yarn
This site is built with the Harp static site generator.
To install Harp globally, make sure you have
yarn package manager installed, and then use the following commands
yarn global add harp
Harp was partially created to be a development tool for static sites, and includes minimal setup to start developing on the site locally
/src directory is the working folder of this project, and contains all necessary code that is compiled in the static site.
To start developing, make sure you have all prerequisites installed, and run the the following commands
# Go to the '_src' folder of the OpenBudget GR project cd [repo-location]/_src # Install required project dependencies yarn install # Run harp development server harp server
The Harp server should tell you where to point your browser. Once you do that you should see the Open Budget Grand Rapids project that you can activey develop on.
Do not be afraid of updating the documentation if there is anyting that should be changed. Also please add to this documentation when a new feature is implemented.
Creating & Editing Pages
- Page content is inserted into the
layout.jadefile (which includes basic header and footer snippets)
- Create your
- Add a link to the main nav in the appropriate place
- Add relevant metadata in
_data.json(page title, page slug (url), ...)
- If your page uses custom page-specific css, add it to a new
.scsspartial and import it into the main stylesheet. (Make sure to namespace it the same way the others are.)
Instructions for "Flow" Diagram Pages
- Flow pages are built off a template; copy one of the
*-budget-flow.jadepages and update the content blocks as necessary.
- Data files must be placed in the
data/flowdirectory. Follow the naming convention seen there or your files won't load properly. Note: Two underscores required in data file name, ex: FY17__final.csv. You also will need to point your page at the appropriate files as seen in the
- The following columns are required in your datafile and their names should be normalized as seen here. Other columns should be removed to minimize the data download.
- account_type (this should be the Expense/Revenue column, if there are duplicate names)
Instructions for "Treemap" Diagram Pages
- Treemap pages are built off a template; copy one of the
*-budget-tree.jadepages and update the content blocks as necessary.
- Instructions for generating the necessary data files can be found here. Add them to the
data/tree/directory following the naming convention seen in the existing files.
- Json files should follow this naming convention, Status (Final, Preliminary, Proposed, etc).Acount Type (Revenue or Expense).Budget Year.json. Examples:
- Update the
datafilescontent block with the appropriate metadata and file path for the data files you generated.
Instructions for "Compare" page
- The Compare page is mainly powered by a React application. The source files are in
_src/js/compare/and are are bundled with Webpack.
- When developing on the Compare page, run
yarnto install all the necessary node dependencies and
yarn run watchto watch the source files for changes and rebuild the asset bundles accordingly.
- The Compare page communicates with a separately maintained API to fetch its data. Documentation for that API can be found in our wiki.
Creating/Updating Budget Timeline
The timeline is made using TimelineJS, an open-source tool that enables anyone to build visually rich, interactive timelines. Beginners can create a timeline using nothing more than a Google spreadsheet, like the one we used for the Timeline above. Experts can use their JSON skills to create custom installations, while keeping TimelineJS's core functionality.
Make changes on your personal fork or branch. If you have repo access, and your changes are ready for review, you can merge them into the development branch and publish to the staging site for review. You can also publish changes to your own server and merge to development afterwards.
Before making your first contribution to this project, please read the Contribution Guide
City of Grand Rapids, MI Data Portal
- Data collection
- Data visualization
- Civic Engagement