Jump to content

Repo comfac-webshop CommonEdits

From Game in the Brain Wiki
Revision as of 16:33, 9 March 2026 by Ocjustin260223 (talk | contribs) ("Repo analysis: comfac-hrms and comfac-webshop (14 pages)")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Repo:comfac-webshop/CommonEdits — Common Edit Scenarios

This page contains practical recipes for common e-commerce customization tasks.

Scenario 1: Adding a Custom Product Field

Goal

Add "Warranty Period" field to Website Items.

Files to Touch

  1. webshop/webshop/doctype/website_item/website_item.json
  2. OR use Frappe Desk Customize Form

Method: Via Desk (Recommended)

  1. Go to Website Item list
  2. Click Customize
  3. Add field:
    • Label: Warranty Period
    • Fieldtype: Select
    • Options: 1 Year\n2 Years\n3 Years\n5 Years
    • Insert After: brand
  4. Save

Method: Via Code

Edit webshop/webshop/doctype/website_item/website_item.json:

Find "fields" array and add:

```json { 

   "fieldname": "warranty_period",
   "fieldtype": "Select",
   "label": "Warranty Period",
   "options": "1 Year\n2 Years\n3 Years\n5 Years",
   "insert_after": "brand"

} ```

Run bench migrate

Display on Product Page

Edit template webshop/templates/webshop/website_item.html:

```html {% if doc.warranty_period %} 

   
   Warranty: Template:Doc.warranty period

{% endif %} ```

How to Verify

  1. Edit a Website Item, set warranty period
  2. View product page
  3. Verify warranty displays correctly

---

Scenario 2: Customizing the Checkout Flow

Goal

Add "Delivery Instructions" field to checkout.

Files to Touch

  1. webshop/www/checkout/index.html
  2. webshop/webshop/shopping_cart/cart.py

Step 1: Add Field to Template

In checkout template, find address section and add:

```html 

   <label>Delivery Instructions (Optional)</label>
   <textarea class="form-control" name="delivery_instructions" 
             placeholder="e.g., Leave at guard house"></textarea>

```

Step 2: Save to Quotation

In cart.py, find place_order or update_cart function:

```python @frappe.whitelist() def place_order(delivery_instructions=None): 

   quotation = _get_cart_quotation()
   
   # Add custom field
   if delivery_instructions:
       quotation.custom_delivery_instructions = delivery_instructions
   
   # Convert to Sales Order
   sales_order = frappe.get_doc(
       make_sales_order(quotation.name)
   )
   sales_order.custom_delivery_instructions = delivery_instructions
   sales_order.insert()
   
   return sales_order.name

```

Step 3: Add Custom Field to Quotation/Sales Order

Via Desk → Customize Form → Quotation:

  • Add field: custom_delivery_instructions (Text)

Repeat for Sales Order.

How to Verify

  1. Add item to cart
  2. Go to checkout
  3. Enter delivery instructions
  4. Place order
  5. Check Sales Order for saved instructions

---

Scenario 3: Adding a New Payment Gateway

Goal

Integrate Philippine payment gateway (e.g., PayMongo).

Files to Touch

  1. webshop/webshop/doctype/override_doctype/payment_request.py
  2. webshop/templates/webshop/checkout/payment.html

Step 1: Override Payment Request

```python import requests from erpnext.accounts.doctype.payment_request.payment_request import PaymentRequest

class WebshopPaymentRequest(PaymentRequest): 

   def get_payment_url(self):
       if self.payment_gateway == "PayMongo":
           return self.create_paymongo_intent()
       return super().get_payment_url()
   
   def create_paymongo_intent(self):
       # PayMongo API integration
       response = requests.post(
           "https://api.paymongo.com/v1/payment_intents",
           headers={"Authorization": "Basic " + get_api_key()},
           json={
               "data": {
                   "attributes": {
                       "amount": int(self.grand_total * 100),  # cents
                       "currency": "PHP",
                       "description": f"Order {self.reference_name}"
                   }
               }
           }
       )
       return response.json()["data"]["attributes"]["checkout_url"]

```

Step 2: Configure Payment Gateway

In Frappe Desk:

  1. Go to Payment Gateway Account
  2. Create new: PayMongo
  3. Add API credentials in Payment Gateway settings

Step 3: Add to Checkout

In payment template:

```html {% if cart_settings.payment_gateway == "PayMongo" %} 

   <button class="btn btn-primary" onclick="payWithPayMongo()">
       Pay with PayMongo
   </button>

{% endif %} ```

How to Verify

  1. Configure PayMongo test credentials
  2. Add item to cart
  3. Checkout and select PayMongo
  4. Verify redirect to PayMongo checkout

---

Scenario 4: Custom Product Filter/Sort

Goal

Add "Sort by Price: Low to High" option.

Files to Touch

  1. webshop/webshop/product_data_engine/query.py
  2. webshop/templates/webshop/all-products.html

Step 1: Add Sort Logic

In query.py, find product listing query builder:

```python def get_product_list(filters=None, sort_by=None): 

   query = build_base_query()
   
   # Apply filters
   if filters:
       query = apply_filters(query, filters)
   
   # Apply sorting
   if sort_by == "price_asc":
       query = query.orderby("price", order=frappe.qb.asc)
   elif sort_by == "price_desc":
       query = query.orderby("price", order=frappe.qb.desc)
   elif sort_by == "newest":
       query = query.orderby("creation", order=frappe.qb.desc)
   
   return query.run()

```

Step 2: Add UI Control

In all-products template:

```html 

   <select id="sort-select" onchange="sortProducts(this.value)">
       <option value="relevance">Relevance</option>
       <option value="price_asc">Price: Low to High</option>
       <option value="price_desc">Price: High to Low</option>
       <option value="newest">Newest First</option>
   </select>

<script> function sortProducts(sortBy) { 

   const url = new URL(window.location);
   url.searchParams.set('sort_by', sortBy);
   window.location = url;

} </script> ```

How to Verify

  1. Visit /all-products
  2. Select different sort options
  3. Verify products reorder correctly

---

Scenario 5: Custom Email Template

Goal

Customize order confirmation email.

Files to Touch

  1. Frappe Desk → Email Template
  2. OR webshop/webshop/notification/order_confirmation/

Method 1: Via Desk

  1. Go to Email Template list
  2. Find Order Confirmation
  3. Edit subject and body:

Subject: ``` Thank you for your order #Template:Doc.name from ComFac! ```

Body: ```html

Hi Template:Doc.customer name,

Thank you for shopping with ComFac Corporation!

Order Details:

Order Number:Template:Doc.name
Order Date:Template:Doc.transaction date
Total:₱Template:Doc.grand total

You can track your order at: <a href="Template:Frappe.utils.get url()/track-order?order=Template:Doc.name"> Track Order </a>

```

Method 2: Via Code

Create webshop/webshop/notification/order_confirmation/order_confirmation.json:

```json { 

   "name": "Order Confirmation - ComFac",
   "subject": "Thank you for your order #Template:Doc.name!",
   "document_type": "Sales Order",
   "event": "New",
   "message": "...template HTML..."

} ```

How to Verify

  1. Place test order
  2. Check email received
  3. Verify custom template applied

---

Scenario 6: Adding Product Reviews

Goal

Enable and display customer reviews.

Files to Touch

  1. Frappe Desk → Webshop Settings
  2. webshop/templates/webshop/website_item.html

Step 1: Enable in Settings

Desk → Webshop Settings:

  • Check "Enable Reviews"

Step 2: Display Reviews

In product page template:

```html <section class="product-reviews">

Customer Reviews

   {% set reviews = frappe.get_all("Item Review",
       filters={"website_item": doc.name, "published": 1},
       fields=["customer", "rating", "review", "creation"]
   ) %}
   
   {% if reviews %}

           Template:Get average rating(reviews) / 5
           (Template:Reviews reviews)

       {% for review in reviews %}
Template:"★" * review.rating

Template:Review.review

           By Template:Review.customer on Template:Review.creation

       {% endfor %}
   {% else %}

No reviews yet. Be the first!

   {% endif %}

</section>

{% if frappe.session.user != "Guest" %} <section class="write-review">

Write a Review

   <form id="review-form">

           <label>Rating:</label>
           <select name="rating">
               <option value="5">5 - Excellent</option>
               <option value="4">4 - Good</option>
               <option value="3">3 - Average</option>
               <option value="2">2 - Poor</option>
               <option value="1">1 - Terrible</option>
           </select>

       <textarea name="review" placeholder="Share your experience..."></textarea>
       <button type="submit">Submit Review</button>
   </form>

</section> {% endif %} ```

Step 3: Add Review Submission Handler

Create whitelisted function:

```python @frappe.whitelist() def submit_review(website_item, rating, review): 

   customer = get_customer_from_user()
   
   review_doc = frappe.get_doc({
       "doctype": "Item Review",
       "website_item": website_item,
       "customer": customer,
       "rating": int(rating),
       "review": review,
       "published": 0  # Requires moderation
   })
   review_doc.insert()
   
   return {"message": "Review submitted for moderation"}

```

How to Verify

  1. Enable reviews in settings
  2. View product page
  3. Submit review as logged-in user
  4. Verify review saved (as unpublished)
  5. Publish review from desk
  6. Verify appears on product page

---

Scenario 7: Stock Alert/Backorder Message

Goal

Custom message when item is out of stock.

Files to Touch

  1. webshop/templates/webshop/website_item.html
  2. webshop/public/js/product_page.js

Template Changes

```html {% set stock_info = get_web_item_qty_in_stock(doc.item_code, doc.website_warehouse) %}

{% if stock_info.in_stock %} 

        In Stock (Template:Stock info.stock qty available)

   <button class="btn btn-primary add-to-cart">Add to Cart</button>

{% elif doc.on_backorder %} 

        Backorder: Ships in 2-3 weeks

   <button class="btn btn-warning add-to-cart">Pre-order</button>

{% else %} 

        Out of Stock

   <button class="btn btn-secondary" disabled>Notify Me When Available</button>

{% endif %} ```

How to Verify

  1. Set item stock to 0
  2. View product page
  3. Verify "Out of Stock" message
  4. Check "on_backorder" checkbox
  5. Verify "Backorder" message appears
Retrieved from "http://wiki.gi7b.org/index.php?title=Repo_comfac-webshop_CommonEdits&oldid=341"