116 lines
4.7 KiB
Text
116 lines
4.7 KiB
Text
=head1 NAME
|
|
|
|
products - RevBank plugin for selling products
|
|
|
|
=head1 SYNOPISIS
|
|
|
|
8710447032756 0.80 Festini Peer
|
|
4029764001807,clubmate 1.40 Club-Mate +half +pf
|
|
pf 0.15@+pfand Pfand NRW-Flasche
|
|
+half -50% 50% discount \o/
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
This plugin turns products from a product list into RevBank commands,
|
|
that add the respective products as Entries to the current Cart.
|
|
|
|
=head1 CONFIGURATION
|
|
|
|
The configuration for this plugin lives in a text file called
|
|
C<revbank.products>.
|
|
|
|
Whitespace at the beginning or end of a line are ignored. Blank lines are
|
|
ignored. Comments are lines that start with C<#> and are also ignored. Note
|
|
that a whole line is either a comment or a data line; trailing comments are
|
|
not supported and C<#> is a valid character in a product description.
|
|
|
|
Data lines have whitespace-separated columns:
|
|
|
|
=head2 Product ids
|
|
|
|
One or more product ids, separated by commas (no whitespace before or after the
|
|
commas). There is no way to have a comma or whitespace in a product id, but
|
|
every other printable character is valid.
|
|
|
|
The first product id on the line is considered canonical, the rest are aliases.
|
|
|
|
Note: if a product id is the same as another RevBank command (e.g. a username),
|
|
the first plugin that accepts the command will "win"; the precedence order is
|
|
defined by the C<revbank.plugins> configuration file. However, when a product
|
|
id appears multiple times within C<revbank.products>, the I<last> one is used.
|
|
|
|
Product ids that begin with C<+> can only be used as addons. When entered as
|
|
user input, it will be ignored by the C<products> plugin.
|
|
|
|
=head2 Price
|
|
|
|
The price of the product. This is the price to be deducted from the user's
|
|
account when they check out with this product in the cart. When it is a
|
|
negative number, the user will instead have money added to their account when
|
|
"buying" this product.
|
|
|
|
Optionally, the price can be augmented with at C<@> sign and the name of the
|
|
contra account. When no contra account is specified, C<+sales/products> is used.
|
|
Internal accounts (that start with C<-> or C<+>) are created automatically. A
|
|
regular account can also be used, but has to exist before the product can be
|
|
used.
|
|
|
|
(Note on internal accounts because they aren't documented elsewhere: liability
|
|
and revenue accounts begin with C<+>, asset and expense accounts begin with
|
|
C<->. The C<+> accounts typically grow larger over time, while C<-> accounts
|
|
typically go negative. In general, you would use a C<+> account in
|
|
C<revbank.products>. User accounts are liability accounts.)
|
|
|
|
=head2 Description
|
|
|
|
The description may contain whitespace.
|
|
|
|
=head2 Addons
|
|
|
|
Addons are products that are added as part of the main product. They are
|
|
specified after the description, with a C<+> sign that has whitespace before
|
|
it, and no whitespace after it.
|
|
|
|
When specifying an addon C<+foo>, and no product with the id C<+foo> exists,
|
|
the product id C<foo> is used instead. The difference is that a product id
|
|
C<+foo> can only be used as an addon for another product, while C<foo> can be
|
|
used either as an addon or a manually entered as a standalone product.
|
|
|
|
example_id 2.20 Example product +first +second
|
|
+first 1.20 First thing
|
|
second 0.80 Second thing
|
|
|
|
In this example, the final price of the example product will be 4.20. It is not
|
|
possible to buy the first thing separate, but it is possible to buy the second
|
|
thing separate.
|
|
|
|
The addon product must be specified in C<revbank.products>; market products
|
|
cannot be used as addons.
|
|
|
|
When a product has addons, it becomes a compound product. This can be used to
|
|
separate a product into individual counter accounts for bookkeeping purposes,
|
|
to add a bottle deposit, or to add other additional fees or discounts.
|
|
|
|
When a compound product has a bare price that isn't 0.00, the bare price is
|
|
listed as a component named "Product".
|
|
|
|
A product can have multiple addons. Addon products themselves can also have
|
|
further addons, but circular recursion is not supported.
|
|
|
|
=head3 Percentage addons
|
|
|
|
As a special case, an addon's price can be a percentage. In this case, the
|
|
price is calculated from the sum of the the product components I<up to that
|
|
point> that have I<the same contra account> as the percentage addon.
|
|
|
|
So, given the following example,
|
|
|
|
example_id 0.90 Example product +some_fee +discount
|
|
+some_fee 0.15@+fees Some fee; might be a bottle deposit
|
|
+discount -50% Special offer discount!
|
|
|
|
only 0.45 is discounted, because the 0.15 has a different contra account. While
|
|
complicated, this is probably what you want in most cases. There is currently
|
|
no way to apply a discount to the product with all of its addons.
|
|
|
|
A percentage addon must have a product_id that begins with C<+>.
|