# Introduction The dream of AdaptCMS is a content management system that is like a sandbox. To be able to build any type of site you want and if you're a developer, to be able to create additional functionality easily. We do this by implementing a modular system that allows us, as well as developers to quickly be able to build plugins, fields, and other types of content. Our upcoming new version continues the tradition of using Laravel and VueJS, but what really makes a difference this time around is using TailwindCSS for the UI and InertiaJS for quickly building web pages. At the time of this writing, a beta version is in the works and will be complimented with the documentation listed here so any developer may use the CMS. # Terminology While using the admin interface, or exploring the code base, here is a simple dictionary of common terminology we use in either/both places. #### Packages So packages can be a few different things! In general it refers to a "package" in the base folder `packages`. Within that may contain our own packages, or plugins. Plugins themselves will also reside in here, as well as Fields. It's the central point for all of those, but with different configuration that will be mentioned below to differentiate. #### Modules For those coming from Laravel Nova, a "module" is similar to a "resource" in that software. If I had a restaurant, I would create a location module. So it can be seen as a category of content items, or a content type that is defined. Upon creation of a module, a `/app/Modules/{moduleName}.php` is created with the option to customize various aspects of behavior in the admin. #### Fields Fields are, at their base, "Field Types". By default, a "Text" field exists, as well as "Textarea". A field you may create, or download could be "Google Places" with a google places address lookup input, for example. #### InertiaJS InertiaJS is one of the most powerful tools we are using. With it enabled, developers can create a route, a HTTP controller with action, and then they create a `page.vue` file with data being received by the aforementioned controller action, as well as a lot of helpful stuff such as flash message support, redirect support, validation, and more :) # Setup a Cloud Server Coming soon... # Web Hosts User contributed notes on various web host that play well or don't play with with Statamic. Send your pull requests, no affiliate links! ### PHP Versions by Host [http://phpversions.info/shared-hosting](http://phpversions.info/shared-hosting/) ## Supported Hosts Any linux based server with a fairly up to date version of it's distro, and CLI access shold work fine. Below is a more fine list of web hosts that *should* work fine: * AWS - [https://aws.amazon.com](https://aws.amazon.com/\\) * Digital Ocean - [https://www.digitalocean.com](https://www.digitalocean.com/\\) * A Small Orange - [http://asmallorange.com](http://asmallorange.com\\) * ArcusTech - [http://arcustech.com](http://arcustech.com\\) * Azure - [https://azure.microsoft.com](https://azure.microsoft.com/\\) * Digital Pacific - [http://www.digitalpacific.com.au/hosting](http://www.digitalpacific.com.au/hosting/\\) - Sydney, Australia * Google Cloud Platform - [https://cloud.google.com](https://cloud.google.com/\\) * HostGator - [http://www.hostgator.com](http://www.hostgator.com/\\) * Laravel Forge - [https://forge.laravel.com](https://forge.laravel.com/\\) * Linode - [http://linode.com](http://linode.com\\) * Media Temple (dv) - [http://mediatemple.net](http://mediatemple.net\\) * Media Temple (grid) [http://mediatemple.net](http://mediatemple.net\\) * Metanet - [http://www.metanet.ch](http://www.metanet.ch\\) - Switzerland * OVH - [https://www.ovh.com/fr/index.xml](https://www.ovh.com/fr/index.xml\\) * Panthur - [http://www.panthur.com.au](http://www.panthur.com.au/\\) - Sydney, Australia * ServInt - [https://www.servint.net](https://www.servint.net/\\) * Site5 - [http://www.site5.com](http://www.site5.com/\\) * WebFaction - [https://www.webfaction.com](https://www.webfaction.com/\\) ## Hosts Not Supported You should probably avoid these. It doesn't mean it's not possible, but will likely require support tickets to enabled PHP modules like \`mcrypt\`, \`mbstring\`, and so on, as well as CLI support. * Go Daddy - [http://godaddy.com](http://godaddy.com\\) - doesn't meet server requirements * NameCheap - [http://namecheap.com](http://namecheap.com\\) * Rackspace Cloud - [http://www.rackspace.com/cloud](http://www.rackspace.com/cloud/\\) - issues with out-of-sync file timestamps and permissions * 1and1.com - [http://1and1.com](http://1and1.com\\) - please [see here](https://github.com/statamic/hosts/issues/12) for more details. # Requirements Below you will find the requirements necessary to install and run this software. A majority of the requiredments are what [**Laravel**](https://laravel.com/docs/5.4#server-requirements) requires, with a few exceptions: * PHP >= 7.2.0 * OpenSSL PHP Extension * XML PHP Extension * PDO PHP Extension * Tokenizer PHP Extension * Mbstring PHP Extension * GD/ImageMagick PHP extension * Mcrypt PHP Extesion * ZIP PHP Extension * MySQL Server/Client * Apache, NGINX * URL Rewriting enabled (mod\_rewrite, try\_files, etc) #### Lerna To manage `npm` dependencies across different packages, we use Lerna. Please install this as well, before installation: ``` yarn global add lerna or npm install --global lerna ``` # Installation ## Setup After ensuring your web server meets the requirements, you will also need NPM/Yarn installed, as well as composer: ``` composer require adaptcms/cms ``` After composer is finished, enter the `adaptcms` directory and modify your `.env` file with your database credentials, mail, anything that you see that you can enter credentials, or to choose drivers. Next, run npm/yarn and composer to install the dependencies: ``` yarn OR npm install composer install ``` When running composer you will be asked for a username and password. Login to the [AdaptCMS website](https://www.adaptcms.com) and go to your dashboard. Once a license has been purchased you will see two lines listed per license. The first line is the username, the long random string below is the password. ![Example Dashboard at AdaptCMS.com](https://794952664-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LCoHzGIZNj7Zx4z2EvE%2F-MUJsLATB-BUFM5P0mnT%2F-MUJssDzILgHWOSG86z_%2FMovavi%20ScreenShot%20007%20-%20AdaptCMS%20-%20new.adaptcms.com.jpg?alt=media\&token=4c6a0ded-0d7f-4729-9bf8-74b914ab0284) After composer is completed, copy the `.env.example` file to `.env`. Open up this new file and enter in your configuration, such as database info. Next, run this command to trigger the initial install, as well as setting up your first admin account: ``` php artisan cms:install ``` If you're looking for a new web host, by the way, we highly recommend [**DigitalOcean**](https://m.do.co/c/083895eaa907)! ![](https://794952664-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LCoHzGIZNj7Zx4z2EvE%2F-LCoI2QMiXezwKicl57Z%2F-LCoI31H-YUxTza6XrCS%2Frsz_do_logo_horizontal_blue-3db19536.png?generation=1526664548824813\&alt=media) ## Permissions We know setting permissions sucks, but one day we sat down and found a good set that worked for us very well. In the root folder, there is a `laravel_permissions.sh` file that you can run. Please note before running this command to ensure your apache/nginx username matches `www-data` in the file, and to either create or edit the group name `dev` that is in the file. We've found having a properly set up user with group permissions to be a big key to getting everything working right. If you are unsure of how to handle group management in the command line, we have a tutorial setup on this. Note in the example the group name being used is `dev`, but that name can be quickly replaced in the permissions bash file: {% embed url="" %} If you choose not to run this bash file, keep in mind that read/write/execute permissions will be needed for the below folders: * app/ (only for upgrading through the CMS) * bootstrap/cache/ * config/ (only for upgrading through the CMS) * database/migrations/ * packages/ * storage/ To upgrade through the CMS, the following files will also need to have read/write permissions: * composer.json * package.json * VERSION # Upgrading With the CMS installed and when in the admin, you will see a button on the navigation that will show if an upgrade is available. Along with upgrading through the CMS, you have one other option when proceeding. **Git Pull** If you pulled down the repository manually, you can simply run a `git pull` which will update the necessary files in the new version of the CMS. **CMS Upgrade** Otherwise, if you did a `composer require` to pull in the CMS, continue on after clicking on upgrade to proceed with the update. If anything failed, there should be a rollback that occurs. Otherwise, you may need to manually look at any files that changed. We highly recommend setting up the CMS in a git repo under your control, especially since running `git status` can quickly help you find any issues that popped up. After the upgrade is complete, run `yarn run prod` to ensure the latest UI has been built for the admin and public side. # Auth The Auth package is exactly how it sounds! It manages logging in, registration, roles, users, and permissions. In this section we'll be covering the specifics of how these work, and include helpful resources for developers so they can take advantage of internally built in helpers, as well as libraries used within this package. #### Users Here are the columns: * name * email * timezone Here are the core relations: * roles * permissions The database table is created out of the box, as well as the first user being created upon installation. Details on roles and permissions can be seen below. Login and registration are handled by the base Laravel configuration out of the box, but may be modified per the [Laravel Docs](https://laravel.com/docs/authentication). The UI views may be modified below: * /packages/Adaptcms/Auth/ui/pages/login.vue * /packages/Adaptcms/Auth/ui/pages/register.vue #### Permissions For permissions and roles, we use a package from Spatie that features full documentation: {% embed url="" %} Permissions are in use in every aspect you will see, from the admin to the public side. Menu links are checked, buttons such as create or delete, search, and all routes are protected by permissions. The base permission for being able to access the admin area at all is named `base.admin.access`. A user that does not belong to a role with that permission will not be able to enter the admin area, regardless of any other permissions attached. Package specific permissions, which are synced upon `composer update`, can be seen in the core class for that Package. For example with the Pages module, the list of permissions that must always exist can be seen in this file: `/packages/Adaptcms/Pages/Pages.php` The method `syncPermissions` will contain this list. If you create a package yourself, such as a plugin, be sure to include this so that there is no issues with missing permissions. Any route name defined with a reference to `admin` will, by default, be attached to all roles that have the aforementioned attached permission `base.admin.access`. Roles without that permission will not have access by default to those permissions, but will for any routes that have no reference to `admin` in it's name. Of course, any of this can be overridden within the admin UI. All permissions can be managed in the admin UI, but we recommend not changing any core permission names as to avoid issues that will occur. Same with deletion of core permissions. Roles can be easily attached, or detached within this UI as well. Lastly, if you manually modify permissions, or the permissions seem to be out of date - run this command: ``` php artisan permission:cache-reset ``` #### Roles Roles are used as sort of a middle-man grouping of permissions for users. Rather than directly assigning permissions to users, although you are free to do that within PHP code, roles are assigned permissions - then users are assigned roles. By default, a User role, Admin role, and Super Admin role are supplied upon installation. Admin and Super Admin are exactly the same, but are separated for those who would like to alter assigned permissions so only one or two people may have super admin access, and others may have admin access - an example being a restaurant admin where some users would only need access to manage locations, but not to have access to sensitive areas such as permissions, roles, etc. # Base The base package is used as a repository of neutral functionality that may be used by many other packages. #### Back-end Helpers One of the most important functions at this time for Base is the various CLI commands that will be of great use for developers: ``` php artisan cms:command:make {vendor} {package} {commandName} php artisan cms:migration:make {vendor} {package} {migrationName} php artisan cms:model:make {vendor} {package} {modelName} php artisan cms:controller:make {vendor} {package} {controllerName} ``` Another useful utility is the ability to get a full list of installed packages, with fields excluded: ``` use Adaptcms\Base\Models\Package; Package::getList(); ``` #### UI Helpers On the UI side of things, base contains a large amount of components and helpers that are in use in every core package. We won't be listing out every single component, you can see them all at - `/packages/Adaptcms/Base/ui/components` - but here are some that may slip past the radar. ``` this.modules Returns list of custom modules created. Looping through this array will return an array of data for the module. ``` Modifying the admin dashboard can be done in this page: `/packages/Adaptcms/Base/ui/pages/admin/dashboard.vue` Admin Utility Mixin: `/packages/Adaptcms/Base/ui/mixins/AdminUtilityMixin.js` Admin Form Mixin: `/packages/Adaptcms/Base/ui/mixins/AdminFormMixin.js` ### Package Fields A large piece of functionality is package fields. Currently this links a field to a specific page, or a field to a specific module. The package field then serves as the director of storing custom data into a pages table, or in the case of modules, a particular modules table (such as a column "overall\_rating" on a games table), as an example. It also serves to be usable by plugins of any sort. To implement this functionality into a plugin you are creating, or better understand this feature, we will document how to do so and what configuration is available with a lot of flexibility. For example, the relation to pages is one where there is only one pages table with all custom columns on that one table. Whereas with modules, there is a table for each module with it's respective package fields contained on it's own table, yet both itself and Pages use Package Fields. **Add new trait usage** To start off with, you need the trait to implement some methods automatically for you: ``` all(); $items->searchable(); } ``` **Admin Link Show** A package that implements the package fields functionality should be searchable. To that end, a standard that is in use for all searchable packages is in place. Here again we show below how the `Pages` package implements this: ``` use URL; /** * @var array */ protected $appends = [ 'admin_link_show' ]; /** * Get Admin Link Show Attribute * * @return string */ public function getAdminLinkShowAttribute() { return URL::route('pages.admin.show', [ 'page' => $this->id ]); } ``` **Global Warnings** Packages may take advantage of a global warning system that stores messages in a session and will return them within the admin UI. Use cases will vary, but one example is an API key not being entered in for a new field type that requires it. You'll want to alert any admins so they can easily fix this issue. To get started, below is an example of creating a warning - note, a URL is optional: ``` use Adaptcms\Base\Models\GlobalWarning; GlobalWarning::storeWarning( 'enter-a-unique-warning-key-here', 'This is a test warning that should be taken very seriously!', route('route.name.here') ); ``` Once a user has taken the required action to fix this issue, you will want to remove the warning. Simply do the below: ``` GlobalWarning::deleteWarning('enter-your-unique-warning-key-here'); ``` That's it! Messages will appear on every admin page until the session has expired/been flushed, or until the warning has been removed with the code above - otherwise if the user deletes the warning. One other utility you may require is to check if the warning is active for your package - here's how to do that below: ``` GlobalWarning::hasWarning('enter-your-unique-warning-key-here'); ``` # Fields Fields are a sort of "field type" grouping which is used for Modules and Pages. A basic example is a "Text" field which is a simple text input and is used as a module field upon creation of a module. ### CLI Commands #### Create Field To create a new "field" that can become a GitHub package later on, simply run this: ``` php artisan cms:field:create {vendor} {package} ``` Upon creation, you will find a new folder path under `/packages` following the vendor/package naming you entered. Creating a field in the admin ends in the same result. Within this folder, there are several key files. #### Sync UI components When creating a field, if you make any changes within the default components inside of `/packages/{vendor/Field{package}/ui/field/` - you must run a CLI sync command for your changes to take effect within your website. Simply run this below with yarn/npm running, or build afterward: ``` php artisan cms:fields:sync ``` ### Field Class File First, under `/packages/{vendor}/Field{package}/src/Field/Field{package}.php` is the primary method for API usage where you may adjust default settings. `$storeRules` and `$updateRules` are default validation rules that will be passed in when the field is used, such as with a module or page. An example would be an email field that would pass in an attribute to assure a proper email address: ``` public $storeRules = [ 'email' ]; ``` If your validation needs to be dynamic, then you can instead hook into the `getStoreRules` and the `getUpdateRules` methods, here's the method: ``` getStoreRules(PackageField $packageField) ``` The other important methods include a `getValue()` and `setValue($value)` methods. This will be the default getter/setter for any package fields created. If a developer modifies the module file this field is attached to, a mutator would override the getValue/setValue methods. The `migrationCommand` method contains a string value of the migration command that will be run upon creation of a package field. The example should be pretty self-explanatory. Just keep in mind to go by the Laravel documentation on column modifiers, ensure `->nullable()` is attached unless the field is built for a specific website, and keep the same syntax standard seen in the default. Using the `shouldNotSetData` attribute and having it return true is mostly used for relationship fields. That way a `hasMany` doesn't try to save data to a column that does not exist. `formatColumnName` controls the value saved to the database for a package field, as does `formatName`. It should be noted that the column name is set first. The methods `afterStore` and `afterUpdate` are called after a package field is stored with this field type. You may use this to update configuration, sync custom database structure, or whatever else you would like. When a model is saved and has a package field linked to your field type, `afterModelStore` and `afterModelUpdate` methods are called, respectively. The same basic idea is used as with the above-after methods. For a relationship field, for example, we hook into this method to manually save data for a `HasMany` relationship. Another relationship-related method is `withLoadedRelationships`, although it can be used for other purposes. Primarily it is used to dynamically define relationships, [as first introduced in Laravel 7](https://laravel.com/docs/7.x/eloquent-relationships#dynamic-relationships). Another important usage is loading relationships that will be returned to the VueJS layer. This second piece can be of great use for those building fields with specific purposes - such as a field for a particular website to achieve specific results. That way your code is still abstracted from the core CMS code, but can still load in the data you need. The `withFormMeta` is yet another helper method, this one allowing a field to pass in data within the create/edit actions. An example is that you need to pass in possible select-able values from the database to a select field. For validation on any options stored in a package field `meta` column, you can create the method `createFieldRules()` which should return an array of Laravel-supported validation rules. An example can be found below for the `FieldPasswordConfirmation` field: ``` /** * Create Field Rules * * @return array */ public function createFieldRules() { return [ 'meta.passwordField' => 'required' ]; } ``` If you need the same validation on editing a package field, use `updateFieldRules()` like the below: ``` /** * Update Field Rules * * @return array */ public function updateFieldRules() { return [ 'meta.passwordField' => 'required' ]; } ``` #### UI Customization There are three UI components that will be used to control how the field value is shown in the admin create/edit pages, index/show pages, and public side views. **/packages/{vendor}/Field{package}/ui/field/AdminField.vue** This field returns the HTML input which will be used for create/edit pages within a created package. **/packages/{vendor}/Field{package}/ui/field/AdminOptions.vue** When creating a module field, for example, you may save `meta` info for use within these other views, or within the field PHP class file. An example of this is with `FieldNumber` which allows customization of minimum value, maximum value, and increment/step value. We store these values in the database and can then use this when rendering the field with the above `AdminField.vue` component. **/packages/{vendor}/Field{package}/ui/field/AdminShow\.vue** Used for the index & show pages within the admin panel for a created package. **/packages/{vendor}/Field{package}/ui/field/PublicShow\.vue** This is used anywhere a package module entry, which is related to this field, returns its value. An example might be returning a google maps image for a google places address picker field. **Field Configuration** A field, or field type, may require custom configuration that the user needs to use - such as providing an API key. While this could be hard-coded in, we provide an easy built-in way to accomplish this. For the field `FieldPlace`, we need to do just that, have the user provide a Google API Key for use with Google Places. Here is our implementation as an example below: ``` class FieldPlace extends FieldType { /** * @var array */ public $defaultSettings = [ 'options' => [ 'is_sortable' => false, 'is_searchable' => false, 'is_required_create' => false, 'is_required_edit' => false ], 'action_rules' => [ 'index' => false, 'create' => true, 'edit' => true, 'show' => true, 'search' => false ], 'config' => [ 'google_api_key' => null ] ]; ``` The relevant part is the `config` array key. Simply pass in key and default values (or null), then a settings page will be viewable within the fields admin section - you'll see a pink button with a cog icon where the user can then put in their configuration. You will also see above an `options` array - this can also be configured to set defaults when a package field is created from your field type. Being a location lookup field, we don't want to require the field by default, nor allow it to be sortable or searchable (the former could work though). The other array key is `action_rules` which enable, or disable showing the field on the relevant page. With the place field, we don't want it showing on the index page nor the search, but should be shown on the create, edit, and show pages when browsing a module. **Settings Integration** Currently when creating a site type, there is configuration where a developer may use custom field types for the user to interact with basic configuration of the site type - such as entering in a site name, or uploading a logo. Unlike other use cases, this data is stored within the settings for the site type. This requires a new method which you can implement below. Included in the example is how to get meta data, the column name, how to get the current value and how to set a new value: ``` /** * Save To Settings * * @param Model $model * @param Request $request * @param array $field * @param string $settingsKey * * @return void */ public function saveToSettings($model, Request $request, array $field, $settingsKey) { $columnName = $field['column_name']; $metaData = $field['meta']; $currentValue = $model->settings()->get($settingsKey); // set new value $newValue = 'test123'; $model->settings()->set($settingsKey, $newValue); } ``` If your field type has meta information that needs to be passed in to the view where it is being displayed on a settings page, there is a separate method from `withFormMeta` called `withSettingsFormMeta`. Below is an example from `FieldImage` which returns full image meta for use. The model is whichever settings is used for - so for site types, it would be the site type model and have media attached to it to retrieve. ``` /** * With Settings Form Meta * * @param Request $request * @param object $model * @param string $columnName * * @return array */ public function withSettingsFormMeta(Request $request, $model, string $columnName) { $meta = []; // set media info to view if (!empty($model)) { $meta = $model->getMedia($columnName); } return $meta; } ``` # Modules Modules are at the very core of this software. Think of them as manageable "content types". A restaurant website may want a "Location" module. A video game website may have a "Console" module, and a "Game" module. They can also be seen as sort of a "category" management too. Managing these modules can be entirely done in the admin, as well as the ability to customize individual modules, and use the command line to manage modules too. #### CLI Commands You can create, update, and delete modules with the below commands: ``` php artisan cms:module:create {name} php artisan cms:module:update {oldName} {newName} php artisan cms:module:delete {name} ``` #### Admin When creating a module, a module file will also be created within this path - `/app/Modules/{module}.php`. A module file is simply a base model file with some extra options. The `indexQueryFilter()` method can be used to modify the query for the index page of a module within the admin. You receive request data, as well as the Eloquent query object, which you also will return. Any filtering here may be done. We also have, commented out, several examples of code for getter/setter attributes of package fields. Keep in mind these overwrite any default getter/setter on a specific Field file. One other helpful method is an example of query filtering for a relation field. An example with a video game website - you have a relationship where a "console" hasMany "game" models. However, you want to filter what consoles are shown when an admin goes to create a game. Utilizing the `fieldQueryFilterConsole()` method would allow you to customize this for the create/edit pages in the admin. **Public** While it is mostly up to the developer to build the public side of their website, we want to make it as easy as possible to do so, while not losing out on the ability for customization. Whenever a module is created, two Vue components are created under the `Site` package to be modified at will. ``` /packages/Adaptcms/Site/ui/pages/modules/{moduleNamePlural}/index.vue /packages/Adaptcms/Site/ui/pages/modules/{moduleNamePlural}/show.vue ``` The routes for these two methods are as follows, including a route for search: ``` /post/{moduleNamePlural} /post/{moduleNamePlural}/{itemSlug} /search/post/{moduleNamePlural}?query={searchInput} ``` An example could be /post/games, or /post/games/halo-2. # Pages Pages are essentially static parts of your public website, such as a home page or an about page. By default, a page has a title, a URL and status. The URL defines where the user will be able to access the page relative to the website domain. To help non-tech users better be able to manage the content that appears on pages without doing any coding themselves, fields may be attached to a page creating a `PackageField`. Utilizing this feature a developer, for example, could define hero fields, content sections using the `FieldRichText` field, basically enabling the user to go into the admin and modify the content in these fields. The developer would then modify the page template to display these values in the appropriate places. To customize the Vue component for a page, you will find it in this path: ``` /packages/Adaptcms/Site/ui/pages/pages/{name}.vue ``` Please note also that you can customize the data that is passed to the view by modifying the `PagesController` which is also in the `Site` package. # Plugins Like Fields, Plugins reside in the root `/packages` folder. Unlike fields, plugins are like mini-apps within your site. UI vue components, routes, controllers, models, commands - anything that Laravel supports is usable within a plugin. They could be used to add a feature, or to add a layer to the CMS fit for the specific website in mind. When creating, or editing a plugin, there is an option to "Publish". As long as a valid GitHub URL is entered, we will update that GitHub repo with the files that reside in the Plugin path. Another feature is the ability to search for a plugin from the AdaptCMS.com Marketplace. You may view the plugin on the marketplace, or even choose to install it directly to your website. # Site Types Site types are a way to quickly set up your own category of website. The first site type we have is `SiteTypePizza`, which allows someone who either owns their own pizza restaurant or is making a website for a pizza company, to have their very own pizza website running in moments. Developers can then customize the public website, and otherwise, content management is already setup. {% hint style="info" %} **Note:** Instances of `SiteTypePizza` are simply an example. Whatever you name as your site type will take the place of that reference in the below docs. {% endhint %} ### Activating a Site Type Coming soon... ### Creating a Site Type **CLI Command** To generate a site type locally through the command line, we have a simple way to do this: ``` php artisan cms:siteType:create VendorName SiteTypeName ``` For the Pizza site type, the formatting was `Adaptcms SiteTypePizza` - however, if you do not include the prefix `SiteType`, it will be prepended automatically anyways. **Base Config** This first page on the site type activation screen is used to store general info for your site type. That may be the site name, a logo image, or other things that can be used in building a layout, for example: ``` src/SiteType/SiteTypePizza.php /** * Base Config * * @return array */ public $config = [ [ 'name' => 'Site Name', 'field' => 'FieldText', 'is_required_create' => true, 'is_required_edit' => true ] ]; ``` Provide a valid `{vendor}/{package}` namespace for a field, define a name for the field, can require the field value to be provided, and can pass in meta-information as seen in an example below: ``` src/SiteType/SiteTypePizza.php /** * Base Config * * @return array */ public $config = [ [ 'name' => 'Site Logo', 'field' => 'FieldImage', 'meta' => [ 'mode' => 'single' ] ] ]; ``` `FieldImage` has an option to support either a single or multiple images above, so providing a `meta` key with key/value of `mode => single` would create the field so a single image can be uploaded to the provided module, or in this case, configuration for the site type. **Custom Modules** Using the Pizza example, we want a `Location` module so the owner can enter in their different store locations to show on the website: ``` src/SiteType/SiteTypePizza.php /** * Custom Modules * * @return array */ public $modules = [ [ 'name' => 'Location', 'fields' => [ [ 'name' => 'Title', 'field' => 'FieldText', 'is_required_create' => true, 'is_required_edit' => true ], [ 'name' => 'Address', 'field' => 'FieldPlace', 'is_required_create' => true, 'is_required_edit' => true ], [ 'name' => 'Notes', 'field' => 'FieldTextarea' ] ] ] ]; ``` So we want a module called `Location`, with a title field (ex. Downtown Atlanta), address (of the store), and notes (ex. store hours or parking info). **Custom Pages** The other piece is static pages. For our example pizza restaurant, we may want an `About Us` page to talk about the history and mission of the pizza chain, a contact page with information on how to get in contact, a catering page with information on how to get pizza catered to you, and so on. For this example, we'll just show a simple `About Us` page: ``` src/SiteType/SiteTypePizza.php /** * Custom Pages * * @return array */ public $pages = [ [ 'name' => 'About Us', 'url' => '/about', 'fields' => [ [ 'name' => 'Body', 'field' => 'FieldRichText', 'is_required_create' => true, 'is_required_edit' => true ] ] ] ]; ``` **UI - Overwrite Layout** When creating a Site Type, you can choose to overwrite the public layout in the `src/SiteType/SiteTypePizza.php` file: ``` class SiteTypePizza { /** * @var bool */ public $overwriteLayout = true; } ``` This value is set to `false` by default, but switching to true will copy the layout in your site type path `ui/layouts/layout.vue` to the `Site` package folder where the public layout resides. Using the power of package fields, you can easily build PHP arrays that contain the configuration used when activating the site type. **UI - Activate Site Type** When activating a site type, there is a basic warning near the top of the page explaining that current data may be overwritten by continuing and below that is where you may choose to show whatever you choose. You may want to simply thank the user for using your site type, show a preview of what it will look like, or other notes. Simply edit, to your heart's content, the file at `ui/ActivateSiteType.vue` within your Site Type's folder. # Creating Your Own Package ### Creating the Package #### Commands ``` php artisan cms:command:make {vendor} {package} {commandName} php artisan cms:migration:make {vendor} {package} {migrationName} php artisan cms:model:make {vendor} {package} {modelName} php artisan cms:module:create {name} php artisan cms:module:update {oldName} {newName} php artisan cms:module:delete {name} ``` #### Package Configuration File ``` /packages/{vendorName}/{packageName}/src/{packageName}.php ``` You will find your package file within the above path. Below are different configuration options. **syncPermissions()** Here is an example from the Notifications package. We recommend sticking to the prefix **{packageName}.admin.{controllerName}.{actionName}** syntax to be consistent. The name of your permission must also match the route name it corresponds to. ```