Skip to content
Browse files

Improve documentation with more examples and explanations.

  • Loading branch information...
1 parent ead183b commit 787ef1a2e1ab77702f820bcef7431925e5b3cc23 @yure yure committed with racke
Showing with 156 additions and 39 deletions.
  1. +101 −26 lib/Nitesi/Account/Manager.pm
  2. +5 −0 lib/Nitesi/Account/Password.pm
  3. +50 −13 lib/Nitesi/Cart.pm
View
127 lib/Nitesi/Account/Manager.pm
@@ -15,26 +15,26 @@ Nitesi::Account::Manager - Account Manager for Nitesi Shop Machine
=head1 SYNOPSIS
- $acct = Nitesi::Account::Manager->instance(provider_sub => \&account_providers,
+ $account = Nitesi::Account::Manager->instance(provider_sub => \&account_providers,
session_sub => \&session);
- $acct->init_from_session;
+ $account->init_from_session;
- $acct->status(login_info => 'Please login before checkout',
+ $account->status(login_info => 'Please login before checkout',
login_continue => 'checkout');
- $acct->login(username => 'shopper@nitesi.biz', password => 'nevairbe');
+ $account->login(username => 'shopper@nitesi.biz', password => 'nevairbe');
- $acct->logout();
+ $account->logout();
- if ($acct->exists('shopper@nitesi.biz')) {
- $acct->password(username => 'shopper@nitesi.biz', password => 'nevairbe');
+ if ($account->exists('shopper@nitesi.biz')) {
+ $account->password(username => 'shopper@nitesi.biz', password => 'nevairbe');
}
- $acct->create(email => 'shopper@nitesi.biz');
+ $account->create(email => 'shopper@nitesi.biz');
# use this with caution!
- $acct->become('shopper@nitesi.biz');
+ $account->become('shopper@nitesi.biz');
=head1 DESCRIPTION
@@ -135,7 +135,12 @@ sub login {
=head2 logout
-Perform logout.
+Perform logout.
+
+
+B<Example:>
+
+ $account->logout();
=cut
@@ -156,14 +161,17 @@ sub logout {
Creates account.
- $acct->create(email => 'shopper@nitesi.biz');
+B<Example:>
+
+ $account->create(email => 'shopper@nitesi.biz');
+
+ Returns uid for the new account.
-Returns uid for the new account.
The password is automatically generated unless you pass it to
this method:
- $acct->create(email => 'shopper@nitesi.biz',
+ $account->create(email => 'shopper@nitesi.biz',
password => 'nevairbe');
=cut
@@ -206,6 +214,10 @@ sub create {
Delete account.
+B<Example:>
+
+ $account->delete('333');
+
=cut
sub delete {
@@ -231,9 +243,13 @@ sub delete {
=head2 uid
-Retrieve user identifier, returns 0 if current user
+Retrieve user identifier of the current user, returns 0 if current user
isn't authenticated.
+B<Example:>
+
+ $account->uid();
+
=cut
sub uid {
@@ -244,8 +260,12 @@ sub uid {
=head2 username
-Retrieve username. Returns empty string if current user
-isn't authenticated.
+Retrieve username of the current user. Returns empty string if current user
+isn't authenticated. If you want to retrieve other user username, use $account->load.
+
+B<Example:>
+
+ $account->username();
=cut
@@ -257,7 +277,11 @@ sub username {
=head2 roles
-Retrieve roles of this user.
+Retrieve roles of current user.
+
+B<Example:>
+
+ $account->roles();
=cut
@@ -271,6 +295,10 @@ sub roles {
Returns true if user is a member of the given role.
+B<Example:>
+
+ if ($account->has_role('admin') { print "Congratulations, you are the admin" };
+
=cut
sub has_role {
@@ -281,7 +309,25 @@ sub has_role {
=head2 status
-Saves or retrieves status information.
+Helps you to redirect users properly on pages available only to authenticated users.
+
+B<Example:> Before login - Page available only if you are logged in (Step 1)
+
+ You are not logged in. You are on a page which is available only to those logged in. You set the message for users not logged in and url of the page where you send them after successful login.
+
+ $account->status(login_info => 'Please login before checkout', login_continue => 'checkout');
+
+B<Example:> At Login page (Step 2)
+
+ You retrieve the login message to make clear to user why they need to login (to access the page from step 1)
+
+ $account->status('login_info');
+
+B<Example:> After login (Step 3)
+
+ Retrieve the login_continue URL and send user to that URL (using redirect or something similar).
+
+ $account->status('login_continue');
=cut
@@ -301,7 +347,9 @@ sub status {
Check whether account exists.
- if ($acct->exists('shopper@nitesi.biz')) {
+B<Example:>
+
+if ($account->exists('shopper@nitesi.biz')) {
print "Account exists\n";
}
@@ -321,7 +369,11 @@ sub exists {
=head2 load
-Loads account data for a given uid.
+Returns account data for a given uid as hash.
+
+B<Example:>
+
+ $account->load('333');
=cut
@@ -340,11 +392,11 @@ sub load {
Changes password for current account:
- $acct->password('nevairbe');
+ $account->password('nevairbe');
Changes password for other account:
- $acct->password(username => 'shopper@nitesi.biz',
+ $account->password(username => 'shopper@nitesi.biz',
password => 'nevairbe');
=cut
@@ -376,7 +428,22 @@ sub password {
=head2 acl
-ACL check, see L<ACL::Lite> for details.
+ACL (Access list) check, see L<ACL::Lite> for details.
+
+B<Example:>
+
+ if ( $account->acl( check => 'view_prices') {
+ print "You can see prices";
+ }
+
+
+B<Example:>
+
+ If you check multiple permissions at once, only one has to granted. The check will return the name of the first granted one in the list (left to right).
+
+ if ( $account->acl( check => [ qw/admin luka/ ] ) {
+ print "This is Luka's account. Only Luka and administrators can see it".
+ }
=cut
@@ -392,7 +459,15 @@ sub acl {
=head2 value
-Retrieve account data.
+Retrieve or set account data.
+
+B<Example:> Retrieve city
+
+ $city = $account->value( 'city');
+
+B<Example:> Set city
+
+ $city = $account->value( city => 'Ljubljana');
=cut
@@ -422,13 +497,13 @@ sub value {
=head2 become
-Become an user:
+Become any user you want:
$acct->become('shopper@nitesi.biz');
Please use this method with caution.
-Providers may choose not to support this method.
+Some parts of the system (DBI, LDAP,...) may choose not to support this method.
=cut
View
5 lib/Nitesi/Account/Password.pm
@@ -68,6 +68,11 @@ sub password {
Creates random password.
+
+B<Example>
+
+ $crypt->make_password();
+
=cut
sub make_password {
View
63 lib/Nitesi/Cart.pm
@@ -175,6 +175,17 @@ than zero. Default for quantity is 1.
Item price is required and a positive number.
+Price is required, because you want to maintain the price that was valid at the time of adding to the cart. Should the price in the shop change in the meantime, it will maintain this price. If you would like to update the pages, you have to do it before loading the cart page on your shop.
+
+
+B<Example:> Add 5 BMX2012 products to the cart
+
+ $cart->add( sku => 'BMX2012', quantity => 5, price => 200);
+
+B<Example:> Add a BMX2012 product to the cart.
+
+ $cart->add( sku => 'BMX2012', price => 200);
+
=back
=cut
@@ -296,7 +307,7 @@ sub remove {
=head2 update
-Update items in the cart.
+Update quantity of items in the cart.
Parameters are pairs of SKUs and quantities, e.g.
@@ -378,7 +389,7 @@ sub clear {
=head2 quantity
Returns the sum of the quantity of all items in the shopping cart,
-which is commonly used as number of items.
+which is commonly used as number of items. If you have 5 apples and 6 pears it will return 11.
print 'Items in your cart: ', $cart->quantity, "\n";
@@ -397,7 +408,7 @@ sub quantity {
=head2 count
-Returns the number of different items in the shopping cart.
+Returns the number of different items in the shopping cart. If you have 5 apples and 6 pears it will return 2 (2 different items).
=cut
@@ -409,21 +420,27 @@ sub count {
=head2 apply_cost
-Apply cost to cart.
+Apply cost to cart. apply_cost is a generic method typicaly used for taxes, discounts, coupons, gift certificates,...
+
+B<Example:> Absolute cost
+
+ Uses absolute value for amount. Amount 5 is 5 units of currency used (ie. $5).
+
+ $cart->apply_cost(amount => 5, name => 'shipping', label => 'Shipping');
-Absolute cost:
+B<Example:> Relative cost
- $cart->apply_cost(amount => 5, name => 'shipping', label => 'Shipping');
+ Uses percentage instead of value for amount. Amount 0.19 in example is 19%.
-Relative cost:
+ relative is a boolean value (0/1).
- $cart->apply_cost(amount => 0.19, name => 'tax', label => 'Sales Tax',
- relative => 1);
+ $cart->apply_cost(amount => 0.19, name => 'tax', label => 'VAT', relative => 1);
-Inclusive cost:
+B<Example:> Inclusive cost
- $cart->apply_cost(amount => 0.19, name => 'tax', label => 'Sales Tax',
- relative => 1, inclusive => 1);
+ Same as relative cost, but it assumes that tax was included in the subtotal already, and only displays it (19% of subtotal value in example). Inclusive is a boolean value (0/1).
+
+ $cart->apply_cost(amount => 0.19, name => 'tax', label => 'Sales Tax', relative => 1, inclusive => 1);
=cut
@@ -440,7 +457,7 @@ sub apply_cost {
=head2 clear_cost
-Clear costs.
+It removes all the costs previously applied (using apply_cost). Used typically if you have free shipping or something similar, you can clear the costs.
=cut
@@ -456,6 +473,18 @@ sub clear_cost {
Returns particular cost by position or by name.
+B<Example:> Return tax value by name
+
+ $cart->cost('tax');
+
+ Returns value of the tax (absolute value in your currency, not percantage)
+
+B<Example:> Return tax value by position
+
+ $cart->cost(0);
+
+ Returns the cost that was first applied to subtotal. By increasing the number you can retrieve other costs applied.
+
=cut
sub cost {
@@ -539,6 +568,14 @@ sub error {
Seeds items within the cart from $item_ref.
+B<Example:>
+
+ $cart->seed([
+ { sku => 'BMX2015', price => 20, quantity = 1 },
+ { sku => 'KTM2018', price => 400, quantity = 5 },
+ { sku => 'DBF2020', price => 200, quantity = 5 },
+ ]);
+
=cut
sub seed {

0 comments on commit 787ef1a

Please sign in to comment.
Something went wrong with that request. Please try again.