# Documentation for THEME_NAME

## Introduction

1. Wordpress Theme for [THEME_NAME](https://THEME_NAME) is based on the Gutenberg block editor
2. Tested and working on PHP [8.0]-[8.2.8]
3. Required plugins:
* **Advanced Custom Fields PRO**
* **Advanced Custom Fields: SVG Icon**
* **WP-SCSS** (or another solution for compiling scss to css)
* **Git Updater** (for deployment)

### Folder structure

themes/THEME_NAME/ 			# → Root of theme 
├── acf-json/ 				# → ACF Fields
├── blocks/				# → All Gutenberg Blocks
|	├── blockname/			# → Gutenberg Block Forder
|	|	├── block-image	# → Block screensot
|	|	├── block-render	# → Block template file
|	|	├── block.json		# → Block configuration
|	...
├── css/				# → Theme stylesheets
├── fonts/				# → Theme fonts
├── images/				# → Theme images
|	├── icons.svg			# → Icons sprite file
├── inc/				# → Theme Functions
├── js/					# → Theme javascript
├── languages/				# → Theme language files
├── page-templates/			# → Theme pages templates
├── scss/				# → Theme scss files
├── template-parts/			# → Theme template parts

## Installation

**Step 1: Download the Theme**

**Step 2: Upload the Theme**

1. Click the "Add New" button at the top of the Themes page.
2. Next, click the "Upload Theme" button.
3. Choose the theme ZIP file you downloaded from our website and click "Install Now."

**Step 3: Activate the Theme**
1. Once the installation is complete, click the "Activate" button to make **THEME_NAME** your active theme.

## Configuration

1. Go to **Theme Settings** and fill in all the necessary fields
2. Go to **Apperance -> Menus** create or edit menu items

## Features and Functionality

Building websites with THEME_NAME is made easy and flexible with the power of Gutenberg blocks. Whether you're a beginner or an experienced developer, our solution offers a seamless way to create stunning and functional web pages. This guide will walk you through the core functionality of our Gutenberg-based website builder.

**Block Library:** Our block library includes a diverse range of blocks to cater to your website's needs. Here are some key features:

- **Block Categories:** Blocks are organized into intuitive categories for easy selection.
- **Custom Blocks:** We've crafted custom blocks to enhance your design and functionality.
- **Third-Party Blocks:** Seamlessly integrate third-party blocks from popular plugins.
- **Block Preview:** Preview blocks in real-time to see how they will appear on your site.

**Block Customization:** With our Gutenberg-based solution, you can customize blocks to match your unique vision:

- **Block Settings:** Adjust block settings, such as colors, fonts, and spacing.
- **Advanced Options:** Dive into advanced options for fine-tuning block behavior.
- **Block Reusability:** Save customized blocks for future use on other pages.

**Layout Building:** Our intuitive layout builder empowers you to create dynamic web pages effortlessly:

- **Drag-and-Drop:** Easily arrange and rearrange blocks with a simple drag-and-drop interface.
- **Grids and Columns:** Create responsive layouts with grid and column blocks.
- **Full-Page Editing:** Edit your entire page within the Gutenberg editor, reducing the need to switch between screens.

**Content Integration:** Integrate various content types seamlessly:

- **Media Integration:** Embed images, videos, and audio directly into your content.
- **Dynamic Content:** Fetch and display dynamic content from posts, pages, and custom post types.
- **Widget Integration:** Place widgets anywhere on your page using widget blocks.

**Responsive Design:** Our Gutenberg-based solution ensures that your website looks great on all devices:

- **Mobile Editing:** Fine-tune the mobile view of your site within the editor.
- **Responsive Blocks:** Most blocks adapt to different screen sizes automatically.

**Collaboration and Publishing:** Collaborate with your team and easily publish your content:

- **User Roles:** Assign roles to team members with varying levels of access.
- **Drafts and Revisions:** Save drafts and review revisions before publishing.
- **One-Click Publishing:** Publish your changes with a single click.

## Deploying

**Introduction:**
Deploying your theme with Git Updater is a streamlined process that ensures your WordPress site is always up-to-date with the latest version of your theme, straight from your Git repository. This guide will walk you through the steps to set up Git Updater for seamless theme deployment.

**Step 1: Installation and Activation**

Install and activate the Git Updater plugin from the WordPress plugin repository.

**Step 2: Configure Git Updater**

In your WordPress admin dashboard, navigate to "Settings" > "Git Updater."
Add your access token key in the "GitHub/GitHub.com Access Token" and "THEME_NAME" field.
Click the "Save Changes" button to save your settings.

**Step 3: Deploy Your Theme**

Click on **"Refresh cache"** to reset the cache and get the latest version of the theme from GitHub.
After configuring Git Updater, navigate to "Appearance" > "Themes" in your WordPress dashboard.
You should now see your theme listed with a "New Version Available" notification.
Click the **"Update Now"** button to deploy the latest version of your theme.

**Conclusion:**

Deploying your theme using Git Updater simplifies the update process, ensuring that your WordPress site is running the latest version of your theme effortlessly. With automatic updates enabled, you can focus on creating and customizing your site, knowing that your theme will always be up-to-date.

## Coding Standards

### SCSS

Use scss variables whenever possible.

To apply adaptivity we use the following structure

.class {
	<!-- common style -->
	@include tablet {
		<!-- style for tablet -->
	}
	@include mobile {
		<!-- style for mobile devices -->
	}
}

### JavaScript

When crafting JavaScript, do not assume jQuery. Try not to use jQuery if at all possible.

It is preferred not to use node import libraries, because of the way our legacy codebase was created, how our caching works, and how our postprocessors are implemented.

Optimize performance by ensuring that your javascript works after the content is loaded.

Try to minimize browser re-painting.

Brackets should open and close on a new line at similar indent levels, to make it easy to spot when they open and close.

Functions should be small, single purpose, and reusable.

If you have to specify more than a few

When crafting functions, don’t specify their triggers internally.

When crafting triggers, don’t specify their functions internally.

window.populateFormUrl = function(){
  //do something
};
document.addEventListener( 'DOMContentLoaded', () =>{
  populateFormUrl();
};

### PHP & HTML
To leave HTML comments, use `<?php /* Comment */ ?>`

Don’t leave HTML `<!-- Comments -->` in your code. These are not stripped out by postprocessors and they will be visible in search engines.

## Development Workflow: Local, Staging, and Production

**Step 1: Local Development**

1. **Environment Setup:**

* Set up a local development environment on your computer using tools like [localwp](https://localwp.com/), XAMPP, WAMP, or Docker.
* Install WordPress locally and configure it to match your production environment.

2. Theme Development:

* Customize your WordPress theme and plugins locally.
* Use version control systems (e.g., Git) to manage your code changes.
* Change theme version in `style.css` file

3. Testing and Debugging:

* Thoroughly test your code for functionality and compatibility.
* Use debugging tools and error logs to identify and fix issues.

**Step 2: Staging Environment**
https://THEME_NAME.staging.url/ - staing Environment

1. Deployment to Staging:

* Deploy your theme version to staging using **Git Updater**, fill in all the data

2. Testing and Quality Assurance:

* Conduct extensive testing on the staging site to simulate the production environment.
* Test for performance, security, and cross-browser compatibility.
* Involve stakeholders and team members in the testing process.

3. Feedback and Revisions:

* Collect feedback from stakeholders and make necessary revisions.
* Refine the code, design, and functionality based on feedback.

**Step 3: Production Deployment**

1. Deployment to Production:

* Deploy your theme version to production using **Git Updater**, fill in all the data
* Clear **WpRocket** cache

**Conclusion:**
A well-structured development workflow, including local development, staging, and production stages, ensures that your WordPress project is built, tested, and deployed systematically and reliably. Following this workflow helps minimize errors, enhances collaboration among team members, and ultimately results in a stable and secure production website.