{"id":19060458,"url":"https://github.com/wearenolte/lean-theme","last_synced_at":"2025-04-24T06:52:30.682Z","repository":{"id":10200956,"uuid":"64257929","full_name":"wearenolte/lean-theme","owner":"wearenolte","description":null,"archived":false,"fork":false,"pushed_at":"2023-01-04T22:00:50.000Z","size":4097,"stargazers_count":39,"open_issues_count":42,"forks_count":18,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-04-24T06:52:04.012Z","etag":null,"topics":["composer","php","theme","wordpress","wordpress-theme"],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wearenolte.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"license.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-07-26T22:06:20.000Z","updated_at":"2025-01-28T06:12:13.000Z","dependencies_parsed_at":"2023-01-13T16:24:19.544Z","dependency_job_id":null,"html_url":"https://github.com/wearenolte/lean-theme","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wearenolte%2Flean-theme","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wearenolte%2Flean-theme/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wearenolte%2Flean-theme/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wearenolte%2Flean-theme/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wearenolte","download_url":"https://codeload.github.com/wearenolte/lean-theme/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250580713,"owners_count":21453531,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["composer","php","theme","wordpress","wordpress-theme"],"created_at":"2024-11-09T00:15:30.415Z","updated_at":"2025-04-24T06:52:30.668Z","avatar_url":"https://github.com/wearenolte.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# The LEAN Theme \n## A no-frills WordPress starter theme - Gutenberg Ready!\n\n![maintained](https://img.shields.io/badge/maintained-yes-brightgreen.svg) ![wordpress](https://img.shields.io/badge/wordpress-%3E%3D4.8-green.svg) ![php](https://img.shields.io/badge/php-%3E%3D7.1-green.svg) [![GitHub contributors](https://img.shields.io/github/contributors/wearenolte/lean-theme.svg)](https://github.com/wearenolte/lean-theme/graphs/contributors)\n\n\nThe Lean Theme is a starter theme for WordPress made by Developers for Developers.\n\nIt focuses on fast development following best development practices.\n\nSome key features:\n* Gutenberg ready\n* Easy configuration with Parcel for building development and live environments\n* ES6 Javascript\n* TailwindCSS\n* SASS preprocessor\n* MVC coding architecture\n* Reusable frontend components (following the Atomic Design methodology)\n* Helper functions to create Custom Post Types, Categories and Endpoints easily\n* ACF integration\n* PHP, JS and SASS linters\n* Composer and NPM for managing dependencies\n\n## Contents\n- [The LEAN Theme](#the-lean-theme)\n  - [A no-frills WordPress starter theme - Gutenberg Ready!](#a-no-frills-wordpress-starter-theme---gutenberg-ready)\n  - [Contents](#contents)\n  - [Pre-requisites](#pre-requisites)\n  - [Installation](#installation)\n  - [Development and Production Building commands](#development-and-production-building-commands)\n    - [Production build command](#production-build-command)\n    - [Development command](#development-command)\n  - [Best Practices](#best-practices)\n    - [Linter command](#linter-command)\n    - [Codacy](#codacy)\n  - [Frontend Components](#frontend-components)\n    - [Atoms](#atoms)\n    - [Molecules](#molecules)\n    - [Organisms](#organisms)\n    - [Templates](#templates)\n    - [Loading Atomic Elements](#loading-atomic-elements)\n  - [Gutenberg Configuration](#gutenberg-configuration)\n    - [Custom Font Sizes](#custom-font-sizes)\n    - [Custom Colors](#custom-colors)\n    - [Custom Blocks](#custom-blocks)\n    - [Extending the editor](#extending-the-editor)\n  - [Helper functions](#helper-functions)\n  - [Assets](#assets)\n    - [Images](#images)\n    - [Web Fonts](#web-fonts)\n    - [Icons](#icons)\n  - [CSS](#CSS)\n  - [Styleguide](#Styleguide)\n  - [JavaScript](#javascript)\n    - [Adding new JS function / behavior](#adding-new-js-function--behavior)\n    - [Adding an external package from NPM](#adding-an-external-package-from-npm)\n  - [Models and Controllers](#models-and-controllers)\n    - [Creating a Custom Post Type](#creating-a-custom-post-type)\n  - [Creating an Endpoint](#creating-an-endpoint)\n  - [Theme Hooks](#theme-hooks)\n    - [Actions](#actions)\n    - [Filters](#filters)\n  - [Contributing](#contributing)\n  - [Credits](#credits)\n  - [Changelog](#changelog)\n  - [License](#license)\n\n\n## Pre-requisites\nYou need the following in order to work with this theme:\n* PHP 7.1 or higher\n* [Composer](https://getcomposer.org/doc/00-intro.md#globally)\n* [Node.js](https://nodejs.org/en/download/)\n* [Yarn](https://yarnpkg.com)\n* [Advanced Custom Fields](https://www.advancedcustomfields.com) WP Plugin v5.8.1 or higher\n\nComposer should be installed globally.\n\n## Installation\nDownload or clone the theme\n\nGo to the theme path and enter\n```bash\ncomposer install\n```\n\n## Development and Production Building commands\nThe theme uses composer as dependency manager for PHP libraries, NPM for the JavaScript libraries and Webpack to build the SASS and JS files.\n\n### Production build command\n```bash\ncomposer build\n```\nThis command will install the NPM dependencies and will run the Webpack production configurations which will get the JS and CSS files optimized for a production server. \n\n### Development command\n```bash\ncd frontend\nyarn start\n```\n\nThis command will run the Webpack development configuration which will start a watcher that compiles the SASS and JS files as soon as you save them.\n\nIt will also enable source maps for easy debugging.\n\n## Best Practices\nThe Lean Theme encourages you to use best practices by using linters for PHP, JS and CSS. This helps  maintain a consistent scode style, leaving it becomes clean and at less risk of bugs or security risks. It will help you to detect errors on your code and give you tips on how to solve them.\n\n### Linter command\nThe PHP linter uses the [WordPress Coding Standards](https://make.wordpress.org/core/handbook/best-practices/coding-standards/php/) specified on the WordPress handbook. The following command should be run manually before committing change, and also added to your continuous integration build configuration.\n\nThe JS linter uses the [ESLint](https://eslint.org/) and the SCSS linter uses [SCSS Lint](https://github.com/sds/scss-lint).\n```bash\ncomposer lint\n```\n\n### Codacy\n[Codacy](https://www.codacy.com/) is a tool that automates code reviews \u0026 code analytics.\n\nIf you use this tool you can move the `.codacy.yml` file to the root of the project.\nThis will tell Codacy to review only the relevant files of your app.\nIt will also tell Codacy to grab the PHP, JS and SCSS linter configuration files so that it uses this rules.  \n\n## Frontend Components\nThe Lean Theme follows the [Atomic Design](http://bradfrost.com/blog/post/atomic-web-design/#atoms) methodology for developing a modular frontend.\n\nBelow the `frontend/components` directories there are 4 directories called Atoms, Molecules, Organisms and Templates to which you can add all the Atomic Elements. \n\n### Atoms\nAtoms are the basic building blocks of matter.\n\nApplied to web interfaces, atoms are our HTML tags, such as a form label, an input or a button.\n\nYour stylesheet of each atom must be added inside of `_style.scss` of the `atoms` directory.\n\n### Molecules\nMolecules are groups of atoms bonded together and are the smallest fundamental units of a compound.\n\nA molecule might be an input that includes a form label and the input error display. They are generally not too useful by themselves, but combine them together as a form and now we have something!\n\nYour stylesheet of each molecule must be added inside of `_style.scss` of the `molecules` directory.\n\n### Organisms\nOrganisms are groups of molecules joined together to form a relatively complex, distinct section of an interface.\n\nFor example, a hero is an organism.\n\nYour stylesheet of each organism must be added inside of `_style.scss` of the `organism` directory.\n\n### Templates\nTemplates consist mostly of groups of organisms stitched together. A template with content in it is a `page`.\n\nYour stylesheet of each template must be added inside of `_style.scss` of the `template` directory.\n\n### Loading Atomic Elements\nThe Lean Theme uses the [Loader Module](https://github.com/wearenolte/loader) to render atomic elements:\n\n```php\nLoad::element_type( ‘element_folder/element_php_file’, element_arguments[] );\n```\n\nTo use it first add its namespace at the beginning of the file:\n\n```php\n\u003c?php\nuse Lean\\Load; \n\n// Example of loading an organism located in patterns/organisms/hero/hero.php\nLoad::organism( \n\t'hero/hero', [\n      'bg_image_url' =\u003e $bg_image_url,\n      'show_header' =\u003e true,\n    ]\n);\n\n// Example of loading an atom located in patterns/atoms/buttons/button.php\nLoad::atom( \n\t'buttons/button', [\n      'label' =\u003e $label,\n      'link' =\u003e $url,\n    ]\n);\n```\n\n## Gutenberg Configuration\nThe Lean Theme comes with preconfigured Gutenberg options for the blocks like Font size and colors setup.\n\nThis settings are changed in `Backend/WP/Gutenberg/Editor.php`\n\n### Custom Font Sizes\nThe font size options in the editor's sidebar can be customized. \nSet the styles in `frontend/components/atoms/gutenberg/_typography.scss` by adding the slugs and font sizes. \nThe font size selectors option can also be removed completely.\n\n### Custom Colors\nTo edit the colors that the user can select, add the colors in `frontend/components/atoms/gutenberg/_colors.scss`. \nThe color palette options can also be removed completely.\n\n### Allowed Blocks\nThe blocks that will be allowed to be used in the Gutenberg editor can also be configured. \nThe discrimination can be done per page or post type.\n\n### Custom Blocks\nSee the [Gutenberg Blocks](/docs/BLOCKS.md) subsection for information on how to create custom blocks.\n\n### Extending the editor\nThe Lean Theme comes with a JS building system already setup and ready to use for customizing the Gutenberg editor. \n\nFor example, you could add a custom field to a core block.\n\nGo to `backend/WP/Gutenberg/js` and run\n```bash\nyarn start\n```\n\nMore info on how to extend the Gutenberg editor:\nhttps://developer.wordpress.org/block-editor/\n\n## Helper functions\nTODO: Add Helper functions to the theme\n\n## Assets\nHere you can store anything that is a static file inside the folder frontend/static and respective subfolder:\n\n### Images\nAll the images are placed here, usually if there are static images that does not depend change and are from the design can be placed here.\n\n### Web Fonts\nThis directory is used to place any custom web font that is not available by default as safe web fonts.\n\n### Icons\nThe SVG icons go here.\n\n## CSS\nThe Lean Theme comes with TailwindCSS and SASS integrated. \n\n## Styleguide\nThe Lean Theme comes with its own custom styleguide. More info here: https://github.com/wearenolte/lean-theme-styleguide\n\n## JavaScript\n### Adding new JS function / behavior\nFirst of all you need to create a new file where it makes more sense. For example, we want to create a listener for the click event in buttons so every time a button is clicked a class is added to the body.\n\nIn this case it would make sense to create a new atom called inside of atoms/buttons/toggle-button-listener.js such as.\n```js\n// Everything inside of this file is going to be local to the scope of this file\nconst targetButtonClassName = '.js-button';\nconst toggleClassName = '.button-is-active';\n\nfunction myMainAction() {\n  const buttons = searchButtons();\n  buttons.forEach( attachEvent );\n}\n\nfunction queryTheDOM() {\n  return Array.from( document.querySelectorAll( targetButtonClassName ) ) ;\n}\n\nfunction attachEvent( node ) {\n  node.addEventListener( 'click', clickListener );\n}\n\nfunction clickListener() {\n  document.body.classList.toggle( toggleClassName );\n}\n\nexport default myMainAction;\n```\nAs you can see the example has several functions but the one that is exported to the outside world is only the function myMainAction. At this point this JS is not going to be executed unless you explicitly specify so inside of main.js inside of the onReady function. Everything inside of this function is going to be executed once the DOM is ready.\n\nSo following the example aboye you need to add this two lines inside of main.js\n\n```js\nimport myMainAction from './atoms/buttons/toggle-button-listener';\n\n// inside of onReady\nfunction onReady() {\n  // other functions before\n  myMainAction();\n}\n```\nNOTE The code is transpiled so can be executed on browsers where import or export is not supported yet.\n\n### Adding an external package from NPM\nInside of your own modules you can import files from node_modules. You only need to make sure you add the dependency inside of package.json.\n\nAnd the syntax is pretty similar to import action from 'package-name';\n\nFor example to add flatpickr we need to run the following command in to the terminal:\n```bash\nyarn add flatpickr\n```\n\nAnd to usage the package you only need to add:\n```js\nimport Flatpickr from 'flatpickr';\n\n// Usage example\nfunction init() {\n  const node = document.querySelector('.flatpickr');\n  const instance = new Flatpickr( node );\n}\n\nexport default init;\n```\n\n## Models and Controllers\nModules specific to your project go in the `backend` directory. We encourage you to follow the [Single Responsibility Principle](https://en.wikipedia.org/wiki/Single_responsibility_principle) so each module just try to address a single responsibility for instance Widgets/Widgets.php only tries to address the Widget rendering problem.\n\nThe `init()` method of each class all be called automatically if the class path is set in `Backend.php`.\n\n### To create a new module:\n\n1 - Create a new directory such as:\n```bash\nMyModule/MyModule.php\n```\n2 - Check if MyModule path is set in `Backend.php\n\n3 - Add the corresponding namespace to the new Class.\n\n4 - The `Lean Theme Loader` is going to check for an optional `init()` method, make sure your this method has the following visibility and variable of scope:\n```bash\npublic static\n```\nThe boilerplate for your module should be:\n```php\n\u003c?php \nnamespace Lean\\Backend\\MyModule;\n\nclass MyModule {\n  public static function init() {\n    // This code is executed automatically by the loader.\n  }\n}\n```\n\nYou can also create a single class directly in the top-level of the `src` folder. The same principles apply to the `init` function. This is useful for simple helper functions or WordPress hook callbacks.\n\n### Creating a Custom Post Type\nTo create a Custom Post Type, the Lean Theme relies on another PHP library called WP-CPT which comes installed with the theme.\n\nFirst create a Module as stated before and add the respective code.\n\nExample of an Invoice CPT:\n\ncode in `backend/WP/CPT/Invoices/Invoices.php`\n```php\n\u003c?php \nnamespace Lean\\Backend\\WP\\CPT\\Invoices;\nuse Lean\\Cpt;\n\n\nclass Invoices {\n  const TYPE = 'invoices';\n\n  public static function init() {\n    // This code is executed automatically by the loader.\n    add_action( 'init', [ __CLASS__, 'register_cpt' ] );\n  }\n  \n  public static function register_cpt() {\n    $invoices = new Cpt(\n    \t[\n          'singular' =\u003e 'Invoice',\n          'plural' =\u003e 'Invoices',\n          'post_type' =\u003e self::TYPE,\n          'slug' =\u003e 'invoice',\n          'supports' =\u003e [\n            'title',\n          ],\n          'args' =\u003e [\n            'menu_icon' =\u003e 'dashicons-media-text',\n          ],\n        ]\n    );\n    \n    $invoices-\u003einit();\n  }\n}\n```\n\n## Creating an Endpoint\nCreate a Class in the folder `Backend/WP/Endpoints`\nand initialize it in `Backend/WP/Endpoints/Api.php`\n\nEndpoint out of the box:\n```\nhttp://[site-url]/wp-json/lean/v1/posts\n```\n\n## Theme Hooks\n### Actions\nList of hooks and filters availables to be used with this theme.\n\n```php\nlean/before_header\n```\nAction executed before the main `\u003cheader\u003e` tag and after the `\u003cbody\u003e` tag, useful if you want to add something before any other tag on the site.\n  \n```php\nlean/after_header\n```  \n\nAction executed after the main `\u003c/header\u003e` tag. Useful if you want to add something just after the header has been rendered.\n\n```php\nlean/before_footer\n```\n\nAction that is executed before the main `\u003cfooter\u003e` tag. Useful to add something before the last tag of the page is added.\n\n```php\nlean/after_footer\n```\n\nAction that is executed before the closing `\u003c/body\u003e` tag and just after the `\u003c/footer\u003e tg. Useful to add something at the end of the site.\n \n### Filters\nThe following is a collection of filters available to be used to change settings and options from the theme at any point.\n\n```php\nlean/acf_path\n```\n\nWith this filter you can change the location of the ACF files, by default saves the ACF Groups into the acf directory located on the theme.\n\n```php\nlean/acf_use_custom_location\n```\n\nBy default is set to true, with this filter you can remove the automatic save of ACF Fields into the lean/acf_path.\n\n## Contributing\nPlease read [CONTRIBUTING.md](https://gist.github.com/PurpleBooth/b24679402957c63ec426) for details on our code of conduct, and the process for submitting pull requests to us.\n\n## Credits\nThanks goes to:\n\n[Francisco Giraldo](http://franciscogiraldo.com)\n\n[Nelson Amaya](https://github.com/nelsonamaya82)\n\n[Cris Hernandez](https://github.com/mitogh)\n\n[Daniel López](https://github.com/zesk8)\n\n[Katia Lira](https://github.com/katialira)\n\n[Adam Fenton](https://github.com/adamf321)\n\n[Oscar Arzola](https://github.com/arzola)\n\n[Raul Marrero](https://github.com/Rulox)\n\n\n## Changelog\nPlease read [CHANGELOG.md](CHANGELOG.md)  this file is going to keep the changes of the project when a new release is sent to the master branch\n\n## License\n[MIT](http://www.opensource.org/licenses/mit-license.php)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwearenolte%2Flean-theme","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwearenolte%2Flean-theme","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwearenolte%2Flean-theme/lists"}