From 938e0517577e41bf5e48d8b450eb4ba083963a3e Mon Sep 17 00:00:00 2001 From: mohamed abdullah Date: Sat, 21 Aug 2021 10:53:45 +0200 Subject: [PATCH 01/19] [MOD]: modify card && table by remove shadow-xl class remove big shadow from card && table --- packages/forms/resources/views/components/card.blade.php | 2 +- packages/tables/resources/views/components/table.blade.php | 2 +- resources/views/components/card.blade.php | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/forms/resources/views/components/card.blade.php b/packages/forms/resources/views/components/card.blade.php index aa3c1302bb..f6a0f997b7 100644 --- a/packages/forms/resources/views/components/card.blade.php +++ b/packages/forms/resources/views/components/card.blade.php @@ -16,6 +16,6 @@ ][$formComponent->getColumnSpan()] @endphp -
+
diff --git a/packages/tables/resources/views/components/table.blade.php b/packages/tables/resources/views/components/table.blade.php index 3743c855be..e18669b96e 100644 --- a/packages/tables/resources/views/components/table.blade.php +++ b/packages/tables/resources/views/components/table.blade.php @@ -12,7 +12,7 @@ @endpushonce @endif -
+
diff --git a/resources/views/components/card.blade.php b/resources/views/components/card.blade.php index 7fec5469f4..61fdaa2195 100644 --- a/resources/views/components/card.blade.php +++ b/resources/views/components/card.blade.php @@ -3,7 +3,7 @@ ])
class([ - 'bg-white shadow-xl rounded p-4 md:p-6', + 'bg-white rounded p-4 md:p-6', 'col-span-full' => $expanded, ]) }}> {{ $slot }} From c79fa354e4e08eb962aea0072fcf769a9bbc032a Mon Sep 17 00:00:00 2001 From: mohamed abdullah Date: Sat, 21 Aug 2021 17:02:55 +0200 Subject: [PATCH 02/19] [FIX]: fix justify start for table head in RTL fix justify label if it not sortable in RTL --- packages/tables/resources/views/components/table.blade.php | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/packages/tables/resources/views/components/table.blade.php b/packages/tables/resources/views/components/table.blade.php index e18669b96e..30bfa963d7 100644 --- a/packages/tables/resources/views/components/table.blade.php +++ b/packages/tables/resources/views/components/table.blade.php @@ -50,7 +50,9 @@ @else - {{ __($column->getLabel()) }} +
+ {{ __($column->getLabel()) }} +
@endif @endforeach From 87895d0cd7dab0cd2745da11340a6a23f56379c7 Mon Sep 17 00:00:00 2001 From: Martin Mildner Date: Wed, 25 Aug 2021 23:20:08 +0200 Subject: [PATCH 03/19] Set initial height when needed --- .../resources/views/components/markdown-editor.blade.php | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/packages/forms/resources/views/components/markdown-editor.blade.php b/packages/forms/resources/views/components/markdown-editor.blade.php index 742a440f9b..55f97a66c4 100644 --- a/packages/forms/resources/views/components/markdown-editor.blade.php +++ b/packages/forms/resources/views/components/markdown-editor.blade.php @@ -88,8 +88,10 @@ }, resize: function () { - this.$refs.overlay.style.height = '150px' - this.$refs.overlay.style.height = this.$refs.textarea.scrollHeight + 'px' + if (this.$refs.textarea.scrollHeight > 0) { + this.$refs.overlay.style.height = '150px' + this.$refs.overlay.style.height = this.$refs.textarea.scrollHeight + 'px' + } this.overlay = mdhl.highlight(this.value = this.$refs.textarea.value) }, From 8ea0abbc57e962239df350792fa12f3fa2101748 Mon Sep 17 00:00:00 2001 From: Dan Harrin Date: Sun, 29 Aug 2021 17:45:16 +0100 Subject: [PATCH 04/19] Update branch name --- .github/FUNDING.yml | 2 +- README.md | 2 +- SECURITY.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml index 5b37ab2230..4df58a127d 100644 --- a/.github/FUNDING.yml +++ b/.github/FUNDING.yml @@ -1 +1 @@ -github: [danharrin, ryangjchandler] +github: [danharrin] diff --git a/README.md b/README.md index bd50cfa74f..ec1d0dd574 100644 --- a/README.md +++ b/README.md @@ -19,4 +19,4 @@ Filament is a content management framework for rapidly building a beautiful admi 🤔 If you have a question or feature request, please [start a new discussion](https://github.com/laravel-filament/filament/discussions/new). We are also partnered with the [Laravel Livewire Discord server](https://discord.gg/livewire). For quick help, ask questions in the Filament channel. -🔐 If you discover a vulnerability within the package, please review our [security policy](https://github.com/laravel-filament/filament/blob/main/SECURITY.md). +🔐 If you discover a vulnerability within the package, please review our [security policy](https://github.com/laravel-filament/filament/blob/1.x/SECURITY.md). diff --git a/SECURITY.md b/SECURITY.md index d5ca045ed9..79f11c67f0 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -8,4 +8,4 @@ ## Reporting a Vulnerability -If you discover a security vulnerability within Filament, please email Ryan Scherler via [ryan@eastslope.studio](mailto:ryan@eastslope.studio) or Dan Harrin via [dan@danharrin.com](mailto:dan@danharrin.com). All security vulnerabilities will be promptly addressed. +If you discover a security vulnerability within Filament, please email Dan Harrin via [dan@danharrin.com](mailto:dan@danharrin.com). All security vulnerabilities will be promptly addressed. From eaa70a6d95be0e03f5617fc385c81a07ba643863 Mon Sep 17 00:00:00 2001 From: Dan Harrin Date: Sun, 29 Aug 2021 17:52:15 +0100 Subject: [PATCH 05/19] wip --- .github/workflows/monorepo-split.yml | 1 - .github/workflows/php-cs-fixer.yml | 10 ++-------- 2 files changed, 2 insertions(+), 9 deletions(-) diff --git a/.github/workflows/monorepo-split.yml b/.github/workflows/monorepo-split.yml index fe4a012f88..f91983d1b5 100644 --- a/.github/workflows/monorepo-split.yml +++ b/.github/workflows/monorepo-split.yml @@ -18,7 +18,6 @@ jobs: run: echo "::set-output name=matrix::$(vendor/bin/monorepo-builder packages-json)" outputs: matrix: ${{ steps.packages-list.outputs.matrix }} - split-monorepo: needs: provide-packages-list runs-on: ubuntu-latest diff --git a/.github/workflows/php-cs-fixer.yml b/.github/workflows/php-cs-fixer.yml index 21472777ff..f126dc804f 100644 --- a/.github/workflows/php-cs-fixer.yml +++ b/.github/workflows/php-cs-fixer.yml @@ -1,9 +1,6 @@ name: php-cs-fixer -on: - push: - branches: - - develop +on: push jobs: php-cs-fixer: @@ -12,16 +9,13 @@ jobs: - name: Checkout code uses: actions/checkout@v2 with: - ref: develop - + ref: ${{ github.head_ref }} - name: Run PHP CS Fixer uses: docker://oskarstark/php-cs-fixer-ga with: args: --config=.php-cs-fixer.dist.php --allow-risky=yes - - name: Commit changes uses: stefanzweifel/git-auto-commit-action@v4 with: - branch: develop commit_message: > chore: styling From c208ce42c593b61173b1f2ceff727c8467fb52b8 Mon Sep 17 00:00:00 2001 From: Dan Harrin Date: Sun, 29 Aug 2021 17:53:58 +0100 Subject: [PATCH 06/19] Update monorepo-split.yml --- .github/workflows/monorepo-split.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/monorepo-split.yml b/.github/workflows/monorepo-split.yml index f91983d1b5..c6b3a14d56 100644 --- a/.github/workflows/monorepo-split.yml +++ b/.github/workflows/monorepo-split.yml @@ -2,7 +2,8 @@ name: monorepo-split on: push: - tags: '*' + branches: + - 2.x jobs: provide-packages-list: From de121abc1add3e819dc80d80c777491a1ab19290 Mon Sep 17 00:00:00 2001 From: Dan Harrin Date: Sun, 29 Aug 2021 17:54:31 +0100 Subject: [PATCH 07/19] Update monorepo-split.yml --- .github/workflows/monorepo-split.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.github/workflows/monorepo-split.yml b/.github/workflows/monorepo-split.yml index c6b3a14d56..f91983d1b5 100644 --- a/.github/workflows/monorepo-split.yml +++ b/.github/workflows/monorepo-split.yml @@ -2,8 +2,7 @@ name: monorepo-split on: push: - branches: - - 2.x + tags: '*' jobs: provide-packages-list: From 139918898203dc65aa18f2fa31b8ceb4868ba04e Mon Sep 17 00:00:00 2001 From: Dan Harrin Date: Sun, 29 Aug 2021 19:38:37 +0100 Subject: [PATCH 08/19] Add docs --- docs/admin/dashboard.md | 36 ++ docs/admin/forms.md | 720 +++++++++++++++++++++++++++++++ docs/admin/index.md | 148 +++++++ docs/admin/navigation.md | 36 ++ docs/admin/pages.md | 75 ++++ docs/admin/plugin-development.md | 219 ++++++++++ docs/admin/resources.md | 411 ++++++++++++++++++ docs/admin/roadmap.md | 35 ++ docs/admin/tables.md | 272 ++++++++++++ docs/admin/theming.md | 118 +++++ 10 files changed, 2070 insertions(+) create mode 100644 docs/admin/dashboard.md create mode 100644 docs/admin/forms.md create mode 100644 docs/admin/index.md create mode 100644 docs/admin/navigation.md create mode 100644 docs/admin/pages.md create mode 100644 docs/admin/plugin-development.md create mode 100644 docs/admin/resources.md create mode 100644 docs/admin/roadmap.md create mode 100644 docs/admin/tables.md create mode 100644 docs/admin/theming.md diff --git a/docs/admin/dashboard.md b/docs/admin/dashboard.md new file mode 100644 index 0000000000..e03bde5430 --- /dev/null +++ b/docs/admin/dashboard.md @@ -0,0 +1,36 @@ +--- +title: Dashboard +description: +extends: _layouts.documentation +section: content +toc: | + - [Disabling the Default Widgets](#disabling-default-widgets) +--- + +# Dashboard + +

Filament allows you to build dynamic custom dashboard widgets very easily. To get started building a `Stats` widget:

+ +```bash +php artisan make:filament-widget Stats +``` + +This command will create two files - a widget class in the `/Widgets` directory of the Filament directory, and a view in the `/widgets` directory of the Filament views directory. + +Widgets are pure [Laravel Livewire](https://laravel-livewire.com) components, so may use any features of that package. + +> Pre-built widget templates are coming soon. For more information, please see our [Development Roadmap](/docs/roadmap). + +## Disabling the Default Widgets {#disabling-default-widgets} + +By default, two widgets are displayed on the dashboard. These widgets can be disabled by updating the `widgets` section of the [configuration](/docs#configuration) file. Updating each entries to `false` will remove the corresponding default widget from the dashboard. + +```php + 'widgets' => [ + // ... + 'default' => [ + 'account' => false, // Disables the account widget. + 'info' => false, // Disables the info widget. + ], + ], +``` diff --git a/docs/admin/forms.md b/docs/admin/forms.md new file mode 100644 index 0000000000..4fb028d0a5 --- /dev/null +++ b/docs/admin/forms.md @@ -0,0 +1,720 @@ +--- +title: Building Forms +description: +extends: _layouts.documentation +section: content +toc: | + - [Fields](#fields) + - [Checkbox](#fields-checkbox) + - [Date Picker](#fields-date-picker) + - [Date-time Picker](#fields-date-time-picker) + - [File Upload](#fields-file-upload) + - [Key-value](#fields-key-value) + - [Markdown Editor](#fields-markdown-editor) + - [Toolbar Buttons](#fields-markdown-editor-toolbar-buttons) + - [Rich Editor](#fields-rich-editor) + - [Toolbar Buttons](#fields-rich-editor-toolbar-buttons) + - [Select](#fields-select) + - [Tags Input](#fields-tags-input) + - [Textarea](#fields-textarea) + - [Text Input](#fields-text-input) + - [Toggle](#fields-toggle) + - [Validation](#validation) + - [Layout](#layout) + - [Grid](#layout-grid) + - [Section](#layout-section) + - [Fieldset](#layout-fieldset) + - [Tabs](#layout-tabs) + - [Group](#layout-group) + - [Placeholder](#layout-placeholder) + - [Dependent Fields](#dependent-fields) + - [Context Customization](#context-customization) + - [Developing Custom Components](#custom-development) +--- + +# Building Forms + +

Filament comes with a powerful form builder which can be used to create intuitive, dynamic, and contextual forms in the admin panel.

+ +Forms have a schema, which is an array that contains many form components. The schema defines the form's [fields](#fields), their [validation rules](#validation), and their [layout](#layout) in the form. + +Here is an example form configuration for a `CustomerResource`: + +```php +use Filament\Resources\Forms\Components; +use Filament\Resources\Forms\Form; + +public static function form(Form $form) +{ + return $form + ->schema([ + Components\TextInput::make('name')->autofocus()->required(), + Components\TextInput::make('email')->email()->required(), + Components\Select::make('type') + ->placeholder('Select a type') + ->options([ + 'individual' => 'Individual', + 'organization' => 'Organization', + ]), + Components\DatePicker::make('birthday'), + ]) + ->columns(2); +} +``` + +> Please note: when building forms for resources, please ensure that you are using components within the `Filament\Resources\Forms\Components` namespace and not `Filament\Forms\Components`. + +## Fields {#fields} + +Resource field classes are located in the `Filament\Resources\Forms\Components` namespace. + +All field components have access to the following customization methods: + +```php +Field::make($name) + ->columnSpan($span = 1) // On large devices, this sets the number of columns that the field should span in the form. + ->default($default) // Sets the default value for this field. + ->dependable() // Reloads the form when this field is changed. + ->disabled($disabled = false) // Make the field read-only. + ->extraAttributes($attributes = []) // A key-value array of extra HTML attributes to pass to the field. + ->helpMessage($message) // Sets an optional message below the field. It supports Markdown. + ->hint($hint) // Sets an optional short message adjacent to the label. It supports Markdown. + ->id($id) // Set the HTML ID of the field, which is otherwise automatically generated based on its name. + ->label($label); // Set custom label text for with the field, which is otherwise automatically generated based on its name. It supports localization strings. +``` + +### Checkbox {#fields-checkbox} + +```php +Checkbox::make($name) + ->autofocus() // Autofocus the field. + ->inline() // Render the checkbox inline with its label. + ->stacked(); // Render the checkbox under its label. +``` + +### Date Picker {#fields-date-picker} + +```php +DatePicker::make($name) + ->autofocus() // Autofocus the field. + ->displayFormat($format = 'F j, Y') // Set the display format of the field, using PHP date formatting tokens. + ->firstDayOfWeek($day = 1) // Set the first day of the week in the calendar view, with 1 being Monday, and 0 or 7 being Sunday. + ->format($format = 'Y-m-d') // Set the storage format of the field, using PHP date formatting tokens. + ->maxDate($date) // Set the maximum date that can be selected. + ->minDate($date) // Set the minimum date that can be selected. + ->placeholder($placeholder) // Set the placeholder for when the field is empty. It supports localization strings. + ->weekStartsOnMonday() // Set the first day of the week to Monday in the calendar view. + ->weekStartsOnSunday(); // Set the first day of the week to Sunday in the calendar view. +``` + +### Date-time Picker {#fields-date-time-picker} + +```php +DateTimePicker::make($name) + ->autofocus() // Autofocus the field. + ->displayFormat($format = 'F j, Y H:i:s') // Set the display format of the field, using PHP date formatting tokens. + ->firstDayOfWeek($day = 1) // Set the first day of the week in the calendar view, with 1 being Monday, and 0 or 7 being Sunday. + ->format($format = 'Y-m-d H:i:s') // Set the storage format of the field, using PHP date formatting tokens. + ->maxDate($date) // Set the maximum date that can be selected. + ->minDate($date) // Set the minimum date that can be selected. + ->placeholder($placeholder) // Set the placeholder for when the field is empty. It supports localization strings. + ->weekStartsOnMonday() // Set the first day of the week to Monday in the calendar view. + ->weekStartsOnSunday() // Set the first day of the week to Sunday in the calendar view. + ->withoutSeconds(); // Hide the seconds input. +``` + +### File Upload {#fields-file-upload} + +```php +FileUpload::make($name) + ->acceptedFileTypes($types = []) // Limit the type of files that can be uploaded using an array of mime types. + ->avatar() // Make the field suitable for uploading and displaying a circular avatar. + ->disk($disk) // Set a custom disk that uploaded files should be read from and written to. + ->directory($directory) // Set a custom directory that uploaded files should be written to. + ->image() // Allow only images to be uploaded. + ->imageCropAspectRatio($ratio) // Crop images to this certain aspect ratio when they are uploaded, e.g: '1:1'. + ->imagePreviewHeight($height) // Set the height of the image preview in pixels. + ->imageResizeTargetHeight($height) // Resize images to this height (in pixels) when they are uploaded. + ->imageResizeTargetWidth($width) // Resize images to this width (in pixels) when they are uploaded. + ->loadingIndicatorPosition($position = 'right') // Set the position of the loading indicator. + ->maxSize($size) // Set the maximum size of files that can be uploaded, in kilobytes. + ->minSize($size) // Set the minimum size of files that can be uploaded, in kilobytes. + ->panelAspectRatio($ratio) // Set the aspect ratio of the panel, e.g: '1:1'. + ->panelLayout($layout) // Set the layout of the panel. + ->placeholder($placeholder) // Set the placeholder for when no file has been uploaded. It supports localization strings. + ->removeUploadButtonPosition($position = 'left') // Set the position of the remove upload button. + ->uploadButtonPosition($position = 'right') // Set the position of the upload button. + ->uploadProgressIndicatorPosition($position = 'right') // Set the position of the upload progress indicator. + ->visibility($visibility = 'public'); // Set the visibility of uploaded files. +``` + +> Please note, it is the responsibility of the developer to delete these files from the disk if they are removed, as Filament is unaware if they are depended on elsewhere. One way to do this automatically is observing a [model event](https://laravel.com/docs/eloquent#events). + +> To customize Livewire's default file upload validation rules, please refer to its [documentation](https://laravel-livewire.com/docs/file-uploads#global-validation). + +> Available values for the position methods can be found on [Filepond's website](https://pqina.nl/filepond/docs/patterns/api/filepond-instance#styles). + +> Support for multiple file uploads is coming soon. For more information, please see our [Development Roadmap](/docs/roadmap). + +### Key-value {#fields-key-value} + +```php +KeyValue::make($name) + ->addButtonLabel($label) // Set the add button label. It supports localization strings. + ->deleteButtonLabel($label) // Set the delete button label. It supports localization strings. + ->disableAddingRows($state = false) // Disable the addition of rows. + ->disableDeletingRows($state = false) // Disable the deletion of rows. + ->disableEditingKeys($state = false) // Disable the editing of keys. + ->keyLabel($label) // Set the key field label label. It supports localization strings. + ->keyPlaceholder($placeholder) // Set the key field placeholder. It supports localization strings. + ->sortable($sortable = true) // Allow the keys to be sorted using drag and drop. + ->sortButtonLabel($label) // Set the sort button label. It supports localization strings. + ->valueLabel($label) // Set the value field label label. It supports localization strings. + ->valuePlaceholder($placeholder); // Set the value field placeholder. It supports localization strings. +``` + +### Markdown Editor {#fields-markdown-editor} + +```php +MarkdownEditor::make($name) + ->attachmentDisk($disk) // Set a custom disk that uploaded attachments should be read from and written to. + ->attachmentDirectory($directory) // Set a custom directory that uploaded attachments should be written to. + ->autofocus() // Autofocus the field. + ->disableAllToolbarButtons() // Disable all toolbar buttons. + ->disableToolbarButtons($buttons = []) // Disable toolbar buttons. See below for options. + ->enableToolbarButtons($buttons = []) // Enable toolbar buttons. See below for options. + ->placeholder($placeholder); // Set the placeholder for when the field is empty. It supports localization strings. +``` + +#### Toolbar Buttons {#fields-markdown-editor-toolbar-buttons} + +``` +attachFiles +bold +bullet +code +italic +link +number +preview +strike +write +``` + +### Rich Editor {#fields-rich-editor} + +```php +RichEditor::make($name) + ->attachmentDisk($disk) // Set a custom disk that uploaded attachments should be read from and written to. + ->attachmentDirectory($directory) // Set a custom directory that uploaded attachments should be written to. + ->autofocus() // Autofocus the field. + ->disableAllToolbarButtons() // Disable all toolbar buttons. + ->disableToolbarButtons($buttons = []) // Disable toolbar buttons. See below for options. + ->enableToolbarButtons($buttons = []) // Enable toolbar buttons. See below for options. + ->placeholder($placeholder); // Set the placeholder for when the field is empty. It supports localization strings. +``` + +#### Toolbar Buttons {#fields-rich-editor-toolbar-buttons} + +``` +attachFiles +bold +bullet +code +heading +italic +link +number +quote +redo +strike +subheading +title +undo +``` + +### Select {#fields-select} + +```php +Select::make($name) + ->autofocus() // Autofocus the field. + ->emptyOptionsMessage($message) // Set the message for when there are no options available to pick from. It supports localization strings. + ->noSearchResultsMessage($message) // Set the message for when there are no option search results. It supports localization strings. + ->options($options = []) // Set the key-value array of available options to pick from. + ->placeholder($placeholder); // Set the placeholder for when the field is empty. It supports localization strings. +``` + +> If you're looking to use a select for a `belongsTo()` relationship, please check out the [`BelongsToSelect` resource field](/docs/resources#relations-single). + +### Tags Input {#fields-tags-input} + +```php +TagsInput::make($name) + ->autofocus() // Autofocus the field. + ->placeholder($placeholder) // Set the placeholder for when the new tag field is empty. It supports localization strings. + ->separator($separator = ','); // Set the separator that should be used between tags. +``` + +### Textarea {#fields-textarea} + +```php +Textarea::make($name) + ->autocomplete($autocomplete = 'on') // Set up autocomplete for the field. + ->autofocus() // Autofocus the field. + ->cols($cols) // The number of columns wide the textarea is. + ->disableAutocomplete() // Disable autocomplete for the field. + ->placeholder($placeholder); // Set the placeholder for when the field is empty. It supports localization strings. + ->rows($rows) // The number of rows tall the textarea is. +``` + +### Text Input {#fields-text-input} + +```php +TextInput::make($name) + ->autocomplete($autocomplete = 'on') // Set up autocomplete for the field. + ->autofocus() // Autofocus the field. + ->disableAutocomplete() // Disable autocomplete for the field. + ->email() // Require a valid email address to be provided. + ->max($max) // Set a maximum numeric value to be provided. + ->min($min) // Set a minimum numeric value to be provided. + ->numeric() // Require a numeric value to be provided. + ->password() // Obfuscate the field's value. + ->placeholder($placeholder) // Set the placeholder for when the field is empty. It supports localization strings. + ->postfix($postfix) // Set a postfix label to be displayed after the input. + ->prefix($prefix) // Set a prefix label to be displayed before the input. + ->tel() // Require a valid telephone number to be provided. + ->type($type = 'text') // Set the input's HTML type. + ->url(); // Require a valid URL to be provided. +``` + +### Toggle {#fields-toggle} + +The `onIcon()` and `offIcon()` methods support the name of any Blade icon component, and passes a set of formatting classes to it. By default, the [Blade Heroicons](https://github.com/blade-ui-kit/blade-heroicons) package is installed, so you may use the name of any [Heroicon](https://heroicons.com) out of the box. However, you may create your own custom icon components or install an alternative library if you wish. + +```php +Toggle::make($name) + ->autofocus() // Autofocus the field. + ->inline() // Render the toggle inline with its label. + ->offIcon($icon) // Set the icon that should be displayed when the toggle is off. + ->onIcon($icon) // Set the icon that should be displayed when the toggle is on. + ->stacked(); // Render the toggle under its label. +``` + +## Validation {#validation} + +Filament provides a number of validation methods that can be applied to fields. Please refer to the [Laravel Validation docs](https://laravel.com/docs/validation#available-validation-rules) if you are unsure about any of these. + +```php +->acceptedFileTypes($types = []) // Accepts an array of mime types, file upload field only. +->confirmed($field = '{field name}Confirmation') // Text-based fields only. +->email() // Text input field only. +->image() // File upload field only. +->max($value) // Text input field only. +->maxDate($date) // Date-based fields only. +->maxLength($length) // Text-based fields only. +->maxSize($size) // In kilobytes, file upload field only. +->min($value) // Text input field only. +->minDate($date) // Date-based fields only. +->minLength($length) // Text-based fields only. +->minSize($size) // In kilobytes, file upload field only. +->nullable() // Applied to all fields by default. +->numeric() // Text input field only. +->required() +->requiredWith() +->same($field) // Text-based fields only. +->tel() // Text input field only. +->unique($table, $column = '{field name}', $exceptCurrentRecord = false) +->url() // Text input field only. +``` + +You may apply additional custom validation rules to any field using the `rules()` method: + +```php +Field($name) + ->rules(['alpha', 'ends_with:a']); +``` + +> Please note: when specifying **resource** field names in custom validation rules, you must prefix them with `record.`. + +## Layout {#layout} + +### Grid {#layout-grid} + +By default, form fields are stacked on top of each other in one column. To change this across the entire form, you may chain the `columns()` method onto the form object: + +```php +use Filament\Resources\Forms\Form; + +public static function form(Form $form) +{ + return $form + ->schema([ + // ... + ]) + ->columns(2); +} +``` + +Alternatively, you may customize the number of columns for a small part of the form using a Grid component: + +```php +use Filament\Resources\Forms\Components; +use Filament\Resources\Forms\Form; + +public static function form(Form $form) +{ + return $form + ->schema([ + // ... + Components\Grid::make([ + // ... + ])->columns(2), + ]); +} +``` + +### Section {#layout-section} + +You may want to separate your fields into sections, each with a heading and subheading. To do this, you can use a Section component: + +```php +use Filament\Resources\Forms\Components; +use Filament\Resources\Forms\Form; + +public static function form(Form $form) +{ + return $form + ->schema([ + // ... + Components\Section::make( + 'Heading', + 'Subheading', + [ + // ... + ], + ), + ]); +} +``` + +If you don't require a subheading, you may use the `schema()` method to declare the section schema late: + +```php +use Filament\Resources\Forms\Components; +use Filament\Resources\Forms\Form; + +public static function form(Form $form) +{ + return $form + ->schema([ + // ... + Components\Section::make('Heading') + ->schema([ + // ... + ]), + ]); +} +``` + +You may use the `columns()` method to easily create a [grid](#layout-grid) within the section: + +```php +use Filament\Resources\Forms\Components; +use Filament\Resources\Forms\Form; + +public static function form(Form $form) +{ + return $form + ->schema([ + // ... + Components\Section::make( + 'Heading', + 'Subheading', + [ + // ... + ], + )->columns(2), + ]); +} +``` + +Sections may be `collapsible()` to optionally hide content in long forms: + +```php +use Filament\Resources\Forms\Components; +use Filament\Resources\Forms\Form; + +public static function form(Form $form) +{ + return $form + ->schema([ + // ... + Components\Section::make( + 'Heading', + 'Subheading', + [ + // ... + ], + )->collapsible(), + ]); +} +``` + +You may `collapse()` sections by default: + +```php +use Filament\Resources\Forms\Components; +use Filament\Resources\Forms\Form; + +public static function form(Form $form) +{ + return $form + ->schema([ + // ... + Components\Section::make( + 'Heading', + 'Subheading', + [ + // ... + ], + )->collapsed(), + ]); +} +``` + +### Fieldset {#layout-fieldset} + +You may want to group fields into a Fieldset. Each fieldset has a label, a border, and a two-column grid: + +```php +use Filament\Resources\Forms\Components; +use Filament\Resources\Forms\Form; + +public static function form(Form $form) +{ + return $form + ->schema([ + // ... + Components\Fieldset::make( + 'Label', + [ + // ... + ], + ), + ]); +} +``` + +You may use the `columns()` method to customize the number of columns in the fieldset: + +```php +use Filament\Resources\Forms\Components; +use Filament\Resources\Forms\Form; + +public static function form(Form $form) +{ + return $form + ->schema([ + // ... + Components\Fieldset::make( + 'Label', + [ + // ... + ], + )->columns(3), + ]); +} +``` + +### Tabs {#layout-tabs} + +Some forms can be long and complex. You may want to use tabs to reduce the number that are available at once: + +```php +use Filament\Resources\Forms\Components; +use Filament\Resources\Forms\Form; + +public static function form(Form $form) +{ + return $form + ->schema([ + // ... + Components\Tabs::make('Label') + ->tabs([ + Components\Tab::make( + 'First Tab', + [ + // ... + ], + ), + Components\Tab::make( + 'Second Tab', + [ + // ... + ], + ), + ]), + ]); +} +``` + +You may use the `columns()` method to easily create a [grid](#layout-grid) within the tab: + +```php +use Filament\Resources\Forms\Components; +use Filament\Resources\Forms\Form; + +public static function form(Form $form) +{ + return $form + ->schema([ + // ... + Components\Tabs::make('Label') + ->tabs([ + Components\Tab::make( + 'Tab', + [ + // ... + ], + )->columns(2), + ]), + ]); +} +``` + +### Group {#layout-group} + +Groups are used to wrap multiple associated form components. They have no effect on the form visually, but are useful for applying modifications to many fields at once: + +```php +use Filament\Resources\Forms\Components; +use Filament\Resources\Forms\Form; + +public static function form(Form $form) +{ + return $form + ->schema([ + // ... + Components\Group::make([ + // ... + ]), + ]); +} +``` + +### Placeholder {#layout-placeholder} + +Placeholders can be used to render text-only "fields" within your forms. Each placeholder has a value, which is cannot be changed by the user. + +```php +use Filament\Resources\Forms\Components; +use Filament\Resources\Forms\Form; + +public static function form(Form $form) +{ + return $form + ->schema([ + // ... + Components\Placeholder::make('website', 'filamentadmin.com'), + ]); +} +``` + +## Dependent Fields {#dependent-fields} + +Dependent fields are fields that are modified based on the value of another. For example, you could show a group of fields based on the value of a Select. + +The first step to setting up dependent fields is to apply the `dependable()` method to the field that should be watched for changes. When the value of this field is changed, the whole form will reload: + +```php +Components\Select::make('type') + ->placeholder('Select a type') + ->options([ + 'individual' => 'Individual', + 'organization' => 'Organization', + ]) + ->dependable(); +``` + +To modify fields based on the value of another, you may use the `when()` method. The first argument to this method is a callback that evaluates the `$record` object, and returns true or false depending on if the modifications should be applied. The second argument makes modifications to the current field. If no second argument is supplied, the field will only be shown when the callback in the first argument is true: + +In this example, the fields in the [group](#layout-group) will only be shown when the `type` field is set to `individual`: + +```php +Components\Group::make([ + // ... +])->when(fn ($record) => $record->type === 'individual'); +``` + +Here, the `company_number` field will only be required when the `type` field is set to `organization`: + +```php +Components\TextInput::make('company_number') + ->when( + fn ($record) => $record->type === 'organization', + fn ($field) => $field->required(), + ); +``` + +## Context Customization {#context-customization} + +You may customize forms based on the page they are used. To do this, you can chain the `only()` or `except()` methods onto any form component. + +```php +use App\Filament\Resources\CustomerResource\Pages; +use Filament\Resources\Forms\Components; +use Filament\Resources\Forms\Form; + +public static function form(Form $form) +{ + return $form + ->schema([ + Components\TextInput::make('name') + ->required() + ->only(Pages\CreateCustomer::class), + ]); +} +``` + +In this example, the `name` field will `only()` be displayed on the `CreateCustomer` page. + +```php +use App\Filament\Resources\CustomerResource\Pages; +use Filament\Resources\Forms\Components; +use Filament\Resources\Forms\Form; + +public static function form(Form $form) +{ + return $form + ->schema([ + Components\TextInput::make('name') + ->except(Pages\EditCustomer::class, fn ($field) => $field->required()), + ]); +} +``` + +In this example, the `name` field will be required, `except()` on the `EditCustomer` page. + +This is an incredibly powerful pattern, and allows you to completely customize a form contextually by chaining as many methods as you wish to the callback. + +## Developing Custom Components {#custom-development} + +To create a custom field, you may use: + +```bash +php artisan make:filament-field CountrySelect --resource +``` + +This will create a new custom class and view for your field, which you may use in a form in the same way as any other field. + +To create a generic form component, which may be commonly used for custom layouts, you may generate a class and view using: + +```bash +php artisan make:filament-form-component SidebarLayout --resource +``` + +Alternatively, simple custom layouts may be created using a `View` component, and passing the name of a `$view` in your app: + +```php +Components\View::make($view); +``` diff --git a/docs/admin/index.md b/docs/admin/index.md new file mode 100644 index 0000000000..d66e77f3d3 --- /dev/null +++ b/docs/admin/index.md @@ -0,0 +1,148 @@ +--- +title: Getting Started +description: +extends: _layouts.documentation +section: content +toc: | + - [Configuration](#configuration) + - [Users](#users) + - [Disabling the Default Migrations](#users-disabling-default-migrations) + - [Stubs](#stubs) + - [Upgrade Guide](#upgrade-guide) +--- + +# Getting Started + +

Filament is a content management framework for rapidly building a beautiful administration interface designed for humans.

+ +> Filament requires Laravel 8.x or higher, and PHP 7.4 or higher. + +Installation: + +```bash +composer require filament/filament +php artisan migrate +``` + +Create an administrator account for your admin panel by running + +```bash +php artisan make:filament-user +``` + +and answering the input prompts. Administrators have access to all areas of Filament, and are able to manage other users. + +Once you have a user account, you can sign in to the admin panel by visiting `/admin` in your browser. + +To start building your admin panel, [create a resource](/docs/resources). + +## Configuration {#configuration} + +If you'd like to expose advanced configuration options for Filament, you may publish its configuration file: + +```bash +php artisan vendor:publish --tag=filament-config +``` + +> If you have published the configuration file for Filament, please ensure that you republish it when you upgrade. + +## Users {#users} + +By default, Filament includes its own authentication guard and users table that is completely separate from your app's users table. This enables you to get up and running with Filament at record speed. + +Some projects may choose to allow their app users access to Filament. In this case, they may customize the auth guard that Filament uses by [configuring](#configuration) `auth.guard` to the name of your default guard, typically `web`. + +The next step is to prepare your `User` model for use with Filament. Implement the `Filament\Models\Contracts\FilamentUser` interface, and apply the `Filament\Models\Concerns\IsFilamentUser` trait. These provide Filament with an API that it can use to interact with your existing user data: + +```php +group === 'Filament Users'; +} +``` + +Filament implements authorization features in its default users table. Admin users are able to access all areas of Filament, and manage other users. Users may have roles, which are associated with certain permissions in your admin panel. + +To configure columns to granting users admin permissions and roles, you may set the static `$filamentAdminColumn` and `$filamentRolesColumn` properties on your class: + +```php +public static $filamentAdminColumn = 'is_filament_admin'; // The name of a boolean column in your database. + +public static $filamentRolesColumn = 'filament_roles'; // The name of a JSON column in your database. +``` + +To disable roles and admin features, just emit these properties from your class. + +Alternatively, you may specify custom logic for calculating if a user has admin permissions by overriding the `isFilamentAdmin()` method: + +```php +public function isFilamentAdmin() +{ + return $this->email === 'dan@danharrin.com'; +} +``` + +### Disabling the Default Migrations {#users-disabling-default-migrations} + +You may wish to prevent the migration for the default users table from being registered. You may do this by calling: + +```php +use Filament\Filament; + +Filament::ignoreMigrations(); +``` + +from the `register()` method of your `AppServiceProvider`. + +## Stubs {#stubs} + +Filament commands use stubs as templates when new files in your project. You may customize these stubs by publishing them to your app: + +```bash +php artisan vendor:publish --tag=filament-stubs +``` + +> If you have published the stubs for Filament, please ensure that you republish them when you upgrade. + +## Upgrade Guide {#upgrade-guide} + +To upgrade Filament to the latest version, you may run: + +```bash +php artisan filament:upgrade +``` + +or the following commands manually: + +```bash +composer update +php artisan migrate +php artisan livewire:discover +php artisan route:clear +php artisan view:clear +``` diff --git a/docs/admin/navigation.md b/docs/admin/navigation.md new file mode 100644 index 0000000000..38ac67b32e --- /dev/null +++ b/docs/admin/navigation.md @@ -0,0 +1,36 @@ +--- +title: Navigation +description: +extends: _layouts.documentation +section: content +--- + +# Navigation + +By default, Filament will register navigation items for each of your [resources](/docs/resources) and [custom pages](/docs/pages). These classes contain static properties that you can override, to configure that navigation item and its order: + +```php +public static $icon = 'heroicon-o-document-text'; + +public static $navigationLabel = 'Custom Navigation Label'; + +public static $navigationSort = 3; +``` + +The `$icon` supports the name of any Blade component, and passes a set of formatting classes to it. By default, the [Blade Heroicons](https://github.com/blade-ui-kit/blade-heroicons) package is installed, so you may use the name of any [Heroicon](https://heroicons.com) out of the box. However, you may create your own custom icon components or install an alternative library if you wish. + +Alternatively, you may completely override the static `navigationItems()` method on the class and register as many custom navigation items as you require: + +```php +use Filament\NavigationItem; + +public static function navigationItems() +{ + return [ + NavigationItem::make($label, $url) + ->activeRule($activeRule) + ->icon($icon = 'heroicon-o-document-text') + ->sort($sort = 0), + ]; +} +``` diff --git a/docs/admin/pages.md b/docs/admin/pages.md new file mode 100644 index 0000000000..f6dfc82959 --- /dev/null +++ b/docs/admin/pages.md @@ -0,0 +1,75 @@ +--- +title: Custom Pages +description: +extends: _layouts.documentation +section: content +toc: | + - [Authorization](#authorization) + - [Customization](#customization) +--- + +# Custom Pages + +

Filament allows you to create completely custom pages for the admin panel.

+ +To create a new page, you can use: + +```bash +php artisan make:filament-page Settings +``` + +This command will create two files - a page class in the `/Pages` directory of the Filament directory, and a view in the `/pages` directory of the Filament views directory. + +Page classes are essentially [Laravel Livewire](https://laravel-livewire.com) components with custom integration utilities for use with Filament. + +## Authorization {#authorization} + +You may create roles for users of Filament that allow them to access specific pages. You may create a `Manager` role using: + +```php +php artisan make:filament-role Manager +``` + +Administrators will now be able to assign this role to any Filament user using the admin panel. + +To only allow users with the `Manager` role to access this page, declare so in the static `authorization()` method: + +```php +use App\Filament\Roles; + +public static function authorization() +{ + return [ + Roles\Manager::allow(), + ]; +} +``` + +You may authorize as many roles as you wish. + +> Please note: administrators will always have full access to every page in your admin panel. + +You may want to only deny users with the `Manager` role from accessing this page. To do this, you may use the static `deny()` method instead: + +```php +use App\Filament\Roles; + +public static function authorization() +{ + return [ + Roles\Manager::deny(), + ]; +} +``` + +## Customization {#customization} + +Filament will automatically generate a title, navigation label and URL (slug) for your page based on its name. You may override it using static properties of your page class: + +```php +public static $label = 'Custom Navigation Label'; + +public static $slug = 'custom-url-slug'; + +public static $title = 'Custom Page Title'; +``` diff --git a/docs/admin/plugin-development.md b/docs/admin/plugin-development.md new file mode 100644 index 0000000000..7be2a9e5be --- /dev/null +++ b/docs/admin/plugin-development.md @@ -0,0 +1,219 @@ +--- +title: Plugin Development +description: +extends: _layouts.documentation +section: content +toc: | + - [Registering Plugins](#registering-plugins) + - [Application Plugins](#application-plugins) + - [Distributed Plugins](#distributed-plugins) + - [Registering Resources](#registering-resources) + - [Registering Pages](#registering-pages) + - [Registering Widgets](#registering-widgets) + - [Registering Roles](#registering-roles) + - [Frontend Assets](#frontend-assets) + - [Stylesheets](#stylesheets) + - [Scripts](#scripts) + - [Providing Data to the Frontend](#providing-data-to-the-frontend) +--- + +# Plugin Development + +

+ Plugins can be used to extend Filament's default behaviour and create reusable modules for use in multiple applications. +

+ +To create a new plugin, extend the `Filament\PluginServiceProvider` class provided by Filament: + +```php +use Filament\PluginServiceProvider; + +class ExampleServiceProvider extends PluginServiceProvider +{ + // +} +``` + +## Registering Plugins {#registering-plugins} + +### Application Plugins {#application-plugins} + +If you're developing a plugin for a specific application, you should register the new service provider in your `config/app.php` file: + +```php +return [ + + 'providers' => [ + //... + + \App\Providers\ExampleServiceProvider::class, + ] + +]; +``` + +Laravel will load your service provider when bootstrapping and your plugin will be initialised. + +### Distributed Plugins {#distributed-plugins} + +Much like a normal Laravel package, you should add your service provider's fully qualified class name to the `extra.laravel.providers` array in your package's `composer.json` file: + +```json +{ + "extra": { + "laravel": { + "providers": [ + "Vendor\\Package\\ExampleServiceProvider" + ] + } + } +} +``` + +This will ensure your service provider is automatically loaded by Laravel when the package is installed. + +## Resources {#registering-resources} + +To register a custom resource, add the fully qualified class name to the `protected $resources` array in your service provider. + +```php +use Vendor\Package\Resources\CustomResource; + +class ExampleServiceProvider extends PluginServiceProvider +{ + protected $resources = [ + CustomResource::class, + ]; +} +``` + +Filament will automatically register your `Resource` and ensure that Livewire can discover it. + +## Pages {#registering-pages} + +To register a custom page, add the fully qualified class name to the `protected $pages` array in your service provider. + +```php +use Vendor\Package\Pages\CustomPage; + +class ExampleServiceProvider extends PluginServiceProvider +{ + protected $pages = [ + CustomPage::class, + ]; +} +``` + +Filament will automatically register your `Page` and ensure that Livewire can discover it. + +## Widgets {#registering-widgets} + +To register a custom widget, add the fully qualified class name to the `protected $widgets` array in your service provider. + +```php +use Vendor\Package\Widgers\CustomWidget; + +class ExampleServiceProvider extends PluginServiceProvider +{ + protected $widgets = [ + CustomWidget::class, + ]; +} +``` + +Filament will automatically register your `Widget` and ensure that Livewire can discover it. + +## Roles {#registering-roles} + +To register a custom role, add the fully qualified class name to the `protected $roles` array in your service provider. + +```php +use Vendor\Package\Roles\CustomRole; + +class ExampleServiceProvider extends PluginServiceProvider +{ + protected $roles = [ + CustomRole::class, + ]; +} +``` + +Filament will automatically register your `Role` and ensure it's available for use throughout your application. + +## Frontend Assets {#frontend-assets} + +Filament plugins can also register their own frontend assets. These assets will be included on all Filament related pages, allowing you to use your own CSS and JavaScript. + +### Stylesheets {#stylesheets} + +To include a custom stylesheet, add it to the `protected $styles` property in your service provider. You should use a unique name as the key and the URL to the stylesheet as the value. + +```php +class ExampleServiceProvider extends PluginServiceProvider +{ + protected $styles = [ + 'my-package-styles' => '/vendor/my-package/css/style.css', + ]; +} +``` + +If you need to dynamically generate the key or value, you can overwrite the `protected styles()` method and return an `array` of key/value pairs, just like the `$styles` property: + +```php +class ExampleServiceProvider extends PluginServiceProvider +{ + protected function styles() + { + return [ + 'my-package-styles' => asset('/vendor/my-package/css/style.css'), + ]; + } +} +``` + +### Scripts {#scripts} + +To include a custom script, add it to the `protected $scripts` property in your service provider. You should use a unique name as the key and the URL to the script as the value. + +```php +class ExampleServiceProvider extends PluginServiceProvider +{ + protected $scripts = [ + 'my-package-scripts' => '/vendor/my-package/js/main.js' + ]; +} +``` + +If you need to dynamically generate the key or value, you can overwrite the `protected scripts()` method and return an `array` of key/value pairs, just like the `$scripts` property: + +```php +class ExampleServiceProvider extends PluginServiceProvider +{ + protected function scripts() + { + return [ + 'my-package-scripts' => asset('/vendor/my-package/js/main.js'), + ]; + } +} +``` + +### Providing Data to the Frontend {#providing-data-to-the-frontend} + +Whilst building your plugin, you might find the need to generate some data on the server and access it on the client. + +To do this, add a new `protected function scriptData()` to your service provider and return an array of `string` keys and values that can be passed to converted into JSON. + +```php +class ExampleServiceProvider extends PluginServiceProvider +{ + protected function scriptData() + { + return [ + 'user' => Auth::user(), + ]; + } +} +``` + +> Filament uses the `@json` Blade directive to convert your script data into a valid JavaScript object. You can find out more about this directive in the [official Laravel documentation](https://laravel.com/docs/blade#rendering-json). \ No newline at end of file diff --git a/docs/admin/resources.md b/docs/admin/resources.md new file mode 100644 index 0000000000..e1d557aea2 --- /dev/null +++ b/docs/admin/resources.md @@ -0,0 +1,411 @@ +--- +title: Resources +description: +extends: _layouts.documentation +section: content +toc: | + - [Forms](#forms) + - [Relations](#relations) + - [Managing Single Related Records](#relations-single) + - [Managing Multiple Related Records](#relations-multiple) + - [Tables](#tables) + - [Pages](#pages) + - [Customizing Default Pages](#pages-customization) + - [Hooks](#pages-customization-hooks) + - [Custom Pages](#pages-custom) + - [Authorization](#authorization) +--- + +# Resources + +

Resources are static classes that describe how administrators should be able to interact with data from your app. They are associated with Eloquent models from your app.

+ +To create a resource for the `App\Models\Customer` model: + +```bash +php artisan make:filament-resource Customer +``` + +This will create several files in the `app/Filament/Resources` directory: + +``` +. ++-- CustomerResource.php ++-- CustomerResource +| +-- Pages +| | +-- CreateCustomer.php +| | +-- EditCustomer.php +| | +-- ListCustomers.php +``` + +Your new resource class lives in `CustomerResource.php`. Resource classes register [forms](#forms), [tables](#tables), [authorization settings](#authorization), and [pages](#pages) associated with that model. + +The classes in the `Pages` directory are used to customize the pages in the admin panel that interact with your resource. + +By default, the model associated with your resource is guessed based on the class name of the resource. You may set the static `$model` property to disable this behaviour: + +```php +public static $model = Customer::class; +``` + +A label for this resource is generated based on the name of the resource's model. It's used the navigation menu and to display breadcrumbs. You may customize it using the static `$label` property: + +```php +public static $label = 'customer'; +``` + +## Forms {#forms} + +Resource classes contain a static `form()` method that is used to customize the forms to create and update resource records. + +```php +use Filament\Resources\Forms\Form; + +public static function form(Form $form) +{ + return $form + ->schema([ + // ... + ]); +} +``` + +The `schema()` method is used to define the structure of your form. It is an array of components, in the order they should appear in your form. + +For more information, please see the page on [Building Forms](/docs/forms). + +## Relations {#relations} + +### Managing Single Related Records {#relations-single} + +The `Filament\Resources\Forms\Components\BelongsToSelect` field can be used in resource form schemas to create a select element with options to search and select a related record. It has the same methods available as [`Filament\Resources\Forms\Components\Select`](/docs/forms#fields-select), and others to define the relationship and column name that should be used: + +```php +Components\BelongsToSelect::make('category_id') + ->relationship('category', 'name'); +``` + +This example assumes the following: + +- A `category_id` foreign key column exists on your parent model. +- A `belongsTo()` `category` relationship on your parent model. +- A `name` column on your category model that can be used to render the list of categories to select from. + +Sometimes, having a lot of related records as options can cause strain on your web browser. By default, options will only load when you start typing a search. To change this, you may `preload()` a select field with options. Please only do this if you are certain that there are only a few related records to choose from: + +```php +Components\BelongsToSelect::make('category_id') + ->relationship('category', 'name') + ->preload(); +``` + +You may also customize the [Query Builder](https://laravel.com/docs/queries) used to get search results by specifying a callback in the third parameter of the `relationship()` method. + +```php +Components\BelongsToSelect::make('category_id') + ->relationship('category', 'name', function ($query) { + return $query->where('is_featured', true); + }); +``` + +This example will only include featured categories in search results. + +### Managing Multiple Related Records {#relations-multiple} + +Relation managers are components that allow administrators to list, create, attach, edit, detach and delete related records without leaving the parent record's edit page. Resource classes contain a static `relations()` method that is used to register relation managers for your resource. + +To create a relation manager, you can use: + +```bash +php artisan make:filament-relation-manager CustomerResource orders +``` + +This will create a `CustomerResource/RelationManagers/OrdersRelationManager.php` file. This contains a class where you are able to define a [form](/docs/forms) and [table](/docs/tables) for your relation manager. The relation manager will interact with the `orders` relationship on your parent model. + +You must set the primary column of related records using the static `$primaryColumn` property on your new relation manager class. The primary column is used to identify related records quickly. This could be a user's `name`, or a blog post's `title`. + +```php +columns([ + // ... + ]) + ->filters([ + // ... + ]); +} +``` + +The `columns()` method is used to define the columns in your table. It is an array of column objects, in the order they should appear in your table. + +Filters are predefined scopes that administrators can use to filter records in your table. The `filters()` method is used to register these. + +For more information, please see the page on [Building Tables](/docs/tables). + +## Pages {#pages} + +Pages are classes that are associated with a resource. They are essentially [Laravel Livewire](https://laravel-livewire.com) components with custom integration utilities for use with Filament. + +Page class files are in the `/Pages` directory of your resource directory. + +By default, resources are generated with three pages: + +- List has a [table](#tables) for displaying, searching and deleting resource records. From here, you are able to access the create and edit pages. It is routed to `/`. +- Create has a [form](#forms) that is able to create a resource record. It is routed to `/create`. +- Edit has a [form](#forms) that is able to update a resource record, along with the [relation managers](#relations-multiple) registered to your resource. It is routed to `/{record}/edit`. + +### Customizing Default Pages {#pages-customization} + +You are able to customize text used in the default pages by overriding properties on the page class. To see the options available, check the static properties defined in the parent class of each default page. + +For further customization opportunities, you can override the static `$view` property on your page to a custom view in your app: + +```php +public static $view = 'customers.list-records'; +``` + +#### Hooks {#pages-customization-hooks} + +Hooks may be used to customize the behaviour of a default page. To set up a hook, create a protected method on the page class with the name of the hook: + +```php +protected function beforeSave() +{ + // ... +} +``` + +In this example, the code in the `beforeSave()` method will be called before the data in the form is saved to the database. + +There are several available hooks for the create and edit pages: + +```php +use Filament\Resources\Pages\CreateRecord; + +class CreateCustomer extends CreateRecord +{ + // ... + + protected function beforeFill() + { + // Runs before the form fields are populated with their default values. + } + + protected function afterFill() + { + // Runs after the form fields are populated with their default values. + } + + protected function beforeValidate() + { + // Runs before the form fields are validated when the form is submitted. + } + + protected function afterValidate() + { + // Runs after the form fields are validated when the form is submitted. + } + + protected function beforeCreate() + { + // Runs before the form fields are saved to the database. + } + + protected function afterCreate() + { + // Runs after the form fields are saved to the database. + } +} +``` + +```php +use Filament\Resources\Pages\EditRecord; + +class EditCustomer extends EditRecord +{ + // ... + + protected function beforeFill() + { + // Runs before the form fields are populated from the database. + } + + protected function afterFill() + { + // Runs after the form fields are populated from the database. + } + + protected function beforeValidate() + { + // Runs before the form fields are validated when the form is saved. + } + + protected function afterValidate() + { + // Runs after the form fields are validated when the form is saved. + } + + protected function beforeSave() + { + // Runs before the form fields are saved to the database. + } + + protected function afterSave() + { + // Runs after the form fields are saved to the database. + } + + protected function beforeDelete() + { + // Runs before the record is deleted. + } + + protected function afterDelete() + { + // Runs after the record is deleted. + } +} +``` + +### Custom Pages {#pages-custom} + +Filament allows you to create completely custom pages for resources. To create a new page, you can use: + +```bash +php artisan make:filament-page SortCustomers --resource=CustomerResource +``` + +This command will create two files - a page class in the `/Pages` directory of your resource directory, and a view in the `/pages` directory of the resource views directory. + +You must register custom pages to a route in the static `routes()` method of your resource: + +```php +public static function routes() +{ + return [ + // ... + Pages\SortCustomers::routeTo('/sort', 'sort'), + ]; +} +``` + +The first parameter of the `routeTo()` method is the path of the route, and the second is its [name](https://laravel.com/docs/routing#named-routes). Any [parameters](https://laravel.com/docs/routing#route-parameters) defined in the route's path will be available to the page class, in an identical way to [Livewire](https://laravel-livewire.com/docs/rendering-components#route-params). + +To generate a URL for a resource route, you may call the static `generateUrl()` method on the page class: + +```php +SortCustomers::generateUrl($parameters = [], $absolute = true); +``` + +## Authorization {#authorization} + +For authorization, Filament will observe any [model policies](https://laravel.com/docs/authorization#creating-policies) that are registered in your app. The `viewAny` action may be used to completely disable resources and remove them from the navigation menu. + +Filament also includes a powerful role-based authorization system, which is set up out of the box with the default users table. You may also implement roles functionality in a [custom users table](/docs#users). + +You may create roles, such as `Manager`, using: + +```php +php artisan make:filament-role Manager +``` + +Administrators will now be able to assign this role to any Filament user through the admin panel. + +To only allow users with the `Manager` role to access a resource, declare so in the static `authorization()` method: + +```php +use App\Filament\Roles; + +public static function authorization() +{ + return [ + Roles\Manager::allow(), + ]; +} +``` + +You may authorize as many roles as you wish. + +> Please note: administrators will always have full access to every resource in your admin panel. + +You may want to only deny users with the `Manager` role from accessing this resource. To do this, you may use the static `deny()` method instead: + +```php +use App\Filament\Roles; + +public static function authorization() +{ + return [ + Roles\Manager::deny(), + ]; +} +``` + +You may specify `only()` certain actions that roles have access to. These follow the same naming conventions as methods in a [policy](https://laravel.com/docs/authorization#policy-methods). + +```php +use App\Filament\Roles; + +public static function authorization() +{ + return [ + Roles\Manager::allow()->only(['viewAny', 'create']), + ]; +} +``` + +There is also the possibility to allow access to all actions `except()` those specified: + +```php +use App\Filament\Roles; + +public static function authorization() +{ + return [ + Roles\Manager::allow()->except(['delete']), + ]; +} +``` \ No newline at end of file diff --git a/docs/admin/roadmap.md b/docs/admin/roadmap.md new file mode 100644 index 0000000000..07d4704d3e --- /dev/null +++ b/docs/admin/roadmap.md @@ -0,0 +1,35 @@ +--- +title: Development Roadmap +description: +extends: _layouts.documentation +section: content +--- + +# Development Roadmap + +## Additional Form Field Types + +- JSON and relationship-based multi-select +- JSON array-powered field repeater +- Block-based page builder + +## Table Filters + +- Filter parameters. +- Applying more than one filter at once. + +## Additional Table Column Types + +- Tags + +## More Relation Types + +- Relation manager support for pivot table sorting. +- Polymorphic select. +- `hasOne()` select. + +## Widget Templates + +- Stats +- Quick actions +- Charts \ No newline at end of file diff --git a/docs/admin/tables.md b/docs/admin/tables.md new file mode 100644 index 0000000000..266de43d21 --- /dev/null +++ b/docs/admin/tables.md @@ -0,0 +1,272 @@ +--- +title: Building Tables +description: +extends: _layouts.documentation +section: content +toc: | + - [Columns](#columns) + - [Displaying Relationship Data](#columns-displaying-relationship-data) + - [Calling Actions](#columns-calling-actions) + - [Boolean](#columns-boolean) + - [Icon](#columns-icon) + - [Image](#columns-image) + - [Text](#columns-text) + - [Developing Custom Column Types](#columns-custom-development) + - [Filters](#filters) + - [Reusable Filters](#filters-reusable) + - [Context Customization](#context-customization) +--- + +# Building Tables + +

Filament includes a table builder which can be used to create interactive tables in the admin panel.

+ +Tables have [columns](#columns) and [filters](#filters), which are defined in two methods on the table object. + +Here is an example table configuration for a `CustomerResource`: + +```php +use Filament\Resources\Tables\Columns; +use Filament\Resources\Tables\Filter; +use Filament\Resources\Tables\Table; + +public static function table(Table $table) +{ + return $table + ->columns([ + Columns\Text::make('name')->primary(), + Columns\Text::make('email')->url(fn ($customer) => "mailto:{$customer->email}"), + Columns\Text::make('type') + ->options([ + 'individual' => 'Individual', + 'organization' => 'Organization', + ]), + Columns\Text::make('birthday')->date(), + Columns\Boolean::make('is_active')->label('Active?'), + ]) + ->filters([ + Filter::make('individuals', fn ($query) => $query->where('type', 'individual')), + Filter::make('organizations', fn ($query) => $query->where('type', 'organization')), + Filter::make('active', fn ($query) => $query->where('is_active', true)), + ]); +} +``` + +## Columns {#columns} + +Resource column classes are located in the `Filament\Resources\Tables\Columns` namespace. + +All columns have access to the following customization methods: + +```php +Column::make($name) + ->action($action) // Set Livewire action that should be called when this column is clicked. The current record key will be passed in as a parameter. + ->getValueUsing($callback = fn ($record) => $record->getAttribute('{column name}')) // Set the callback used to retrieve the value of the column from a given record. + ->label($label) // Set custom label text for with the column header, which is otherwise automatically generated based on its name. It supports localization strings. + ->primary() // Sets the column as primary, which emphasises it and links to access a record. + ->searchable() // Allows the values in this column to be searched. + ->sortable() // Allows the values in this column to be sorted. + ->url($url, $shouldOpenInNewTab = false); // Set URL callback that should be used to generate a URL to send the user to when this column is clicked. +``` + +### Displaying Relationship Data {#columns-displaying-relationship-data} + +You set up columns that display results from a related model using dot syntax in its name: + +```php +Column::make('customer.name'); +``` + +This would check for a `customer` relationship on the parent model and output the related customer's name. + +### Calling Actions {#columns-calling-actions} + +You may want something to happen when a cell is clicked. Usually, this is opening a URL, or running a custom Livewire action. + +To open a URL when a cell is clicked, a callback is used to generate the destination. For example: + +```php +Column::make('website') + ->url(fn ($record) => $record->website, true); +``` + +Cells of the above column will display the contents of the record's `website`, and redirect the user to it when they click. The second parameter to `url()`, `true`, means that the website will open in a new tab when clicked. + +Alternatively, you may specify a custom Livewire action that should run when the column is clicked. The primary key of the clicked record will be passed as a parameter to the action: + +```php +Column::make('username') + ->action('editUsername'); +``` + +Cells of the above column will call the `editUsername()` Livewire action when clicked. + +### Boolean {#columns-boolean} + +The `trueIcon()` and `falseIcon()` methods support the name of any Blade icon component, and passes a set of formatting classes to it. By default, the [Blade Heroicons](https://github.com/blade-ui-kit/blade-heroicons) package is installed, so you may use the name of any [Heroicon](https://heroicons.com) out of the box. However, you may create your own custom icon components or install an alternative library if you wish. + +```php +Boolean::make($name) + ->falseIcon($icon = 'heroicon-o-x-circle') // Set the icon that should be displayed when the cell is false. + ->trueIcon($icon = 'heroicon-s-check-circle'); // Set the icon that should be displayed when the cell is true. +``` + +### Icon {#columns-icon} + +The `options()` method supports the names of any Blade icon components, and passes a set of formatting classes to them. By default, the [Blade Heroicons](https://github.com/blade-ui-kit/blade-heroicons) package is installed, so you may use the name of any [Heroicon](https://heroicons.com) out of the box. However, you may create your own custom icon components or install an alternative library if you wish. + +```php +Icon::make($name) + ->options($options = []); // Set the icon that should be displayed when the cell is a given value. +``` + +Here is an example usage of this column: + +```php +Icon::make('status') + ->options([ + 'heroicon-s-check-circle' => fn ($status) => $status === 'accepted', // When the `status` is `accepted`, render the `check-circle` Heroicon. + 'heroicon-s-x-circle' => fn ($status) => $status === 'declined', // When the `status` is `declined`, render the `x-circle` Heroicon. + 'heroicon-s-clock' => fn ($status) => $status === 'pending', // When the `status` is `pending`, render the `clock` Heroicon. + ]); +``` + +### Image {#columns-image} + +```php +Image::make($name) + ->disk($disk) // Set a custom disk that images should be read from. + ->height($height = 40) // Set the height of the image in pixels. + ->rounded() // Make the image preview fully rounded. + ->size($size) // Set the height and width of the image in pixels. + ->width($width); // Set the width of the image in pixels. +``` + +### Text {#columns-text} + +```php +Text::make($name) + ->currency($symbol = '$', $decimalSeparator = '.', $thousandsSeparator = ',', $decimals = 2) // Format values in this column in a currency format. + ->date($format = 'F j, Y') // Format values in this column as dates, using PHP date formatting tokens. + ->dateTime($format = 'F j, Y H:i:s') // Format values in this column as date-times, using PHP date formatting tokens. + ->default() // Set the default value for when this field does not exist. + ->formatUsing($callback = fn ($value) => $value) // Set the callback used to format the value of the column. + ->limit($limit) // Truncate the value of this column to a certain number of characters. + ->options($options = []); // Set the key-value array of available values that this column could hold. +``` + +> Other column types are coming soon. For more information, please see our [Development Roadmap](/docs/roadmap). + +### Developing Custom Column Types {#columns-custom-development} + +To create a new column type, which may be used in any table, you may generate a class and cell view using: + +```bash +php artisan make:filament-column Avatar --resource +``` + +Alternatively, simple custom columns may be created using a `View` component, and passing the name of a cell `$view` in your app: + +```php +Columns\View::make($view) + ->data($data = []); // Set the key-value array of available data that the view has access to. +``` + +## Filters {#filters} + +Filters are used to scope results in the table. Here is an example of a filter at allows only customers with a `type` of `individual` to be shown in the table: + +```php +Filter::make('individuals', fn ($query) => $query->where('type', 'individual')); +``` + +They have access to the following customization options: + +```php +Filter::make($name, $callback = fn ($query) => $query) + ->label($label); // Set custom label text for with the filter, which is otherwise automatically generated based on its name. It supports localization strings. +``` + +### Reusable Filters {#filters-reusable} + +You may wish to create a filter that you may reuse across multiple tables. + +To create a reusable filter, you may use the following command: + +```bash +php artisan make:filament-filter ActiveFilter --resource +``` + +This will create a new filter in the `app/Filament/Resources/Tables/Filters` directory: + +```php +name('active'); + } + + public function apply($query) + { + return $query; + } +} +``` + +You may modify the filter's query in the `apply()` method of that class: + +```php +public function apply($query) +{ + return $query->where('is_active', true); +} +``` + +> Currently, filters are static and only one may be applied at a time. Parameter-based filters and support for applying multiple filters at once is coming soon. For more information, please see our [Development Roadmap](/docs/roadmap). + +## Context Customization {#context-customization} + +You may customize tables based on the page they are used. To do this, you can chain the `only()` or `except()` methods onto any column or filter. + +```php +use App\Filament\Resources\CustomerResource\Pages; +use Filament\Resources\Tables\Filter; +use Filament\Resources\Tables\Table; + +public static function table(Table $table) +{ + return $table + ->filters([ + Filter::make('individuals', fn ($customer) => $customer->type === 'individual') + ->only(Pages\ListCustomers::class), + ]); +} +``` + +In this example, the `individuals` filter will `only()` be available on the `ListCustomers` page. + +```php +use App\Filament\Resources\CustomerResource\Pages; +use Filament\Resources\Tables\Columns; +use Filament\Resources\Tables\Table; + +public static function table(Table $table) +{ + return $table + ->columns([ + Columns\Text::make('name') + ->except(Pages\ListCustomers::class, fn ($column) => $column->primary()), + ]); +} +``` + +In this example, the `name` column will be primary, `except()` on the `ListCustomers` page. + +This is an incredibly powerful pattern, and allows you to completely customize a table contextually by chaining as many methods as you wish to the callback. diff --git a/docs/admin/theming.md b/docs/admin/theming.md new file mode 100644 index 0000000000..8b96220786 --- /dev/null +++ b/docs/admin/theming.md @@ -0,0 +1,118 @@ +--- +title: Theming +description: +extends: _layouts.documentation +section: content +toc: | + - [Registering a Theme](#registering-a-theme) +--- + +# Theming + +

+ Filament makes it incredibly simple to customise the look and feel of the panel through "themes". +

+ +To create your first theme, run the following command: + +```bash +php artisan make:filament-theme name-of-theme +``` + +This command will create a new file in `resources/css/filament` called `name-of-theme.css`. + +All of the colors used by Filament can be customised using [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties). This means you can change a color in a single place and it will be used throughout the entire panel. + +Filament uses 6 different colors: + +* `primary` +* `success` +* `danger` +* `gray` +* `blue` +* `white` + +The default theme stylesheet should look like this: + +```css +:root { + /* + --f-primary-100: #; + --f-primary-200: #; + --f-primary-300: #; + --f-primary-400: #; + --f-primary-500: #; + --f-primary-600: #; + --f-primary-700: #; + --f-primary-800: #; + --f-primary-900: #; + --f-success-100: #; + --f-success-200: #; + --f-success-300: #; + --f-success-400: #; + --f-success-500: #; + --f-success-600: #; + --f-success-700: #; + --f-success-800: #; + --f-success-900: #; + --f-danger-100: #; + --f-danger-200: #; + --f-danger-300: #; + --f-danger-400: #; + --f-danger-500: #; + --f-danger-600: #; + --f-danger-700: #; + --f-danger-800: #; + --f-danger-900: #; + --f-gray-100: #; + --f-gray-200: #; + --f-gray-300: #; + --f-gray-400: #; + --f-gray-500: #; + --f-gray-600: #; + --f-gray-700: #; + --f-gray-800: #; + --f-gray-900: #; + --f-blue-100: #; + --f-blue-200: #; + --f-blue-300: #; + --f-blue-400: #; + --f-blue-500: #; + --f-blue-600: #; + --f-blue-700: #; + --f-blue-800: #; + --f-blue-900: #; + --f-white: #; + */ +} +``` + +> Filament uses [Tailwind CSS](https://tailwindcss.com) for styling, therefore each color has 9 different scales. + +To customise a color, uncomment the appropriate line in the CSS file and replace the `#` placeholder with any valid CSS color (hex, RGB, HSL, etc): + +```css +:root { + --f-primary-600: #339E8B; +} +``` + +## Registering a Theme {#registering-a-theme} + +Once you've created your theme, you should register it using the `Filament::serving` and `Filament::registerStyle` methods inside the `boot` method of a service provider: + +```php +use Filament\Filament; + +class AppServiceProvider extends ServiceProvider +{ + public function boot() + { + Filament::serving(function () { + Filament::registerStyle('my-custom-theme', resource_path('css/filament/name-of-theme.css')); + }); + } +} +``` + +> Wrapping your style, script and script data related calls in `Filament::serving` ensures that they will only be run when Filament is being used. \ No newline at end of file From 15176b10e814e4b609fee5a2a13622e02d4354ae Mon Sep 17 00:00:00 2001 From: Dan Harrin Date: Sun, 29 Aug 2021 20:41:18 +0100 Subject: [PATCH 09/19] Update monorepo-split.yml --- .github/workflows/monorepo-split.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/monorepo-split.yml b/.github/workflows/monorepo-split.yml index f91983d1b5..832fe68500 100644 --- a/.github/workflows/monorepo-split.yml +++ b/.github/workflows/monorepo-split.yml @@ -37,7 +37,7 @@ jobs: package_directory: 'packages/${{ matrix.package }}' repository_organization: 'laravel-filament' repository_name: '${{ matrix.package }}' - branch: main + branch: 1.x tag: ${{ steps.previous-tag.outputs.tag }} user_name: "Dan Harrin" user_email: "dan@danharrin.com" From b5b3f249736625bf931b1fe2fcde1ed9a7e17204 Mon Sep 17 00:00:00 2001 From: Dan Harrin Date: Mon, 30 Aug 2021 09:30:06 +0100 Subject: [PATCH 10/19] Move docs --- docs/{admin => }/dashboard.md | 0 docs/{admin => }/forms.md | 0 docs/{admin => }/index.md | 0 docs/{admin => }/navigation.md | 0 docs/{admin => }/pages.md | 0 docs/{admin => }/plugin-development.md | 0 docs/{admin => }/resources.md | 0 docs/{admin => }/roadmap.md | 0 docs/{admin => }/tables.md | 0 docs/{admin => }/theming.md | 0 10 files changed, 0 insertions(+), 0 deletions(-) rename docs/{admin => }/dashboard.md (100%) rename docs/{admin => }/forms.md (100%) rename docs/{admin => }/index.md (100%) rename docs/{admin => }/navigation.md (100%) rename docs/{admin => }/pages.md (100%) rename docs/{admin => }/plugin-development.md (100%) rename docs/{admin => }/resources.md (100%) rename docs/{admin => }/roadmap.md (100%) rename docs/{admin => }/tables.md (100%) rename docs/{admin => }/theming.md (100%) diff --git a/docs/admin/dashboard.md b/docs/dashboard.md similarity index 100% rename from docs/admin/dashboard.md rename to docs/dashboard.md diff --git a/docs/admin/forms.md b/docs/forms.md similarity index 100% rename from docs/admin/forms.md rename to docs/forms.md diff --git a/docs/admin/index.md b/docs/index.md similarity index 100% rename from docs/admin/index.md rename to docs/index.md diff --git a/docs/admin/navigation.md b/docs/navigation.md similarity index 100% rename from docs/admin/navigation.md rename to docs/navigation.md diff --git a/docs/admin/pages.md b/docs/pages.md similarity index 100% rename from docs/admin/pages.md rename to docs/pages.md diff --git a/docs/admin/plugin-development.md b/docs/plugin-development.md similarity index 100% rename from docs/admin/plugin-development.md rename to docs/plugin-development.md diff --git a/docs/admin/resources.md b/docs/resources.md similarity index 100% rename from docs/admin/resources.md rename to docs/resources.md diff --git a/docs/admin/roadmap.md b/docs/roadmap.md similarity index 100% rename from docs/admin/roadmap.md rename to docs/roadmap.md diff --git a/docs/admin/tables.md b/docs/tables.md similarity index 100% rename from docs/admin/tables.md rename to docs/tables.md diff --git a/docs/admin/theming.md b/docs/theming.md similarity index 100% rename from docs/admin/theming.md rename to docs/theming.md From 35e8ef2545552185298ef4ba6653d381d8566ce9 Mon Sep 17 00:00:00 2001 From: Dan Harrin Date: Mon, 30 Aug 2021 10:06:14 +0100 Subject: [PATCH 11/19] wip --- docs/dashboard.md | 5 ----- docs/forms.md | 30 ------------------------------ docs/index.md | 9 --------- docs/navigation.md | 3 --- docs/pages.md | 6 ------ docs/plugin-development.md | 17 +---------------- docs/resources.md | 16 +--------------- docs/roadmap.md | 5 +---- docs/tables.md | 15 --------------- docs/theming.md | 7 +------ 10 files changed, 4 insertions(+), 109 deletions(-) diff --git a/docs/dashboard.md b/docs/dashboard.md index e03bde5430..12180b6310 100644 --- a/docs/dashboard.md +++ b/docs/dashboard.md @@ -1,10 +1,5 @@ --- title: Dashboard -description: -extends: _layouts.documentation -section: content -toc: | - - [Disabling the Default Widgets](#disabling-default-widgets) --- # Dashboard diff --git a/docs/forms.md b/docs/forms.md index 4fb028d0a5..c0cd03323b 100644 --- a/docs/forms.md +++ b/docs/forms.md @@ -1,35 +1,5 @@ --- title: Building Forms -description: -extends: _layouts.documentation -section: content -toc: | - - [Fields](#fields) - - [Checkbox](#fields-checkbox) - - [Date Picker](#fields-date-picker) - - [Date-time Picker](#fields-date-time-picker) - - [File Upload](#fields-file-upload) - - [Key-value](#fields-key-value) - - [Markdown Editor](#fields-markdown-editor) - - [Toolbar Buttons](#fields-markdown-editor-toolbar-buttons) - - [Rich Editor](#fields-rich-editor) - - [Toolbar Buttons](#fields-rich-editor-toolbar-buttons) - - [Select](#fields-select) - - [Tags Input](#fields-tags-input) - - [Textarea](#fields-textarea) - - [Text Input](#fields-text-input) - - [Toggle](#fields-toggle) - - [Validation](#validation) - - [Layout](#layout) - - [Grid](#layout-grid) - - [Section](#layout-section) - - [Fieldset](#layout-fieldset) - - [Tabs](#layout-tabs) - - [Group](#layout-group) - - [Placeholder](#layout-placeholder) - - [Dependent Fields](#dependent-fields) - - [Context Customization](#context-customization) - - [Developing Custom Components](#custom-development) --- # Building Forms diff --git a/docs/index.md b/docs/index.md index d66e77f3d3..6705cb0a57 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,14 +1,5 @@ --- title: Getting Started -description: -extends: _layouts.documentation -section: content -toc: | - - [Configuration](#configuration) - - [Users](#users) - - [Disabling the Default Migrations](#users-disabling-default-migrations) - - [Stubs](#stubs) - - [Upgrade Guide](#upgrade-guide) --- # Getting Started diff --git a/docs/navigation.md b/docs/navigation.md index 38ac67b32e..a70c5c9a15 100644 --- a/docs/navigation.md +++ b/docs/navigation.md @@ -1,8 +1,5 @@ --- title: Navigation -description: -extends: _layouts.documentation -section: content --- # Navigation diff --git a/docs/pages.md b/docs/pages.md index f6dfc82959..c293d7c06b 100644 --- a/docs/pages.md +++ b/docs/pages.md @@ -1,11 +1,5 @@ --- title: Custom Pages -description: -extends: _layouts.documentation -section: content -toc: | - - [Authorization](#authorization) - - [Customization](#customization) --- # Custom Pages diff --git a/docs/plugin-development.md b/docs/plugin-development.md index 7be2a9e5be..f5aff01b5f 100644 --- a/docs/plugin-development.md +++ b/docs/plugin-development.md @@ -1,20 +1,5 @@ --- title: Plugin Development -description: -extends: _layouts.documentation -section: content -toc: | - - [Registering Plugins](#registering-plugins) - - [Application Plugins](#application-plugins) - - [Distributed Plugins](#distributed-plugins) - - [Registering Resources](#registering-resources) - - [Registering Pages](#registering-pages) - - [Registering Widgets](#registering-widgets) - - [Registering Roles](#registering-roles) - - [Frontend Assets](#frontend-assets) - - [Stylesheets](#stylesheets) - - [Scripts](#scripts) - - [Providing Data to the Frontend](#providing-data-to-the-frontend) --- # Plugin Development @@ -216,4 +201,4 @@ class ExampleServiceProvider extends PluginServiceProvider } ``` -> Filament uses the `@json` Blade directive to convert your script data into a valid JavaScript object. You can find out more about this directive in the [official Laravel documentation](https://laravel.com/docs/blade#rendering-json). \ No newline at end of file +> Filament uses the `@json` Blade directive to convert your script data into a valid JavaScript object. You can find out more about this directive in the [official Laravel documentation](https://laravel.com/docs/blade#rendering-json). diff --git a/docs/resources.md b/docs/resources.md index e1d557aea2..0fd8eb118f 100644 --- a/docs/resources.md +++ b/docs/resources.md @@ -1,19 +1,5 @@ --- title: Resources -description: -extends: _layouts.documentation -section: content -toc: | - - [Forms](#forms) - - [Relations](#relations) - - [Managing Single Related Records](#relations-single) - - [Managing Multiple Related Records](#relations-multiple) - - [Tables](#tables) - - [Pages](#pages) - - [Customizing Default Pages](#pages-customization) - - [Hooks](#pages-customization-hooks) - - [Custom Pages](#pages-custom) - - [Authorization](#authorization) --- # Resources @@ -408,4 +394,4 @@ public static function authorization() Roles\Manager::allow()->except(['delete']), ]; } -``` \ No newline at end of file +``` diff --git a/docs/roadmap.md b/docs/roadmap.md index 07d4704d3e..c6de66f8d0 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -1,8 +1,5 @@ --- title: Development Roadmap -description: -extends: _layouts.documentation -section: content --- # Development Roadmap @@ -32,4 +29,4 @@ section: content - Stats - Quick actions -- Charts \ No newline at end of file +- Charts diff --git a/docs/tables.md b/docs/tables.md index 266de43d21..dcf2eb9185 100644 --- a/docs/tables.md +++ b/docs/tables.md @@ -1,20 +1,5 @@ --- title: Building Tables -description: -extends: _layouts.documentation -section: content -toc: | - - [Columns](#columns) - - [Displaying Relationship Data](#columns-displaying-relationship-data) - - [Calling Actions](#columns-calling-actions) - - [Boolean](#columns-boolean) - - [Icon](#columns-icon) - - [Image](#columns-image) - - [Text](#columns-text) - - [Developing Custom Column Types](#columns-custom-development) - - [Filters](#filters) - - [Reusable Filters](#filters-reusable) - - [Context Customization](#context-customization) --- # Building Tables diff --git a/docs/theming.md b/docs/theming.md index 8b96220786..874131e916 100644 --- a/docs/theming.md +++ b/docs/theming.md @@ -1,10 +1,5 @@ --- title: Theming -description: -extends: _layouts.documentation -section: content -toc: | - - [Registering a Theme](#registering-a-theme) --- # Theming @@ -115,4 +110,4 @@ class AppServiceProvider extends ServiceProvider } ``` -> Wrapping your style, script and script data related calls in `Filament::serving` ensures that they will only be run when Filament is being used. \ No newline at end of file +> Wrapping your style, script and script data related calls in `Filament::serving` ensures that they will only be run when Filament is being used. From 03f21156580f8103763e53a63a966231163907e9 Mon Sep 17 00:00:00 2001 From: Dan Harrin Date: Mon, 30 Aug 2021 10:40:09 +0100 Subject: [PATCH 12/19] wip --- docs/{index.md => 01-getting-started.md} | 0 docs/{resources.md => 02-resources.md} | 0 docs/{forms.md => 03-forms.md} | 0 docs/{tables.md => 04-tables.md} | 0 docs/{pages.md => 05-pages.md} | 0 docs/{dashboard.md => 06-dashboard.md} | 0 docs/{navigation.md => 07-navigation.md} | 0 docs/{theming.md => 08-theming.md} | 0 ...evelopment.md => 09-plugin-development.md} | 0 docs/roadmap.md | 32 ------------------- 10 files changed, 32 deletions(-) rename docs/{index.md => 01-getting-started.md} (100%) rename docs/{resources.md => 02-resources.md} (100%) rename docs/{forms.md => 03-forms.md} (100%) rename docs/{tables.md => 04-tables.md} (100%) rename docs/{pages.md => 05-pages.md} (100%) rename docs/{dashboard.md => 06-dashboard.md} (100%) rename docs/{navigation.md => 07-navigation.md} (100%) rename docs/{theming.md => 08-theming.md} (100%) rename docs/{plugin-development.md => 09-plugin-development.md} (100%) delete mode 100644 docs/roadmap.md diff --git a/docs/index.md b/docs/01-getting-started.md similarity index 100% rename from docs/index.md rename to docs/01-getting-started.md diff --git a/docs/resources.md b/docs/02-resources.md similarity index 100% rename from docs/resources.md rename to docs/02-resources.md diff --git a/docs/forms.md b/docs/03-forms.md similarity index 100% rename from docs/forms.md rename to docs/03-forms.md diff --git a/docs/tables.md b/docs/04-tables.md similarity index 100% rename from docs/tables.md rename to docs/04-tables.md diff --git a/docs/pages.md b/docs/05-pages.md similarity index 100% rename from docs/pages.md rename to docs/05-pages.md diff --git a/docs/dashboard.md b/docs/06-dashboard.md similarity index 100% rename from docs/dashboard.md rename to docs/06-dashboard.md diff --git a/docs/navigation.md b/docs/07-navigation.md similarity index 100% rename from docs/navigation.md rename to docs/07-navigation.md diff --git a/docs/theming.md b/docs/08-theming.md similarity index 100% rename from docs/theming.md rename to docs/08-theming.md diff --git a/docs/plugin-development.md b/docs/09-plugin-development.md similarity index 100% rename from docs/plugin-development.md rename to docs/09-plugin-development.md diff --git a/docs/roadmap.md b/docs/roadmap.md deleted file mode 100644 index c6de66f8d0..0000000000 --- a/docs/roadmap.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Development Roadmap ---- - -# Development Roadmap - -## Additional Form Field Types - -- JSON and relationship-based multi-select -- JSON array-powered field repeater -- Block-based page builder - -## Table Filters - -- Filter parameters. -- Applying more than one filter at once. - -## Additional Table Column Types - -- Tags - -## More Relation Types - -- Relation manager support for pivot table sorting. -- Polymorphic select. -- `hasOne()` select. - -## Widget Templates - -- Stats -- Quick actions -- Charts From d5a1eaabcf7ac8f91a90bd232a327ff7e7054327 Mon Sep 17 00:00:00 2001 From: Dan Harrin Date: Mon, 30 Aug 2021 13:54:43 +0100 Subject: [PATCH 13/19] wip --- docs/01-getting-started.md | 2 -- docs/02-resources.md | 2 -- docs/03-forms.md | 2 -- docs/04-tables.md | 2 -- docs/05-pages.md | 2 -- docs/06-dashboard.md | 2 -- docs/07-navigation.md | 2 -- docs/08-theming.md | 2 -- docs/09-plugin-development.md | 2 -- 9 files changed, 18 deletions(-) diff --git a/docs/01-getting-started.md b/docs/01-getting-started.md index 6705cb0a57..cfd61ffdc6 100644 --- a/docs/01-getting-started.md +++ b/docs/01-getting-started.md @@ -2,8 +2,6 @@ title: Getting Started --- -# Getting Started -

Filament is a content management framework for rapidly building a beautiful administration interface designed for humans.

> Filament requires Laravel 8.x or higher, and PHP 7.4 or higher. diff --git a/docs/02-resources.md b/docs/02-resources.md index 0fd8eb118f..e4941f1ba3 100644 --- a/docs/02-resources.md +++ b/docs/02-resources.md @@ -2,8 +2,6 @@ title: Resources --- -# Resources -

Resources are static classes that describe how administrators should be able to interact with data from your app. They are associated with Eloquent models from your app.

To create a resource for the `App\Models\Customer` model: diff --git a/docs/03-forms.md b/docs/03-forms.md index c0cd03323b..1dd8b8d212 100644 --- a/docs/03-forms.md +++ b/docs/03-forms.md @@ -2,8 +2,6 @@ title: Building Forms --- -# Building Forms -

Filament comes with a powerful form builder which can be used to create intuitive, dynamic, and contextual forms in the admin panel.

Forms have a schema, which is an array that contains many form components. The schema defines the form's [fields](#fields), their [validation rules](#validation), and their [layout](#layout) in the form. diff --git a/docs/04-tables.md b/docs/04-tables.md index dcf2eb9185..e80684d623 100644 --- a/docs/04-tables.md +++ b/docs/04-tables.md @@ -2,8 +2,6 @@ title: Building Tables --- -# Building Tables -

Filament includes a table builder which can be used to create interactive tables in the admin panel.

Tables have [columns](#columns) and [filters](#filters), which are defined in two methods on the table object. diff --git a/docs/05-pages.md b/docs/05-pages.md index c293d7c06b..4ee617b581 100644 --- a/docs/05-pages.md +++ b/docs/05-pages.md @@ -2,8 +2,6 @@ title: Custom Pages --- -# Custom Pages -

Filament allows you to create completely custom pages for the admin panel.

To create a new page, you can use: diff --git a/docs/06-dashboard.md b/docs/06-dashboard.md index 12180b6310..60fa347299 100644 --- a/docs/06-dashboard.md +++ b/docs/06-dashboard.md @@ -2,8 +2,6 @@ title: Dashboard --- -# Dashboard -

Filament allows you to build dynamic custom dashboard widgets very easily. To get started building a `Stats` widget:

```bash diff --git a/docs/07-navigation.md b/docs/07-navigation.md index a70c5c9a15..5b69029c74 100644 --- a/docs/07-navigation.md +++ b/docs/07-navigation.md @@ -2,8 +2,6 @@ title: Navigation --- -# Navigation - By default, Filament will register navigation items for each of your [resources](/docs/resources) and [custom pages](/docs/pages). These classes contain static properties that you can override, to configure that navigation item and its order: ```php diff --git a/docs/08-theming.md b/docs/08-theming.md index 874131e916..6d5e1433b1 100644 --- a/docs/08-theming.md +++ b/docs/08-theming.md @@ -2,8 +2,6 @@ title: Theming --- -# Theming -

Filament makes it incredibly simple to customise the look and feel of the panel through "themes".

diff --git a/docs/09-plugin-development.md b/docs/09-plugin-development.md index f5aff01b5f..2f7b1842db 100644 --- a/docs/09-plugin-development.md +++ b/docs/09-plugin-development.md @@ -2,8 +2,6 @@ title: Plugin Development --- -# Plugin Development -

Plugins can be used to extend Filament's default behaviour and create reusable modules for use in multiple applications.

From 10f70d1900335a5d2e99c5ecffecc4f4efa22a86 Mon Sep 17 00:00:00 2001 From: Wadim Sewo <33370479+wadimsewo@users.noreply.github.com> Date: Mon, 30 Aug 2021 16:00:04 +0200 Subject: [PATCH 14/19] Add "Cancel" to create-record (de) Hi, The translation for "cancel" in German was missing --- resources/lang/de/resources/pages/create-record.php | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/resources/lang/de/resources/pages/create-record.php b/resources/lang/de/resources/pages/create-record.php index c8000a2def..f2a0f9a11f 100644 --- a/resources/lang/de/resources/pages/create-record.php +++ b/resources/lang/de/resources/pages/create-record.php @@ -11,6 +11,10 @@ return [ 'createAnother' => [ 'label' => 'Erstellen & weitere erstellen', ], + + 'cancel' => [ + 'label' => 'Abbrechen' + ] ], ]; From b3834604e76a05c2e8419458f617cbbe1b8a9fa3 Mon Sep 17 00:00:00 2001 From: Anthony Chan Date: Mon, 30 Aug 2021 12:21:15 -0400 Subject: [PATCH 15/19] Fix typo in Getting Started - Stubs Hi there! Found a minor typo in the Stubs section. --- docs/01-getting-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/01-getting-started.md b/docs/01-getting-started.md index cfd61ffdc6..324f7dde29 100644 --- a/docs/01-getting-started.md +++ b/docs/01-getting-started.md @@ -110,7 +110,7 @@ from the `register()` method of your `AppServiceProvider`. ## Stubs {#stubs} -Filament commands use stubs as templates when new files in your project. You may customize these stubs by publishing them to your app: +Filament commands use stubs as templates when creating new files in your project. You may customize these stubs by publishing them to your app: ```bash php artisan vendor:publish --tag=filament-stubs From e2ddfee86a5e93049305f7958792d5fe5160dbcf Mon Sep 17 00:00:00 2001 From: Dan Harrin Date: Mon, 30 Aug 2021 17:34:29 +0100 Subject: [PATCH 16/19] wip --- docs/01-getting-started.md | 10 +++---- docs/02-resources.md | 20 +++++++------- docs/03-forms.md | 52 +++++++++++++++++------------------ docs/06-dashboard.md | 2 +- docs/08-theming.md | 2 +- docs/09-plugin-development.md | 22 +++++++-------- 6 files changed, 54 insertions(+), 54 deletions(-) diff --git a/docs/01-getting-started.md b/docs/01-getting-started.md index cfd61ffdc6..ae082165c0 100644 --- a/docs/01-getting-started.md +++ b/docs/01-getting-started.md @@ -25,7 +25,7 @@ Once you have a user account, you can sign in to the admin panel by visiting `/a To start building your admin panel, [create a resource](/docs/resources). -## Configuration {#configuration} +## Configuration If you'd like to expose advanced configuration options for Filament, you may publish its configuration file: @@ -35,7 +35,7 @@ php artisan vendor:publish --tag=filament-config > If you have published the configuration file for Filament, please ensure that you republish it when you upgrade. -## Users {#users} +## Users By default, Filament includes its own authentication guard and users table that is completely separate from your app's users table. This enables you to get up and running with Filament at record speed. @@ -96,7 +96,7 @@ public function isFilamentAdmin() } ``` -### Disabling the Default Migrations {#users-disabling-default-migrations} +### Disabling the Default Migrations You may wish to prevent the migration for the default users table from being registered. You may do this by calling: @@ -108,7 +108,7 @@ Filament::ignoreMigrations(); from the `register()` method of your `AppServiceProvider`. -## Stubs {#stubs} +## Stubs Filament commands use stubs as templates when new files in your project. You may customize these stubs by publishing them to your app: @@ -118,7 +118,7 @@ php artisan vendor:publish --tag=filament-stubs > If you have published the stubs for Filament, please ensure that you republish them when you upgrade. -## Upgrade Guide {#upgrade-guide} +## Upgrade Guide To upgrade Filament to the latest version, you may run: diff --git a/docs/02-resources.md b/docs/02-resources.md index e4941f1ba3..03a3829427 100644 --- a/docs/02-resources.md +++ b/docs/02-resources.md @@ -38,7 +38,7 @@ A label for this resource is generated based on the name of the resource's model public static $label = 'customer'; ``` -## Forms {#forms} +## Forms Resource classes contain a static `form()` method that is used to customize the forms to create and update resource records. @@ -58,9 +58,9 @@ The `schema()` method is used to define the structure of your form. It is an arr For more information, please see the page on [Building Forms](/docs/forms). -## Relations {#relations} +## Relations -### Managing Single Related Records {#relations-single} +### Managing Single Related Records The `Filament\Resources\Forms\Components\BelongsToSelect` field can be used in resource form schemas to create a select element with options to search and select a related record. It has the same methods available as [`Filament\Resources\Forms\Components\Select`](/docs/forms#fields-select), and others to define the relationship and column name that should be used: @@ -94,7 +94,7 @@ Components\BelongsToSelect::make('category_id') This example will only include featured categories in search results. -### Managing Multiple Related Records {#relations-multiple} +### Managing Multiple Related Records Relation managers are components that allow administrators to list, create, attach, edit, detach and delete related records without leaving the parent record's edit page. Resource classes contain a static `relations()` method that is used to register relation managers for your resource. @@ -144,7 +144,7 @@ Once a table and form have been defined for the relation manager, visit the edit public static $inverseRelationship = 'products'; ``` -## Tables {#tables} +## Tables Resource classes contain a static `table()` method that is used to customize the table to list resource records. @@ -169,7 +169,7 @@ Filters are predefined scopes that administrators can use to filter records in y For more information, please see the page on [Building Tables](/docs/tables). -## Pages {#pages} +## Pages Pages are classes that are associated with a resource. They are essentially [Laravel Livewire](https://laravel-livewire.com) components with custom integration utilities for use with Filament. @@ -181,7 +181,7 @@ By default, resources are generated with three pages: - Create has a [form](#forms) that is able to create a resource record. It is routed to `/create`. - Edit has a [form](#forms) that is able to update a resource record, along with the [relation managers](#relations-multiple) registered to your resource. It is routed to `/{record}/edit`. -### Customizing Default Pages {#pages-customization} +### Customizing Default Pages You are able to customize text used in the default pages by overriding properties on the page class. To see the options available, check the static properties defined in the parent class of each default page. @@ -191,7 +191,7 @@ For further customization opportunities, you can override the static `$view` pro public static $view = 'customers.list-records'; ``` -#### Hooks {#pages-customization-hooks} +#### Hooks Hooks may be used to customize the behaviour of a default page. To set up a hook, create a protected method on the page class with the name of the hook: @@ -294,7 +294,7 @@ class EditCustomer extends EditRecord } ``` -### Custom Pages {#pages-custom} +### Custom Pages Filament allows you to create completely custom pages for resources. To create a new page, you can use: @@ -324,7 +324,7 @@ To generate a URL for a resource route, you may call the static `generateUrl()` SortCustomers::generateUrl($parameters = [], $absolute = true); ``` -## Authorization {#authorization} +## Authorization For authorization, Filament will observe any [model policies](https://laravel.com/docs/authorization#creating-policies) that are registered in your app. The `viewAny` action may be used to completely disable resources and remove them from the navigation menu. diff --git a/docs/03-forms.md b/docs/03-forms.md index 1dd8b8d212..74321562a1 100644 --- a/docs/03-forms.md +++ b/docs/03-forms.md @@ -32,7 +32,7 @@ public static function form(Form $form) > Please note: when building forms for resources, please ensure that you are using components within the `Filament\Resources\Forms\Components` namespace and not `Filament\Forms\Components`. -## Fields {#fields} +## Fields Resource field classes are located in the `Filament\Resources\Forms\Components` namespace. @@ -51,7 +51,7 @@ Field::make($name) ->label($label); // Set custom label text for with the field, which is otherwise automatically generated based on its name. It supports localization strings. ``` -### Checkbox {#fields-checkbox} +### Checkbox ```php Checkbox::make($name) @@ -60,7 +60,7 @@ Checkbox::make($name) ->stacked(); // Render the checkbox under its label. ``` -### Date Picker {#fields-date-picker} +### Date Picker ```php DatePicker::make($name) @@ -75,7 +75,7 @@ DatePicker::make($name) ->weekStartsOnSunday(); // Set the first day of the week to Sunday in the calendar view. ``` -### Date-time Picker {#fields-date-time-picker} +### Date-time Picker ```php DateTimePicker::make($name) @@ -91,7 +91,7 @@ DateTimePicker::make($name) ->withoutSeconds(); // Hide the seconds input. ``` -### File Upload {#fields-file-upload} +### File Upload ```php FileUpload::make($name) @@ -124,7 +124,7 @@ FileUpload::make($name) > Support for multiple file uploads is coming soon. For more information, please see our [Development Roadmap](/docs/roadmap). -### Key-value {#fields-key-value} +### Key-value ```php KeyValue::make($name) @@ -141,7 +141,7 @@ KeyValue::make($name) ->valuePlaceholder($placeholder); // Set the value field placeholder. It supports localization strings. ``` -### Markdown Editor {#fields-markdown-editor} +### Markdown Editor ```php MarkdownEditor::make($name) @@ -154,7 +154,7 @@ MarkdownEditor::make($name) ->placeholder($placeholder); // Set the placeholder for when the field is empty. It supports localization strings. ``` -#### Toolbar Buttons {#fields-markdown-editor-toolbar-buttons} +#### Toolbar Buttons ``` attachFiles @@ -169,7 +169,7 @@ strike write ``` -### Rich Editor {#fields-rich-editor} +### Rich Editor ```php RichEditor::make($name) @@ -182,7 +182,7 @@ RichEditor::make($name) ->placeholder($placeholder); // Set the placeholder for when the field is empty. It supports localization strings. ``` -#### Toolbar Buttons {#fields-rich-editor-toolbar-buttons} +#### Toolbar Buttons ``` attachFiles @@ -201,7 +201,7 @@ title undo ``` -### Select {#fields-select} +### Select ```php Select::make($name) @@ -214,7 +214,7 @@ Select::make($name) > If you're looking to use a select for a `belongsTo()` relationship, please check out the [`BelongsToSelect` resource field](/docs/resources#relations-single). -### Tags Input {#fields-tags-input} +### Tags Input ```php TagsInput::make($name) @@ -223,7 +223,7 @@ TagsInput::make($name) ->separator($separator = ','); // Set the separator that should be used between tags. ``` -### Textarea {#fields-textarea} +### Textarea ```php Textarea::make($name) @@ -235,7 +235,7 @@ Textarea::make($name) ->rows($rows) // The number of rows tall the textarea is. ``` -### Text Input {#fields-text-input} +### Text Input ```php TextInput::make($name) @@ -255,7 +255,7 @@ TextInput::make($name) ->url(); // Require a valid URL to be provided. ``` -### Toggle {#fields-toggle} +### Toggle The `onIcon()` and `offIcon()` methods support the name of any Blade icon component, and passes a set of formatting classes to it. By default, the [Blade Heroicons](https://github.com/blade-ui-kit/blade-heroicons) package is installed, so you may use the name of any [Heroicon](https://heroicons.com) out of the box. However, you may create your own custom icon components or install an alternative library if you wish. @@ -268,7 +268,7 @@ Toggle::make($name) ->stacked(); // Render the toggle under its label. ``` -## Validation {#validation} +## Validation Filament provides a number of validation methods that can be applied to fields. Please refer to the [Laravel Validation docs](https://laravel.com/docs/validation#available-validation-rules) if you are unsure about any of these. @@ -304,9 +304,9 @@ Field($name) > Please note: when specifying **resource** field names in custom validation rules, you must prefix them with `record.`. -## Layout {#layout} +## Layout -### Grid {#layout-grid} +### Grid By default, form fields are stacked on top of each other in one column. To change this across the entire form, you may chain the `columns()` method onto the form object: @@ -341,7 +341,7 @@ public static function form(Form $form) } ``` -### Section {#layout-section} +### Section You may want to separate your fields into sections, each with a heading and subheading. To do this, you can use a Section component: @@ -450,7 +450,7 @@ public static function form(Form $form) } ``` -### Fieldset {#layout-fieldset} +### Fieldset You may want to group fields into a Fieldset. Each fieldset has a label, a border, and a two-column grid: @@ -494,7 +494,7 @@ public static function form(Form $form) } ``` -### Tabs {#layout-tabs} +### Tabs Some forms can be long and complex. You may want to use tabs to reduce the number that are available at once: @@ -550,7 +550,7 @@ public static function form(Form $form) } ``` -### Group {#layout-group} +### Group Groups are used to wrap multiple associated form components. They have no effect on the form visually, but are useful for applying modifications to many fields at once: @@ -570,7 +570,7 @@ public static function form(Form $form) } ``` -### Placeholder {#layout-placeholder} +### Placeholder Placeholders can be used to render text-only "fields" within your forms. Each placeholder has a value, which is cannot be changed by the user. @@ -588,7 +588,7 @@ public static function form(Form $form) } ``` -## Dependent Fields {#dependent-fields} +## Dependent Fields Dependent fields are fields that are modified based on the value of another. For example, you could show a group of fields based on the value of a Select. @@ -624,7 +624,7 @@ Components\TextInput::make('company_number') ); ``` -## Context Customization {#context-customization} +## Context Customization You may customize forms based on the page they are used. To do this, you can chain the `only()` or `except()` methods onto any form component. @@ -665,7 +665,7 @@ In this example, the `name` field will be required, `except()` on the `EditCusto This is an incredibly powerful pattern, and allows you to completely customize a form contextually by chaining as many methods as you wish to the callback. -## Developing Custom Components {#custom-development} +## Developing Custom Components To create a custom field, you may use: diff --git a/docs/06-dashboard.md b/docs/06-dashboard.md index 60fa347299..f0b8ab7e0c 100644 --- a/docs/06-dashboard.md +++ b/docs/06-dashboard.md @@ -14,7 +14,7 @@ Widgets are pure [Laravel Livewire](https://laravel-livewire.com) components, so > Pre-built widget templates are coming soon. For more information, please see our [Development Roadmap](/docs/roadmap). -## Disabling the Default Widgets {#disabling-default-widgets} +## Disabling the Default Widgets By default, two widgets are displayed on the dashboard. These widgets can be disabled by updating the `widgets` section of the [configuration](/docs#configuration) file. Updating each entries to `false` will remove the corresponding default widget from the dashboard. diff --git a/docs/08-theming.md b/docs/08-theming.md index 6d5e1433b1..6d58feab85 100644 --- a/docs/08-theming.md +++ b/docs/08-theming.md @@ -90,7 +90,7 @@ To customise a color, uncomment the appropriate line in the CSS file and replace } ``` -## Registering a Theme {#registering-a-theme} +## Registering a Theme Once you've created your theme, you should register it using the `Filament::serving` and `Filament::registerStyle` methods inside the `boot` method of a service provider: diff --git a/docs/09-plugin-development.md b/docs/09-plugin-development.md index 2f7b1842db..2d9c8d79e2 100644 --- a/docs/09-plugin-development.md +++ b/docs/09-plugin-development.md @@ -17,9 +17,9 @@ class ExampleServiceProvider extends PluginServiceProvider } ``` -## Registering Plugins {#registering-plugins} +## Registering Plugins -### Application Plugins {#application-plugins} +### Application Plugins If you're developing a plugin for a specific application, you should register the new service provider in your `config/app.php` file: @@ -37,7 +37,7 @@ return [ Laravel will load your service provider when bootstrapping and your plugin will be initialised. -### Distributed Plugins {#distributed-plugins} +### Distributed Plugins Much like a normal Laravel package, you should add your service provider's fully qualified class name to the `extra.laravel.providers` array in your package's `composer.json` file: @@ -55,7 +55,7 @@ Much like a normal Laravel package, you should add your service provider's fully This will ensure your service provider is automatically loaded by Laravel when the package is installed. -## Resources {#registering-resources} +## Resources To register a custom resource, add the fully qualified class name to the `protected $resources` array in your service provider. @@ -72,7 +72,7 @@ class ExampleServiceProvider extends PluginServiceProvider Filament will automatically register your `Resource` and ensure that Livewire can discover it. -## Pages {#registering-pages} +## Pages To register a custom page, add the fully qualified class name to the `protected $pages` array in your service provider. @@ -89,7 +89,7 @@ class ExampleServiceProvider extends PluginServiceProvider Filament will automatically register your `Page` and ensure that Livewire can discover it. -## Widgets {#registering-widgets} +## Widgets To register a custom widget, add the fully qualified class name to the `protected $widgets` array in your service provider. @@ -106,7 +106,7 @@ class ExampleServiceProvider extends PluginServiceProvider Filament will automatically register your `Widget` and ensure that Livewire can discover it. -## Roles {#registering-roles} +## Roles To register a custom role, add the fully qualified class name to the `protected $roles` array in your service provider. @@ -123,11 +123,11 @@ class ExampleServiceProvider extends PluginServiceProvider Filament will automatically register your `Role` and ensure it's available for use throughout your application. -## Frontend Assets {#frontend-assets} +## Frontend Assets Filament plugins can also register their own frontend assets. These assets will be included on all Filament related pages, allowing you to use your own CSS and JavaScript. -### Stylesheets {#stylesheets} +### Stylesheets To include a custom stylesheet, add it to the `protected $styles` property in your service provider. You should use a unique name as the key and the URL to the stylesheet as the value. @@ -154,7 +154,7 @@ class ExampleServiceProvider extends PluginServiceProvider } ``` -### Scripts {#scripts} +### Scripts To include a custom script, add it to the `protected $scripts` property in your service provider. You should use a unique name as the key and the URL to the script as the value. @@ -181,7 +181,7 @@ class ExampleServiceProvider extends PluginServiceProvider } ``` -### Providing Data to the Frontend {#providing-data-to-the-frontend} +### Providing Data to the Frontend Whilst building your plugin, you might find the need to generate some data on the server and access it on the client. From ddd036b3bc8d9a472b9cc020beb5d1969016fa27 Mon Sep 17 00:00:00 2001 From: Dan Harrin Date: Mon, 30 Aug 2021 17:34:44 +0100 Subject: [PATCH 17/19] wip --- docs/04-tables.md | 22 +++++++++++----------- docs/05-pages.md | 4 ++-- 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/04-tables.md b/docs/04-tables.md index e80684d623..cc73cd7313 100644 --- a/docs/04-tables.md +++ b/docs/04-tables.md @@ -35,7 +35,7 @@ public static function table(Table $table) } ``` -## Columns {#columns} +## Columns Resource column classes are located in the `Filament\Resources\Tables\Columns` namespace. @@ -52,7 +52,7 @@ Column::make($name) ->url($url, $shouldOpenInNewTab = false); // Set URL callback that should be used to generate a URL to send the user to when this column is clicked. ``` -### Displaying Relationship Data {#columns-displaying-relationship-data} +### Displaying Relationship Data You set up columns that display results from a related model using dot syntax in its name: @@ -62,7 +62,7 @@ Column::make('customer.name'); This would check for a `customer` relationship on the parent model and output the related customer's name. -### Calling Actions {#columns-calling-actions} +### Calling Actions You may want something to happen when a cell is clicked. Usually, this is opening a URL, or running a custom Livewire action. @@ -84,7 +84,7 @@ Column::make('username') Cells of the above column will call the `editUsername()` Livewire action when clicked. -### Boolean {#columns-boolean} +### Boolean The `trueIcon()` and `falseIcon()` methods support the name of any Blade icon component, and passes a set of formatting classes to it. By default, the [Blade Heroicons](https://github.com/blade-ui-kit/blade-heroicons) package is installed, so you may use the name of any [Heroicon](https://heroicons.com) out of the box. However, you may create your own custom icon components or install an alternative library if you wish. @@ -94,7 +94,7 @@ Boolean::make($name) ->trueIcon($icon = 'heroicon-s-check-circle'); // Set the icon that should be displayed when the cell is true. ``` -### Icon {#columns-icon} +### Icon The `options()` method supports the names of any Blade icon components, and passes a set of formatting classes to them. By default, the [Blade Heroicons](https://github.com/blade-ui-kit/blade-heroicons) package is installed, so you may use the name of any [Heroicon](https://heroicons.com) out of the box. However, you may create your own custom icon components or install an alternative library if you wish. @@ -114,7 +114,7 @@ Icon::make('status') ]); ``` -### Image {#columns-image} +### Image ```php Image::make($name) @@ -125,7 +125,7 @@ Image::make($name) ->width($width); // Set the width of the image in pixels. ``` -### Text {#columns-text} +### Text ```php Text::make($name) @@ -140,7 +140,7 @@ Text::make($name) > Other column types are coming soon. For more information, please see our [Development Roadmap](/docs/roadmap). -### Developing Custom Column Types {#columns-custom-development} +### Developing Custom Column Types To create a new column type, which may be used in any table, you may generate a class and cell view using: @@ -155,7 +155,7 @@ Columns\View::make($view) ->data($data = []); // Set the key-value array of available data that the view has access to. ``` -## Filters {#filters} +## Filters Filters are used to scope results in the table. Here is an example of a filter at allows only customers with a `type` of `individual` to be shown in the table: @@ -170,7 +170,7 @@ Filter::make($name, $callback = fn ($query) => $query) ->label($label); // Set custom label text for with the filter, which is otherwise automatically generated based on its name. It supports localization strings. ``` -### Reusable Filters {#filters-reusable} +### Reusable Filters You may wish to create a filter that you may reuse across multiple tables. @@ -214,7 +214,7 @@ public function apply($query) > Currently, filters are static and only one may be applied at a time. Parameter-based filters and support for applying multiple filters at once is coming soon. For more information, please see our [Development Roadmap](/docs/roadmap). -## Context Customization {#context-customization} +## Context Customization You may customize tables based on the page they are used. To do this, you can chain the `only()` or `except()` methods onto any column or filter. diff --git a/docs/05-pages.md b/docs/05-pages.md index 4ee617b581..3cad8ea844 100644 --- a/docs/05-pages.md +++ b/docs/05-pages.md @@ -14,7 +14,7 @@ This command will create two files - a page class in the `/Pages` directory of t Page classes are essentially [Laravel Livewire](https://laravel-livewire.com) components with custom integration utilities for use with Filament. -## Authorization {#authorization} +## Authorization You may create roles for users of Filament that allow them to access specific pages. You may create a `Manager` role using: @@ -54,7 +54,7 @@ public static function authorization() } ``` -## Customization {#customization} +## Customization Filament will automatically generate a title, navigation label and URL (slug) for your page based on its name. You may override it using static properties of your page class: From 266eb19ec42a51e49bd16fc99e3337972dbbeecc Mon Sep 17 00:00:00 2001 From: Dan Harrin Date: Tue, 31 Aug 2021 08:18:28 +0100 Subject: [PATCH 18/19] wip --- docs/01-getting-started.md | 2 +- docs/02-resources.md | 4 ++-- docs/03-forms.md | 8 ++++---- docs/04-tables.md | 2 +- docs/05-pages.md | 2 +- docs/06-dashboard.md | 2 +- docs/08-theming.md | 4 +--- docs/09-plugin-development.md | 4 +--- 8 files changed, 12 insertions(+), 16 deletions(-) diff --git a/docs/01-getting-started.md b/docs/01-getting-started.md index 8cc873dd6b..5eee538e91 100644 --- a/docs/01-getting-started.md +++ b/docs/01-getting-started.md @@ -2,7 +2,7 @@ title: Getting Started --- -

Filament is a content management framework for rapidly building a beautiful administration interface designed for humans.

+Filament is a content management framework for rapidly building a beautiful administration interface designed for humans. > Filament requires Laravel 8.x or higher, and PHP 7.4 or higher. diff --git a/docs/02-resources.md b/docs/02-resources.md index 03a3829427..2b9f545597 100644 --- a/docs/02-resources.md +++ b/docs/02-resources.md @@ -2,7 +2,7 @@ title: Resources --- -

Resources are static classes that describe how administrators should be able to interact with data from your app. They are associated with Eloquent models from your app.

+Resources are static classes that describe how administrators should be able to interact with data from your app. They are associated with Eloquent models from your app. To create a resource for the `App\Models\Customer` model: @@ -62,7 +62,7 @@ For more information, please see the page on [Building Forms](/docs/forms). ### Managing Single Related Records -The `Filament\Resources\Forms\Components\BelongsToSelect` field can be used in resource form schemas to create a select element with options to search and select a related record. It has the same methods available as [`Filament\Resources\Forms\Components\Select`](/docs/forms#fields-select), and others to define the relationship and column name that should be used: +The `Filament\Resources\Forms\Components\BelongsToSelect` field can be used in resource form schemas to create a select element with options to search and select a related record. It has the same methods available as [`Filament\Resources\Forms\Components\Select`](/docs/forms#select), and others to define the relationship and column name that should be used: ```php Components\BelongsToSelect::make('category_id') diff --git a/docs/03-forms.md b/docs/03-forms.md index 74321562a1..de20237f63 100644 --- a/docs/03-forms.md +++ b/docs/03-forms.md @@ -2,7 +2,7 @@ title: Building Forms --- -

Filament comes with a powerful form builder which can be used to create intuitive, dynamic, and contextual forms in the admin panel.

+Filament comes with a powerful form builder which can be used to create intuitive, dynamic, and contextual forms in the admin panel. Forms have a schema, which is an array that contains many form components. The schema defines the form's [fields](#fields), their [validation rules](#validation), and their [layout](#layout) in the form. @@ -384,7 +384,7 @@ public static function form(Form $form) } ``` -You may use the `columns()` method to easily create a [grid](#layout-grid) within the section: +You may use the `columns()` method to easily create a [grid](#grid) within the section: ```php use Filament\Resources\Forms\Components; @@ -526,7 +526,7 @@ public static function form(Form $form) } ``` -You may use the `columns()` method to easily create a [grid](#layout-grid) within the tab: +You may use the `columns()` method to easily create a [grid](#grid) within the tab: ```php use Filament\Resources\Forms\Components; @@ -606,7 +606,7 @@ Components\Select::make('type') To modify fields based on the value of another, you may use the `when()` method. The first argument to this method is a callback that evaluates the `$record` object, and returns true or false depending on if the modifications should be applied. The second argument makes modifications to the current field. If no second argument is supplied, the field will only be shown when the callback in the first argument is true: -In this example, the fields in the [group](#layout-group) will only be shown when the `type` field is set to `individual`: +In this example, the fields in the [group](#group) will only be shown when the `type` field is set to `individual`: ```php Components\Group::make([ diff --git a/docs/04-tables.md b/docs/04-tables.md index cc73cd7313..8efe76da47 100644 --- a/docs/04-tables.md +++ b/docs/04-tables.md @@ -2,7 +2,7 @@ title: Building Tables --- -

Filament includes a table builder which can be used to create interactive tables in the admin panel.

+Filament includes a table builder which can be used to create interactive tables in the admin panel. Tables have [columns](#columns) and [filters](#filters), which are defined in two methods on the table object. diff --git a/docs/05-pages.md b/docs/05-pages.md index 3cad8ea844..4350ff9e55 100644 --- a/docs/05-pages.md +++ b/docs/05-pages.md @@ -2,7 +2,7 @@ title: Custom Pages --- -

Filament allows you to create completely custom pages for the admin panel.

+Filament allows you to create completely custom pages for the admin panel. To create a new page, you can use: diff --git a/docs/06-dashboard.md b/docs/06-dashboard.md index f0b8ab7e0c..94952a7578 100644 --- a/docs/06-dashboard.md +++ b/docs/06-dashboard.md @@ -2,7 +2,7 @@ title: Dashboard --- -

Filament allows you to build dynamic custom dashboard widgets very easily. To get started building a `Stats` widget:

+Filament allows you to build dynamic custom dashboard widgets very easily. To get started building a `Stats` widget: ```bash php artisan make:filament-widget Stats diff --git a/docs/08-theming.md b/docs/08-theming.md index 6d58feab85..c28fa67e5f 100644 --- a/docs/08-theming.md +++ b/docs/08-theming.md @@ -2,9 +2,7 @@ title: Theming --- -

- Filament makes it incredibly simple to customise the look and feel of the panel through "themes". -

+Filament makes it incredibly simple to customise the look and feel of the panel through "themes". To create your first theme, run the following command: diff --git a/docs/09-plugin-development.md b/docs/09-plugin-development.md index 2d9c8d79e2..bd8a256ac6 100644 --- a/docs/09-plugin-development.md +++ b/docs/09-plugin-development.md @@ -2,9 +2,7 @@ title: Plugin Development --- -

- Plugins can be used to extend Filament's default behaviour and create reusable modules for use in multiple applications. -

+Plugins can be used to extend Filament's default behaviour and create reusable modules for use in multiple applications. To create a new plugin, extend the `Filament\PluginServiceProvider` class provided by Filament: From e20ecdd3ec99780ccc1ba731e0126f68792483ce Mon Sep 17 00:00:00 2001 From: Dan Harrin Date: Tue, 31 Aug 2021 08:22:02 +0100 Subject: [PATCH 19/19] wip --- docs/01-getting-started.md | 2 +- docs/02-resources.md | 10 +++++----- docs/03-forms.md | 4 ++-- docs/04-tables.md | 4 ++-- docs/06-dashboard.md | 4 ++-- docs/07-navigation.md | 2 +- 6 files changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/01-getting-started.md b/docs/01-getting-started.md index 5eee538e91..e96ba26151 100644 --- a/docs/01-getting-started.md +++ b/docs/01-getting-started.md @@ -23,7 +23,7 @@ and answering the input prompts. Administrators have access to all areas of Fila Once you have a user account, you can sign in to the admin panel by visiting `/admin` in your browser. -To start building your admin panel, [create a resource](/docs/resources). +To start building your admin panel, [create a resource](resources). ## Configuration diff --git a/docs/02-resources.md b/docs/02-resources.md index 2b9f545597..c81ce140dd 100644 --- a/docs/02-resources.md +++ b/docs/02-resources.md @@ -56,13 +56,13 @@ public static function form(Form $form) The `schema()` method is used to define the structure of your form. It is an array of components, in the order they should appear in your form. -For more information, please see the page on [Building Forms](/docs/forms). +For more information, please see the page on [Building Forms](forms). ## Relations ### Managing Single Related Records -The `Filament\Resources\Forms\Components\BelongsToSelect` field can be used in resource form schemas to create a select element with options to search and select a related record. It has the same methods available as [`Filament\Resources\Forms\Components\Select`](/docs/forms#select), and others to define the relationship and column name that should be used: +The `Filament\Resources\Forms\Components\BelongsToSelect` field can be used in resource form schemas to create a select element with options to search and select a related record. It has the same methods available as [`Filament\Resources\Forms\Components\Select`](forms#select), and others to define the relationship and column name that should be used: ```php Components\BelongsToSelect::make('category_id') @@ -104,7 +104,7 @@ To create a relation manager, you can use: php artisan make:filament-relation-manager CustomerResource orders ``` -This will create a `CustomerResource/RelationManagers/OrdersRelationManager.php` file. This contains a class where you are able to define a [form](/docs/forms) and [table](/docs/tables) for your relation manager. The relation manager will interact with the `orders` relationship on your parent model. +This will create a `CustomerResource/RelationManagers/OrdersRelationManager.php` file. This contains a class where you are able to define a [form](forms) and [table](tables) for your relation manager. The relation manager will interact with the `orders` relationship on your parent model. You must set the primary column of related records using the static `$primaryColumn` property on your new relation manager class. The primary column is used to identify related records quickly. This could be a user's `name`, or a blog post's `title`. @@ -167,7 +167,7 @@ The `columns()` method is used to define the columns in your table. It is an arr Filters are predefined scopes that administrators can use to filter records in your table. The `filters()` method is used to register these. -For more information, please see the page on [Building Tables](/docs/tables). +For more information, please see the page on [Building Tables](tables). ## Pages @@ -328,7 +328,7 @@ SortCustomers::generateUrl($parameters = [], $absolute = true); For authorization, Filament will observe any [model policies](https://laravel.com/docs/authorization#creating-policies) that are registered in your app. The `viewAny` action may be used to completely disable resources and remove them from the navigation menu. -Filament also includes a powerful role-based authorization system, which is set up out of the box with the default users table. You may also implement roles functionality in a [custom users table](/docs#users). +Filament also includes a powerful role-based authorization system, which is set up out of the box with the default users table. You may also implement roles functionality in a [custom users table](#users). You may create roles, such as `Manager`, using: diff --git a/docs/03-forms.md b/docs/03-forms.md index de20237f63..4f04280c3b 100644 --- a/docs/03-forms.md +++ b/docs/03-forms.md @@ -122,7 +122,7 @@ FileUpload::make($name) > Available values for the position methods can be found on [Filepond's website](https://pqina.nl/filepond/docs/patterns/api/filepond-instance#styles). -> Support for multiple file uploads is coming soon. For more information, please see our [Development Roadmap](/docs/roadmap). +> Support for multiple file uploads is coming soon. For more information, please see our [Development Roadmap](roadmap). ### Key-value @@ -212,7 +212,7 @@ Select::make($name) ->placeholder($placeholder); // Set the placeholder for when the field is empty. It supports localization strings. ``` -> If you're looking to use a select for a `belongsTo()` relationship, please check out the [`BelongsToSelect` resource field](/docs/resources#relations-single). +> If you're looking to use a select for a `belongsTo()` relationship, please check out the [`BelongsToSelect` resource field](resources#managing-single-related-records). ### Tags Input diff --git a/docs/04-tables.md b/docs/04-tables.md index 8efe76da47..c77374ca06 100644 --- a/docs/04-tables.md +++ b/docs/04-tables.md @@ -138,7 +138,7 @@ Text::make($name) ->options($options = []); // Set the key-value array of available values that this column could hold. ``` -> Other column types are coming soon. For more information, please see our [Development Roadmap](/docs/roadmap). +> Other column types are coming soon. For more information, please see our [Development Roadmap](roadmap). ### Developing Custom Column Types @@ -212,7 +212,7 @@ public function apply($query) } ``` -> Currently, filters are static and only one may be applied at a time. Parameter-based filters and support for applying multiple filters at once is coming soon. For more information, please see our [Development Roadmap](/docs/roadmap). +> Currently, filters are static and only one may be applied at a time. Parameter-based filters and support for applying multiple filters at once is coming soon. For more information, please see our [Development Roadmap](roadmap). ## Context Customization diff --git a/docs/06-dashboard.md b/docs/06-dashboard.md index 94952a7578..6220e0e250 100644 --- a/docs/06-dashboard.md +++ b/docs/06-dashboard.md @@ -12,11 +12,11 @@ This command will create two files - a widget class in the `/Widgets` directory Widgets are pure [Laravel Livewire](https://laravel-livewire.com) components, so may use any features of that package. -> Pre-built widget templates are coming soon. For more information, please see our [Development Roadmap](/docs/roadmap). +> Pre-built widget templates are coming soon. For more information, please see our [Development Roadmap](roadmap). ## Disabling the Default Widgets -By default, two widgets are displayed on the dashboard. These widgets can be disabled by updating the `widgets` section of the [configuration](/docs#configuration) file. Updating each entries to `false` will remove the corresponding default widget from the dashboard. +By default, two widgets are displayed on the dashboard. These widgets can be disabled by updating the `widgets` section of the [configuration](#configuration) file. Updating each entries to `false` will remove the corresponding default widget from the dashboard. ```php 'widgets' => [ diff --git a/docs/07-navigation.md b/docs/07-navigation.md index 5b69029c74..965ee10a24 100644 --- a/docs/07-navigation.md +++ b/docs/07-navigation.md @@ -2,7 +2,7 @@ title: Navigation --- -By default, Filament will register navigation items for each of your [resources](/docs/resources) and [custom pages](/docs/pages). These classes contain static properties that you can override, to configure that navigation item and its order: +By default, Filament will register navigation items for each of your [resources](resources) and [custom pages](pages). These classes contain static properties that you can override, to configure that navigation item and its order: ```php public static $icon = 'heroicon-o-document-text';