Foodclub:Documentation:FAQ

From Foodclub

The Foodclub FAQ currently serves as the documentation for the Foodclub software. If you have a question about the software which is not answered here, please add a new question to the relevant section below. This wiki page is monitored for any modifications, so new questions will be answered in a timely manner.

NAME

foodclub.org FAQ - frequently asked questions

DESCRIPTION

These are frequently asked questions about foodclub.org. Please read this before sending me e-mail.

GENERAL QUESTIONS

What is foodclub.org?

It is a site designed to facilitate running an organic food-buying club.

What is a food-buying club?

A group of people who order food directly from a wholesale distributor.

Who should use foodclub.org?

It is designed to accommodate new or existing food-buying clubs who order from one or more distributors or directly from farms. The software supports any distributor since the order form is intentionally generic. The only thing it requires is that products you order have unique item codes.

If you already have an operating buying club (i.e. an account with a distributor, a group of people ordering food periodically, product catalogs from the company, an existing system to get orders placed, food distributed to people, and a way of figuring out how much everyone owes) then this site is for you, especially if your existing system is paper or spreadsheet based.

What does it do?

It is a collaborative forum for posting food orders, requesting splits, combining everyone's order into one to be sent to the distributor, and calculating how much everyone owes once the order comes in.

Does it cost anything?

No. It only costs a minimal time investment to set up accounts for users in your food-buying club, and the normal cost of internet access. If everyone in your club already has internet access, it is totally free.

How long has it been up?

I originally wrote the foodclub software for my buying club in Alsea in the Fall of 1999. It was up just for our club from late 1999 until Fall 2000. In the Fall of 2000 I rewrote the software for use by multiple buying-clubs simultaneously, and more suitable for open source development. I bought the foodclub.org domain sometime around Sept, 2000 and the site has been up ever since.

What's the catch?

There is no catch. I was once in a food-buying club and I loved it. I think more people should get their food this way. I hope this site will make food-buying clubs more widespread and organic foods more affordable and accessible to more people.

The only thing I would caution against is getting lazy. This site will make your chores much easier, but you are doing them now the hard way, so obviously you are dedicated. Technology tends to make people lose dedication (aka. get lazy... you know the tune). On the bright side, it will save you lots of time, so just try to do something productive with all that extra time!

Can I start a new food-buying club here?

No. You need to get a group of people together who are interested in ordering quality inexpensive, organic bulk food, and then contact a distributor to open an account with them.

An up-to-date list of organic and natural foods distributors across North America is maintained on this wiki:

 http://foodclub.org/wiki/Main_Page#Distributors_and_farms

Once you have a group of interested people and an account with a distributor, Foodclub will make starting your food-buying club easy.

How do I join a food-buying club?

You need to find people around where you live who have one running, and join them. If you tell them about this site I'm sure they'll like you enough to let you join!

If anyone knows of a list of food-buying clubs around the country and/or world, please pass it along and I will add it here.

Portland, Oregon Area Buying Clubs

TECHNICAL QUESTIONS

How do I start?

First you need to create a new buying-club account. Go to:

 http://foodclub.org/account_wizard

and complete the few pages of the wizard. Once you complete this, you will have your own URL (e.g. foodclub.org/my-club/) that you can give out as your world headquarters! You need to give people login accounts before they can access it though. See next question.

How do I create user accounts for people in my club?

Currently, the easiest way is to enable user registration and have them register themselves. After they register, their user login will wait in a pending state until you or another admin user approves them. You have to enable the user registration feature on your Global settings page, which will cause a Register as a new user link to appear on your club's login page. Check your User maintenance page to see and approve new users.

The other way to create new user accounts is to manually create them for your members on the User maintenance page.

What if people don't want to remember a username/password?

Sorry, they need to. You don't want just anybody going in and futzing with your orders, do you?

How do I change someone's password? (they forgot it.)

As of version 0.32, you can login as the account admin and change any user's password, except for other admin users.

I forgot the administrator username/password! Help!!

You can use the Forgot username/password feature (on login page) to get it reset, just like any other user. We also recommend that you have more than one administrator login, in case one gets lost. If you are truly locked out of your account, you'll have to send us e-mail.

What is the purpose of the "user suspend" and "unsuspend" options?

The user suspend feature is meant for disabling an account temporarily without altering their password or other user information. So unsuspending it brings it back with all the same information it had, unlike deleting it (where you'd have to add it back again with a new password).

This feature is not necessarily very often used by buying clubs. But maybe you'd have a situation where one of your members is "on vacation" or "out-of-the-country" for an extended period of time, and you wanted to increase security by making sure nobody else used their account while they were gone. When they get back their password and everything would be the same. Not deleting their account also preserves their username so other people can't take it, which is an issue on foodclub.org, because there are new clubs signing up all the time to test out the system.

How do I enter my order?

Go to your Order page. It saves everything when you submit, so you can go back and change it later. Note that the Order page is for full case orders, or single items which are small enough to order by yourself, as opposed to splitting with others. (see next question)

How do I request a split?

Go to the Splits page. You can post requests for partial orders and if enough other people order it will be added to the Final order that will be sent to the distributor.

How do I delete a split I've requested?

Only admin users can delete an entire split. You can just remove yourself from a split by editing the split with the change link. Recently a feature was added that highlights the entire split row on mouseover. You can now just click anywhere on the highlighted row to take you to the Edit split item page.

How do I order some of a split someone else requested?

Click order and then enter the amount that you want. You can now just click anywhere on the highlighted row to get here.

It is time to send in the final merged order to the distributor, but there are errors in the splits page that I need to fix. How?

Only an administrator user can change splits. Login as an admin user and go to the Splits page. You should see a change link next to every split request. Click this and then make the necessary changes. You can now just click anywhere on the highlighted row to get here.

How do I merge everyone's order together to send to the distributor?

The Final order page does this for you. It merges every individual's order plus all the splits that were filled. It shows your group addresses at the top of the page, and no individual identifying information, perfect for faxing or e-mail'ing to the distributor.

Does Foodclub automatically transfer the Final order to the distributor?

Yes, but only for certain supported distributors. If the distributor you order from has an online ordering site which Foodclub has integrated with, you will see a Submit order link next to Final order. The Submit order page will prompt you for your login info to the distributor ordering site, and then transfer your entire Final order over. Any information or necessary actions specific to the distributor will be displayed.

Can I prevent users from modifying or adding items to their orders when I'm sending the merged order to the distributor?

Yes. You can "lock" the order which temporarily prevents modification of orders or splits by non-admin users. Click the "Lock Order" button on any page as an admin user.

How does order merging work? AKA, Foodclub ordered too many of an item and we had to return some...

On occasion, users report that the Final order they sent to the distributor had an incorrect quantity for one or more items - usually that it is too high - resulting in some of the order needing to be returned to the distributor.

This is usually a result of not understanding how orders get merged together. The single most important thing to understand is that orders are merged together based on the single, uniquely identifying Code value for each item.

Other fields are ignored when merging, so two items with the same Code should be the same product - otherwise you will get an undesired result.

A specific example of this is that the Associated Buyers distributor allows ordering "repack" items. Repacks are not the same as normal items, so they should not have the same Code value. Buying clubs ordering from Associated Buyers should append an 'R' to the item code for repacks (e.g. 01234R).

How do I figure out how much everyone owes after the order comes in?

Go to the Invoice processing page. It lists every item that was ordered and an input field for you to enter the product's actual cost. Go through the distributor's shipping invoice and enter the price they charged you for each item. Note: if you are using a product database (see below), especially an official database which contains accurate prices, then some or all of these prices will be automatically filled in for you.

When you save, it will generate Invoices for all users who placed an order: detailed itemized price totals for each person, and an overall order total which you can use to match against the distributor's invoice total. You can keep making changes until the Foodclub total equals the distributor invoice total.

Can we calculate how much everyone owes before we send the order to the distributor?

Yes, but only if you are using a product database (see below) with accurate prices for all the items you order. Foodclub provides several "official" product databases, which come directly from distributors and would allow you to do this.

If you are using such a database, all you need to do is go to the Invoice processing page and calculate totals using all the prices pre-filled from the database. However, keep in mind that it will not always be accurate due to items being out-of-stock at delivery time, and price changes between the publishing of a database and placing the order. Also, all users can see their "rough estimate" order total on their Shopping cart page, so sending out an invoice pre-delivery is probably not too useful.

A change was made on someone's order. Why isn't the change showing up in Invoices?

Certain changes made to individual user orders or to splits after Invoices have been generated require the invoices to be re-generated. The main change that requires re-generation of invoices is adding a new item to someone's order or splits. The new item will not have a price, so will show as 0.00 until you go to the Invoice processing page, enter a price, and save.

Most changes, such as changes in qty for existing items and removal of items, will show up automatically in the Invoices page even if they have already been generated. But if something doesn't look right on invoices after you know you made changes to orders or splits, you may want to just re-generate invoices (via Invoice processing) just to be safe, i.e. before spending a bunch of time trying to reconcile and figure out where the discrepancy is.

How do I archive all the data and start over for next month/week/etc?

Only the administrator can do this; login as admin and click Archive order. It will ask you whether you want to unlock the order so non-admins can enter new orders (the default), or to keep the order locked, possibly because you need to update the product database.

Does the software support multiple distributors?

Yes. Each buying-club account on foodclub.org only supports one distributor, but you can create several accounts via the admin interface:

http://foodclub.org/admin

and link them together. Linking accounts allows any user in any of these accounts to login to all of the accounts, and shows a dropdown menu of all the linked accounts for easy navigation between them.

What do the out-of-stock and returned-for-refund checkboxes in Invoice processing do? Can I use them if multiple people ordered an item but only half of the items were delivered?

The returned-for-refund feature in Invoice processing will add a separate line item (Refunds) for every person who ordered this item. The invoice totals will not change, but they will have a new refund line, and their overall total will decrease by the refund.

The out-of-stock feature is similar. Everyone who ordered the item gets charged zero (shows as Out-of-stock), but there is not a separate line item for it. It also subtracts the item cost before calculating the invoice total, not after.

The main difference between the two is out-of-stock is meant for items the distributor knew about, and deducted from your invoice total. The refund feature is for items you returned to them for some reason, but where you want to still have the foodclub invoice total match the invoice total from the distributor.

If multiple people ordered an item and only half the items came in, you will need to use the Separate by item checkbox to flag some users as out-of-stock. Note that Separate by item will not work for splits. If a split is partially out-of-stock or returned, then you need to go back and adjust the split to reflect which users got the items that arrived.

How do we keep track of refunds to co-op members if they paid in advance of order delivery, and then some items were out-of-stock?

If people are paying in advance and then get refunded later when the order arrives, you should probably use the Refund feature and not the Out-of-stock feature, since the refund is a separate line item and doesn't affect the invoice totals. This will allow you to keep a record of how much they paid, and then how much you refunded to them. The downside is that the invoice total in Foodclub Invoices will not match the invoice total from the distributor (unless the distributor shows your total before out-of-stock items).

Can the administrator go in and edit any user's information once they have been created?

Yes. Admin users can edit any user's Order or Splits, and any personal info that a user sets on their User settings page.

To edit a user's individual order, use the Edit order drop-down as an admin, or click on their name on the right side of the Group order page.
Editing splits can be done using the change link for the item on the Splits page.
Changing a user's User settings can be done via the link to the right of their user record on the User maintenance page.

User Interface themes... what are they and why would I use them?

Foodclub now supports themes, which are just a predefined set of CSS styles which determine a coherent and attractive appearance of your site. All you need to do is choose one of the provided themes to change your Foodclub site's appearance. If you do not like any of the provided themes, or you want your Foodclub site to match your public-facing home page, you can design your own theme. Here are some tips for designing your own Foodclub UI theme:

Install the "Firebug" plugin for Firefox, and use it on a page in your Foodclub site
- right click anywhere on the page, and choose Firebug's "Inspect element"
- this will show you the HTML element, and all CSS styles currently applying to it
You can make changes to your CSS settings via Source settings, and see the changes in real-time to test and debug
- CSS settings in Source settings are applied after any themes, so you can override styles in a theme selectively (per the cascading feature of CSS)
- or design a theme from scratch by not using any theme to begin with
You may not be able to do everything you need to without some HTML changes (i.e. adding some class or id attributes). Feel free to e-mail support as you are working on it.

CSS styles... what are they and how do I use them?

Cascading Style Sheets (CSS) can be used to change the appearance of your Foodclub site. Various HTML elements that are rendered by the application have attributes which allow you to set a "style" for them. There is no comprehensive list of elements and/or pages which can be "styled" but you can use your browser's "View page source" to see the HTML and find the class attributes of the elements on the page. The Firefox "Firebug" plugin is also very helpful if doing any serious design work.

Here are a few simple examples of what some users have done with CSS styles:

hide the navigation links with full descriptions from the home page

.indexLinksTable {
  display: none;
}

set the font of account news to Arial

.indexAccountNewsTable {
  font-family: Arial;
}

If you want to re-style your Foodclub site, we recommend first learning CSS (many resources are available for free on the internet). Also, not all HTML elements in Foodclub have class or id attributes, so if you find some that you want to style but cannot, e-mail us and we can add necessary element attributes for you.

How to change visibility of table columns? (e.g. show the item category columns, or hide columns for suppliers who don't have some data)

The column data that is visible in most tables throughout the Foodclub system can be configured for your specific vendor. There are several columns which are hidden by default, and can be made visible, or alternatively columns which seem to always be empty for your food supplier can be hidden to take up less space. It is done using CSS styles.

The columns which are hidden by default in all tables (except product database search results) are:

category
sub_category
sub_category2

The data for them is there, just hidden. If you want to show them for one of your sources (perhaps the category or sub_category has some vital identifying information about the item in that supplier's data), you would add one or all of the following CSS directives to your CSS styles on the Source settings page.

table .CategoryCol { display: table-cell; }

table .SubCategoryCol { display: table-cell; }

table .SubCategory2Col { display: table-cell; }

Note that the above causes all pages where these columns are available to show the hidden column(s). If you only want to show the hidden column(s) on a single page, you can specify the table ID attribute. For example, to only show them on Splits, you would do this:

table#splitItemsTable .CategoryCol { display: table-cell; }

table#splitItemsTable .SubCategoryCol { display: table-cell; }

table#splitItemsTable .SubCategory2Col { display: table-cell; }

Also, showing the extra category columns allows you to sort by them on the pages where sorting is available (e.g. Splits, Group order, Final order, Shopping cart). This would be necessary for sources where you need to separate your group order up by item category.

Alternatively, if you want to hide some columns which do not have data, you would add CSS directives like these to your CSS styles.

table .ManufacturerCol { display: none; }

table .SizeCol { display: none; }

If you want to find the correct CSS / HTML class names for other columns to hide, you can either just view the HTML source for the page, or better yet install the "Firebug" plugin for Firefox and then just right-click on the column and "Inspect element."

Note that all of the above can be made either to a single source via the CSS styles in Source settings, or to all your sources via the CSS styles in Global settings.

PRODUCT DATABASE QUESTIONS

How does the product database work?

You can choose to store your product data in a database on the foodclub.org server. If you have a database set up, you can choose to add item data to it each time you archive your order. You can also add item data from all past orders.

Once you have item data in your database, you can quickly search the database from the Order and Splits pages. You can search on the item's description, manufacturer, code and various other properties. When you find the item you want, you can just click Add to add it to your order or split requests.

What data is stored in the product database?

Each product's item code, case size, manufacturer, description, price, and several other fields are stored. For a full description of all the database fields, see Description of product database fields.

Is any information about who ordered what stored in the database?

No. Only information about the products themselves is stored, not anything about who ordered it. It keeps the date each product was last ordered, but not who ordered it then.

How do I set up the product database for my buying-club?

Login as an administrator user, and go to the Product database page. Here you will see settings which control how your product database works. If you enable private database mode, you can then enable access to phpMyAdmin to directly maintain your private database.

An alternative to using phpMyAdmin to maintain your database is to import your past and future Foodclub orders into your private database: a list of your past orders appears below the database setup options, with a button allowing you to import them. Future orders can be imported on an ongoing basis on the Archive order page.

If you choose to use an official product database, you cannot add past orders to it since it already contains the entire product line that the distributor carries, with accurate prices.

What is an official database?

Foodclub provides several "official" product databases, which come directly from distributors that users of Foodclub commonly order from. They contain up-to-date prices as of a specified date, and some even contain the current sale items for the month. If you are ordering from a distributor with an official database available in Foodclub, this is by far the easiest way to use Foodclub. You can even disable manual entry of items by non-admin users to prevent any mistakes in your order. Users will need to search or browse the database to find what they want, much like standard online shopping carts.

Can I directly maintain the items in my product database?

Yes. If you use a private database, you can enable a phpMyAdmin account, which will allow you to login via a separate web interface to add, edit, or delete items in your product database.

The fields for enabling phpMyAdmin only appear after you have chosen to use a private database, on the Product database page.

Our price list is small enough to manually enter - how can I?

You can manually enter items into a private database one by one, but you need to use phpMyAdmin to do it. First, enable your phpMyAdmin account as described above. Once you have a phpMyAdmin account, follow the steps below:

Login to your phpMyAdmin account (created on Foodclub Product database page as an admin user)
Click on foodclub (1) in the left-side frame
Click on your private database table in the left-side frame, e.g. "private_<your-account-id>"
Click the Insert tab at the top of the right-side frame
Enter values for the fields for which you have data.
- The minimum required set of fields is: code, description, size (if item will be split), price
- Other fields which are nice to have are: category (for browsing), manufacturer, sale_price (if currently on sale)
- All other input fields on the Insert page can be left blank
Click the "Go" button below the input fields. This will create one new record in your private database, which you can immediately see on your Foodclub Order and Splits pages.

What if a product in the database has wrong information?

The solution to fixing data in the database depends on what database mode you are using:

private database with phpMyAdmin: item data can only be changed in phpMyAdmin - nothing will not be modified when your order is archived, since you have the ability to edit items yourself.
private database without phpMyAdmin: update any incorrect item data on your order form, and the newer information will be saved to the database when the overall group order is archived (by an admin user).
official database: everything should be accurate - if not, it means either that the distributor had a mistake in their database or there was an error in the Foodclub import process. E-mail us and we'll get to the bottom of it.

Brief step-by-step instructions for importing a pricelist from a distributor using phpMyAdmin

This process may vary depending on the format of your pricelist, but here is a simple step-by-step guide for importing a basic Excel pricelist.

In Excel, or OpenOffice/Calc, save the pricelist in CSV format (e.g. File -> Save as... then change File type to CSV)
Login to your phpMyAdmin account (created on Foodclub Product database page as an admin user)
Click on foodclub (1) in the left-side frame
Click on your private database table in the left-side frame, e.g. "private_<your-account-id>"
Click the Import tab at the top of the right-side frame
Under File to Import -> Location of the text file, Browse to select the file you exported in the first step, above
Under Format of imported file, select "CSV"
In Format of imported file -> Options -> Fields terminated by, change the ";" (semicolon) to a "," (comma)
In Format of imported file -> Options -> Column names, enter the comma-separated list of Foodclub database columns corresponding to the data in your pricelist file
1. See Description of product database fields for a full description of Foodclub database columns
2. Example: size,unit_size,description,code,price,unit_price,origin
Click the Go button

Troubleshooting tips:

the code field is required; the import will fail if it is blank for any item in your CSV file - actually, it will result in a partial import
the code field must be unique for each item; if there are duplicate codes (two or more items with the same code), the import will fail / result in partial import
beware of embedded double-quotes in your CSV file, e.g. this will cause your import to fail: "some item ""description"" ..."
- the only quotes which should exist are the ones at the beginning and end of a field, right next to the commas
- if you need to have double-quotes in a field, they should be escaped with backslash, e.g. \"

CONTACT QUESTIONS

Who maintains foodclub.org?

Various people help with the maintenance of the site. For questions or problems you find, please e-mail <support at foodclub.org>.

Where can I discuss the software with other users?

You can use this wiki to communicate with other users. Anyone can edit these pages, so feel free to start a new section of the wiki to connect with other users.

A better way to communicate would be to use the Foodclub forums. However, at the moment these are only used by existing food buying clubs to communicate amongst their own members.

If you have a specific issue you want to discuss, the best way is probably to just e-mail <support at foodclub.org> and we will put you in touch with other users who can help you.

I have an idea to improve the software. How do I submit a feature request?

Send e-mail to <support at foodclub.org>. We will evaluate the request, and add it to the to-do list if appropriate and useful to other users. It will be implemented in a timely manner, especially small and easy requests. If it's a large request it may not be done for a while.