This document provides an overview of the technologies used in FarmData2, describes the roles that they play, and provides some resources for learning the essentials of each.
Interacting with FarmData2 requires a basic familiarity with git and GitHub. FarmData2 development uses a fairly standard web technology stack including HTML, CSS, Bootstrap, JavaScript, and Vue.js. The front-end uses Axios to accesses FarmData2 data in a MariaDB database through the FarmOS API and a custom Express API. End-to-end testing is done using the Cypress framework. The automation, configuration, and back-end development of FarmData2 use a number of other technologies including Drupal, drush, FarmOS, Docker, docker-compose, and bash scripting.
This document is intended to be used in two ways. When you are new to FarmData2, it is recommended that you work through this document from the top down. However, it is not essential that you fully master every tool and technology on the first pass. Rather, once you feel basically comfortable with a tool or technology (or if you already know it), skip to the next one. Then later, while working on FarmData2 you can return to this document and jump directly to the relevant section(s) to find a reference or to learn a little bit more as needed.
Before continuing, if you haven't already, please review the README, the CODE_OF_CONDUCT, the LICENSE and the CONTRIBUTING documents as they provide information that is important to getting started and to maintaining the FarmData2 community.
The INSTALL.md file contains the instructions for doing a Developer Install. After you complete the developer install, FarmData2 will be setup and ready for you to work on.
The FarmData2 community uses Zulip as its communication platform. Zulip is a group chat application that blends the benefits of asynchronous threaded discussions (e.g. a forum) with live chat.
Connecting with the FarmData2 community on Zulip provides a place to ask questions of the project managers and the broader developer community.
- Resources:
- Streams and Topics: An introduction to the two key features of Zulip. Once you understand streams and topics, Zulip is relatively easy to use.
- Zulip Home Page: This page has a quick tour of Zulip's features that you can click through.
- User Documentation: A comprehensive set of documentation on Zulip's use and features.
The FarmData2 documentation and resources assume a basic facility with git, GitHub and a familiarity with the GitFlow branching workflow. You'll need to understand the steps outlined in the CONTRIBUTNG document.
The following resources can be useful for learning what you'll need to know about git and GitHub:
- Resources:
- Hello World: A first introduction to GitHub that will get you started if you haven't used it before.
- GitFlow Intro: An introduction to an effective way of using GitHub (i.e. a workflow). The following two guides walk through how to work with existing open source projects and essentially follow GitFlow:
- Git Immersion: A tutorial walks through a series of short hands-on exercises that provide practice with the key features of git.
- Pro Git Book | Learn Git Tutorial: More detailed and comprehensive coverage of git's features and use.
FarmData2 has been used in a number of undergraduate computer science courses, and activities have been developed to guide students through an introduction to front-end development in FarmData2. If you are new to open source and FarmData2 or to any of the technologies that FarmData2 uses, working through these activities will be an efficient way to get up to speed. If you are a more experienced developer you might just pick and choose from these activities, or skip over them completely to the more general resources in the sections below. If you are an instructor for a course, these activities can provide a way to on-board your students to the project. Please get in touch on Zulip if you are an instructor interested in using FarmData2 in a course, and we will be happy to help.
The FarmData2 School Activities and associated information can be found in the README.md in the FarmData2 School Module.
The FarmData2 code and documentation can be edited with any editor. However, for convenience, the FarmData2 installation includes ...
TODO: Write this for VSCodium.
The majority of development for FarmData2 is front-end (i.e. browser-based). This section outlines the key technologies that are used for this development.
Hypertext Markup Language (HTML) is the base language that is used to create web pages. It defines the structure of a page and allows page elements (e.g. headings, paragraphs, lists, images, etc.) to be tagged and labeled with attributes. The way that an element is tagged and labeled allows the browser (with CSS) to determine how the content of the element should be displayed. Elements and attributes also allow JavaScript, Vue.js and Cypress to interact with the page style, structure and content.
- Resources:
- HTML Basics: A great place to start if you have not worked with HTML before or want a refresher.
- Your first form: An introduction to HTML forms, which FarmData2 uses to collect input from the user (e.g. plantings, harvests, search criteria, etc.)
- HTML Tables: An introduction to creating tables in HTML, which FarmData2 uses to display many of the different reports that can be generated.
- Introduction to HTML: A collection of guides and assessments that give a comprehensive introduction to HTML.
- HTML Reference: A comprehensive reference to all of the HTML elements and attributes.
Cascading Style Sheets (CSS) is a language for specifying how an HTML document should be presented (i.e. how it is displayed by the browser). CSS uses rules to apply styles to HTML elements. Each CSS rule selects HTML elements to which it applies, specifies the properties of the element that are to be styled (e.g. color, font-family, etc.) and gives a value that indicates how they are to be styled (e.g. blue, cursive). JavaScript can interact with CSS rules, properties, and values to dynamically change how (and if) HTML elements are displayed.
- Resources:
- What is CSS?: A (mostly) conceptual introduction to what CSS is and what it does.
- CSS Basics: A great place to start if you have not worked with CSS before or want a refresher.
- Learn to style HTML using CSS: A collection of modules that give a comprehensive introduction to CSS.
- CSS reference: A comprehensive reference to all of the CSS properties and values.
JavaScript is a programming language that can be used to add interactivity to HTML pages. JavaScript can add or remove HTML elements, change CSS styles and respond to events (e.g. button clicks, text entry). JavaScript is also used to produce dynamic content by exchanging information with web services through Application Programming Interfaces (APIs). For example, when a user of FarmData2 saves or retrieves information about plantings or harvests it is done by JavaScript code using an API (see FarmOS API).
- Resources:
- JavaScript Basics: A great place to start if you have not worked with JavaScript before or want a refresher.
- Strings: An introduction to the way that strings are created and used in JavaScript.
- Arrays: An introduction to the way that arrays are created and used in JavaScript.
- JavaScript object basics: An introduction to the way that objects are created and used in JavaScript.
- JavaScript - Dynamic client-side scripting: A collection of modules that give a comprehensive introduction to JavaScript.
- JavaScript Reference: A comprehensive reference to all of the JavaScript language features.
Vue.js is a JavaScript framework for simplifying the creation of interactive web applications. Creating highly interactive applications using HTML, CSS and JavaScript is possible, but some of the details become repetitive and tedious. Vue.js simplifies many of the common operations by allowing parts of the displayed page to be bound to a data object. In that way, when JavaScript code changes the data object, the view of that data displayed in the browser is automatically updated.
- Resources:
- Vue.js Fundamentals: A video-based course and a great place to start if you have not worked with Vue.js before or want a refresher. Click the "Start Course" button.
- Vue.js Guide: A textual introduction to using Vue.js.
- Vue.js Components: A video-based course that introduces the basics of Vue Components.
- Components Basics: A textual introduction to Vue Components.
- FarmData2 Vue Component Details: Information on specifically how FarmData2 uses and tests Vue Components.
The FarmData2 front-end exchanges data with the server using the FarmOS V1 API. JavaScript code using the Axios library requests data from FarmOS (e.g. a list of fields) or sends new data to FarmOS (e.g. a new planting). When data is received from FarmOS, the Vue.js object is updated, which in turn updates what is displayed in the browser. Conversely, when the user enters data in the browser, that data updates the Vue.js object and that information is used to make requests to the server.
- Resources:
- What is an API and how does it work?: A video introduction to APIs with a few examples. This is a good place to start if you are new to APIs.
- Using Axios to Consume APIs: A short example of a
GETrequest using Axios and Vue.js. - Axios: Full documentation for the Axios library. This shows how to do both
GETandPOSTrequests. - FarmOS V1 API: Documentation for Version 1 of the FarmOS API.
- Hoppscotch: A tool for experimenting with API calls. This can be useful in figuring out how to request what you want from the FarmData2 API and how its responses are formatted.
TODO: Write this and point to documentation.
Bootstrap is a framework and CSS component library used by farmOS, and thus by FarmData2, to provide stylized HTML components. Polished production FarmData2 modules will use Bootstrap components instead of basic HTML elements so that FarmData2 integrates visually into the farmOS interface.
- Resources:
- Introduction to Bootstrap: Comprehensive documentation for the Bootstrap framework.
The functionality of FarmData2 is tested using the Cypress framework. The tests in FarmData2 consist of end-to-end tests and component tests. The end-to-end tests run against the developer instance of FarmData2 and check the functionality of the pages. The component tests check the behavior of custom components that appear in FarmData2, in isolation from the running instance. FarmData2 provides support for running both types of Cypress tests in a Docker container that eliminates the need to install or configure Cypress. See the documentation in the farmdata2_modules/fd2_tabs/fd2_example/README.md file for information about running Cypress tests in FarmData2.
The Cypress end-to-end test framework works by controlling the web browser. A test typically consists of a series of steps that are automated by the Cypress tests, called specs. A typical spec consists of these steps:
- Setup the test (e.g. login, prime the database)
- Visit a specific page
- Query the page for an HTML element of interest (e.g. button, ext field)
- Interact with that element (e.g. click the button, enter some text)
- Make an assertion about the result (e.g. new information appears on the page)
- Resources
- Introduction to Cypress: As the docs say..."the single most important guide for understanding how to test with Cypress. Read it. Understand it."
- Writing Your First Test: A good overview of how a typical Cypress test works, what the code looks like, and how to use the Cypress test runner.
- Selecting Elements: Best practices for selecting elements that are manipulated and checked by your tests. Following these will make your tests less brittle.
- Selector Playground: A tool within the Cypress test runner that will help you find good selectors to use for the elements used in your tests.
- Interacting with Elements: The main commands in Cypress for interacting with elements in the page (e.g. click, select, etc.).
- should: Documentation for the
shouldstatement that is used to make assertions in Cypress tests. - Assertions: A reference for all of the assertions (e.g. assertions and chainers for should) that can be used in Cypress tests.
- FarmData2 Cypress Tests Details: Information on specifically how FarmData2 uses Cypress tests.
Cypress component tests work by mounting a Vue Component into a browser and allowing tests to interact with it in isolation from the application. A typical component test will
- Configure and mount the component into the test framework.
- Query the component for an HTML element of interest (e.g. button, ext field).
- Interact with that element (e.g. click the button, enter some text).
- Make an assertion about the result (e.g. the component emits an event or changes state).
- Resources:
- All of the Cypress resources above are also relevant here.
- Component Testing: An introduction to the component testing in Cypress. Note: With FarmData2 support, you will not need to install or setup the component testing framework.
- Vue Test Utils Guides: Cypress component testing is built on top of the Vue Test Utils. So all of their functionality is also available within a Cypress component test. The Getting Started, Common Tips, Testing Key, Mouse and other DOM Events and Testing Asynchronous Behavior sections are most relevant to FarmData2 testing.
- Vue Test Utils API: API documentation for all of the functionality of the Vue Test Utils.
- FarmData2 Cypress Tests Details: Information on specifically how FarmData2 uses Cypress tests.
The developer install of FarmData2 relies on docker containers running
- the core FarmData2 system including farmOS and Drupal.
- an instance of MariaDB for data storage by farmOS and Drupal.
- an instance of PHPmyAdmin to allow developers to interact directly with the MariaDB instance as necessary.
- an instance of the TheiaIDE.
- an instance of the Cypress testing environment.
All of the docker related configuration and source files are found in the docker directory.
FarmData2 uses docker-compose to build custom docker images for farmOS and the TheiaIDE containers and to start and network all of the containers.
See the docker-compose.yml file in the docker directory.
Bash scripts are provided in the docker directory to simplify the process of bringing up and taking down FarmData2.
FarmData2 is built as a set of customizations to farmOS. The majority of FarmData2's features are added as custom modules displayed in tabs within the farmOS interface. See the README.md in the fd2_example module for a description of how FarmData2 modules are added to farmOS.
TODO: Write this and add links.
TODO: Write this and add links.
farmOS runs on top of Drupal. From the FarmData2 perspective, this is largely transparent. As it is discovered that more information is necessary, it will be added here.
For a few particular tasks related to initialization and configuration, FarmData2 makes use of drush to interact with the Drupal instance on which farmOS is running. As it is discovered that more information is necessary, it will be added here.