diff --git a/resources/boost/guidelines/core.blade.php b/resources/boost/guidelines/core.blade.php new file mode 100644 index 0000000000..fd663969ef --- /dev/null +++ b/resources/boost/guidelines/core.blade.php @@ -0,0 +1,98 @@ +## Statamic +- This application uses Statamic. +- Statamic is an open source, PHP CMS designed and built specifically for developers and their clients or content managers. +- Out of the box, Statamic stores content in Markdown files. It's trivial to move into a database later, if necessary. +- Statamic comes in two flavours: + - **Statamic Core** which is free to use, however you want, forever. It includes everything needed to build a blog or portfolio site. + - **Statamic Pro** which includes everything from Core, as well as unlimited user accounts, revision history, multi-site, Git integration, white labelling and more. Tailored for most production websites. + - For more information on pricing, please send the user to https://statamic.com/pricing. + +### Folder Structure +Statamic is a Laravel package, meaning it can be used alone or alongside an existing Laravel application. + +Most of the folder structure will feel familiar to Laravel developers. However, Statamic creates a few additional files and folders during the install process. + +@verbatim + +├── app/ +├── bootstrap/ +├── config/ +│ ├── statamic/ # Statamic-specific configs +├── content/ +│ ├── assets/ # Asset containers +│ ├── collections/ # Collections and entries +│ ├── globals/ # Global sets +│ ├── navigation/ # Navigations +│ ├── trees/ # Collection and navigation trees +├── database/ +├── lang/ +├── public/ +│ ├── assets/ # Default location for assets +│ ├── ... +├── resources/ +│ ├── addons/ +│ ├── blueprints/ # Blueprints +│ ├── fieldsets/ # Fieldsets +│ ├── users/ # User roles & groups +│ ├── preferences.yaml # Default preferences +│ ├── sites.yaml # Sites config +│ ├── ... +├── routes/ +├── storage/ +├── tests/ +├── users/ +├── please # Statamic's CLI tool +├── ... + +@endverbatim + +### Statamic's CLI +- Statamic ships with its own `please` CLI tool, useful for creating tags or fieldtypes, updating search indexes, enabling multi-site and much more. +- You may run `php please` to get the list of available commands. You may use the `--help` option on a command to inspect its required parameters. + +### Statamic's Core Concepts +- **Assets:** Files managed by Statamic and made available to your writers and developers with tags and fieldtypes. They can be images, videos, PDFs, or any other type of file. +- **Collections:** Collections are containers that hold groups of related entries. Each entry in a collection can represent a blog post, product, recipe or page. +- **Globals:** Global variables store content that belongs to your whole site, not just a single page or URL. They're available everywhere, in all of your views, all the time. +- **Navigations:** A navigation is a hierarchy of links and text nodes that are used to build navs and menus on the frontend of your site. +- **Taxonomies:** A taxonomy is a system of classifying data around a set of unique characteristics. Think things like tags, categories, etc. +- **Users:** Users are the member accounts to your site or application. What a user can do with their account is up to you. They could have limited or full access to the Control Panel, a login-only area of the front-end, or even something more custom by tapping into Laravel. +- **Blueprints:** Blueprints determine the fields shown in your publish forms. You can configure the field's order, each field's width and group them into sections and tabs. Blueprints are attached to collections, taxonomies, globals, assets, users and even forms, all of which help to determine their content schema. +- **Fieldsets:** Fieldsets are used to store and organize reusable fields. Blueprints can reference fields or entire fieldsets, helping you keep your configurations nice and DRY. + +### Templating +- Statamic supports two templating languages: + - **Antlers** is tightly integrated and simple to learn. Uses the `.antlers.html` file extension. + - **Laravel Blade** ships with Laravel and is familiar to most Laravel developers. Uses the `.blade.php` file extension. +- When creating views, you should familiarize yourself with the project and determine which templating language is already in use. +- When using Laravel Blade, you may want to use the "Antlers Blade Components" feature which lets you use a Blade-component-esque syntax with Statamic's tags feature: + +@verbatim + + + {{ $title }} + + +@endverbatim + +### Control Panel +- The Control Panel is the primary way to create and manage content. +- Unless disabled or overridden, the Control Panel is usually accessible from `https://your-website.com/cp`. +- Super users can do and see everything, while non-super users can only do & see what their roles allow for. + +### Extending Statamic +- You can either extend Statamic in the context of an application, or in the context of an addon. +- Addons are Composer packages, meaning they can be reused, distributed, or even sold to others later. +- There are a variety of ways you can extend Statamic: creating tags, fieldtypes, modifiers, etc. A lot of these things can be bootstrapped with `php please make:` commands. + +#### Extending the Control Panel +- The Control Panel is built with Inertia.js and Vue 3. +- When running the `make:fieldtype` or `make:widget` commands, Statamic will install the necessary npm packages and configure Vite. +- Running `setup-cp-vite` in an application context will also do this for you. You'll be able to use `npm run cp:dev` and `npm run cp:build` to run Vite. +- You should use Statamic's UI Components where possible. It includes components for buttons, cards, inputs, etc. + - UI Components can be imported from `@statamic/cms/ui`. + - For more information on Statamic's UI Components, please visit our Storybook docs: https://ui.statamic.dev + +### Additional Context +- Statamic Documentation: https://statamic.dev/llms.txt +- GitHub Issues: https://github.com/statamic/cms/issues