OpenEcoLab-LasAlpujarras
/
farmOS
mirror of https://github.com/farmOS/farmOS.git
3
0
Fork 0
Code Wiki

Copy and update user guide from 1.x docs to 2.x.

This commit is contained in:
Michael Stenta 2021-12-27 10:20:47 -05:00
parent 2c55037ed2
commit ad9b4f81c7
11 changed files with 785 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

250
docs/guide/assets.md Normal file
View File

@ -0,0 +1,250 @@
# Managing Assets
All the important and valuable things on your farm are represented as "Assets"
in farmOS. Asset types include Land, Plants, Animals, Equipment, Structures,
etc. Assets can be accessed from "Records > Assets" in the toolbar.
Assets can be archived, so they do not show in farmOS unless you specifically
want to see them. For example, when you are done harvesting a "Plant" Asset,
you can mark it as "archived" to hide it in your Asset lists. Archived records
can be retrieved using the "Filters" options on Asset listing pages.
Assets can be designated as "locations", which will cause them to show up in
the "Locations" hierarchy (available from the toolbar). It also allows other
Assets to be moved to them. For example, a "Plant" or "Animal" Asset can be
moved to a "Land" Asset. The hierarchy of location Assets is determined by
their "parent" field relationships.
For more information on Asset location, refer to the
[location logic](/model/logic/location) section of the
[farmOS data model](/model) docs.
Assets can also be cloned by selecting one or more in a list and clicking the
"Clone asset" button that appears at the bottom. This will clone the Asset
record(s), but will not clone the Logs that are associated with them.
For more information on Asset records, refer the [Assets](/model/type/asset)
section of the [farmOS data model](/model) docs.
## Asset types
farmOS comes with a number of Asset types, summarized below. Additional types
can be added via modules.
### Land
Land Assets represent the fields, properties, beds, paddocks, etc that are
being managed. They can be mapped and arranged hierarchically to make
navigation easier, and they can be referenced by Logs to record events,
activities, inputs, observations, etc. If you perform soil tests, these
can be stored as "Lab test" Logs associated with land Assets for easy
access.
### Plants
farmOS can be used for very fine-grained crop planning and record keeping. It
can be used by large or small operations, nurseries, seed producers, breeders,
and home gardeners.
The Plant Asset type can be used to represent groups of plants (eg: a field of
corn, or a group of seedlings), or it can be used to represent individual plants
(eg: in the case of nurseries).
When you create a plant Asset, you will need to define what **crop/variety** it
is. Crops/varieties represent the various **types** of plants you grow. These
can be very general crop names (eg: "Broccoli") or very specific breeds or
varieties (eg: "Belstar F1 Organic Broccoli"). Your Crops/varieties taxonomy
can be managed/organized as a hierarchy in Administration > Structure >
Taxonomy.
Plants are the specific Asset you are growing, whereas crops/varieties are terms
used to categorize and define plant types. You may have multiple plant Assets of
the same crop/variety. Consider the following example:
> 1 pound of red lettuce seed was purchased and seeded 4 times over the course
> of 8 weeks (every two weeks).
In this example, there would be 4 plant Assets with a crop/variety of "Red
lettuce":
- 2017 Red lettuce planting 1
- 2017 Red lettuce planting 2
- 2017 Red lettuce planting 3
- 2017 Red lettuce planting 4
The way you name your Assets is up to you - this is just an example. Including
the year at the beginning and the planting number at the end is helpful when
you are trying to distinguish plant Assets from one another.
[Seeding](/guide/logs/#seedings) and [Transplanting](/guide/logs/#transplantings)
Logs can be created in reference to plants.
If you are direct seeding into the field, you may only use the seeding Log. If
you are purchasing starts from another grower, you may only use the
transplanting Log. If you are starting your plants in a greenhouse and then
planting them out in the field, you may use both a seeding and transplanting
Log.
Together, seeding and transplanting Logs allow you to keep track of where a
plant has moved throughout its life. For more general information on tracking
the location of Assets in farmOS, refer to the overview of
[movements and location](/guide/location).
### Animals
farmOS can be used to manage animal/livestock records.
When you create an animal Asset, you will need to define what **species/breed**
it is. Species/breeds represent the various **types** of animals you manage.
These can be very general names (eg: "Cattle") or more specific breeds (eg:
"Jersey cattle"). Your Species/breeds taxonomy can be managed/organized as a
hierarchy in Administration > Structure > Taxonomy.
Animal Assets can be used to represent either individual animals, or multiple
animals (as a head count inventory, adjustable via Logs). This is useful in
cases where animals don't need to be tracked individually, for instance with
flocks of birds or heads of cattle, where individual tracking/tagging is not
necessary for record keeping purposes.
For more information, see the guide to [inventory tracking](/guide/inventory)
in farmOS.
Animals can also be organized into groups using the "Group" Asset type. This is
useful if you always manage certain animals together, as a herd or flock, for
instance. It is also possible to assign animals to more than one group. This can
be used in different ways to help manage large numbers of animals in farmOS.
> Q: Should I use inventory or groups for my animals?
This comes down to whether or not you need to maintain separate records for
individual animals. If you do, then create a separate animal Asset for each
animal, and you can optionally organize them into group Assets after that. If
you don't need individual animal records, you can create a single animal Asset
and use the inventory features to track a head count over time with Logs. Or,
you could do both! Perhaps you have a herd (group Asset) with some individual
animals, and some larger groups of animals (head count). It's just a matter of
how granular you need to be with your record keeping.
Animals can be moved from place to place in farmOS using movement Logs. You
can also filter your animal list down to a set of animals, select them all, and
create a combined movement Log for all of them at once. Or, you can move the
group Asset that contains animals (eg: a herd), and all the animal locations
will be updated along with it. This is a great way to manage grazing records as
you move animals from paddock to paddock.
For more general information on tracking the location of Assets in farmOS,
refer to the overview of [movements and location](/guide/location).
[Medical](/guide/logs/#medical) and [Birth](/guide/logs/#births) Logs can be
created in reference to animals.
### Equipment
farmOS can be used to manage equipment Assets on the farm.
[Maintenence Logs](/guide/logs/#maintenance) can be recorded alongside
equipment.
When you are creating Logs in farmOS, you can also reference the equipment
Asset(s) that were used to perform the activity. In combination with the
"Assets" field on Logs, this allows you to distinguish which Assets
**received** the action, and which equipment Assets **performed** it. These
"equipment use" Logs will appear on the equipment Asset record in farmOS.
Suggested uses:
* Use activity Logs to record equipment use.
* Keep track of equipment location via movement Logs.
* Record oil changes, repairs, and inspections with maintenance Logs.
* Track fuel usage or machine hours with input or observation Logs.
### Structures
Structure Assets can be used to represent buildings, greenhouses, and other
permanent or movable structures on the farm.
Like equipment Assets, [maintenence Logs](/guide/logs/#maintenance) can be used
to record when upkeep/repairs are performed.
Greenhouses can be represented as structure Assets, with Logs used to record
activities and observations within them. This can be very powerful, especially
when combined with sensors, data streams, notifications, and custom modules
that communicate with actuators to automate fans, ventilation, and irrigation.
### Water
Water Assets can be used to represent fixed water features like lakes, ponds,
and streams, or they can be used to represent fixed or movable irrigation
systems. Equipment and Structure Assets can be used similarly, so it is up to
you to decide how you prefer to organize things.
### Material
Material Assets can be used to track inventory of various materials.
For more information, see the guide to [inventory tracking](/guide/inventory)
in farmOS.
### Seed
Seed Assets can be used to track seed inventory before it is used to create
Plant Assets (via seeding Logs). Seeds share the same **crop/variety**
taxonomy with plant Assets.
### Compost
farmOS can be used to manage all types of compost production activities. A
generic "Compost" Asset type is provided, which can be used with various Log
types to record activities, observations, inputs, harvests, etc. These compost
Assets can be used to represent a compost pile,
[windrows](https://en.wikipedia.org/wiki/Windrow_composting),
[vermicompost](https://en.wikipedia.org/wiki/Vermicompost),
[compost tea](https://soiltest.uconn.edu/factsheets/composttea.pdf),
or any other form of production.
### Sensors
In addition to manually-entered records, farmOS also provides a framework for
receiving data from automated environmental sensors. The Sensor Asset type can
be used to represent individual sensor devices, which can provide one or more
[Data streams](/model/type/data_stream).
A "Basic" data stream type is provided, which stores data in the local database.
Add-on modules can be written to integrate with other data storage systems, or
provide custom sensor integrations.
It is possible to assemble your own sensors with inexpensive components and
send their data to farmOS without any soldering or programming.
### Groups
Groups are a special type of Asset in farmOS, which are used for organizing
other Assets, so they can be managed together.
This provides a lot of flexibility in managing and organizing your Assets.
Logs can reference the group Asset, instead of all the individual members.
One example where this is useful is managing herds of animals. Each herd can
be represented as a group Asset, with animal members. A movement Log can be
used to move the whole group, instead of referencing animal Assets
individually.
You can also use groups to organize equipment, plants, or any other Asset type.
It's even possible to have groups within groups, to create a hierarchy of group
membership.
Group membership is assigned to Assets via Logs, in very much the same way that
[location](/guide/location) is. You can assign Assets to a group via the
"Group" and "Is group assignment" fields on Logs. These specify that any
Asset(s) referenced by the Log will become members of the group at the time of
the Log.
Therefore, Assets can also change their membership over time, moving from one
group to another. One example where this is useful is in managing cattle: you
may have a group of mothers with calves, a group of weaned calves, and other
groups of steers, heifers, etc. As a calf grows up, weans, and perhaps has
their own calf, they can be moved from group to group, and the full history of
their group membership is saved as Logs.
For more information, refer to the [group membership logic](/model/logic/group)
section of the [farmOS data model](/model) docs.

6
docs/guide/export.md Normal file
View File

@ -0,0 +1,6 @@
# Exporting data
All [Asset](/guide/assets), [Log](/guide/logs), and
[Quantity](/guide/quantities) lists in farmOS include an "Export CSV" link at
the bottom that will generate and download a CSV file. Any sorts or filters
that are applied to the list will be represented in the CSV output.

83
docs/guide/index.md Normal file
View File

@ -0,0 +1,83 @@
# farmOS User Guide
## Introduction
Welcome to the official farmOS user guide. These documents are intended for
people who will be using farmOS for record keeping and farm management.
If you are looking for information about hosting farmOS, or contributing to
the development, refer to the dedicated documentation on those topics:
- [Hosting farmOS](/hosting)
- [Contributing to farmOS](https://github.com/farmOS/farmOS/blob/2.x/CONTRIBUTING.md)
## Logging in
The first step to using farmOS is logging in. All records are private by
default, and can only be viewed by people with a username and password.
To log in, first you need to know the address of your farmOS site. If you are
hosting farmOS on [Farmier](https://farmier.com), this address will most likely
be something like `https://myfarm.farmos.net` (where `myfarm` is the name of
your farm). If your farmOS is hosted by someone else, they will be able to point
you to the correct URL.
Enter the URL into the web browser on your computer, phone, or tablet, and you
should see a login form. Enter your username and password, and click "Log in"
to begin using farmOS.
## Dashboard
The first thing you will see when you log in is the farmOS dashboard.
On top is the farm map, where you will see all active location Assets that you
have mapped. You can use this to navigate to your records within farmOS by
clicking on a location and then clicking on the available links within the
Asset details popup.
Below the map you will see "Upcoming tasks" and "Late tasks" on the left, which
summarize Logs that are still in "pending" status. From here you can quickly
select Logs and mark them as "complete", reschedule them, clone them, or delete
them.
To the right you will see a summary of various farm metrics, including total
Asset and Log counts. Additional metrics can be added via modules.
## Navigation
farmOS is designed to make your records approachable from multiple angles, so
it is easy to find records you made in the past, and add new ones in the
future.
The toolbar on the left provides quick access to various records and tools:
- **[Quick forms](/guide/quick)** - Lists "quick forms" available for easy data
entry of common records. This will only be visible if you have quick form
modules enabled.
- **[Locations](/guide/mapping)** - Manage the hierarchy of location Assets.
- **Plans** - Provide high-level management of Assets and Logs around a
particular purpose. This will only be visible if you have plan type modules
enabled.
- **Records** - Direct access to raw lists of records by type and sub-type.
- **[Assets](/guide/assets)** - These are the "management units" of farmOS.
They represent the things of value that you are managing.
- **[Logs](/guide/logs)** - These are the events that that place in
relation to Assets.
- **[Quantities](/guide/quantities)** - These represent granular
measurements of quantitative data points associated with Logs.
- **Reports** - Lists "reports" available for easy data analysis. This will
only be visible if you have report modules enabled.
- **[People](/guide/people)** - Users with access to the farmOS instance.
- **Administration** - Links to various administrative sections.
You can also use the map to navigate to records that relate to specific
locations. For example, if you want to view the record for a specific plant
Asset, you can navigate to the field in the map where the plant is located, and
you will be able to find all Assets in that field.
If you are looking for a specific Log, you can either find it via "Records >
Logs" in the toolbar, or you can find the Asset that the Log is associated with,
and the Log will appear there as well.
All your records can be connected and related in this way to make navigating
them easier.

21
docs/guide/inventory.md Normal file
View File

@ -0,0 +1,21 @@
# Inventory tracking
Every Asset in farmOS can have one or more inventory levels associated with it.
These are tracked via Quantities on Logs, allowing for inventory adjustments to
be tracked over time. Inventory levels can be incremented, decremented, or
reset by a Log.
To adjust the inventory of an Asset, enable the Inventory module, and create a
Log with a Quantity. Within the Quantity, select "Increment", "Decrement", or
"Reset" in the "Inventory adjustment" options, and then select the Asset whose
inventory you would like to adjust. Fill in the Quantity's value (and
optionally its measure, units, and label), set the Log's status to "complete",
and then save the Log. Browse to the Asset you selected, and you will see the
new inventory level.
Multiple inventory levels can be tracked on each Asset, based on the measure
and units specified in the Quantity. Each measure+unit pair (or lack thereof)
will be counted as a separate inventory level.
For more information, refer to the [inventory logic](/model/logic/inventory)
section of the [farmOS data model](/model) docs.

38
docs/guide/location.md Normal file
View File

@ -0,0 +1,38 @@
# Movements and location
The locations of all Assets in farmOS are determined by "Movement" fields on
Log entries.
When you create an Asset, it will not be located anywhere until a Log is added
that "moves" it somewhere. These Logs are referred to as "movement" Logs, even
though they are actually a more specific Log type like "Activity",
"Observation", "Seeding", etc. Any Log type can be used to move Assets.
farmOS determines the "current location" of an Asset by looking at the Asset's
most recent movement Log (with a date less than or equal to the present moment).
Only Logs that have been marked as "complete" are taken into consideration.
Every Log has a "Location" reference field (for referencing the location Asset
that things are moving to), a "Geometry" field (for recording the precise
geometry where things are moving), and an "Is movement" field (for designating
the Log as a movement).
For more information on Asset location, refer to the
[location logic](/model/logic/location) section of the
[farmOS data model](/model) docs.
## Movement Logs
There are three ways that movement Logs can be created:
- Click "Add an activity" (or other Log type) when you are viewing a single
Asset. This will present you with a new Log form, and automatically fill in
the "Assets" field with the Asset you were looking at. In the "Location"
field, select the new location of the Assets, and check the "Is movement"
box to designate the Log as a movement.
- Select multiple Assets in a list, and select the "Move assets" option that
appears. This allows you to move multiple Assets at once. This will present
you with a simplified form for specifying details of the movement.
- Click "Add Log" from the farmOS dashboard, and select a Log type. This
presents you with a blank Log form, which you can fill in however you'd like.
Use the "Location", "Geometry", and "Is movement" fields as described above.

112
docs/guide/logs.md Normal file
View File

@ -0,0 +1,112 @@
# Logging events
Logs represent all kinds of events. You can be as granular as you want: the
more information you're recording, the more you can look back on and learn from
in the future.
Planning ahead in farmOS is exactly the same as recording things that already
happened. The only difference is that the date is in the future, and the Log
status is "pending" instead of "complete".
Logs that are in the future and "pending" will appear in your "Upcoming Tasks"
list on the dashboard. Underneath that is a "Late tasks" list, which shows all
"pending" Logs with a date in the past. So as time goes by, you can mark your
Logs as done (or not), and it will keep track of what happened and what didn't.
Logs can be assigned to one or more person(s) in farmOS using the Log's *Owner*
field. Users can view a list of all Logs assigned to them by navigating to their
profile and then clicking the "Logs" tab.
Logs can be also be categorized for organizing, sorting, and filtering your
Logs in ways that make sense to you, so you can find the Logs you need easily
in the future.
If you want to create a Log that references multiple Assets, you can either
create the Log and then add each Asset to it individually, or you can select
multiple Assets in a list and click the "Add log" button that appears at the
bottom. This will open up a new Log form with the Assets pre-selected.
For more information on Log records, refer the [Logs](/model/type/log)
section of the [farmOS data model](/model) docs.
## Log types
farmOS comes with a number of Log types, summarized below. Additional types can
be added via modules.
### Activities
Activities are a sort of catch-all, or default, Log type, which can be used for
general planning and record keeping of activities that don't fit any of the
other, more specific, Log types.
### Observations
Observations are used to record any kind of passive observation on the farm. For
example, recording that a planting has germinated is an observation. This is a
very flexible Log type that can be used for a lot of different things.
### Inputs
Input Logs are used to record resources that are put into an Asset. Fertilizer
(for plants) or feed (for animals) can be recorded with input Logs.
### Harvests
Harvest Logs are used to record harvests taken from an Asset.
In some cases, you may want to archive the Asset when a harvest is recorded
(eg: harvesting a crop or slaughtering an animal). In other cases, one Asset
may produce multiple harvests (eg: picking apples or collecting eggs).
### Seedings
Seeding Logs are used to represent when seeds are planted in the ground or in
containers. With a seeding Log, you can specify the seeding quantity (eg: 100
lbs, 20 72-plug trays, etc), and you can specify where the seeding occurred so
that farmOS knows where the plant Asset is located.
### Transplantings
Transplanting Logs are used to represent when a plant Asset is moved from one
place to another. For example, when vegetable starts are moved from a greenhouse
to the field, or when tree saplings are purchased from a nursery and planted in
the ground. Similar to seeding Logs, transplantings can have a quantity and a
location.
### Lab tests
Lab test logs can be used to record when/where you have samples analyzed by a
lab, and the results can be attached as a file and/or recorded as
[Quantity](/guide/quantities) measurements on the Log.
These can be used for tracking soil tests, water tests, plant tissue analysis,
etc. Logs can be linked to a specific land or water Asset, and you can specify
the exact points on a map where samples were taken from if you want, as well as
the name of the lab that performed the analysis.
### Maintenance
Maintenance Logs can be used to record when you perform maintenance on a piece
of equipment, structure, or other Asset type. This can be a repair, a tune-up,
an oil change, a cleaning, or anything else that is related to the proper use
and functioning of the Asset. All your maintenance records can be organized,
categorized, and filtered like other Log types in farmOS.
### Medical
Medical Logs can be used to record animal health records. This can be a
veterinary visit, administering medicine/vaccinations, or other medical
procedures. You can also use standard **Input** Logs when administering
medicine or vaccinations, if you prefer, and reserve **Medical** Logs for more
serious events/procedures.
### Births
Birth Logs can be used to record the birth of one or more animals on the farm.
Birth Logs can optionally reference the mother animal, and when they are saved
they will automatically update the "Parents" and "Date of birth" fields on all
referenced child animals. The "Date of birth" field on animal records will
automatically link back to their birth Log (if one exists). The child animal
Asset records must be created before the birth Log, so that they can be
referenced.

157
docs/guide/mapping.md Normal file
View File

@ -0,0 +1,157 @@
# Mapping locations
farmOS gives you the ability to organize all the various places on (and off)
your farm. These places are represented as [Assets](/guide/assets) in farmOS,
and they can be referenced when you are [logging events](/guide/logs). Assets
can be located in other Assets via movement Logs and
[location logic](/guide/location).
To create a location Asset, go to the farmOS Dashboard and click the "Add
asset" button. Select the Asset type you want to map, such as Land or
Structure, and you will be taken to a form for creating the Asset.
You will see a Geometry field with a map for drawing the shape of the Asset.
Generally a single polygon is all that is required, but points and lines are
also allowed.
Make sure that the "Is location" option is enabled so that the Asset is
designated as a location.
When you're done modifying your area, remember to click the Save button at the
bottom of the page to save your changes.
## Map controls
### Zooming
There are three ways to zoom in/out:
- On touch screens, you can "pinch zoom" using two fingers.
- With a computer mouse, you can use the scroll wheel to zoom in/out (click
on the map first to enable scroll zoom).
- The plus (+) and minus (+) buttons in the top left of the map control zoom.
### Geolocating
A "Geolocate" button is available in the top left of the map. This will use your
device's GPS (if available) and/or IP-based geolocation service to try to find
your current location and center the map on that point. While geolocation is
turned on, your position will automatically update as you move around. In
addition to the point, a circle will also be displayed around the point with an
accuracy radius to tell you how confident the geolocated position is.
### Address search
A search button is available in the top of the map for performing an address
search. As you type into the search box, matching addresses will be displayed
in a dropdown. Select the address that you want from that list, and the map
will be automatically re-centered on that location. Geocoding is provided by
[Nominatim](https://nominatim.org/).
### Drawing
There are four buttons for drawing shapes:
- **Polygon**: Use this to draw closed shapes like squares, rectangles, etc.
Click at each vertex of the shape, and end by either connecting to the first
point or double-clicking to connect automatically.
- **Line**: Create a series of line segments by clicking points on the map, and
double-clicking when you're done. You can also hold shift to draw freehand.
- **Point**: Click on the map to create a point.
- **Circle**: Create a circle by clicking where you want the center to be,
dragging the circle outward to expand it, and clicking again to finish.
### Modifying
There are three buttons for modifying shapes:
- **Modify**: Click the modify button, and then click a shape to select it. You
can click and drag any of the vertices to modify the overall shape.
- **Move**: Click the move button, and then click a shape to select it. Then
click and drag the shape to move it to a different position.
- **Delete**: The delete button will clear any selected shapes from the map.
This button will appear when either the Modify or Move buttons are active,
and a shape has been selected. If you accidentally delete a shape, refresh
the page WITHOUT saving, and you will revert to the previously saved shapes.
Note that this will also revert any other changes to your area that you
haven't saved.
## Geometry import and export
### Importing geometry from files
farmOS can import geometries from KML, KMZ, GPX, and GeoJSON files. If you
already have your farm mapped in another software (like Google Earth), you
can export KML files for each area and then import them into farmOS records.
Alternatively, you can use the *KML Importer* module to import a single KML
file that contains the shapes for multiple land Assets.
To import a KML file of an individual Asset or Log, follow these steps:
1. Create a new Asset or Log (or edit an existing one).
2. Scroll down to the Files field and upload your KML file.
3. Scroll to the Geometry field, and just below the map you will see a button
labeled "Import geometry from uploaded files". If you uploaded a valid file,
you will see the shape(s) appear in the map.
To import a KML/KMZ file containing multiple Assets, follow these steps:
1. Enable the *KML Importer* module.
2. Go to Administration > Import > KML Import in the toolbar.
3. Upload your KML/KMZ file, select the default land type to assign to new
Assets, and click "Parse".
4. If geometries are found in the file, a fieldset will be shown for each of
them, letting you customize the Asset name, land type, and whether or not it
should be imported.
5. At the bottom of the form, there is an option to create a new Asset that will
contain all the imported Assets. It is a good idea to use this so that you
can easily review the Asset that were imported, without having them mixed in
with your existing Asset right away. If you find that the import didn't work
properly, you can select all the Asset under this parent Asset and delete them
in bulk.
### Exporting a KML file
KML files can be exported from both Assets and Logs. Open any list of Assets or
Logs, select one or more of them, and select the "Export KML" option that
appears at the bottom.
## Location hierarchy
Location Assets can be organized into a hierarchy. This is visible from the
"Locations" page in the Toolbar. There are three ways to modify the hierarchy:
- Click "Locations" in the toolbar, then click "Toggle drag and drop" at the
bottom. Drag locations to their new parents to modify the hierarchy. Click
"Save" when you are done, or "Reset" to undo your changes.
- The same drag and drop editor is available for child hierarchies of
individual location Assets. Go to the parent Asset record and click the
"Locations" tab to see the hierarchy of children, with the option to modify
via drag and drop.
- When you are editing an individual location Asset, modify its "Parent"
relationship to point to the Asset that should appear above it in the
hierarchy.
## Use the Snapping Grid
farmOS includes a "snapping grid" tool to aid in creating regular/aligned
geometries. When drawing, the cursor will only snap to existing geometries by
default. However, the snapping grid adds a grid of evenly spaced points to which
the cursor will snap preferentially.
![snapping_grid_demo](https://user-images.githubusercontent.com/30754460/88995756-5cb22300-d2a0-11ea-88a1-50edac1c0168.gif)
To activate the grid, click the '#' icon in the bottom left corner above the
scale line, then select two points. The first point is the "origin" of the grid
while the second point we will call a "rotation anchor" and describes how the
grid should be rotated around the origin point.
In addition to controlling the origin/rotation of the grid, its dimensions can
be specified. To do so, hover your mouse over the '#' icon then enter the `x` and
`y` dimensions in the controls which appear. Since the grid can be rotated, the
dimensions are independent of the compass directions on the map. Instead, the `x`
dimension represents the distances between the grid points on lines parallel with
the line formed by the origin and rotation anchor points. Similarly, the `y` dimension
represents distances perpendicular to that line.
![farmOS Snapping Grid dimensions screenshot](/img/snapping_grid_dimension_explanation.png)

69
docs/guide/people.md Normal file
View File

@ -0,0 +1,69 @@
# People
farmOS allows a farm to have multiple "users" accessing it, and each of those
users is assigned one or more "roles" to grant them different levels of
permission.
Roles can be "managed" or "unmanaged." The permissions of managed roles are
controlled by modules and cannot be modified through the UI. Unmanaged roles
can be added/edited through the UI.
Three managed roles are provided with farmOS:
- **Manager** - Has access to everything in farmOS. They can create, edit, and
delete records, and they can change configuration settings.
- **Worker** - Has most of the same permissions as Managers, but cannot change
configuration.
- **Viewer** - Limited to viewing farmOS records - but they cannot edit, delete
or change configuration. This role is useful if you want to share your farm's
activities with someone, but you don't want to give them the ability to make
changes. For example, if you need to share your farm records with an Organic
Certifying Agent, you can give them a user account with the Viewer role.
These roles can be disabled by uninstalling the "Default Roles" module.
Permissions for managed roles cannot be modified through the UI. This is not
generally an issue since the provided roles have been carefully tailored to
work for most applications. In some cases, you may want to further customize
user permissions.
The simplest way to customize permissions is to add unmanaged roles alongside
the managed ones. With this strategy, users are given the minimum required
permissions using the managed roles then granted additional permissions via
unmanaged roles that are manually configured. Permissions are additive, so
a user with multiple roles will have all the permissions included with each.
For example, imagine some users who have the Worker role but not the Manager
role need to be able to configure farm reports - which they cannot do with
Worker role alone. One option would be to make them all Managers, but this can
be confusing or risky if it doesn't match their real-world role or trust level.
Instead, a new role called "Report Manager" (the name is arbitrary) can be
created with permission to configure farm reports. This new role can then be
selectively given to just those users who need the additional access.
In some cases where significantly different permissions are required than
default managed roles, it may be preferable to disable the "Default Roles"
module and create alternate roles manually - or through a custom module.
For example, imagine some users are responsible only for animals and other
users are responsible only for plants. One option would be to make them all
Workers or use the above strategy of additional roles to give those users only
the required permissions on top of the Viewer role. However, in some scenarios
it may be desirable to make alternate roles which completely supersede the
provided ones.
This carries some advantages:
- Allows role naming and structure to more directly match an organizations'
- May allow closer adherence to the
[Principle of Least Privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege)
where the existing roles are overly permissive for most users
But also some disadvantages:
* The alternate roles have to be manually maintained over time - including
across farmOS version upgrades which may imply permission changes for all
features to work or continue working
* All the permissions for the alternate roles have to be manually configured
which increases the likelihood of human error in that configuration granting
potentially dangerous permissions to some users

28
docs/guide/quantities.md Normal file
View File

@ -0,0 +1,28 @@
# Quantities
All Logs in farmOS have the ability to record structured quantitative
measurements alongside other details. These can be used to collect data about
your farm activities in an organized way, which can be analyzed later to
provide insights.
Each Quantity consists of four optional sub-fields:
* Measure - What type of measurement is this? Eg: Weight, Volume, Count,
Temperature, etc.
* Value - The measurement value (a number).
* Units - The unit of measure. This can be anything you like, but it's always
good to keep your units consistent for later analysis.
* Label - Labels are just a text field that allow you to label the Quantity.
This is helpful if you have multiple Quantities of the same measure or units.
A single Log in farmOS can have multiple Quantities, but only the first will be
included when viewing a list of Logs. In order to see a list of all Quantities,
go to Records > Quantities and optionally filter by Log name, type, date range,
or Quantity fields like measure, value, units, or label. A CSV file can be
exported from the filtered results. This provides a flexible approach to
gathering ongoing quantitative data on your farm, and then analyzing it for
trends over time.
For more information on Quantity records, refer the
[Quantities](/model/type/quantity) section of the [farmOS data model](/model)
docs.

10
docs/guide/quick.md Normal file
View File

@ -0,0 +1,10 @@
# Quick forms
farmOS provides a framework for building "quick forms" for common data entry
needs. This allows a simplified and focused UI to be provided for fast and easy
recording of common events, while maintaining the underlying flexibility of
the generalized Asset and Log data architecture.
If you have the "farmOS Quick" module enabled, you will see a new "Quick forms"
link in the toolbar. This will list all available quick forms, which are
provided by modules.

11
mkdocs.yml
View File

@ -1,5 +1,16 @@
site_name: farmOS Docs
nav:
- User Guide:
- Introduction: guide/index.md
- Mapping locations: guide/mapping.md
- Managing assets: guide/assets.md
- Logging events: guide/logs.md
- Movements and location: guide/location.md
- Quantities: guide/quantities.md
- Inventory: guide/inventory.md
- People: guide/people.md
- Quick forms: guide/quick.md
- Exporting data: guide/export.md
- Data model:
- Introduction: model/index.md
- Record types: