-```
+### `setTemplate(View|string $template)`
+Pass a blade view path, or a blade content.
## Data valuation
-Valuation is handled by a dedicated `$this->setPanelData(string $panelWidgetKey, array $data)` in the Dashboard class:
+Valuation is handled by a dedicated `$this->setPanelData(string $panelWidgetKey, array $data)` in the Dashboard class.
+
+Example:
```php
-function buildWidgetsData(): void
+class MyDashboard extends SharpDashboard
{
- $count = 36; // [...];
-
- $this->setPanelData(
- 'messages', ['count' => $count]
- );
+ // ...
+
+ protected function buildWidgets(WidgetsContainer $widgetsContainer): void
+ {
+ $widgetsContainer
+ ->addWidget(
+ SharpPanelWidget::make('my_panel')
+ ->setTitle('My custom panel')
+ ->setTemplate(view('sharp.templates.dashboard_panel')) // Must be an existing blade view
+ );
+ }
+
+ public function buildWidgetsData(): void
+ {
+ // ...
+
+ $this->setPanelData('my_panel', [
+ // Add here every data required by the blade template
+ 'author' => $author,
+ 'post_count' => $count,
+ ]);
+ }
}
```
-Pass there the widget `key` and an array with the data required by your template.
diff --git a/docs/guide/data-localization.md b/docs/guide/data-localization.md
index ef71d6b0a..0a8e891b7 100644
--- a/docs/guide/data-localization.md
+++ b/docs/guide/data-localization.md
@@ -39,11 +39,7 @@ class BookForm extends SharpForm
}
```
-Once one field at least is localized, here's what appears on the front side:
-
-)
-
-A global locale selector is added, as well as individual ones on each localized field.
+Once one field at least is localized, the form will present a global locale selector, and additionaly each localized field will have his own locale selector.
## Transform the data accordingly
@@ -130,7 +126,7 @@ class BookForm extends SharpForm
Validation allows differentiating rules between locales:
```php
-class BookValidator extends FormRequest
+class BookForm extends SharpForm
{
// [...]
diff --git a/docs/guide/entity-authorizations.md b/docs/guide/entity-authorizations.md
index 77d6c2a45..d9749194f 100644
--- a/docs/guide/entity-authorizations.md
+++ b/docs/guide/entity-authorizations.md
@@ -4,12 +4,13 @@ You can check documentation of authorizations for [Commands](commands.md) or [En
## Available permissions
-Entities have five permission keys:
+Entities have six permission keys:
- `entity`: to see the entity in the side-menu, and to display its Entity List or single Show Page. Without this, the entity is hidden to the user.
- `view`: without this, the user can access the Entity list, but not the Show Page nor the Form.
- `update`: without this, the user can't access the Form.
- `create`: without this, the user can't display the create Form.
+- `reorder`: without this, the user can't reorder instances in the Entity List (if a [reorder handler](reordering-instances.md) is configured).
- `delete`: without this, the user can't delete an instance.
## Globally prohibited actions
@@ -21,7 +22,7 @@ For this add the permission keys in the `$prohibitedActions` attribute og the En
```php
class UserEntity extends SharpEntity
{
- // [...]
+ // ...
protected ?string $list = UserSharpList::class;
protected array $prohibitedActions = [
@@ -42,31 +43,36 @@ For user-based rules, create a `Policy` class which is just a plain class defini
It must extend `Code16\Sharp\Auth\SharpEntityPolicy`:
```php
-class SpaceshipPolicy extends SharpEntityPolicy
+class PostPolicy extends SharpEntityPolicy
{
public function entity($user): bool
{
- return sharp_user()->hasGroup('admin');
+ return $user->hasGroup('admin');
}
public function view($user, $instanceId): bool
{
- return sharp_user()->owner_id == $user->id;
+ return Post::find($instanceId)?->owner_id == $user->id;
}
public function update($user, $instanceId): bool
{
- // [...]
+ // ...
}
public function delete($user, $instanceId): bool
{
- // [...]
+ // ...
}
public function create($user): bool
{
- // [...]
+ // ...
+ }
+
+ public function reorder($user): bool
+ {
+ // ...
}
}
```
@@ -78,13 +84,24 @@ Only write methods which don't return true, as this is the default behaviour.
The policy must be declared in the [Entity class](entity-class.md):
```php
-class SpaceshipEntity extends SharpEntity
+class PostEntity extends SharpEntity
{
- // [...]
- protected ?string $policy = SpaceshipSharpPolicy::class;
+ // ...
+ protected ?string $policy = PostSharpPolicy::class;
}
```
### Policies for Dashboards
-It's all the same, except Dashboards have only one method: `public function entity($user): bool`.
\ No newline at end of file
+The only useful method in case of a Dashboard is `function entity($user)`; apart from this, they work the same.
+
+```php
+class SalesDashboardPolicy extends SharpEntityPolicy
+{
+ public function entity($user): bool
+ {
+ return $user->hasGroup('admin');
+ }
+}
+```
+
diff --git a/docs/guide/entity-class.md b/docs/guide/entity-class.md
index ab1ea3485..fcc0ddd3d 100644
--- a/docs/guide/entity-class.md
+++ b/docs/guide/entity-class.md
@@ -8,6 +8,12 @@ An `entity` is simply a data structure which has a meaning in the application co
The `entity class` is the place where you can declare the entity configuration: its Entity List, Form, Show Page...
+## Generator
+
+```bash
+php artisan sharp:make:entity [--label,--dashboard,--show,--form,--policy,--single]
+```
+
## Write the class
The class must extend `Code16\Sharp\Entities\SharpEntity`. The easiest way to declare your attached classes is to simply override a bunch of protected attributes:
@@ -70,6 +76,68 @@ class MyEntity extends SharpEntity
}
```
+### Single shows and forms
+
+When you need to configure a "unique" resource that does not fit into a List / Show schema, like for instance an account, or a configuration item, you can use a Single Show or Form. This is a dedicated topic, [documented here](single-show.md).
+
### Handle Multiforms
-This is a dedicated topic, [documented here](multiforms.md).
+Multiforms allows to declare different forms for the same entity, to hanle variants. This is a dedicated topic, [documented here](multiforms.md).
+
+## Declare the Entity in Sharp configuration
+
+The last step is to declare the entity in Sharp, in the ServiceProvider:
+
+```php
+class SharpServiceProvider extends SharpAppServiceProvider
+{
+ protected function configureSharp(SharpConfigBuilder $config): void
+ {
+ $config
+ ->setName('My new project')
+ ->addEntity('product', ProductEntity::class);
+ // ...
+ }
+}
+```
+
+## Custom Entity Resolver
+
+In some very specific cases, you may want to have more control over the entity declaration, depending on some context. You can use a custom SharpEntityResolver to do that.
+
+```php
+use Code16\Sharp\Utils\Entities\SharpEntityResolver;
+
+class MySharpEntityResolver implements SharpEntityResolver
+{
+ public function entityClassName(string $entityKey): ?string
+ {
+ return match ($entityKey) {
+ 'product' => auth()->user()->isAdmin()
+ ? AdminProductEntity::class
+ : ProductEntity::class,
+ 'order' => OrderEntity::class,
+ // ...
+ };
+ }
+}
+```
+
+Then, in the ServiceProvider, you can declare the resolver like this:
+
+```php
+class SharpServiceProvider extends SharpAppServiceProvider
+{
+ protected function configureSharp(SharpConfigBuilder $config): void
+ {
+ $config
+ ->setName('My new project')
+ ->declareEntityResolver(MySharpEntityResolver::class);
+ // ...
+ }
+}
+```
+
+::: warning
+You must remove all `->addEntity()` calls in order to use `->declareEntityResolver()`.
+:::
\ No newline at end of file
diff --git a/docs/guide/entity-states.md b/docs/guide/entity-states.md
index 928657ef5..b61e8bbe2 100644
--- a/docs/guide/entity-states.md
+++ b/docs/guide/entity-states.md
@@ -21,7 +21,7 @@ The goal is to declare the available states for the entity, using `$this->addSta
```php
class ProductEntityState extends EntityState
{
- // [...]
+ // ...
protected function buildStates()
{
@@ -46,7 +46,7 @@ When the user clicks on a state to update it, the `updateState()` method is call
```php
class ProductEntityState extends EntityState
{
- // [...]
+ // ...
public function updateState($instanceId, $stateId): array
{
@@ -67,7 +67,7 @@ Once the Entity state class is defined, we have to add it in the Entity List or
```php
class ProductEntityList extends SharpEntityList
{
- // [...]
+ // ...
function buildListConfig(): void
{
@@ -78,6 +78,27 @@ class ProductEntityList extends SharpEntityList
The first parameter is a key which should be the name of the attribute.
+## Display the state
+
+The state will be displayed in the top section of the Show Page (if you have one).
+
+In the Entity List, it will be displayed in a new column at the end of the list, unless you have declared a specific column (in this case, you can choose where to place it):
+
+```php
+class ProductEntityList extends SharpEntityList
+{
+ protected function buildList(EntityListFieldsContainer $fields): void
+ {
+ $fields
+ ->addField(EntityListField::make('title')->setLabel('Title'))
+ ->addField(EntityListStateField::make()->setLabel('State'))
+ ->addField(/* ... */);
+ }
+
+ // ...
+}
+```
+
## Authorizations
Entity states can declare an authorization check very much like Instance Commands:
@@ -85,7 +106,7 @@ Entity states can declare an authorization check very much like Instance Command
```php
class ProductEntityState extends EntityState
{
- // [...]
+ // ...
public function authorizeFor($instanceId): bool
{
diff --git a/docs/guide/filters.md b/docs/guide/filters.md
index 47b47eb3a..f9ae0d137 100644
--- a/docs/guide/filters.md
+++ b/docs/guide/filters.md
@@ -33,7 +33,7 @@ You can implement the optional `buildFilterConfig()` method to configure the fil
```php
class ProductCategoryFilter extends EntityListSelectFilter
{
- // [...]
+ // ...
public function buildFilterConfig(): void
{
@@ -55,7 +55,7 @@ Next, in the Entity List, we must declare the filter:
```php
class ProductEntityList extends SharpEntityList
{
- // [...]
+ // ...
function getFilters(): ?array
{
@@ -77,7 +77,7 @@ Example:
```php
class ProductEntityList extends SharpEntityList
{
- // [...]
+ // ...
function getListData()
{
@@ -87,7 +87,7 @@ class ProductEntityList extends SharpEntityList
$products->where('category_id', $cat);
}
- // [...]
+ // ...
}
}
```
@@ -101,7 +101,7 @@ In this case, with Eloquent for instance, your might have to modify your code to
```php
class ProductEntityList extends SharpEntityList
{
- // [...]
+ // ...
function getListData()
{
@@ -111,7 +111,7 @@ class ProductEntityList extends SharpEntityList
$products->whereIn('category_id', $categories);
}
- // [...]
+ // ...
}
}
```
@@ -122,41 +122,41 @@ Note that a filter can't be required AND multiple.
You might find useful to filter list elements on a specific date range. Date range filters enable you to show only data that meets a given time period. To implement such a filter, your filter class must extend `Code16\Sharp\EntityList\Filters\EntityListDateRangeFilter`.
-Then you need to adjust the query with selected range (Sharp will return an associative array of two Carbon date objects). In this case, with Eloquent for instance, you might add a condition like:
+Then you need to adjust the query with selected range; in this case, with Eloquent for instance, you might add a condition like:
```php
class ProductEntityList extends SharpEntityList
{
- // [...]
+ // ...
- function getListData()
+ public function getListData(): array|Arrayable;
{
$products = Product::query();
if ($range = $this->queryParams->filterFor(ProductCreationDateFilter::class)) {
- $products->whereBetween(
- 'created_at', [$range['start'], $range['end']]
- );
+ $products->whereBetween('created_at', [$range->getStart(), $range->getEnd()]);
}
- // [...]
+ // ...
}
}
```
### Configuration
-You can define the date display format (default is `MM-DD-YYYY`, using [the Moment.js parser syntax](https://momentjs.com/docs/#/parsing/string-format/)) and choose if the week should start on monday (default is sunday) implementing those two optional methods in your filter implementation:
+You can define the date display format (default is `MM-DD-YYYY`, using [Carbon isoFormat() syntax](https://carbon.nesbot.com/docs/#iso-format-available-replacements)) and choose if the week should start on monday (default is sunday).
+With `configureShowPresets()`, a list of buttons is displayed allowing the user to quickly select a date range.
```php
class ProductCreationDateFilter extends EntityListDateRangeFilter
{
- // [...]
+ // ...
public function buildFilterConfig(): void
{
$this->configureDateFormat("YYYY-MM-DD")
- ->configureMondayFirst(false);
+ ->configureMondayFirst(false)
+ ->configureShowPresets();
}
}
```
@@ -207,50 +207,6 @@ public function buildFilterConfig(): void
}
```
-## Filter template
-
-Sometimes you need your select filter results to be a little more than a label. For this, configure a template (similar to form fields with templates):
-
-```php
-public function buildFilterConfig(): void
-{
- $this->configureTemplate('
{{label}}
{{detail}}
');
-}
-```
-
-You can also, for more control, return a view here.
-
-The template will be [interpreted by Vue.js](https://vuejs.org/v2/guide/syntax.html), meaning you can add data placeholders, DOM structure but also directives, and anything that Vue will parse. It's the same as [Autocomplete's templates](form-fields/autocomplete.md).
-
-You'll need also to change your `values()` function, returning more than an `[{id}=>{value}]` array. For instance:
-
-```php
-public function values()
-{
- return ProductCategory::orderBy('label')
- ->get()
- ->map(function ($category) {
- return [
- 'id' => $category->id,
- 'label' => $category->label,
- 'detail' => $category->detail_text
- ];
- });
-}
-```
-
-Note that **the label attribute is mandatory**: it is used for the result display of the filter.
-
-Finally, if your filter is also searchable, you'll need to configure attributes which should be searched in the template:
-
-```php
-public function buildFilterConfig(): void
-{
- $this->configureSearchable()
- ->configureSearchKeys(['label', 'detail']);
-}
-```
-
## Check filter
In case of a filter that is just a matter on true / false ("only show admins" for example), just make your filter class extend `Code16\Sharp\EntityList\Filters\EntityListCheckFilter`.
@@ -283,15 +239,42 @@ And with that Sharp will keep the filter value in session and ensure it is value
In order to make this feature work, since filters are generalized, you'll need to have unique filters key (the filter class name by default).
:::
+## Drop filters depending on functional data
+
+Sometimes you may want to hide a filter to the user depending on the actual data, or on other filters values. This can be achieved by using the `useFilter()` method in your EntityList class, typically in the `getListData()` method.
+
+```php
+class OrderEntityList extends SharpEntityList
+{
+ // ...
+
+ protected function getFilters(): ?array
+ {
+ return [
+ PaymentMethodFilter::class,
+ OnlinePaymentProviderFilter::class,
+ ];
+ }
+
+ public function getListData(): array|Arrayable
+ {
+ if ($this->queryParams->filterFor(PaymentMethodFilter::class) !== 'online') {
+ // No need to show the OnlinePaymentProviderFilter
+ $this->hideFilter(OnlinePaymentProviderFilter::class);
+ }
+
+ // ...
+ }
+}
+```
+
## Filters for Dashboards
[Dashboards](building-dashboard.md) also can take advantage of filters; the API the same, but base classes are specific: `Code16\Sharp\Dashboard\Filters\DashboardSelectFilter`, `Code16\Sharp\Dashboard\Filters\DashboardDateRangeFilter`,`Code16\Sharp\Dashboard\DashboardCheckFilter` and so on.
## Global menu Filters
-You may want to "scope" the entire data set: an example of this could be a user which can manage several organizations. Instead of adding a filter on almost every Entity List, in this case, you can define a global filter, which will appear like this (on the left menu):
-
-
+You may want to "scope" the entire data set: an example of this could be a user which can manage several organizations. Instead of adding a filter on almost every Entity List, in this case, you can define a global filter, which will appear on top of the global menu.
To achieve this, first write the filter class, like any filter, except it must
extend `\Code16\Sharp\Utils\Filters\GlobalRequiredFilter` — meaning it must be a required filter.
@@ -310,27 +293,33 @@ class OrganizationGlobalFilter extends GlobalRequiredFilter
{
return Corporation::first()->id;
}
+
+ public function authorize(): bool
+ {
+ // Optional: you can define an authorization logic here
+ return true;
+ }
}
```
-And then, we declare it in Sharp's config file:
+And then, we declare it:
```php
-// in config/sharp.php
-
-return [
- // [...]
-
- 'global_filters' => [
- OrganizationGlobalFilter::class
- ],
-];
+class SharpServiceProvider extends SharpAppServiceProvider
+{
+ protected function configureSharp(SharpConfigBuilder $config): void
+ {
+ $config
+ ->addGlobalFilter(OrganizationGlobalFilter::class)
+ // ...
+ }
+}
```
Finally, to get the actual value of the filter on your Entity List, Show Page or Form classes, you must use the context:
```php
-currentSharpRequest()->globalFilterFor(OrganizationGlobalFilter::class)
+sharp()->context()->globalFilterValue(OrganizationGlobalFilter::class)
```
The usage of Sharp Context is [detailed here](context.md).
diff --git a/docs/guide/form-editor-embeds.md b/docs/guide/form-editor-embeds.md
index 1a1ee4017..e116018a5 100644
--- a/docs/guide/form-editor-embeds.md
+++ b/docs/guide/form-editor-embeds.md
@@ -1,20 +1,16 @@
# Write an Embed for the Editor field
-Form's [Editor field](form-fields/editor.md) is a full-featured wysiwyg / markdown field which can contain images,
-files, and user defined embeds; tou should first look at the Editor field documentation to understand the concept, since
-here's the details on how to write an Embed class.
+Form's [Editor field](form-fields/editor.md) is a full-featured wysiwyg / markdown field which can contain images, files, and user defined embeds; tou should first look at the Editor field documentation to understand the concept, since here's the details on how to write an Embed class.
## How does an Embed work?
-First a quick presentation: an embed is not a structured data, meant to be stored in a database or to be represented by
-a Model. I will be stored in the content of an Editor text, as a custom HTML tag, with attributes. Here's an example of
-how a `RelatedPostEmbed` can be presented in the Editor field:
+First a quick presentation: an embed is not a structured data, meant to be stored in a database or to be represented by a Model. I will be stored in the content of an Editor text, as a custom HTML tag, with attributes. Here's an example of how a `RelatedPostEmbed` can be presented in the Editor field:
-
+
Here's how it can be edited, in Sharp:
-
+
And here's how it could be stored, as a reference:
@@ -28,14 +24,11 @@ The purpose of this class is to define all this: how to present, edit and store
### Required methods
-The class must extend `Code16\Sharp\Form\Fields\Embeds\SharpFormEditorEmbed`; you'll have to implement at least these
-two methods:
+The class must extend `Code16\Sharp\Form\Fields\Embeds\SharpFormEditorEmbed`; you'll have to implement at least these two methods:
### `buildFormFields(FieldsContainer $formFields): void`
-Here you can declare the form fields of the embed; the API is the same as building a standard Form (
-see [Building an Entity Form](building-form.md)). This form will appear in a modal when the use creates a new embed, or
-clicks in the edit button of an existing one.
+Here you can declare the form fields of the embed; the API is the same as building a standard Form (see [Building an Entity Form](building-form.md)). This form will appear in a modal when the use creates a new embed, or clicks in the edit button of an existing one.
::: tip
You can choose to name one (and only one) field `slot`: it will be stored as the component content, rather than in an attribute. This could be easier to handle complex data (an Editor HTML text for instance) this way, in the public site, where you can use the standard `{{ $slot }}` attribute to display it.
@@ -65,10 +58,11 @@ This is not required, but you should implement `buildEmbedConfig(): void`, where
- `configureLabel(string $label): self`: to define the name of the embed (should be short)
- `configureTagName(string $tagName): self`: to define the tag name (typically starting with `x-`)
-- `configureFormInlineTemplate(string $template): self` and `configureFormTemplatePath(string $templatePath): self`: to
- define the .vue template for displaying the embed in the Editor field in the form
-- `configureShowInlineTemplate(string $template): self` and `configureShowTemplatePath(string $templatePath): self`:
- same, but for the show page, only you need to have a different version for it.
+- `configureTemplate(string|View $template): self`: to define the blade as inline string or as a `view('my-template')` for both show & form. If you want to specify different templates between show & form you can use following methods :
+ - `configureShowTemplate(string|View $template): self`
+ - `configureFormTemplate(string|View $template): self`
+- `configureIcon(string $icon): self`: to define an icon used when the embed is placed in the toolbar. The icon is also displayed in the embed header.
+- `configureDisplayEmbedHeader(bool $display = true, ?string $title = null): self`: to hide the default embed header. The title is the label defined in `configureLabel()` but it can be overridden here.
Here's a complete example:
@@ -78,23 +72,27 @@ public function buildEmbedConfig(): void
$this
->configureLabel('Related Post')
->configureTagName('x-related-post')
- ->configureFormInlineTemplate('
+ HTML);
}
```
-Templates are vue-based, and work the same as for autocompletes or html form fields. We chose to write it inline here,
-but we could refer to a `.vue` file, with `configureFormTemplatePath` instead. The same template will be used in Show
-page, if the editor text should be displayed there, since we didn't configure anything (
-via `configureShowInlineTemplate` or `configureShowTemplatePath`).
-
### Additional useful methods
Two more methods can be implemented, in case you need more control of data transformation:
### `transformDataForTemplate(array $data, bool $isForm): array`
-This method is called before the template rendering. This is where you have a chance to format data for the template,
-which could even mean to make a DB query, in some cases.
+This method is called before the template rendering. This is where you have a chance to format data for the template, which could even mean to make a DB query, in some cases.
Here's an example, matching the template seen above:
@@ -114,24 +112,17 @@ public function transformDataForTemplate(array $data, bool $isForm): array
}
```
-The embed data is simply `post`, which is an id. So we find the related post, and return attributes needed by the
-template, leveraging Sharp's transformation API (see [how to transform data](how-to-transform-data.md)) — but we could
-instead directly build and return an array, as always.
+The embed data is simply `post`, which is an id. So we find the related post, and return attributes needed by the template, leveraging Sharp's transformation API (see [how to transform data](how-to-transform-data.md)) — but we could instead directly build and return an array, as always.
::: warning
-There is a catch on transformation: instead of simply using `->transform()`, we
-used `->transformForTemplate()`: although this is not needed in all cases, this will ensure that field formatters are
-not called, since this could lead to unwanted transformation of the templates.
+There is a catch on transformation: instead of simply using `->transform()`, we used `->transformForTemplate()`: although this is not needed in all cases, this will ensure that field formatters are not called, since this could lead to unwanted transformation of the templates.
:::
Notice the `$isForm` param, which allows differentiating data depending on the context (Form or Show).
### `transformDataForFormFields(array $data): array`
-Similarly, this method is called to transform the data before displaying the form. This can be required in case your
-form includes fields like autocompletes, or uploads. You can refer once again to the documentation
-on [how to transform data](how-to-transform-data.md), and this time be sure to use the regular `->transform()` method,
-since data needs to be formatted for fields.
+Similarly, this method is called to transform the data before displaying the form. This can be required in case your form includes fields like autocompletes, or uploads. You can refer once again to the documentation on [how to transform data](how-to-transform-data.md), and this time be sure to use the regular `->transform()` method, since data needs to be formatted for fields.
## Configure the fields in Form and Show
diff --git a/docs/guide/form-fields/autocomplete-list.md b/docs/guide/form-fields/autocomplete-list.md
index 4283c6977..9b2dd1eab 100644
--- a/docs/guide/form-fields/autocomplete-list.md
+++ b/docs/guide/form-fields/autocomplete-list.md
@@ -12,7 +12,7 @@ You can in fact define the list as this:
SharpFormAutocompleteListField::make('winners')
->setLabel('Winners')
->setItemField(
- SharpFormAutocompleteField::make('item', 'remote')
+ SharpFormAutocompleteRemoteField::make('item')
->setRemoteEndpoint('/players')
// [...]
)
@@ -30,7 +30,7 @@ But why can't we use a classic List for this? Well, the `model->winners` relatio
Configuration is the same as the classic [List](list.md), except for:
-### `setItemField(SharpFormAutocompleteField $field)`
+### `setItemField(SharpFormAutocompleteRemoteField $field)`
You can use this function instead of `addItemField`, since items of AutocompleteList have only one field.
diff --git a/docs/guide/form-fields/autocomplete.md b/docs/guide/form-fields/autocomplete.md
index 32d70e45d..ed782ccc7 100644
--- a/docs/guide/form-fields/autocomplete.md
+++ b/docs/guide/form-fields/autocomplete.md
@@ -1,12 +1,8 @@
# Autocomplete
-Class: `Code16\Sharp\Form\Fields\SharpFormAutocompleteField`
+Classes: `Code16\Sharp\Form\Fields\SharpFormAutocompleteLocalField` and `Code16\Sharp\Form\Fields\SharpFormAutocompleteRemoteField`
-## Configuration
-
-### `self::make(string $key, string $mode)`
-
-`$mode` must be either "local" (dictionary is defined locally with `setLocalValues()`) or "remote" (a endpoint must be provided).
+## Configuration for local autocomplete
### `setLocalValues($localValues)`
@@ -17,109 +13,94 @@ Set the values of the dictionary on mode=local, as an object array with at least
Set the names of the attributes used in the search (mode=local).
Default: `['value']`
-### `setSearchMinChars(int $searchMinChars)`
+### `setLocalValuesLinkedTo(string ...$fieldKeys)`
-Set a minimum number of character to type before performing the search.
-Default: `1`
+This method is useful to link the dataset of a local autocomplete (aka: the `localValues`) to another form field. Please refer to [the documentation of the select field's `setOptionsLinkedTo()` method](select.md), which is identical.
-### `setRemoteEndpoint(string $remoteEndpoint)`
+## Configuration for remote autocomplete
-The endpoint to hit with mode=remote.
+### `setRemoteEndpoint(string $remoteEndpoint)`
-If this endpoint is yours (`remote` mode here is useful to avoid loading a lot of data in the view), you can add the `sharp_auth` middleware to the API route to handle authentication and prevent this API endpoint to be called by non-sharp users:
+The remote endpoint which should return JSON-formatted results. Note that you can add the `sharp_auth` middleware to this route to handle authentication and prevent this API endpoint to be called by non-sharp users:
```php
-Route::get('/api/sharp/clients')
- ->middleware('sharp_auth')
- ->uses('MySharpApiClientController@index')
-```
-
-### `setRemoteSearchAttribute(string $remoteSearchAttribute)`
-
-The attribute name sent to the remote endpoint as search key.
-Default: `'query'`
-
-### `setDataWrapper($dataWrapper)`
-
-Configure an optional dataWrapper to handle results sent in a wrapper, typically "data".
-Default: empty string.
-
-### `setDebounceDelayInMilliseconds($debounceDelay)`
-
-Configure the debounce delay between each endpoint call
-Default: 300.
+// in a route file
-### `setRemoteMethodGET()`
-### `setRemoteMethodPOST()`
-
-Set the remote method to GET (default) or POST.
+Route::get('/api/sharp/clients', [MySharpApiClientController::class, 'index'])
+ ->middleware('sharp_auth');
+```
-### `setItemIdAttribute(string $itemIdAttribute)`
+::: tip
+This endpoint MUST be part of your application. If you need to hit an external endpoint, you should create a custom endpoint in your application that will call the external endpoint (be sure to check the alternative `setRemoteCallback` method).
+:::
-Set the name of the id attribute for items. This is useful :
-- if you pass an object as the data for the autocomplete (meaning: in the formatter's `toFront`).
-- to designate the id attribute in the remote API call return.
-Default: `"id"`
+### `setRemoteCallback(Closure $closure, ?array $linkedFields = null)`
-### `setListItemInlineTemplate(string $template)`
-### `setResultItemInlineTemplate(string $template)`
-Just write the template as a string, using placeholders for data like this: `{{var}}`.
+To avoid the pain of writing a new dedicated endpoint, and for simple cases, you can use this method to provide a callback that will be called when the autocomplete field needs to fetch data. The callback will receive the search string as a parameter and should return an array of objects.
Example:
```php
-$panel->setInlineTemplate(
- 'Foreground: {{color}}'
-)
+SharpFormAutocompleteRemoteField::make('customer')
+ ->setRemoteCallback(function ($search) {
+ return Customer::select('id', 'name', 'email')
+ ->where('name', 'like', "%$search%")
+ ->get();
+ });
```
-The template will be used, depending on the function, to display either the list item (in the result dropdown) or the result item (meaning the valuated form input).
+The second argument, `$linkedFields`, allows you to provide a list of fields that will be sent with their values to the callback, so you can filter the results based on the values of other fields.
-Be aware that you'll need for this to work to pass a valuated object to the Autocomplete, as data.
+Example:
-### `setListItemTemplatePath(string $listItemTemplatePath)`
-### `setResultItemTemplatePath(string $resultItemTemplate)`
+```php
+SharpFormAutocompleteRemoteField::make('customer')
+ ->setRemoteCallback(function ($search, $linkedFields) {
+ return Customer::select('id', 'name', 'email')
+ ->when(
+ $linkedFields['country'],
+ fn ($query) => $query->where('country_id', $linkedFields['country'])
+ )
+ ->where('name', 'like', "%$search%")
+ ->get();
+ }, linkedFields: ['country']);
+```
-Use this if you need more control: give the path of a full template, in its own file.
+### `allowEmptySearch()`
-The template will be [interpreted by Vue.js](https://vuejs.org/v2/guide/syntax.html), meaning you can add data placeholders, DOM structure but also directives, and anything that Vue will parse. For instance:
+This method allows to call the endpoint / callback with empty search (on first click on the field for example). It's equivalent to `setSearchMinChars(0)`.
-```vue
-
result is {{value}}
-
result is unknown
-```
+### `setSearchMinChars(int $searchMinChars)`
-The template will be use, depending on the function, to display either the list item (in the result dropdown) or the result item (meaning the valuated form input).
+Set a minimum number of character to type before performing the search.
+Default: `1`
-Be aware that you'll need for this to work to pass a valuated object to the Autocomplete, as data.
+### `setRemoteSearchAttribute(string $remoteSearchAttribute)`
-### `setAdditionalTemplateData(array $data)`
+The attribute name sent to the remote endpoint as search key.
+Default: `'query'`
-Useful to add some static (or at least not instance-dependant) data to the template. For instance:
+### `setDataWrapper($dataWrapper)`
-```php
-SharpFormAutocompleteField::make('brand', 'remote')
- ->setAdditionalTemplateData([
- 'years' => [2020, 1018, 2017]
- ]);
-```
+Configure an optional dataWrapper to handle results sent in a wrapper, typically "data".
+Default: empty string.
-In the template, the provided data can be used as normal:
+### `setDebounceDelayInMilliseconds($debounceDelay)`
-```vue
-
{{ year }}
-```
+Configure the debounce delay between each endpoint call
+Default: 300.
-### `setLocalValuesLinkedTo(string ...$fieldKeys)`
+### `setRemoteMethodGET()`
+### `setRemoteMethodPOST()`
-This method is useful to link the dataset of a local autocomplete (aka: the `localValues`) to another form field. Please refer to [the documentation of the select field's `setOptionsLinkedTo()` method](select.md), which is identical.
+Set the remote method to GET (default) or POST.
### `setDynamicRemoteEndpoint(string $dynamicRemoteEndpoint, array $defaultValues)`
In a remote autocomplete case, you can use this method instead of `setRemoteEndpoint` to handle a dynamic URL, based on another form field. Here's how, for example:
```php
-SharpFormAutocompleteField::make('brand', 'remote')
+SharpFormAutocompleteRemoteField::make('brand')
->setDynamicRemoteEndpoint('/brands/{{country}}');
```
@@ -129,7 +110,7 @@ You may need to provide a default value for the endpoint, used when `country` (i
fill the second argument:
```php
-SharpFormAutocompleteField::make('model', 'remote')
+SharpFormAutocompleteRemoteField::make('model')
->setDynamicRemoteEndpoint(''/models/{{country}}/{{brand}}'', [
'country' => 'france',
'brand' => 'renault'
@@ -138,6 +119,34 @@ SharpFormAutocompleteField::make('model', 'remote')
The default endpoint would be `/brands/france/renault`.
+
+## Common configuration for both modes
+
+### `setItemIdAttribute(string $itemIdAttribute)`
+
+Set the name of the id attribute for items. This is useful :
+- if you pass an object as the data for the autocomplete (meaning: in the formatter's `toFront`).
+- to designate the id attribute in the remote API call return.
+Default: `"id"`
+
+### `setListItemTemplate(View|string $template)`
+### `setResultItemTemplate(View|string $template)`
+
+The templates for the list and result items can be set in two ways: either by passing a string, or by passing a Laravel view.
+
+Examples:
+
+```php
+SharpFormAutocompleteRemoteField::make('customer')
+ ->setRemoteCallback(function ($search) {
+ return Customer::select('id', 'name', 'email')
+ ->where('name', 'like', "%$search%")
+ ->get();
+ })
+ ->setListItemTemplate('
{{$name}}
{{$email}}
')
+ ->setResultItemTemplate(view('my/customer/blade/view'));
+```
+
## Formatter
### `toFront`
diff --git a/docs/guide/form-fields/date.md b/docs/guide/form-fields/date.md
index e79d644f2..630ab9d56 100644
--- a/docs/guide/form-fields/date.md
+++ b/docs/guide/form-fields/date.md
@@ -2,8 +2,6 @@
Class: `Code16\Sharp\Form\Fields\SharpFormDateField`
-
-
## Configuration
### `setHasDate($hasDate = true)`
@@ -31,10 +29,6 @@ If set, the time-chooser will be constraint as defined.
Set a time step (in minutes) for the time-chooser. Default is 30.
-### `setDisplayFormat(string $displayFormat)`
-
-Set the date / time display format in the field, as defined by [moment.js](https://momentjs.com/docs/#/parsing/string-format/). Default is `YYYY-MM-DD`.
-
## Formatter
diff --git a/docs/guide/form-fields/editor.md b/docs/guide/form-fields/editor.md
index c767059ae..241b6b9e7 100644
--- a/docs/guide/form-fields/editor.md
+++ b/docs/guide/form-fields/editor.md
@@ -4,9 +4,6 @@ This form field is a rich text editor, with formatting and an optional toolbar.
Class: `Code16\Sharp\Form\Fields\SharpFormEditorField`
-
-
-
## Configuration
### `setHeight(int $height, int|null $maxHeight = null)`
@@ -36,8 +33,6 @@ const A = 'link';
const H1 = 'heading-1';
const H2 = 'heading-2';
const H3 = 'heading-3';
-const UPLOAD_IMAGE = 'upload-image';
-const UPLOAD = 'upload';
const TABLE = 'table';
const IFRAME = 'iframe';
const RAW_HTML = 'html';
@@ -53,14 +48,29 @@ Example:
```php
SharpFormEditorField::make("description")
->setToolbar([
- SharpFormEditorField::B, SharpFormEditorField::I,
- SharpFormEditorField::SEPARATOR,
- SharpFormEditorField::UPLOAD_IMAGE,
+ SharpFormEditorField::B,
+ SharpFormEditorField::I,
SharpFormEditorField::SEPARATOR,
SharpFormEditorField::A,
]);
```
+If you have editor embeds you can add them to the toolbar alongside other buttons (instead of the embeds dropdown) :
+
+```php
+SharpFormEditorField::make("description")
+ ->setToolbar([
+ SharpFormEditorField::B,
+ SharpFormEditorField::I,
+ AuthorEmbed::class,
+ ])
+ ->allowEmbeds([
+ AuthorEmbed::class,
+ ]);
+```
+
+See full [embed docs](../form-editor-embeds.md).
+
### `setRenderContentAsMarkdown(bool $renderAsMarkdown = true)`
If true the front will send the content as markdown to the back, for storage. Default is false.
@@ -83,55 +93,44 @@ Display a character count in the status bar. Default is false.
## Embed images and files in content
-The Editor field can directly embed images or regular files. This works with `UPLOAD_IMAGE` and `UPLOAD` tools from the toolbar. To use this feature, add the tool in the toolbar and configure the environment:
+The Editor field can embed images or regular files. To use this feature, you must first allow the field to handle uploads:
+
+### `allowUploads(SharpFormEditorEmbedUpload $formEditorUpload)`
-### `setMaxFileSize(float $sizeInMB)`
+This method allows the user to upload files and images in the editor:
+
+```php
+$formFields->addField(
+ SharpFormEditorField::make('bio')
+ ->allowUploads(
+ SharpFormEditorEmbedUpload::make()
+ ->setStorageBasePath('posts/embeds')
+ ->setStorageDisk('local')
+ )
+);
+```
-Max file size allowed.
+The `SharpFormEditorEmbedUpload` can be configured with the same API as the `SharpFormUploadField`: `setMaxFileSize()`, `setImageOnly()`, `setAllowedExtensions()`, ... ([see full documentation](../form-fields/upload.md))
-### `setTransformable(bool $transformable = true, bool $transformKeepOriginal = true)`
+### A note on `setImageTransformable(bool $transformable = true, bool $transformKeepOriginal = true)`
-Allow the user to crop or rotate a visual, after the upload.
+As for a regular upload field, you can allow the user to crop or rotate the visual, after the upload.
With `$transformKeepOriginal` set to true, the original file will remain unchanged, meaning the transformations will be stored directly in the `` tag. For instance:
```blade
+{{-- (attribute JSON formatted for readability) --}}
+ file='{
+ "name":"image.jpg",
+ "path": "data/Posts/1/image.jpg",
+ "disk": "local",
+ "filters": { "crop": { "x":0, "y":0, "width":.5, "height":.5 } } }
+ '>
```
Then at render Sharp will take care of that for the thumbnail (see *Display embedded files in the public site* below).
-### `setCropRatio(string $ratio, array $croppableFileTypes = null)`
-
-Set a ratio constraint to uploaded images, formatted like this: `width:height`. For instance: `16:9`, or `1:1`.
-
-When a crop ratio is set, any uploaded picture will be auto-cropped (centered).
-
-The second argument, `$croppableFileTypes`, provide a way to limit the crop configuration to a list of image files extensions. For instance, it can be useful to define a crop for jpg and png, but not for gif because it would break animation.
-
-### `setStorageDisk(string $storageDisk)`
-
-Set the destination storage disk (as configured in Laravel's `config/filesystem.php` config file).
-
-### `setStorageBasePath(string $storageBasePath)`
-
-Set the destination base storage path. You can use the `{id}` special placeholder to add the instance id in the path.
-
-For instance:
-`$field->setStorageBasePath('/users/{id}/markdown')`
-
-### `setFileFilter($fileFilter)`
-
-Set the allowed file extensions. You can pass either an array, or a comma-separated list.
-
-### `setFileFilterImages()`
-
-Just a `setFileFilter(['.jpg','.jpeg','.gif','.png'])` shorthand.
-
### Store images and files
Sharp takes care of copying the file at the right place (after image transformation, if wanted), based on the configuration.
@@ -139,19 +138,25 @@ Sharp takes care of copying the file at the right place (after image transformat
When inserting a file, the following tag is added in field text value:
```blade
+{{-- (attribute JSON formatted for readability) --}}
+ file='{
+ "name": "doc.pdf",
+ "path": "data/Posts/1/doc.pdf",
+ "disk": "local"
+ '>
```
In case of an image the inserted tag is:
```blade
+{{-- (attribute JSON formatted for readability) --}}
+ file='{
+ "name":"image.jpg",
+ "path": "data/Posts/1/image.jpg",
+ "disk": "local",
+ '>
```
@@ -205,7 +210,7 @@ To add custom attributes to `` component you can use the followin
You can extend `` and `` components by publishing them:
```
-php artisan vendor:publish --provider=Code16\\Sharp\\SharpServiceProvider --tag=views
+php artisan vendor:publish --tag=sharp-views
```
Here are the parameters passed to the components:
@@ -230,19 +235,13 @@ Example:
## Custom embeds
-This feature allows to embed any structured data in the content. A common use case is to embed a reference to another
-instance, like for example: in a blog post, you want to insert a reference to another post, that would be rendered as
-a "read also" block / link in the public section.
-
-
+This feature allows to embed any structured data in the content. A common use case is to embed a reference to another instance, like for example: in a blog post, you want to insert a reference to another post, that would be rendered as a “read also” block / link in the public section.
-In practice, the Editor field can allow custom embeds, which defines how the data is stored in the field (as HTML
-attributes), and how it is edited in the UI, via a full-featured form.
+In practice, the Editor field can allow custom embeds, which defines how the data is stored in the field (as HTML attributes), and how it is edited in the UI, via a full-featured form.
### `allowEmbeds(array $embeds)`
-This method expects an array of embeds that could be inserted in the content, declared as full class names. An embed
-class must extend `Code16\Sharp\Form\Fields\Embeds\SharpFormEditorEmbed`.
+This method expects an array of embeds that could be inserted in the content, declared as full class names. An embed class must extend `Code16\Sharp\Form\Fields\Embeds\SharpFormEditorEmbed`.
The [documentation on how to write an Embed class is available here](../form-editor-embeds.md).
diff --git a/docs/guide/form-fields/geolocation.md b/docs/guide/form-fields/geolocation.md
index 8e98e029c..c21569a78 100644
--- a/docs/guide/form-fields/geolocation.md
+++ b/docs/guide/form-fields/geolocation.md
@@ -4,23 +4,6 @@ A map-based field to pick a precise location and return its coordinates (latitud
Class: `Code16\Sharp\Form\Fields\SharpFormGeolocationField`
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
## Configuration
### `setDisplayUnitDegreesMinutesSeconds()`
@@ -77,6 +60,9 @@ This method will set the API key for geocoding only.
This method will set the API key for maps only.
+### `setGoogleMapsMapId(string $mapId)`
+
+Google Maps API now requires a [Map ID](https://developers.google.com/maps/documentation/get-map-id) to use markers. It must be defined if maps provider is set to "gmaps".
## Formatter
diff --git a/docs/guide/form-fields/html.md b/docs/guide/form-fields/html.md
index 0e8c4a21d..9899fb551 100644
--- a/docs/guide/form-fields/html.md
+++ b/docs/guide/form-fields/html.md
@@ -6,43 +6,33 @@ This field is read-only, and is meant to display some dynamic information in the
## Configuration
-### `setInlineTemplate(string $template)`
+### `setTemplate(string|View $template)`
-Write the template as a string, using placeholders for data like this: `{{var}}` where "var" is some key to data sent to the front
-
-Example:
+Write the blade template as a string. Example:
```php
SharpFormHtmlField::make('panel')
- ->setInlineTemplate('This product is offline since {{date}}')
+ ->setTemplate('This product is offline since {{ $date }}')
```
-Like other fields, this example would mean that your transformed data has an object named `panel` containing a `date` attribute. Here more than elsewhere you may need to use a custom transformer, like this is this piece of code:
+This example would mean that your transformed data has an object named `panel` containing a `date` attribute. Here a custom transformer example for this particular case:
```php
function find($id): array
- {
- return $this
- ->setCustomTransformer('panel', function($product) {
- return [
- 'date' => $product->deprecated_at->isoFormat()
- ];
- })
- ->transform(
- Product::findOrFail($id)
- );
- }
+{
+ return $this
+ ->setCustomTransformer('panel', fn ($value, $instance) => [
+ 'date' => $instance->deprecated_at->isoFormat()
+ ])
+ ->transform(Product::find($id));
+}
```
-### `setTemplatePath(string $templatePath)`
-
-Use this if you need more control: give the path of a full template, in its own file.
-
-The template will be [interpreted by Vue.js](https://vuejs.org/v2/guide/syntax.html), meaning you can add data placeholders, DOM structure but also directives, and anything that Vue will parse. For instance:
+You can also pass a view (blade) :
-```vue
-
result is {{value}}
-
result is unknown
+```php
+SharpFormHtmlField::make('panel')
+ ->setTemplate(view('sharp.form-htm-field'))
```
## Formatter
diff --git a/docs/guide/form-fields/list.md b/docs/guide/form-fields/list.md
index 7b4ac45a0..85abb3cd3 100644
--- a/docs/guide/form-fields/list.md
+++ b/docs/guide/form-fields/list.md
@@ -12,21 +12,21 @@ Here's how we can build this:
function buildFormFields()
{
$this->addField(
- SharpFormListField::make("pieces")
- ->setLabel("Art pieces")
+ SharpFormListField::make('pieces')
+ ->setLabel('Art pieces')
->setAddable()
->setRemovable()
->addItemField(
- SharpFormDateField::make("acquisition_date")
- ->setLabel("Acquisition")
+ SharpFormDateField::make('acquisition_date')
+ ->setLabel('Acquisition')
)
->addItemField(
- SharpFormTextField::make("title")
- ->setLabel("Title")
+ SharpFormTextField::make('title')
+ ->setLabel('Title')
)
->addItemField(
- SharpFormSelectField::make("artist_id", [...])
- ->setLabel("Artist")
+ SharpFormSelectField::make('artist_id', /*[...]*/)
+ ->setLabel('Artist')
)
);
}
@@ -63,29 +63,6 @@ Default: false.
This is only useful when using the `WithSharpFormEloquentUpdater` trait. You can define here the name of an numerical order attribute (typically: `order`), and it will be automatically updated in the `save()` process.
-### `setCollapsedItemInlineTemplate(string $template)`
-### `setCollapsedItemTemplatePath(string $template)`
-
-The UI for a `sortable` List is to add a "reorder" button, which swaps the list in a readonly state. But for big List items it can be useful to define a special template for this reordering state.
-For inline template, just write the template as a string, using placeholders for data like this: `{{var}}`.
-
-
-Example:
-
-```php
-$list->setCollapsedItemInlineTemplate(
- "Foreground: {{color}}"
-)
-```
-
-For template path, give the relative path of a template file (stating in the views Laravel folder).
-The template will be [interpreted by Vue.js](https://vuejs.org/v2/guide/syntax.html), meaning you can add data placeholders, DOM structure but also directives, and anything that Vue will parse. For instance:
-
-```vue
-
result is {{value}}
-
result is unknown
-```
-
### `setRemovable(bool $removable = true)`
Defines if items can be removed by the user.
@@ -110,18 +87,27 @@ Default: 10
## Layout
-The List item layout must be defined like the form itself, in the `buildFormLayout()` function. The item layout is managed as a Form column, with a `FormLayoutColumn` object. To link the column and the item, use the classic `withSingleField()` function with a second argument, a Closure accepting a `FormLayoutColumn`.
+The List item layout must be defined like the form itself, in the `buildFormLayout()` function. The item layout is managed as a Form column, with a `FormLayoutColumn` object. To link the column and the item, use the classic `withField()` function with a second argument, a Closure accepting a `FormLayoutColumn`.
Here's an example for the Museum List defined above:
```php
-$this->addColumn(6, function(FormLayoutColumn $column) {
- $column->withSingleField("pieces", function(FormLayoutColumn $listItem) {
- $listItem->withSingleField("acquisition_date")
- ->withSingleField("title")
- ->withSingleField("artist_id");
- });
- });
+class MyForm extends SharpForm
+{
+ // [...]
+
+ function buildFormLayout(FormLayout $formLayout)
+ {
+ $this->addColumn(6, function (FormLayoutColumn $column) {
+ $column->withListField('pieces', function (FormLayoutColumn $listItem) {
+ $listItem
+ ->withField('acquisition_date')
+ ->withField('title')
+ ->withField('artist_id');
+ });
+ });
+ }
+}
```
## Formatter
diff --git a/docs/guide/form-fields/select.md b/docs/guide/form-fields/select.md
index 918a3f91f..cbba056ca 100644
--- a/docs/guide/form-fields/select.md
+++ b/docs/guide/form-fields/select.md
@@ -2,8 +2,6 @@
Class: `Code16\Sharp\Form\Fields\SharpFormSelectField`
-
-
## Configuration
### `self::make(string $key, array $options)`
@@ -42,9 +40,6 @@ SharpFormSelectField::make(
Allow multi-selection (default: false)
-
-
-
### `setClearable(bool $clearable = true)`
Allow null value in non-multiple selection (default: false)
@@ -56,14 +51,10 @@ Display as a list (the default value):
- radio if multiple=false
- checkboxes if multiple=true
-
-
### `setDisplayAsDropdown()`
Display as a classic dropdown.
-
-
### `setMaxSelected(int $maxSelected)`
Set a maximum item selection (multiple only).
diff --git a/docs/guide/form-fields/text.md b/docs/guide/form-fields/text.md
index a76625dff..d8ede24e8 100644
--- a/docs/guide/form-fields/text.md
+++ b/docs/guide/form-fields/text.md
@@ -10,7 +10,19 @@ Used to set the type to regular `text` (the default).
### `setInputTypePassword()`
-Used to set the type to `password`.
+Used to set the type to `password`. An "eye button" is displayed to show / hide the input value.
+
+### `setInputTypeEmail()`
+
+Used to set the type to `email`.
+
+### `setInputTypeTel()`
+
+Used to set the type to `tel`.
+
+### `setInputTypeUrl()`
+
+Used to set the type to `url`.
### `setMaxLength(int $maxLength)`
@@ -24,4 +36,4 @@ Unset the max character count.
## Formatter
- `toFront`: expect a string.
-- `fromFront`: returns a string.
\ No newline at end of file
+- `fromFront`: returns a string.
diff --git a/docs/guide/form-fields/upload.md b/docs/guide/form-fields/upload.md
index 331264c62..ddfb7c13a 100644
--- a/docs/guide/form-fields/upload.md
+++ b/docs/guide/form-fields/upload.md
@@ -2,76 +2,78 @@
Class: `Code16\Sharp\Form\Fields\SharpFormUploadField`
-
-
## General configuration
-First, in order to get the upload part working, you have to define a "tmp" path where files will be stored until they are moved to the final folder. Here's the default:
+You can define the temp disk and directory where files will be stored until they are moved to the final folder, as well as a global max file size (which can be overriden by each field). Here are the default values:
```php
-// in config/sharp.php
-
-'uploads' => [
- 'tmp_disk' => env('SHARP_UPLOADS_TMP_DISK', 'local'),
- 'tmp_dir' => env('SHARP_UPLOADS_TMP_DIR', 'tmp'),
-]
+class SharpServiceProvider extends SharpAppServiceProvider
+{
+ protected function configureSharp(SharpConfigBuilder $config): void
+ {
+ $config
+ ->configureUploads(
+ uploadDisk: 'local',
+ uploadDirectory: 'tmp',
+ globalMaxFileSize: 5,
+ keepOriginalImageOnTransform: true
+ )
+ // [...]
+ }
+}
```
-This `tmp_dir` path is relative to the `uploads.tmp_disk` filesystem defined.
+The fourth argument, `keepOriginalImageOnTransform`, is a boolean that defines if the original image should be kept when a transformation is applied on it (meaning that transformations are stored and applied on-the-fly: this is transparent when using Sharp’s [built-in way to handle uploads](../sharp-uploads.md). It can be overriden by each field (see below).
## Field Configuration
-### `setMaxFileSize(float $sizeInMB)`
-
-Max file size allowed.
+### `setStorageDisk(string $storageDisk)`
-### `setTransformable(bool $transformable = true, ?bool $transformKeepOriginal = null)`
+Set the destination storage disk (as configured in Laravel’s `config/filesystem.php` config file).
-Allow the user to crop or rotate the visual, after the upload.
-The argument `$transformKeepOriginal` overrides the following config which is `true` by default.
-```php
-// config/sharp.php
+### `setStorageBasePath(string|Closure $storageBasePath)`
-'uploads' => [
- 'transform_keep_original_image' => true,
-]
-```
-With `$transformKeepOriginal` set to true, the original file will remain unchanged, meaning the transformations will be stored apart: using the [built-in way to handle uploads](../sharp-uploads.md), it's transparent. Otherwise, see the Formatter part below.
+Set the destination base storage path.
-### `setCropRatio(string $ratio, array $croppableFileTypes = null)`
+::: warning
+If you want to use a `{id}` special placeholder to add the instance id in the path (for instance: `$field->setStorageBasePath('/users/{id}/avatar')`), you must be the Eloquent case, leveraging `Code16\Sharp\Form\Eloquent\WithSharpFormEloquentUpdater` (see [Eloquent form](../building-form#eloquent-case-where-the-magic-happens))
+:::
-Set a ratio constraint to uploaded images, formatted like this: `width:height`. For instance: `16:9`, or `1:1`.
+### `setAllowedExtensions(string|array $allowedExtensions)`
-When a crop ratio is set, any uploaded picture will be auto-cropped (centered).
+Define the allowed file extensions.
-The second argument, `$croppableFileTypes`, provide a way to limit the crop configuration to a list of image files extensions. For instance, it can be useful to define a crop for jpg and png, but not for gif because it will destroy animation.
+For instance: `$field->setAllowedExtensions(['pdf', 'zip'])`
-### `setStorageDisk(string $storageDisk)`
+## Field Configuration in image case
-Set the destination storage disk (as configured in Laravel's `config/filesystem.php` config file).
+### `setImageOnly(bool $imageOnly = true)`
-### `setStorageBasePath(string|Closure $storageBasePath)`
+When an upload field is configured to accept only images:
+- the field will be forced to accept only images (allowed extensions set to "jpg, png, gif, svg, webp, bmp" by default),
+- the uploaded file will be validated as an image (see below for more options),
+- a thumbnail will be generated for the uploaded image.
-Set the destination base storage path.
+### `setImageTransformable(bool $transformable = true, ?bool $transformKeepOriginal = null)`
-You can use the `{id}` special placeholder to add the instance id in the path, which can be useful sometimes; **be sure to read the “Delayed creation” section, at the end of this page if you do.**
+Allow the user to crop or rotate the visual, after the upload.
+The argument `$transformKeepOriginal` overrides the global config (which is `true` by default).
-For instance:
-`$field->setStorageBasePath('/users/{id}/avatar')`
+With `$transformKeepOriginal` set to true, the original file will remain unchanged, meaning the transformations will be stored apart: using the [built-in way to handle uploads](../sharp-uploads.md), it's transparent. Otherwise, see the Formatter part below.
-### `setFileFilter($fileFilter)`
+### `setImageCropRatio(string $ratio, array $croppableFileTypes = null)`
-Set the allowed file extensions. You can pass either an array or a comma-separated list.
+Set a ratio constraint to uploaded images, formatted like this: `width:height`. For instance: `16:9`, or `1:1`.
-### `setFileFilterImages()`
+When a crop ratio is set, any uploaded picture will be auto-cropped (centered).
-Just a `setFileFilter(['.jpg','.jpeg','.gif','.png'])` shorthand.
+The second argument, `$croppableFileTypes`, provide a way to limit the crop configuration to a list of image files extensions. For instance, it can be useful to define a crop for jpg and png, but not for gif because it will destroy animation.
-### `setCompactThumbnail(bool $compactThumbnail = true)`
+### `setImageCompactThumbnail(bool $compactThumbnail = true)`
If true and if the upload has a thumbnail, it is limited to 60px high (to compact in a list item, for instance).
-### `shouldOptimizeImage(bool $shouldOptimizeImage = true)`
+### `setImageOptimizeImage(bool $imageOptimize = true)`
If true, some optimization will be applied on the uploaded images (in order to reduce files weight). It relies on spatie's [image-optimizer](https://github.com/spatie/image-optimizer). Please note that you will need some of these packages on your system:
- [JpegOptim](http://freecode.com/projects/jpegoptim)
@@ -83,6 +85,20 @@ If true, some optimization will be applied on the uploaded images (in order to r
Check their documentation for [more instructions](https://github.com/spatie/image-optimizer#optimization-tools) on how to install.
+## Validation
+
+Notice that `setAllowedExtensions()` and `setImageOnly()` already are basic validation rules that Sharp will use both on the front-end and in the back-end.
+
+But there are a few more rules available:
+
+### `setMaxFileSize(int $maxFileSizeInMB)` and `setMinFileSize(int $minFileSizeInMB)`
+
+Set the maximum and minimum (even if this is a rare use-case) file size in MB.
+
+### `setImageDimensionConstraints(Illuminate\Validation\Rules\Dimensions $dimensions)`
+
+Set image dimension constraints, leveraging the dedicated Laravel validation rule (see [the documentation](https://laravel.com/docs/validation#rule-dimensions)).
+
## Formatter
First, let's mention that Sharp provides an Eloquent built-in solution for uploads with the `SharpUploadModel` class, as [detailed here](../sharp-uploads.md), which greatly simplify the work (to be clear: it will handle everything from storage to image transformations).
@@ -126,15 +142,13 @@ function find($id): array
'name' => basename($product->picture->name),
'path' => $product->picture->name,
'disk' => 's3',
- 'thumbnail' => [...],
+ 'thumbnail' => /* thumbnail URL */,
'size' => $product->picture->size,
'filters' => $product->picture->filters
];
}
)
- ->transform(
- Product::findOrFail($id)
- );
+ ->transform(Product::find($id));
}
```
@@ -146,14 +160,14 @@ There are four cases:
#### newly uploaded file
-The formatter will store the file on the configured location, and return an array like this:
+The formatter must return an array like this:
```php
[
- 'file_name' => '', // Relative file path
+ 'file_name' => '', // Target file path (relative)
'size' => x, // File size in bytes
'mime_type' => '', // File mime type
- 'disk' => '', // Storage disk name
+ 'disk' => '', // Target storage disk name
'filters' => [ // Transformations applied to the (image) file
'crop' => [
'x' => x,
@@ -183,9 +197,9 @@ function update($id, array $data)
}
```
-#### existing transformed file
+#### existing transformed image
-In this case, the file was already stored in a previous post, and was then transformed (cropped, or rotated). The formatter will simply return and array with one `filters` key:
+In this case, the image was already handled in a previous post, and was then transformed (cropped, or rotated). The formatter will simply return and array with one `filters` key:
```php
[
@@ -213,54 +227,23 @@ The formatter will return `null` (note that the file **will not** be deleted fro
The formatter will return **an empty array**.
-## Delayed creation
-
-As described in the `setStorageBasePath()` section of this document, you can configure the file storage path with an `{id}` placeholder, meaning that `/users/{id}/avatar` will be converted (by the field formatter) in `/users/1/avatar` for instance.
-
-But in order to do this in a creation case, when there is no id yet, Sharp will need your instance to be stored first. To do so, the `update()` method of your Form will be called twice:
-
-- one first time without any upload which needs the `{id}`,
-- and one second time only with these fields, using the new id returned by `update()`.
+## Configure files jobs
-This is usually OK, but in some cases this could lead to unexpected errors. Consider this code where we handle `Products` with a `picture` configured with an `{id}` placeholder in its path:
+Sharp handle files in jobs (copy / move and transformation). You can configure how these job should be dispatched:
```php
-class ProductForm extends SharpForm
+class SharpServiceProvider extends SharpAppServiceProvider
{
- // [...]
-
- public function buildFormFields(FieldsContainer $formFields): void
+ protected function configureSharp(SharpConfigBuilder $config): void
{
- // [...]
-
- $formFields
- ->addField(
- SharpFormUploadField::make('picture')
- ->setLabel('Picture')
- ->setFileFilterImages()
- ->setStorageDisk('local')
- ->setStorageBasePath('data/products/{id}'),
- );
- }
-
- function update($id, array $data)
- {
- $instance = $id ? Product::findOrFail($id) : new Product();
-
- $this->save($instance, $data);
-
- if(($data['price']) >= 1000) {
- $this->notify('Yay, this is an expensive product...');
- }
-
- return $instance->id;
+ $config
+ ->configureUploads(
+ fileHandingQueue: 'default',
+ fileHandlingQueueConnection: 'sync',
+ )
+ // [...]
}
}
```
-Here we're using the `notify()` feature to display a message back to the user, and it's working, excepted in one case: on a Product creation with a picture, Sharp will delay the upload handling and call this method twice, because the picture field needs the product {id} it the storage base path. On the second pass (for the upload), This code will crash on the `if(($data['price']) ...)` condition, because `$data['price']` is not set (only the `picture` upload field would be set on this second pass). This has to be addressed, and a working solution (among others) could be to replace this line with:
-```php
-if(($data['price'] ?? 0) >= 1000) {
- [...]
-}
-```
+Queue and connection should be [properly configured](https://laravel.com/docs/queues).
\ No newline at end of file
diff --git a/docs/guide/global-search.md b/docs/guide/global-search.md
index 889a29696..a982e8377 100644
--- a/docs/guide/global-search.md
+++ b/docs/guide/global-search.md
@@ -2,20 +2,20 @@
This feature allows the user to globally search across a selected set of entities of your application.
-
+
## Configuration
```php
-// In config/sharp.php
-return [
- // ...
- 'search' => [
- 'enabled' => true,
- 'placeholder' => 'Search for anything...',
- 'engine' => \App\Sharp\MySearchEngine::class,
- ],
-];
+class SharpServiceProvider extends SharpAppServiceProvider
+{
+ protected function configureSharp(SharpConfigBuilder $config): void
+ {
+ $config
+ ->enableGlobalSearch(\App\Sharp\MySearchEngine::class, 'Search for anything...')
+ // ...
+ }
+}
```
## Write the class
@@ -28,10 +28,7 @@ class MySearchEngine extends SharpSearchEngine
public function searchFor(array $terms): void
{
$resultSet = $this
- ->addResultSet(
- label: 'Posts',
- icon: 'fa-file-o',
- );
+ ->addResultSet('Posts');
$builder = Post::query();
@@ -74,10 +71,7 @@ class MySearchEngine extends SharpSearchEngine
public function searchFor(array $terms): void
{
$resultSet = $this
- ->addResultSet(
- label: 'Posts',
- icon: 'fa-file-o',
- );
+ ->addResultSet('Posts');
if (! $resultSet->validateSearch(
['string', 'min:3'],
@@ -95,6 +89,21 @@ class MySearchEngine extends SharpSearchEngine
As you can see in this example, the `validateSearch()` method accepts an array of regular Laravel validation rules, and an optional array of custom validation messages. Sharp will not display results if the validation fails, but a good practice is to return early in this case, to avoid unnecessary queries.
+### Authorization
+You may need to enable global search only for a subset of your users. You can do so by overriding the `authorize()` method in your search engine class:
+
+```php
+class MySearchEngine extends SharpSearchEngine
+{
+ // ...
+
+ public function authorize(): bool
+ {
+ return auth()->user()->isAdministrator();
+ }
+}
+```
+
## Use the search field
-The search field is available in the top bar of Sharp, and can be called with these pretty standard keyboard shortcuts: `Ctrl+K`, `Cmd+K` (Mac) or simply `/`.
\ No newline at end of file
+The search field is available in the top bar of Sharp, and can be called with these pretty standard keyboard shortcuts: `Ctrl+K`, `Cmd+K` (Mac) or simply `/`.
diff --git a/docs/guide/how-to-transform-data.md b/docs/guide/how-to-transform-data.md
index 3a994f6cd..34f31d5e9 100644
--- a/docs/guide/how-to-transform-data.md
+++ b/docs/guide/how-to-transform-data.md
@@ -11,7 +11,7 @@ Note that transformers need your data models to allow direct access to their att
In an Entity List, a Show Page or a Form, you can use the `transform()` function which will:
- apply all custom transformers on your list (see below),
-- transform the given model(s) into an array, handling pagination if a `LengthAwarePaginator` is provided.
+- transform the given model(s) into an array, handling pagination if a `Paginator` is provided.
Eloquent example in an Entity List:
@@ -105,7 +105,7 @@ class ProductEntityList extends SharpEntityList
function buildList(EntityListFieldsContainer $fields): void
{
- $fieldsContainer->addField(
+ $fields->addField(
EntityListDataContainer::make('author:name')
->setLabel('Author')
);
diff --git a/docs/guide/img/breadcrumb-v8.png b/docs/guide/img/breadcrumb-v8.png
deleted file mode 100644
index e05ebf6a3..000000000
Binary files a/docs/guide/img/breadcrumb-v8.png and /dev/null differ
diff --git a/docs/guide/img/embed-editor.png b/docs/guide/img/embed-editor.png
deleted file mode 100644
index b3e44616f..000000000
Binary files a/docs/guide/img/embed-editor.png and /dev/null differ
diff --git a/docs/guide/img/embed-form.png b/docs/guide/img/embed-form.png
deleted file mode 100644
index 8c6fc3f18..000000000
Binary files a/docs/guide/img/embed-form.png and /dev/null differ
diff --git a/docs/guide/img/form-localization-v8.png b/docs/guide/img/form-localization-v8.png
deleted file mode 100644
index c5b169681..000000000
Binary files a/docs/guide/img/form-localization-v8.png and /dev/null differ
diff --git a/docs/guide/img/global-filters.png b/docs/guide/img/global-filters.png
deleted file mode 100644
index dada7ebee..000000000
Binary files a/docs/guide/img/global-filters.png and /dev/null differ
diff --git a/docs/guide/img/global-search.png b/docs/guide/img/global-search.png
deleted file mode 100644
index e37bf8a7e..000000000
Binary files a/docs/guide/img/global-search.png and /dev/null differ
diff --git a/docs/guide/img/menu-v8.png b/docs/guide/img/menu-v8.png
deleted file mode 100644
index e5690e48a..000000000
Binary files a/docs/guide/img/menu-v8.png and /dev/null differ
diff --git a/docs/guide/img/page-alert-v8.png b/docs/guide/img/page-alert-v8.png
deleted file mode 100644
index 2a07bcb5e..000000000
Binary files a/docs/guide/img/page-alert-v8.png and /dev/null differ
diff --git a/docs/guide/img/v9/embed-editor.png b/docs/guide/img/v9/embed-editor.png
new file mode 100644
index 000000000..d95197eb4
Binary files /dev/null and b/docs/guide/img/v9/embed-editor.png differ
diff --git a/docs/guide/img/v9/embed-form.png b/docs/guide/img/v9/embed-form.png
new file mode 100644
index 000000000..b0c619f28
Binary files /dev/null and b/docs/guide/img/v9/embed-form.png differ
diff --git a/docs/guide/img/v9/global-search.png b/docs/guide/img/v9/global-search.png
new file mode 100644
index 000000000..e2c67c324
Binary files /dev/null and b/docs/guide/img/v9/global-search.png differ
diff --git a/docs/guide/img/v9/page-alert.png b/docs/guide/img/v9/page-alert.png
new file mode 100644
index 000000000..c948f4cab
Binary files /dev/null and b/docs/guide/img/v9/page-alert.png differ
diff --git a/docs/guide/img/v9/wizard-command.gif b/docs/guide/img/v9/wizard-command.gif
new file mode 100644
index 000000000..0939fbfbd
Binary files /dev/null and b/docs/guide/img/v9/wizard-command.gif differ
diff --git a/docs/guide/img/wizard-command.gif b/docs/guide/img/wizard-command.gif
deleted file mode 100644
index b664b7111..000000000
Binary files a/docs/guide/img/wizard-command.gif and /dev/null differ
diff --git a/docs/guide/index.md b/docs/guide/index.md
index 6e9cece95..eebaead21 100644
--- a/docs/guide/index.md
+++ b/docs/guide/index.md
@@ -1,13 +1,13 @@
-# Getting started
+# Getting started and installation
## Terminology, general concept
In Sharp, we handle `entities`; an `entity` is simply a data structure which has a meaning in the application context. For instance, a `Person`, a `Post` or an `Order`. In the Eloquent world, for which Sharp is optimized, it's typically a Model — but it's not necessarily a 1-1 relationship, a Sharp `entity` can represent a portion of a Model, or several Models.
-Each instance of an `entity` is called... an `instance`.
+An instance of an `entity` is simply called an `instance`.
Each `entity` in Sharp can be displayed:
-- in an `Entity List`, which is the list of all the `instances` for this `entity`: with some configuration and code, the user can sort the data, add filters, pagination, and perform searches. From there we also gain access to applicative `commands` applied either to an `instance` or to the whole (filtered) list, and to a simple `state` changer (the published state of an Article, for instance). All of that is described below.
+- in an `Entity List`, which is the list of all the `instances` for this `entity`: with some configuration and code, the user can sort the data, add filters, pagination, and perform searches. From there we also gain access to applicative `commands` applied either to any particular `instance` or to the whole (filtered) list, and to a simple `state` changer (the published state of an Article, for instance). All of that is described below.
- In a `Show Page`, optionally, to display an `instance` details.
- And in a `Form`, either to update or create a new `instance`.
@@ -35,45 +35,39 @@ Finally, **orders**, must be listed, detailed and updatable, and we also need to
-Maybe we can add an `Entity Cmmand` to export orders in a CSV file in the `Entity List`, and an `Instance command` on the order `Show Page` to declare the order as shipped.
+Maybe we can add an `Entity Command` to export orders in a CSV file in the `Entity List`, and an `Instance command` on the order `Show Page` to declare the order as shipped.
This is a simple example to illustrate the main concepts of Sharp: we'll see in this guide how to build such structures but also more complexe ones, and how to manage states, commands, dashboards, authorizations, errors, validation... in the process.
## Installation
-Sharp 8 needs Laravel 10+ and PHP 8.2+.
+Sharp 9 needs Laravel 11+ and PHP 8.2+.
- Add the package with composer: `composer require code16/sharp`
-- And then publish assets: `php artisan vendor:publish --provider="Code16\Sharp\SharpServiceProvider" --tag=assets`
-
-A tip on this last command: you'll need fresh assets each time Sharp is updated, so a good practice is to add the command in the `scripts.post-autoload-dump` section of your `composer.json` file:
-
-```json
-"scripts": {
- [...]
- "post-autoload-dump": [
- "Illuminate\\Foundation\\ComposerScripts::postAutoloadDump",
- "@php artisan vendor:publish --provider=Code16\\Sharp\\SharpServiceProvider --tag=assets --force",
- "@php artisan package:discover"
- ]
-},
-```
-
-## Configuration
+- Then run: `php artisan sharp:install`
-Sharp needs a `config/sharp.php` config file, mainly to declare `entities`.
+This last script will publish required assets, create a `SharpServiceProvider` in the `App\Providers` namespace, and a `SharpMenu` class in the `App\Sharp` namespace.
-You can initialize this file with `php artisan vendor:publish --provider="Code16\Sharp\SharpServiceProvider" --tag=config`
+## Configuration via a new Service Provider
-Here's an example:
+All Sharp behavior is configured in the `App\Providers\SharpServiceProvider` class created by the `sharp:install` command; you can declare your entities in the `configureSharp()` method:
```php
-return [
- 'entities' => [
- 'products' => \App\Sharp\Entities\ProductEntity::class,
- // Other entities...
- ]
-];
+use Code16\Sharp\SharpAppServiceProvider;
+use Code16\Sharp\Config\SharpConfigBuilder;
+use App\Sharp\SharpMenu;
+
+class SharpServiceProvider extends SharpAppServiceProvider
+{
+ protected function configureSharp(SharpConfigBuilder $config): void
+ {
+ $config
+ ->setName('My new project')
+ ->setSharpMenu(SharpMenu::class)
+ ->addEntity('product', ProductEntity::class);
+ // ...
+ }
+}
```
This `ProductEntity` class could be written like this:
@@ -101,19 +95,22 @@ Almost each one is optional, in fact: we could skip the `show` and go straight t
We'll get into all those classes in this guide. The important thing to notice is that Sharp provides base classes to handle all the wiring (and more), but as we'll see, the applicative code is totally up to you.
::: tip
-Instead of directly declaring an array of entities in the config file, you can type the full path of a class that implements the `Code16\Sharp\Utils\Entities\SharpEntityResolver` interface, and define here a `public function entityClassName(string $entityKey): ?string` method.
+Use the artisan command `php artisan sharp:make:entity` to generate a new entity with all the required classes, or the global one (prompt based) `php artisan sharp:generator`.
:::
## Access to Sharp
-Once installed, Sharp is accessible via the url `/sharp`, by default. If you wish to change this default value, you'll need to define the `custom_url_segment` config value, in `config/sharp.php`:
+Once installed, Sharp is accessible via the url `/sharp`, by default. If you wish to change this default value, you'll need to configure a custom segment path:
```php
-// config/sharp.php
-
-return [
- 'name' => 'My Sharp app',
- 'custom_url_segment' => 'admin',
- // ...
-]
+class SharpServiceProvider extends SharpAppServiceProvider
+{
+ protected function configureSharp(SharpConfigBuilder $config): void
+ {
+ $config
+ ->setCustomUrlSegment('admin')
+ ->addEntity('product', ProductEntity::class)
+ // ...
+ }
+}
```
diff --git a/docs/guide/link-to.md b/docs/guide/link-to.md
index bfd75a82d..c92b07c1d 100644
--- a/docs/guide/link-to.md
+++ b/docs/guide/link-to.md
@@ -10,10 +10,11 @@ Depending on your target, you'll want to use either:
- `Code16\Sharp\Utils\Links\LinkToShowPage`
- `Code16\Sharp\Utils\Links\LinkToSingleShowPage`
- `Code16\Sharp\Utils\Links\LinkToSingleForm`
+- `Code16\Sharp\Utils\Links\LinkToDashboard`
To create an instance, use the static `make` method, which may take one or two arguments:
-- For `LinkToEntityList`, `LinkToSingleShowPage` and `LinkToSingleForm`: `::make($entityKey)`
+- For `LinkToEntityList`, `LinkToSingleShowPage`, `LinkToSingleForm` and `LinkToDashboard`: `::make($entityKey)`
- For `LinkToForm` and `LinkToShowPage`: `::make($entityKey, $instanceId)`
## Link use case
diff --git a/docs/guide/page-alerts.md b/docs/guide/page-alerts.md
index cd2cb9abb..134a89394 100644
--- a/docs/guide/page-alerts.md
+++ b/docs/guide/page-alerts.md
@@ -1,132 +1,56 @@
# Add global page alert
-This feature makes it possible to add a message (with an alert or not) at the top of an Entity List, a Form (including a Command Form), a Show Page or a Dashboard.
+This feature makes it possible to add a message (with an alert or not) at the top of an Entity List, a Form (including a Command Form), a Show Page, a Dashboard or an Embed.
-
+
A global page alert can be great to provide feedback to the user, to remind him of a particular state, to warn him of potential consequences of a Command...
## Declaration
-Use the `configurePageAlert()` method, in the `buildXXXConfig()` method of your Entity List, Show Page, Command, Form or Dashboard:
+Create a `buildPageAlert()` method:
```php
-class PostShow extends SharpShow
+class MyShow extends SharpShow
{
// [...]
- function buildShowConfig(): void
- {
- $this
- ->configurePageAlert(
- 'Warning: this post is still in draft.',
- );
+ protected function buildPageAlert(PageAlert $pageAlert): void
+ {
+ $pageAlert
+ ->setLevelInfo()
+ ->setMessage('This post is planned for publication');
}
}
```
-This method accepts one to 4 arguments: `configurePageAlert(string $template, string $alertLevel = null, string $fieldKey = null, bool $declareTemplateAsPath = false)`
-
-- `$template` is the only one required: you must provide here a Vue.js template, just like for Autocompletes fields or Dashboard panels
-- `$alertLevel` formats the message as an alert, with the following possibilities:
- - `static::$pageAlertLevelNone`
- - `static::$pageAlertLevelInfo`
- - `static::$pageAlertLevelWarning`
- - `static::$pageAlertLevelDanger`
- - `static::$pageAlertLevelPrimary`
- - `static::$pageAlertLevelSecondary`
-- `$fieldKey` allows to declare the key of a data to allow dynamic messages (see below)
-- finally, if `$declareTemplateAsPath` is set to true then `$template` should be passed as a path to a template file.
+You can use several styles: `setLevelInfo()`, `setLevelWarning()`, `setLevelDanger()`, `setLevelPrimary()` or `setLevelSecondary()`.
## Dynamic messages
-Page alerts can be dynamic, using the power of a regular Vue.js template.
-
-### Show Page, Form and Command cases
-
-To this end, we can define a `$fieldKey` to work with in the config, and reference it in the data part; here's an example in a Show Page (it is very similar in Form and Command case):
+To provide a dynamic message, depending on the actual data of the Show, Entity List and so on, you can pass a closure to the `setMessage()` method:
```php
-class PostShow extends SharpShow
+class MyShow extends SharpShow
{
// [...]
- function buildShowConfig(): void
+ protected function buildPageAlert(PageAlert $pageAlert): void
{
- $this
- ->configurePageAlert(
- 'Warning: this post is still in {{state}} state.',
- static::$pageAlertLevelWarning,
- 'globalMessage'
- );
- }
-
- function find($id): array
- {
- return $this
- ->setCustomTransformer('globalMessage', function($value, Post $post) {
- return [
- 'is_draft' => in_array($post->state, ['draft', 'pending']),
- 'state' => $post->state
- ];
- })
- ->transform(Post::findOrFail($id));
+ $pageAlert
+ ->setLevelInfo()
+ ->setMessage(function (array $data) {
+ return $data['is_planned']
+ ? 'This post is planned for publication, on ' . $data['published_at']
+ : null;
+ });
}
}
```
-Note that we use the dynamic data in two ways, in this example:
-
-- the page alert will appear only if the post state is "draft" or "pending"
-- and the actual state will be injected in the text message.
-
-### The Entity List case
-
-In an Entity List, for dynamic messages, you can use the `getGlobalMessageData()` method:
-
-```php
-class PostList extends SharpEntityList
-{
- // [...]
-
- public function buildListConfig(): void
- {
- $this
- ->configurePageAlert('Hey there, please not that {{ text }}.');
- }
-
- public function getGlobalMessageData(): ?array
- {
- if($this->getQueryParams()->filterFor('draft')) {
- return ['text' => 'draft posts are not visible'];
- }
-
- return ['text' => 'everything is OK'];
- }
-```
-
-### The Dashboard case
+The `$data` array passed to the closure is the result of your `find()` (Show, Form), `getListData()` (Entity List), `buildWidgetsData()` (Dashboard) or `initialData()` (Command) method.
-For the Dashboard, the API is slightly different: first the 3rd argument of `configurePageAlert()`, `$fieldKey`, is not really used, since there is no field in a Dashboard.
-
-Second, and more importantly, here's how you can handle data binding for dynamic messages:
-
-```php
-class CompanyDashboard extends SharpDashboard
-{
- // [...]
-
- public function buildDashboardConfig(): void
- {
- $this->configurePageAlert('Graphs below are delimited by period {{period}}.');
- }
-
- protected function buildWidgetsData(): void
- {
- $period = $this->getQueryParams()->filterFor(PeriodFilter::class);
- $this->setPageAlertData([
- 'period' => sprintf('%s - %s', $period['start'], $period['end']),
- ]);
- }
-}
-```
\ No newline at end of file
+::: tip
+If your message is complex to build, you can defer to a blade template to encapsulate the logic, eg:
+`return view('sharp._post-planned-info', ['data' => $data])->render();`
+:::
\ No newline at end of file
diff --git a/docs/guide/quick-creation-form.md b/docs/guide/quick-creation-form.md
new file mode 100644
index 000000000..ac4ac86e4
--- /dev/null
+++ b/docs/guide/quick-creation-form.md
@@ -0,0 +1,45 @@
+# Quick creation form
+
+Sometimes you may want to allow the creation of a new instance directly from the list page, without having to navigate to a dedicated creation form. It's especially useful when the create form does not require a lot of fields, to keep the user in the list context — and since Sharp will display a “Create and create another” button in the modal, the user can quickly create many instances.
+
+## Prerequisites
+
+This feature will only work if a Form is defined for the entity (since Sharp will entirely rely on it).
+
+## Configuration
+
+The configuration is done in the Entity List:
+
+```php
+class MyList extends SharpEntityList
+{
+ public function buildListConfig(): void
+ {
+ $this->configureQuickCreationForm();
+ }
+ // ...
+}
+```
+
+With this, when the user clicks on the "New..." button, a modal will open with the form fields defined in the Form. One common practice is to limit the fields to the strict minimum: this can be achieved by passing an array of field keys to the `configureQuickCreationForm` method:
+
+```php
+class MyList extends SharpEntityList
+{
+ public function buildListConfig(): void
+ {
+ $this->configureQuickCreationForm(['name', 'price']);
+ }
+ // ...
+}
+```
+
+Of course, ensure that these fields are defined in the Form and that all the required fields are present.
+
+::: warning
+The quick creation form is designed for simple forms. In particular, the layout is entirely ignored, as fields are simply placed one below another. If your form contains many fields or require a specific layout, it is better to use the regular creation form.
+:::
+
+## Redirect to the Show Page
+
+When the Form is configured with `configureDisplayShowPageAfterCreation()`, and if the user does not choose to stay in creation (with the "submit and reopen" button), Sharp will redirect to the Show Page after the creation.
\ No newline at end of file
diff --git a/docs/guide/reordering-instances.md b/docs/guide/reordering-instances.md
index b75938402..0227e1de3 100644
--- a/docs/guide/reordering-instances.md
+++ b/docs/guide/reordering-instances.md
@@ -1,6 +1,6 @@
# Reordering instances
-It's sometimes useful to allow the user to rearrange instances right from the Entity List.
+Allow the user to rearrange instances in the Entity List.
## Generator Command
@@ -36,7 +36,7 @@ Then, in your Entity List you have to configure your reorder handler:
```php
class PageEntityList extends SharpEntityList
{
- // [...]
+ // ...
public function buildListConfig()
{
@@ -47,6 +47,36 @@ class PageEntityList extends SharpEntityList
And that’s it, the list now presents a "Reorder" button, and your code will be called when needed.
+::: tip
+Note that you can also pass a ReorderHandler classname, or an anonymous class that extends ReorderHandler, to the `configureReorderable()` method.
+:::
+
+## Authorizations
+
+The reorder action depends on the `reorder` permission. You can define it in the [Entity Policy](entity-authorizations.md):
+
+Sometimes you may need to restrict the reorder action depending on the actual data, or on some filters values. This can be achieved by using the `disableReorder()` method in your EntityList class, typically in the `getListData()` method.
+
+```php
+class PostEntityList extends SharpEntityList
+{
+ // ...
+
+ public function buildListConfig()
+ {
+ $this->configureReorderable(new PostReorderHandler());
+ }
+
+ public function getListData(): array|Arrayable
+ {
+ // We can’t reorder if there is a search
+ $this->disableReorder($this->queryParams->hasSearch());
+
+ // ...
+ }
+}
+```
+
## Handle exceptions
If you need to abort the process, for any reason, you can raise a `Code16\Sharp\Exceptions\SharpException\SharpApplicativeException` in the `reorder(array $ids)` function.
@@ -56,21 +86,31 @@ If you need to abort the process, for any reason, you can raise a `Code16\Sharp\
A common pattern with an Eloquent model is to simply define an `order` attribute. In this simple case, you can leverage a default implementation built in Sharp:
```php
-public function buildListConfig()
+class PageEntityList extends SharpEntityList
{
- $this->configureReorderable(new SimpleEloquentReorderHandler(MyModel::class));
+ // [...]
+
+ public function buildListConfig()
+ {
+ $this->configureReorderable(new SimpleEloquentReorderHandler(MyModel::class));
+ }
}
```
The `Code16\Sharp\EntityList\Eloquent\SimpleEloquentReorderHandler` class expects the full classname of the Eloquent Model to reorder, and will use the `id` and `order` attribute by default. You can change this default behavior with the dedicated methods:
```php
-public function buildListConfig()
+class PageEntityList extends SharpEntityList
{
- $this->configureReorderable(
- new SimpleEloquentReorderHandler(MyModel::class)
- ->setIdAttribute('uuid')
- ->setOrderAttribute('position')
- );
+ // [...]
+
+ public function buildListConfig()
+ {
+ $this->configureReorderable(
+ new SimpleEloquentReorderHandler(MyModel::class)
+ ->setIdAttribute('uuid')
+ ->setOrderAttribute('position')
+ );
+ }
}
```
diff --git a/docs/guide/sharp-breadcrumb.md b/docs/guide/sharp-breadcrumb.md
index 788b8d174..0ec393b56 100644
--- a/docs/guide/sharp-breadcrumb.md
+++ b/docs/guide/sharp-breadcrumb.md
@@ -4,17 +4,18 @@ Under the hood Sharp manages a breadcrumb to keep track of stacked pages.
## Display the breadcrumb
-
-
You can activate the breadcrumb display in sharp's configuration:
```php
-// config/sharp.php
-return [
- // [...]
-
- "display_breadcrumb" => true,
-];
+class SharpServiceProvider extends SharpAppServiceProvider
+{
+ protected function configureSharp(SharpConfigBuilder $config): void
+ {
+ $config
+ ->displayBreadcrumb()
+ // [...]
+ }
+}
```
## Configure entity label
@@ -71,4 +72,8 @@ class PostShow extends \Code16\Sharp\Show\SharpShow
::: tip
In the Form, the breadcrumb label is only used in one particular case: when coming from an embedded Entity List inside a Show Page. In this case, the Show Page and the Form entity are different, and the breadcrumb helps to keep track of the current edited entity.
-:::
\ No newline at end of file
+:::
+
+## Interact with Sharp's Breadcrumb
+
+Refer to [the Context documentation](context.md) to find out how to interact with Sharp's breadcrumb.
\ No newline at end of file
diff --git a/docs/guide/sharp-uploads.md b/docs/guide/sharp-uploads.md
index a167c3293..1f55ee8fd 100644
--- a/docs/guide/sharp-uploads.md
+++ b/docs/guide/sharp-uploads.md
@@ -4,13 +4,13 @@ Uploads are painful.
Sharp provide a very opinionated and totally optional solution to handle if you are using Eloquent and the `WithSharpFormEloquentUpdater` trait (see [related documentation](building-form.md)).
-The proposal is to use a special Sharp Model for all your uploads, and to link them to your Models with Eloquent's Morph relationships.
+The proposal is to use a special Sharp Model for all your uploads, and to link them to your Models with Eloquent’s Morph relationships.
## Use `SharpUploadModel`
The base Model class is `Code16\Sharp\Form\Eloquent\Uploads\SharpUploadModel`. Just create your own Model class and make it extends this base class.
-You'll have to define the Eloquent `$table` attribute to indicate the table name. So for instance, let's say your Model name choice is `Media`, here's the class code:
+You’ll have to define the Eloquent `$table` attribute to indicate the table name. So for instance, let’s say your Model name choice is `Media`, here’s the class code:
```php
use Code16\Sharp\Form\Eloquent\Uploads\SharpUploadModel;
@@ -85,13 +85,10 @@ class Book extends Model
## Use it!
-Let's pretend you already have data in this new table, here how to handle it.
-
### Properties
By default, you can get the `file_name`, but also `mime_type` and file's `size`.
-
### Custom properties
You can add whatever property you need through custom properties, by setting it:
@@ -100,7 +97,7 @@ You can add whatever property you need through custom properties, by setting it:
$book->cover->author = 'Tomi Ungerer';
```
-Custom properties will be stored in the `custom_properties` column, as JSON.
+Custom properties are stored in the `custom_properties` column, as JSON.
You can retrieve the value the same way:
@@ -110,50 +107,85 @@ $author = $book->cover->author;
### Thumbnails
-Thumbnail creation, for image, is built-in, with this function:
+Thumbnail creation is built-in, you can configure thumbnail disk and base directory:
```php
-thumbnail($width=null, $height=null, $filters=[]);
+class SharpServiceProvider extends SharpAppServiceProvider
+{
+ protected function configureSharp(SharpConfigBuilder $config): void
+ {
+ $config
+ ->configureUploadsThumbnailCreation(
+ // NB: all these values are the default ones
+ thumbnailsDisk: 'public',
+ thumbnailsDir: 'thumbnails',
+ )
+ // [...]
+ }
+}
```
-You must first define the thumbnail directory, in Sharp's config:
+Then you can create a thumbnail using the `thumbnail` method directly on the upload model:
```php
-// config/sharp.php
-
-'uploads' => [
- 'thumbnails_dir' => 'thumbnails',
-],
+thumbnail(int $width = null, int $height = null, array $modifiers = []);
```
-This path is relative to the `public` directory.
+For instance, you can display a 150px width thumbnail in a view like this:
-Then you can call `$thumb = $book->cover->thumbnail(150)` to have a full URL to a 150px (width) thumbnail.
+```php
+
+```
-#### Filters
+Another option is to use the fluent API, calling `thumbnail()` without parameters:
-The third argument is for Filters. For now, only two are available:
+```php
+$thumb = $book->cover->thumbnail()->setQuality(60)->toJpeg()->make(150);
+```
-- **greyscale**
-`->thumbnail(150, null, ['greyscale' => []])`
+Available methods are:
+- `setQuality(int $quality)`: set the quality of the thumbnail used by some encoders (default to 90).
+- `toWebp()`, `toPng()`, `toJpeg()`, `toGif()`, `toAvif()`: force the use of a specific encoder for the thumbnail.
+- `setAppendTimestamp(bool $appendTimestamp = true)`: append a timestamp to the thumbnail URL (useful for browser cache).
+- `setAfterClosure(Closure $closure)`: set a closure to be executed after the thumbnail creation. Intended to be used like this:
-- **fit**: this one has 2 params, `w` for width and `h` for height, and will center-fit the image in those constraints.
-`->thumbnail(150, null, ['fit' => ['w'=>150, 'h'=>100]])`
+```php
+$book->cover
+ ->thumbnail()
+ ->setAfterClosure(function ($wasCreated, $thumbnailPath, $thumbnailDisk) {
+ // Do something...
+ })
+ ->make(150);
+```
-But of course you can provide here a custom one. You'll need for that to first create a Filter class that extends `Code16\Sharp\Form\Eloquent\Uploads\Thumbnails\ThumbnailFilter`, implementing:
+- `addModifier(ThumbnailModifier $modifier)`: apply an image modifier (see below).
+- `make(int $width = null, int $height = null)`: create the thumbnail, with the given size. Must be called last.
-- `function applyFilter(Intervention\Image\Image $image)`: apply you filter, using the great [Intervention API](http://image.intervention.io).
-- `function resized()`: (optional, default to false) Return true if the resize is part of the `applyFilter()` code.
+#### Modifiers
-Once the class is created, pass the full class path as filter name:
+You can specify Modifiers to perform image processing on the fly. A Modifier must extend the `Code16\Sharp\Form\Eloquent\Uploads\Thumbnails\ThumbnailModifier` class:
```php
-return $this->thumbnail($size, $size, [
- CustomThumbnailFilter::class => ['w' => $w, 'fill' => '#ffffff']
-]);
+class MyModifier extends ThumbnailModifier
+{
+ public function apply(ImageInterface $image): ImageInterface
+ {
+ // Do something...
+ }
+}
```
+The following modifiers are available out of the box:
+
+- `GreyscaleModifier`
+- `FitModifier`: will center-fit the image with a constraints set via `->setSize($width, $height)`.
+
+You can provide a custom Modifier; you’ll need to create a class that extends `Code16\Sharp\Form\Eloquent\Uploads\Thumbnails\ThumbnailModifier`, implementing:
+
+- `function apply(ImageInterface $image): ImageInterface`: apply your filter, using the great [Intervention API](https://image.intervention.io/v3).
+- `function resized(): bool`: must return true if the resize is part of the `apply()` code (optional, default to false).
+
## Update with Sharp
The best part is this: Sharp will take care of everything related to update and store.
@@ -166,8 +198,8 @@ function buildFormFields()
$this->addField(
SharpFormUploadField::make('cover')
->setLabel('Cover')
- ->setFileFilterImages()
- ->setCropRatio('1:1')
+ ->setImageOnly()
+ ->setImageCropRatio('1:1')
->setStorageDisk('local')
->setStorageBasePath('data/Books')
);
@@ -245,7 +277,7 @@ $this->addField(
->setOrderAttribute('order')
->addItemField(
SharpFormUploadField::make('file')
- ->setFileFilterImages()
+ ->setImageOnly()
->setStorageDisk('local')
->setStorageBasePath('data/Books/Pictures')
)
@@ -272,7 +304,7 @@ All set.
```php
$this->addField(
SharpFormListField::make('pictures')
- [...]
+ // [...]
->addItemField(
SharpFormUploadField::make('file')
)
diff --git a/docs/guide/show-fields/embedded-entity-list.md b/docs/guide/show-fields/embedded-entity-list.md
index f034d860e..89151f153 100644
--- a/docs/guide/show-fields/embedded-entity-list.md
+++ b/docs/guide/show-fields/embedded-entity-list.md
@@ -4,34 +4,61 @@ Class: `Code16\Sharp\Show\Fields\SharpShowEntityListField`
## Constructor
-This field needs two keys:
-- the name of the local field key, that will be used in the Show layout to display the Entity List,
-- and the entity key as defined in sharp's config, fot the Entity that declares an Entity List.
+This field needs, as first parameter, either the entity key or the `SharpEntity` class that declares the Entity List which will be embedded.
For instance:
```php
-SharpShowEntityListField::make('products', 'product')
+SharpShowEntityListField::make('products')
+```
+
+or
+
+```php
+SharpShowEntityListField::make(ProductEntity::class)
```
-... where `products` is the field key and `product` is the related Entity List key. In the very common case where the two keys are the same, you can omit the second argument; the local field key is only used for the layout: unlike every other field, the `instance` of the Show don't have to expose an attribute named like that, since the EntityList data is gathered with a dedicated request.
+::: warning
+This last syntax is better in terms of DX (since it allows to use the IDE to navigate to the Entity List implementation), but it won’t work in two specific cases: if you use a custom `SharpEntityResolver` or if you your Entity is declared with multiple keys.
+:::
+
+To handle special (rare) cases you can provide a second string argument: in this case the first argument is the field key (as referred in the layout), and the second argument is the related Entity List key:
+
+```php
+SharpShowEntityListField::make('order_products', 'products')
+```
+
+::: tip
+Note that unlike every other Show Field, the `instance` of the Show don't have to expose an attribute named like that, since the EntityList data is gathered with a dedicated request.
+:::
-Embedded Entity List are really just regular Entity List presented in a Show page: we therefore need a full Entity List implementation, declared in an Entity. To scope the data to the `instance` of the Show, use `hideFilterWithValue()` (see below).
+Embedded Entity List are really just regular Entity List presented in a Show page: we therefore need a full Entity List implementation, declared in an Entity. To scope the data to the `instance` of the Show, you can use `hideFilterWithValue()` (see below).
## Configuration
### `hideFilterWithValue(string $filterName, $value)`
-This is maybe the most important method of the field, since it will not only hide a filter, but also set its value. The purpose is to allow to scope the data to the instance of the Show Page. For instance, let's say we display an Order and that we want to embed a list of products:
+This is the most important method of the field, since it will not only hide a filter, but also set its value. The purpose is to allow to **scope the data to the instance** of the Show Page. For example let’s say we display an Order and that we want to embed a list of its products:
```php
-SharpShowEntityListField::make('products')
- ->hideFilterWithValue(OrderFilter::class, 64);
+class OrderShow extends SharpShow
+{
+ // ...
+
+ public function buildShowFields(FieldsContainer $showFields): void
+ {
+ $showFields->addField(
+ SharpShowEntityListField::make(ProductEntity::class)
+ ->hideFilterWithValue(OrderFilter::class, 64)
+ );
+ }
+}
```
-We defined here that we want a `products` fields related to an Entity List which implementation class is defined in the `products` Entity, and its `OrderFilter` filter (which must be declared as usual in the Entity List implementation) must be hidden AND valued to `64` when gathering the data. In short: we want the products for the order of id `64`.
+We defined here that we want to embed the Entity List defined in the `ProductEntity`, with its `OrderFilter` filter (which must be declared as usual in the Entity List implementation) hidden AND valued to `64` when gathering the data. In short: we want the products for the order of id `64`.
-::: tip Note on the filter name: passing its full classname will always work, but you can also directly pass its `key`, in case you defined one.
+::: tip
+Note on the filter name: passing its full classname will always work, but you can also directly pass its `key`, in case you defined one.
:::
You can pass a closure as the value, and it will contain the current Show instance id. In most cases, you'll have to write this:
@@ -41,6 +68,48 @@ SharpShowEntityListField::make('products')
->hideFilterWithValue(OrderFilter::class, fn ($instanceId) => $instanceId);
```
+One final note: sometimes the linked filter is really just a scope, never displayed to the user. In this case, it can be tedious to write a full implementation in the Entity List. In this situation, you can use the `HiddenFiler` class for the filter, passing a key:
+
+```php
+class OrderShow extends SharpShow
+{
+ // ...
+
+ public function buildShowFields(FieldsContainer $showFields): void
+ {
+ $showFields->addField(
+ SharpShowEntityListField::make('products')
+ ->hideFilterWithValue('order', fn ($instanceId) => $instanceId);
+ );
+ }
+}
+```
+
+```php
+use \Code16\Sharp\EntityList\Filters\HiddenFilter;
+
+class OrderProductList extends SharpEntityList
+{
+ // ...
+
+ protected function getFilters(): ?array
+ {
+ return [
+ HiddenFilter::make('order')
+ ];
+ }
+
+ public function getListData(): array|Arrayable
+ {
+ return $this->transform(
+ Products::query()
+ ->forOrderId($this->queryParams->filterFor('order'))
+ ->get()
+ );
+ }
+}
+```
+
### `hideEntityCommand(array|string $commands): self`
Use it to hide any entity command in this particular embedded Entity List (useful when reusing an EntityList). This will apply before looking at authorizations.
@@ -72,7 +141,3 @@ Use it to show or hide the count of items in the embedded Entity List.
## Transformer
There is no transformer, since Sharp will NOT look for an attribute in the instance sent. The data of the Entity List is brought by a distinct XHR call, the same Sharp will use for a non embedded Entity List.
-
-## A note on extending existing Entity List
-
-You can of course build a dedicated Entity List, but in many cases it may be easier to extend one already needed in the main menu. In our products / order example for instance, we can have a full products EntityList, presented in the main menu, with all products and some general commands, and another one for the order Show Page which extends the first one and maybe redefine its layout, or allow to reorder in this case it's useful.
\ No newline at end of file
diff --git a/docs/guide/show-fields/file.md b/docs/guide/show-fields/file.md
index ef93ac297..b4037f2c6 100644
--- a/docs/guide/show-fields/file.md
+++ b/docs/guide/show-fields/file.md
@@ -10,34 +10,25 @@ The purpose of this field is to present a downloadable file to the user.
Set the field label.
-### `setStorageDisk(string $storageDisk)`
-
-Declare the file storage disk (as configured in Laravel's `config/filesystem.php` config file).
-
-### `setStorageBasePath(string $storageBasePath)`
-
-Declare the destination base storage path.
-
-You can use the `{id}` special placeholder to declare the instance id in the path, which can be useful sometimes. For instance:
-`$field->setStorageBasePath('/users/{id}/avatar')`
-
## Transformer
-Sharp expects an array with 3 keys:
+Sharp expects an array formatted like this:
```php
[
'name' => '', // Relative file path
+ 'path' => '', // Full file path
+ 'disk' => '', // Disk name
+ 'mime_type' => '', // Mime type
'thumbnail' => '', // 1000px w * 400px h thumbnail full url
'size' => x, // Size in bytes
]
```
-I you are using Sharp solution for uploads, meaning the `SharpUploadModel` class [detailed here](../sharp-uploads.md),
-you can simply call the built-in transformer:
+If you are using Sharp solution for uploads, meaning the `SharpUploadModel` class [detailed here](../sharp-uploads.md), you can simply call the built-in transformer:
```php
-$this->setCustomTransformer("file", new SharpUploadModelFormAttributeTransformer());
+$this->setCustomTransformer('file', new SharpUploadModelFormAttributeTransformer());
```
-This transformer allows to act a bit n the thumbnail creation part, see its constructor for more details.
\ No newline at end of file
+This transformer allows to act a bit on the thumbnail creation part, see its constructor for more details.
\ No newline at end of file
diff --git a/docs/guide/show-fields/list.md b/docs/guide/show-fields/list.md
index 56b4a932d..6a45d809b 100644
--- a/docs/guide/show-fields/list.md
+++ b/docs/guide/show-fields/list.md
@@ -7,21 +7,25 @@ This field is very similar to the [Form's File field](../form-fields/list.md), a
Here's an example, for a list of pictures with a legend:
```php
-function buildShowFields()
+class MyShow extend SharpShow
{
- $this->addField(
- SharpShowListField::make('pictures')
- ->setLabel('additional pictures')
- ->addItemField(
- SharpShowFileField::make('file')
- ->setStorageDisk('local')
- ->setStorageBasePath('data/Product/{id}/pictures')
- )
- ->addItemField(
- SharpShowTextField::make('legend')
- ->setLabel('Legend')
- )
- );
+ // [...]
+ function buildShowLayout(ShowLayout $showLayout): void
+ {
+ $showLayout->addField(
+ SharpShowListField::make('pictures')
+ ->setLabel('additional pictures')
+ ->addItemField(
+ SharpShowFileField::make('file')
+ ->setStorageDisk('local')
+ ->setStorageBasePath('data/Product/{id}/pictures')
+ )
+ ->addItemField(
+ SharpShowTextField::make('legend')
+ ->setLabel('Legend')
+ )
+ );
+ }
}
```
@@ -37,20 +41,27 @@ Add a SharpShowField in the item.
## Layout
-The List item layout must be defined like the show itself, in the `buildShowLayout()` function. The item layout is managed as a column, with a `ShowLayoutColumn` object. To link the column and the item, use the classic `withSingleField()` function with a second argument, a Closure accepting a `ShowLayoutColumn`.
+The List item layout must be defined like the show itself, in the `buildShowLayout()` function. The item layout is managed as a column, with a `ShowLayoutColumn` object. To link the column and the item, use the classic `withField()` function with a second argument, a Closure accepting a `ShowLayoutColumn`.
Example:
```php
-$this->addColumn(6, function(ShowLayoutColumn $column) {
- $column->withSingleField('pieces', function(ShowLayoutColumn $listItem) {
- $listItem->withSingleField('acquisition_date')
- ->withSingleField('title')
- ->withSingleField('artist');
- });
- });
+class MyShow extend SharpShow
+{
+ // [...]
+ function buildShowLayout(ShowLayout $showLayout): void
+ {
+ $showLayout->addColumn(6, function (ShowLayoutColumn $column) {
+ $column->withListField('pieces', function (ShowLayoutColumn $listItem) {
+ $listItem->withField('acquisition_date')
+ ->withField('title')
+ ->withField('artist');
+ });
+ });
+ }
+}
```
## Formatter
-The Formatter expects an array or a `Collection` of models, each one defining attributes for each list item keys at the format expected by the corresponding Field Formatter.
\ No newline at end of file
+The Formatter expects an array or a `Collection` of models, each one defining attributes for each list item keys at the format expected by the corresponding Field Formatter.
diff --git a/docs/guide/show-fields/picture.md b/docs/guide/show-fields/picture.md
index 312d929c6..f8447f0bd 100644
--- a/docs/guide/show-fields/picture.md
+++ b/docs/guide/show-fields/picture.md
@@ -23,5 +23,3 @@ function find($id): array
->transform([...]);
}
```
-
-See [related documentation of this transformer here](../how-to-transform-data.md#SharpUploadModelThumbnailUrlTransformer).
\ No newline at end of file
diff --git a/docs/guide/show-fields/text.md b/docs/guide/show-fields/text.md
index 17d69fc7a..e960c65fc 100644
--- a/docs/guide/show-fields/text.md
+++ b/docs/guide/show-fields/text.md
@@ -12,6 +12,14 @@ Set the field label.
Collapse the text if too long, and add a "show more" link. Use it for long texts (even markdown formatted) in sections with only one field.
+### `doNotCollapse()`
+
+Reset the collapse configuration.
+
+### `setHtml(bool $html = true)`
+
+By default, the text is escaped. If you want to display HTML, set this to true.
+
### `allowEmbeds(array $embeds)`
This method expects an array of embeds that could be inserted in the content, declared as full class names. An embed class must extend `Code16\Sharp\Form\Fields\Embeds\SharpFormEditorEmbed`.
diff --git a/docs/guide/single-form.md b/docs/guide/single-form.md
index 33b80c104..702040d4b 100644
--- a/docs/guide/single-form.md
+++ b/docs/guide/single-form.md
@@ -38,10 +38,10 @@ class AccountSharpForm extends SharpSingleForm
function buildFormLayout(FormLayout $formLayout): void
{
- $formLayout->addColumn(6, function($column) {
+ $formLayout->addColumn(6, function ($column) {
return $column
- ->withSingleField('name')
- ->withSingleField('email');
+ ->withField('name')
+ ->withField('email');
});
}
diff --git a/docs/guide/style-visual-theme.md b/docs/guide/style-visual-theme.md
index cef9f507f..9b2466406 100644
--- a/docs/guide/style-visual-theme.md
+++ b/docs/guide/style-visual-theme.md
@@ -5,108 +5,102 @@
The primary color is customisable, and is applied to the header and buttons. Although every hue works well, too light colors aren't supported (e.g. works well with [tailwind colors](https://tailwindcss.com/docs/customizing-colors#color-palette-reference) >= 600).
```php
-// config/sharp.php
-return [
- // [...]
-
- 'theme' => [
- 'primary_color' => '#004D40',
- ],
-];
+class SharpServiceProvider extends SharpAppServiceProvider
+{
+ protected function configureSharp(SharpConfigBuilder $config): void
+ {
+ $config
+ ->setThemeColor('#004D40')
+ // [...]
+ }
+}
```
-### Login and menu logos
+### Header logo
-By default, the `config('sharp.name')` is displayed on the login page and on top of the menu. You can if you wish display images instead: Sharp will look for PNGs named `login-icon.png` and `menu-icon.png`, in a `/public/sharp-assets/` directory. Note that :
-- `login-icon.png` is limited to 200 pixels in width and 100 pixels in height,
-- and `menu-icon.png` must fit in 150 pixels in width and 50 pixels in height.
-
-If you need to configure the image files URLs, you can do it with this config:
+By default, the configured `name` is displayed on the header. If you want to show custom logo, you can do it with this config:
```php
-// config/sharp.php
-
-return [
- // [...]
-
- 'theme' => [
- 'primary_color' => ...,
- 'logo_urls' => [
- 'menu' => '/sharp/subdir/my-custom-menu-icon.png',
- 'login' => '/sharp/subdir/my-custom-login-icon.png',
- ],
- ],
-];
+class SharpServiceProvider extends SharpAppServiceProvider
+{
+ protected function configureSharp(SharpConfigBuilder $config): void
+ {
+ $config
+ ->setName('My Sharp App')
+ ->setThemeLogo(
+ logoUrl: '/my-sharp-assets/my-custom-logo.svg',
+ logoHeight: '1.5rem',
+ faviconUrl: '/my-sharp-assets/favicon.png'
+ )
+ // [...]
+ }
+}
```
-#### Display a custom message on login page
+The file should be an SVG, you can customize the logo height by setting the `logo_height` config.
-You can display a custom content under the form on login page; you'll need to create a new template file:
+:::tip
+With the newly added dark theme, it is recommended to use an SVG logo with `fill="currentColor"` to allow the logo to adapt to the theme, Sharp will handle it for you.
+:::
-```blade
-
+### Login form
-
- Display a custom message to your users
-
-```
-
-And then define the path to this custom blade in the `config/sharp.php` config file:
+You can customize the login form with a custom message.
```php
-// config/sharp.php
+class SharpServiceProvider extends SharpAppServiceProvider
+{
+ protected function configureSharp(SharpConfigBuilder $config): void
+ {
+ $config
+ ->appendMessageOnLoginForm('sharp.login-page-message')
+ // or a direct message
+ // ->appendMessageOnLoginForm('Display a custom message to your users')
+ // [...]
+ }
+}
+```
-return [
- // [...]
+The custom message is displayed under the form; you can either provide HTML or the name of a custom blade template file.
- 'login_page_message_blade_path' => 'sharp/_login-page-message',
-];
+```blade
+
+
+
+ Display a custom message to your users
+
```
### Favicon
-You can define an URL for a favicon that Sharp will use in the config:
+You can define an URL for a favicon that Sharp will as a 3rd argument of the same `setThemeLogo()` method:
```php
-// config/sharp.php
-
-return [
- // [...]
-
- 'theme' => [
- 'favicon_url' => '/sharp-img/favicon.png',
- ],
-]
+class SharpServiceProvider extends SharpAppServiceProvider
+{
+ protected function configureSharp(SharpConfigBuilder $config): void
+ {
+ $config
+ ->setThemeLogo(
+ faviconUrl: '/my-sharp-assets/favicon.png'
+ )
+ // [...]
+ }
+}
```
-### Injecting Assets
+### Injecting CSS
-You may globally inject custom CSS files after the Sharp assets by defining their paths in the `config/sharp.php` config file.
+If you want to inject custom CSS in Sharp, you can do so by using `loadViteAssets()` or `loadStaticCss()`. Be aware that tailwind classes may clash with Sharp default CSS so you may define a [Tailwind prefix](https://tailwindcss.com/docs/configuration#prefix).
```php
-// config/sharp.php
-
-return [
- // [...]
-
- 'extensions' => [
- 'assets' => [
- 'strategy' => 'raw',
- 'head' => [
- '/css/inject.css', // Outputs after sharp assets
- ],
- ],
- ],
-];
+class SharpServiceProvider extends SharpAppServiceProvider
+{
+ protected function configureSharp(SharpConfigBuilder $config): void
+ {
+ $config
+ ->loadViteAssets(['resources/css/sharp.css']) // to load a CSS file built with Vite
+ ->loadStaticCss(asset('/css/sharp.css')) // Or to load a static CSS file
+ }
+}
```
-
-The comment next to the item within the `head` position show how the output would appear in the HTML.
-
-### Strategy
-
-The `strategy` defines how the asset path will be rendered
-
-- `raw` to output the path in the form it appears in your array
-- `asset` to pass the path to the laravel [`asset()`](https://laravel.com/docs/5.6/helpers#method-asset) function
-- `mix` to pass the path to the laravel [`mix()`](https://laravel.com/docs/5.6/helpers#method-mix) function
-- `vite` to pass to path to the laravel [`Vite::asset()`](https://laravel.com/docs/10.x/vite#blade-processing-static-assets) function
diff --git a/docs/guide/testing-with-sharp.md b/docs/guide/testing-with-sharp.md
index 62823186f..20e284a82 100644
--- a/docs/guide/testing-with-sharp.md
+++ b/docs/guide/testing-with-sharp.md
@@ -4,36 +4,44 @@ Sharp provides a few assertions and helpers to help you test your Sharp code.
## The `SharpAssertions` trait
-The `Code16\Sharp\Utils\Testing\SharpAssertions` trait is intended to be used in a Feature test. It has to be initialized, like this:
+The `Code16\Sharp\Utils\Testing\SharpAssertions` trait is intended to be used in a Feature test.
```php
-protected function setUp()
+class PostFormTest extends TestCase
{
- parent::setUp();
-
- $this->initSharpAssertions();
+ use SharpAssertions;
+
+ // ...
}
```
### Helpers
-First, the trait adds a few helpers:
-
+The trait adds a few helpers:
#### `loginAsSharpUser($user)`
Logs in the given user as a Sharp user.
+#### `getSharpShow(string $entityKey, $instanceId)`
+
+Call the Sharp API to display the Show Page for the Entity `$entityKey` and instance `$instanceId`.
#### `getSharpForm(string $entityKey, $instanceId = null)`
-Call the Sharp API to display the form for the Entity `$entityKey`. If `$instanceId` is provided, it will be an edit form, and otherwise a create one.
+Call the Sharp API to display the Form for the Entity `$entityKey`. If `$instanceId` is provided, it will be an edit form, and otherwise a creation one.
+
+#### `getSharpSingleForm(string $entityKey)`
+Call the Sharp API to display the edit Form for the single Entity `$entityKey`.
#### `updateSharpForm(string $entityKey, $instanceId, array $data)`
Call the Sharp API to update the Entity `$entityKey` of id `$instanceId`, with `$data`.
+#### `updateSharpSingleForm(string $entityKey, array $data)`
+
+Call the Sharp API to update the single Entity `$entityKey` with `$data`.
#### `storeSharpForm(string $entityKey, array $data)`
@@ -47,96 +55,33 @@ Call the Sharp API to delete an `$entityKey` instance on the Entity List.
Call the Sharp API to delete an `$entityKey` instance on the Show Page.
-#### `callSharpEntityCommandFromList(string $entityKey, string $commandKeyOrClassName, array $data)`
+#### `callSharpEntityCommandFromList(string $entityKey, string $commandKeyOrClassName, array $data, ?string $commandStep = null)`
Call the `$commandKeyOrClassName` Entity Command with the optional `$data`.
-#### `callSharpInstanceCommandFromList(string $entityKey, $instanceId, string $commandKeyOrClassName, array $data)`
+#### `callSharpInstanceCommandFromList(string $entityKey, $instanceId, string $commandKeyOrClassName, array $data, ?string $commandStep = null)`
Call the `$commandKeyOrClassName` Instance Command with the optional `$data`.
-#### `callSharpInstanceCommandFromShow(string $entityKey, $instanceId, string $commandKeyOrClassName, array $data)`
+#### `callSharpInstanceCommandFromShow(string $entityKey, $instanceId, string $commandKeyOrClassName, array $data, ?string $commandStep = null)`
Call the `$commandKeyOrClassName` Instance Command with the optional `$data`.
-#### `withSharpCurrentBreadcrumb(array $breadcrumb): self`
-
-It can be useful to fake a Sharp context before calling a Sharp endpoint, and that's the purpose of this method; `$breadcrumb` is an array of arrays, each one containing, in this order:
- - a Sharp page type: "list", "show" or "form"
-- an entityKey
-- (optional) an instanceId
+#### `withSharpBreadcrumb(Closure $callback): self`
-For instance:
+Most of the time, the breadcrumb automatically set by Sharp is enough. But sometimes it can be useful to define a whole Sharp context before calling an endpoint, and that's the purpose of this method. The `$callback` contains a built instance of Code16\Sharp\Utils\Links\BreadcrumbBuilder, which can be used like this:
```php
+it('allow the user to display a leaf form', function () {
$this
- ->withSharpCurrentBreadcrumb([
- ['list', 'trees'],
- ['show', 'trees', 8],
- ['show', 'leaves', 16],
- ['form', 'leaves', 16],
- ])
- ->getSharpForm(...)
+ ->loginAsSharpUser()
+ ->withSharpBreadcrumb(function (BreadcrumbBuilder $builder) {
+ return $builder
+ ->appendEntityList('trees')
+ ->appendShowPage('trees', 6)
+ ->appendShowPage('leaves', 16);
+ })
+ ->getSharpForm('leaves', 16)
->assertOk();
+});
```
-
-### Assertions
-
-You can use regular assertions, for instance:
-
-```php
-$this
- ->updateSharpForm(
- 'orders',
- $order->id,
- array_merge($order->toArray(), [
- 'client' => 'test',
- 'payment_delay' => 10
- ])
- )
- ->assertStatus(200);
-```
-
-But sometimes you'll want to test some specific Sharp things. Here's the list of custom assertions added by the `SharpAssertions` trait:
-
-#### `assertSharpHasAuthorization($authorization)`
-#### `assertSharpHasNotAuthorization($authorization)`
-
-Example:
-
-```php
-$this->getSharpForm('orders', $order->id)
- ->assertSharpHasAuthorization('update')
- ->assertSharpHasAuthorization('delete');
-```
-
-#### `assertSharpFormHasFields($names)`
-
-Example:
-
-```php
-$this->getSharpForm('orders')
- ->assertSharpFormHasFields([
- 'number', 'client'
- ]);
-```
-
-#### `assertSharpFormHasFieldOfType($name, $formFieldClassName)`
-
-Example:
-
-```php
-$this->getSharpForm('orders', $order->id)
- ->assertSharpFormHasFieldOfType(
- 'number', SharpFormTextField::class
- );
-```
-
-#### `assertSharpFormDataEquals($name, $value)`
-
-Example:
-
-```php
-$this->getSharpForm('orders', $order->id)
- ->assertSharpFormDataEquals('number', $order->number);
-```
\ No newline at end of file
diff --git a/docs/guide/upgrading/9.0.md b/docs/guide/upgrading/9.0.md
new file mode 100644
index 000000000..3f45279fe
--- /dev/null
+++ b/docs/guide/upgrading/9.0.md
@@ -0,0 +1,1002 @@
+---
+outline: [1, 2]
+---
+
+# Upgrading from 8.x to 9.x
+
+This is a very big release, with a lot of changes. We try to limit breaking changes, but there are some... This guide will help you to upgrade your Sharp 8.x app to Sharp 9.x.
+
+# General
+
+## Get new assets, clear cache
+
+This is true for every update: be sure to grab the latest assets and to clear the view cache:
+
+```bash
+php artisan vendor:publish --tag=sharp-assets --force
+php artisan view:clear
+```
+
+## Update your composer.json
+
+The command used to publish sharp's assets **changed**, you should update your `composer.json`:
+
+```diff
+{
+ "scripts": {
+ "post-autoload-dump": [
+ [...],
+- "@php artisan vendor:publish --provider='Code16\\Sharp\\SharpServiceProvider' --tag=assets --force",
++ "@php artisan vendor:publish --tag=sharp-assets --force"
+ ]
+ }
+}
+```
+
+## Deprecated methods have been removed
+
+- Entity List: deprecated `buildListFields()` and `buildListLayout()` were removed, use `buildList()` instead
+- Form: deprecated `delete()` method was removed (since it was moved to show / entity list in 8.x)
+
+## New way to configure Sharp, via a dedicated builder class
+
+The `config/sharp.php` file was entirely removed in favor of a dedicated builder class. This is not a breaking change since the config file is still supported, but deprecated, so you are encouraged to migrate to the new builder class.
+
+To migrate, you should first create a new Service Provider which extends `Code16\Sharp\SharpAppServiceProvider` and implements the `configureSharp()` method:
+
+```php
+use Code16\Sharp\SharpAppServiceProvider;
+
+class MySharpServiceProvider extends SharpAppServiceProvider
+{
+ protected function configureSharp(SharpConfigBuilder $config): void
+ {
+ $config
+ ->setName('My project')
+ ->addEntity('posts', PostEntity::class)
+ // ...
+ }
+}
+```
+
+Report all you configuration using the API of this new `SharpConfigBuilder` class. It should be pretty straightforward, as all the methods are named after the config keys they replace. For example:
+
+In 8.x:
+
+```php
+// Old config/sharp.php
+return [
+ 'name' => 'Demo project',
+ 'custom_url_segment' => 'sharp',
+ 'display_breadcrumb' => true,
+ 'entities' => [
+ 'posts' => \App\Sharp\Entities\PostEntity::class,
+ ],
+
+ 'global_filters' => fn () => auth()->id() === 1 ? [] : [\App\Sharp\DummyGlobalFilter::class],
+
+ 'search' => [
+ 'enabled' => true,
+ 'placeholder' => 'Search for posts or authors...',
+ 'engine' => \App\Sharp\AppSearchEngine::class,
+ ],
+
+ 'menu' => \App\Sharp\SharpMenu::class,
+
+ // ...
+];
+```
+
+In 9.x:
+
+```php
+class MySharpServiceProvider extends SharpAppServiceProvider
+{
+ protected function configureSharp(SharpConfigBuilder $config): void
+ {
+ $config
+ ->setName('Demo project')
+ ->setCustomUrlSegment('sharp')
+ ->setDisplayBreadcrumb()
+ ->addEntity('posts', PostEntity::class)
+ ->addGlobalFilter(DummyGlobalFilter::class) // The auth()->id() === 1 no longer can be handled here, as the auth context is yet not available. Use the new authorize() method of the global filter instead.
+ ->enableGlobalSearch(AppSearchEngine::class, 'Search for posts or authors...')
+ ->setMenu(SharpMenu::class)
+ // ...
+ }
+}
+```
+
+::: warning
+Be sure to [register this new Service Provider](https://laravel.com/docs/providers#registering-providers) in your app.
+:::
+
+## Middleware updates (legacy config only)
+
+Due to migration to inertia, two middleware must be added to the config. Also, `SetSharpLocale` must be removed from `api` group.
+
+::: info
+If you migrated to the new config builder class, you should be ok unless you have explicitly overridden the whole middleware list.
+:::
+
+Here is the impact on the deprecated config file:
+
+```php
+// config/sharp.php
+
+return [
+ 'middleware' => [
+ // ...
+ 'web' => [
+ // ...
+ \Code16\Sharp\Http\Middleware\HandleSharpErrors::class,
+ \Code16\Sharp\Http\Middleware\HandleInertiaRequests::class,
+ ],
+ 'api' => [
+ // To remove :
+ // \Code16\Sharp\Http\Middleware\Api\SetSharpLocale::class,
+ ]
+ ],
+]
+```
+
+## Migration to `blade-icons`
+
+In 8.x, menu icons were FontAwesome classes like `fa fa-user` or `fas fa-user`. Now icons must be [blade-icons](https://blade-ui-kit.com/blade-icons) icon names with its associated package installed.
+
+Icons are not required but if you want to keep FontAwesome, you can install the following package:
+```bash
+composer require owenvoke/blade-fontawesome
+```
+And rename old icon names to blade-fontawesome names in your `SharpMenu` :
+```diff
+# Solid icons
+- ->addEntityLink('entity', 'Entity', 'fas fa-user')
+- ->addEntityLink('entity', 'Entity', 'fa fa-user')
++ ->addEntityLink('entity', 'Entity', logo: 'fas-user')
+
+# Regular (outline) icons
+- ->addEntityLink('entity', 'Entity', 'far fa-envelope')
+- ->addEntityLink('entity', 'Entity', 'fa fa-envelope-o')
++ ->addEntityLink('entity', 'Entity', logo: 'far-envelope')
+
+# Brand icons
+- ->addEntityLink('entity', 'Entity', 'fa fa-github')
+- ->addEntityLink('entity', 'Entity', 'fab fa-github')
++ ->addEntityLink('entity', 'Entity', logo: 'fab-github')
+```
+If you were using old fontawesome 4 icons you may need to [rename them](https://docs.fontawesome.com/v5/web/setup/upgrade-from-v4#icon-name-changes-between-version-4-and-5).
+
+### Restore fontawesome icons default behavior *(optional)*
+
+As the default behavior of `blade-icons` (which uses an `svg` tag) differs from the previous behavior of FontAwesome’s `` tag (which was inline and matched the font size), you may need to adjust the `blade-icons` configuration to replicate the original behavior.
+
+First, publish the FontAwesome blade-icons configuration file:
+```bash
+php artisan vendor:publish --tag=blade-fontawesome-config
+```
+
+Then add default attributes for each FontAwesome classes (solid, regular, brands, and optionally pro):
+```php
+// file: config/blade-fontawesome.php
+return [
+ // ...
+ 'regular' => [
+ // ...
+ 'attributes' => [
+ 'width' => '1rem',
+ 'height' => '1rem',
+ 'style' => 'display: inline;'
+ ],
+ ],
+];
+```
+
+## No more Bootstrap.css / Font awesome classes
+
+You may be using Custom HTML (entity list row, editor embeds, form HTML field, form Autocomplete item template, page alerts) with CSS classes that was present in Sharp 8.x but that don't exist anymore:
+
+- If you were using bootstrap classes like `row` / `col` / `badge` in HTML content. These are no longer available, you can either :
+ - Convert to inline CSS (for bootstrap grid classes / utilities)
+ - Inject a custom CSS file as described [here](../style-visual-theme.md)
+- If you were using inline Font Awesome icons like ``
+ - Using [blade-fontawesome](https://github.com/owenvoke/blade-fontawesome) component like : ``. In Sharp 9.x all templates are now Blade.
+ - For `` inside a custom transformer of an EntityList field, you must now do `Blade::render('')`
+
+## Page Alerts (aka global messages) are not based on Vue templates anymore
+
+This part has been entirely rewritten, and will need substantial changes in your code.
+
+In 8.x and below, you were asked to configure page alerts in the `buildConfig()` method; and if your page alert was displaying dynamic data, you had to use a custom transformer to inject the data in the page alert. All of this was removed, in favor of a much simpler "back only" system. Here’s an example of a page alert in a Show Page (this is the same in Form, Dashboard, Entity List, Embed and Command cases):
+
+```php
+class MyShow extends SharpShow
+{
+ // ...
+
+ protected function buildPageAlert(PageAlert $pageAlert): void
+ {
+ $pageAlert
+ ->setLevelInfo()
+ ->setMessage(function (array $data) {
+ return $data['is_planned']
+ ? 'This post is planned for publication, on ' . $data['published_at']
+ : null;
+ });
+ }
+}
+```
+
+As you can see, this new `buildPageAlert()` method takes a `PageAlert` object as parameter to work with. You'll have access to the `$data` array returned by your `find()` or `getListData()` method, to inject dynamic data in your page alert if needed. Vue templates are no longer handled, as the page alert is now rendered on the back only.
+
+See [global page alert documentation](../page-alerts.md) for more detail.
+
+## Related models handling in custom transformers was fixed (and potentially breaking)
+
+This bug fix potentially brings a breaking change: if you were using a custom transformer to handle related models, you may have to update it.
+
+Here’s code which will work in Sharp 8.x and below:
+
+```php
+$this
+ ->setCustomTransformer('customer:name', function ($value, $instance, $attribute) {
+ return $instance->customer->name; // $instance is the Order
+ })
+ ->transform(Order::find(1))
+```
+
+Is has to be rewritten like this in Sharp 9.x:
+
+```php
+$this
+ ->setCustomTransformer('customer:name', function ($value, $instance, $attribute) {
+ return $instance->name; // $instance is the Customer, as it should be.
+ })
+ ->transform(Order::find(1))
+```
+
+The main difference is that the `$instance` parameter refers to the related model, not the main model anymore. To summarize:
+
+In 8.x:
+
+```php
+$value: 'Joe Doe'
+$instance: // the Order instance
+$attribute: 'customer:name'
+```
+
+In 9.x:
+
+```php
+$value: 'Joe Doe'
+$instance: // the **Customer** instance
+$attribute: 'name'
+```
+
+## Thumbnails custom filters must be refactored to Modifiers
+
+First, if you defined custom filters classes for your thumbnails, you must refactor it to the new ThumbnailModifier API, which is very close:
+
+In 8.x
+
+```php
+class MyFilter extends ThumbnailFilter
+{
+ public function applyFilter(Image $image): Image
+ {
+ // ...
+ }
+}
+```
+
+In 9.x
+
+```php
+use Code16\Sharp\Form\Eloquent\Uploads\Thumbnails\ThumbnailModifier;
+use Intervention\Image\Interfaces\ImageInterface;
+
+class MyModifier extends ThumbnailModifier
+{
+ public function apply(ImageInterface $image): ImageInterface
+ {
+ // ...
+ }
+}
+```
+
+And secondly, in 9.x you can’t pass modifier's parameters as an array anymore:
+
+In 8.x
+
+```php
+$book->cover->thumbnail(100, 100, ['fit'=>['w'=>100, 'h'=>100]]);
+```
+
+In 9.x
+
+```php
+$book->cover->thumbnail(100, 100, [new FitModifier(100, 100)]);
+
+// or with the new fluent API
+$book->cover->thumbnail()
+ ->addModifier(new FitModifier(100, 100))
+ ->make();
+```
+
+## `currentSharpRequest()` is now deprecated in favor of `sharp()->context()` helper
+
+The `currentSharpRequest()` helper is now deprecated, and will be entirely removed in a future version. You should migrate your code to use the `sharp()->context()` helper instead (see [the dedicated documentation](../context.md)).
+
+## `SharpAuthenticationCheckHandler` is now deprecated in favor of `viewSharp` Gate
+
+The use of a `SharpAuthenticationCheckHandler` is now deprecated, and will be entirely removed in a future version. You should migrate your handler to a Gate:
+
+In 8.x:
+
+```php
+class MySharpAuthenticationCheckHandler implements SharpAuthenticationCheckHandler
+{
+ public function check(Authenticatable $user): bool;
+ {
+ return $user->is_sharp_admin;
+ }
+}
+```
+
+In 9.x:
+
+```php
+class AppServiceProvider extends ServiceProvider
+{
+ // ...
+
+ public function boot(): void
+ {
+ Gate::define('viewSharp', fn ($user) => $user->is_sharp_admin);
+ }
+}
+```
+
+::: tip
+You should place this code in the new Sharp dedicated Service Provider you will create to configure your Sharp app, overriding the `declareAccessGate()` method. See [the dedicated documentation](../authentication#global-access-gate).
+:::
+
+Next, the `sharp.auth.check_handler` config key can be safely removed from your `config/sharp.php` file (in case you have not yet migrated to the dedicated builder class, see above), along with the `SharpAuthenticationCheckHandler` implementation class.
+
+## Injected CSS must now be loaded with the `SharpConfigBuilder`
+
+In 8.x,
+```php
+// config/sharp.php
+
+return [
+ 'extensions' => [
+ 'assets' => [
+ 'strategy' => 'vite',
+ 'head' => [
+ 'resources/css/sharp.css',
+ ],
+ ],
+ ],
+];
+```
+
+In 9.x :
+```php
+class MySharpServiceProvider extends SharpAppServiceProvider
+{
+ protected function configureSharp(SharpConfigBuilder $config): void
+ {
+ $config
+ ->loadViteAssets(['resources/css/sharp.css']) // to load a CSS file built with Vite
+ ->loadStaticCss(asset('/css/sharp.css')) // Or to load a static CSS file
+ }
+}
+```
+
+## All test assertions were removed
+
+All assertions, like for instance `assertSharpHasAuthorization`, were removed because they were clumsy and not really useful. You must remove them from your tests, and use standard comparisons instead — although in real world, it’s easier and cleaner to just check the return status (ie: `assertOk()`) and check, if needed, the consequences in the database directly.
+
+This means you also need to remove all `$this->initSharpAssertions()` calls from your tests.
+
+Of course, the test helpers remain available, see the dedicated [testing documentation](../testing-with-sharp.md).
+
+Also take note that the `withSharpCurrentBreadcrumb()` method is now deprecated, in favor of the new `withSharpBreadcrumb()` method also documented in the section linked above.
+
+# Dashboard
+
+## `SharpWidgetPanel`s are now based on blade template
+
+In a similar way to Page Alerts, we abandoned Vue templates for custom `SharpWidgetPanel`s in favor of blade templates. This is a breaking change, as the `setTemplatePath(...)`and `setInlineTemplate(...)` methods were removed, placed by a unique `setTemplate(View $template)`.
+
+There's almost nothing to change on the PHP side:
+
+In 8.x:
+
+```php
+class MyDashboard extends SharpDashboard
+{
+ // ...
+
+ protected function buildWidgets(WidgetsContainer $widgetsContainer): void
+ {
+ $widgetsContainer
+ ->addWidget(
+ SharpPanelWidget::make('my_custom_panel')
+ ->setTitle('My custom panel')
+ ->setTemplatePath('sharp.templates.my_template') // Must be an existing **vue file**
+ );
+ }
+}
+```
+
+In 9.x:
+
+```php
+class MyDashboard extends SharpDashboard
+{
+ // ...
+
+ protected function buildWidgets(WidgetsContainer $widgetsContainer): void
+ {
+ $widgetsContainer
+ ->addWidget(
+ SharpPanelWidget::make('my_custom_panel')
+ ->setTitle('My custom panel')
+ ->setTemplate(view('sharp.templates.my_template')) // Must be an existing **blade view**
+ );
+ }
+}
+```
+
+The main change is the template itself, which must be a blade view now.
+
+See [panel widget documentation](../dashboard-widgets/panel.md) for more detail.
+
+# Entity Lists
+
+## Entity Lists have a new authorization: `reorder`
+
+Previously the `reorder` authorization was handled by the `update` authorization, which can lead to unwanted effects. You should now declare a specific `reorder` authorization in your Policies:
+
+```php
+class PostPolicy extends SharpEntityPolicy
+{
+ public function reorder($user): bool
+ {
+ return $user->isEditor();
+ }
+
+ // ...
+}
+```
+
+## Entity List's `setWidth()` method as a new signature (non-breaking change: old signature is still supported)
+
+The `->setWith($width)` method now expects a percentage value, expressed as a string (eg: `'20'` or `'20%'`), a float (eg: `.2` for 20%) or an integer (eg: `20` for 20%). The old signature use to accept a 1 to 12 integer (12-grid): it is still supported (Sharp will transform a 6 in 50%), but deprecated, and you are strongly encourage to migrate to the new signature.
+
+## Methods to handle Entity List columns width on small screen were deprecated
+
+The `->setWithOnSmallScreen($width)` and `->setWithOnSmallScreenFill()` methods were deprecated, because they are no more used in the new front table UI system. You can safely remove them, Sharp will rely on the `setWidth($width)` method, or, even easier, will deduce width based on content like a regular table.
+
+The `->hideOnSmallScreens()` method remains.
+
+## All filters must be declared in order to be used
+
+In Sharp 8.x it was possible, in an Embedded Entity List (EEL) case, to use a filter without declaring it. This was a kind of bug, and has been fixed in 9.x: all filters must be declared in the `getFilters()` method.
+
+Consider this code in 8.x, where we have a `PostShow` that embeds a `PostBlockList` as an EEL:
+
+```php
+class PostShow extends SharpShow
+{
+ protected function buildShowFields(FieldsContainer $showFields): void
+ {
+ $showFields
+ ->addField(SharpShowTextField::make('title')->setLabel('Title'))
+ ->addField(
+ SharpShowEntityListField::make('blocks')
+ ->setLabel('Blocks')
+ ->hideFilterWithValue('post', fn($instanceId) => $instanceId)
+ );
+ }
+ // ...
+}
+
+class PostBlockList extends SharpEntityList
+{
+ // ...
+
+ protected function getFilters(): ?array
+ {
+ return [
+ // Nothing there
+ ];
+ }
+
+ public function getListData(): array|Arrayable
+ {
+ return $this->transform(
+ PostBlock::query()
+ ->where('post_id', $this->queryParams->filterFor('post'))
+ ->get()
+ );
+ }
+}
+```
+
+We can see that `PostBlockList` does not define any Filter, but uses one in the `getListData()` method, valued by the `PostShow` via `hideFilterWithValue()`. In 9.x, this won't work as the Filter must be declared in the `getFilters()` method. There is a new way to quickly declare such Filters that are not meant to be shown to the user, `HiddenFiler`:
+
+In 9.x
+
+```php
+use \Code16\Sharp\EntityList\Filters\HiddenFilter;
+
+class PostBlockList extends SharpEntityList
+{
+ // ...
+
+ protected function getFilters(): ?array
+ {
+ return [
+ HiddenFilter::make('post')
+ ];
+ }
+
+ // ... The rest is the same
+}
+```
+
+You can of course instead declare a real Filter.
+
+## Select filter `configureTemplate()` has been dropped
+
+If you were using this method, you must do the string transformation in the label of each value.
+
+## New performance optimization for Commands and Policies in Entity List (n+1)
+
+This is not a breaking change, in fact you can ignore this step entirely, but since it's can lead to a significative performance boost, this is worth mentioning: you can now quite easily implement a [caching mechanism of instances for your Commands and Policies in Entity List](../avoid-n1-queries-in-entity-lists.md).
+
+# Forms & Shows
+
+## Form and Show layout methods were renamed (old ones are deprecated)
+
+The `->withSingleField()` method was deprecated, in favor of:
+
+- `->withField(string $fieldKey)` for simple fields
+- `->withListField(string $fieldKey, Closure $subLayoutCallback)` for List fields, which requires a sub-layout handled by a callback.
+
+The method `->withFields(string ...$fieldKeys)`, used for multiple fields layout, remains unchanged.
+
+## Form and Show Fields are now formatted even if you don’t transform them
+
+This shouldn’t cause any trouble, as this is a fix, but it could break unorthodox code: field formatters (which are used to format the field value for the frontend) are now properly and always called before displaying data to the front, even if you don’t transform your data with `$this->transform()` method.
+
+## Custom form / show fields are not supported anymore
+
+In 8.x, you could define custom field by creating a Vue component ([in form](https://sharp8.code16.fr/docs/guide/custom-form-fields) or [in show](https://sharp8.code16.fr/docs/guide/custom-show-fields)) but this is not supported anymore.
+
+In the initial 9.0 release, there isn't a straightforward alternative, but we are looking for ways to easily integrate Alpine / Livewire component. If you only need to render static blade file you can use [SharpFormHtmlField](../form-fields/html.md) or [SharpShowTextField](../show-fields/text.md).
+
+# Forms
+
+## New validation system (and deprecation of the old one)
+
+The validation system has been revamped in version 9.x to align better with Laravel and improve consistency.
+
+You may now define your validation rules in two ways:
+- implement new `rules()` and `messages()` methods in your `SharpForm` or `Command`; those methods accepts an optional `$formattedData` parameter which represents the... formatted posted data.
+- or make a call to `->validate(array $data, array $rules)`.
+
+In consequence, **Form Validators are now deprecated**: the `$formValidatorClass` property in `SharpForm` is deprecated. You are strongly encouraged to switch to the `rules()` method.
+
+This code in 8.x:
+```php
+class PostForm extends SharpForm
+{
+ protected ?string $formValidatorClass = PostFormValidator::class;
+
+ // ...
+}
+
+class PostFormValidator extends SharpFormRequest
+{
+ public function rules(): array
+ {
+ return [
+ 'title' => 'required',
+ 'content' => 'required',
+ ];
+ }
+}
+```
+
+Should be rewritten in this in 9.x:
+```php
+class PostForm extends SharpForm
+{
+ public function rules(): array
+ {
+ return [
+ 'title' => 'required',
+ 'content' => 'required',
+ ];
+ }
+
+ // ...
+}
+```
+
+Or:
+```php
+class PostForm extends SharpForm
+{
+ // ...
+
+ public function update($id, array $data)
+ {
+ $this->validate($data, [
+ 'title' => 'required',
+ 'content' => 'required',
+ ]);
+
+ // ...
+ }
+}
+```
+
+This version brings two huge benefits (besides the fact that it's clearer):
+
+- the "delayed creation" thing is gone (hooray!): the `{id}` parameter in a `SharpFormUploadField` storageBasePath isn't anymore an issue in creation case as Sharp will no longer call the `update()` method twice.
+- **Validation is now called AFTER data formatters**, even in `SharpForm` (it was already the case with `Command`). This cause a breaking change (see below).
+
+**If you decide to migrate** to this new validation system (and you should), pay attention to:
+- remove special workarounds you may have done to handle the "delayed creation" thing,
+- remove the `.text` suffix you may have added for `SharpFormEditorField` validation rules,
+- remove the common `.id` suffix you may have added for `SharpFormAutocomplete(Remote|Local)Field` validation rules.
+
+Here's a code example (in which editor is a `SharpFormEditorField` and authors is a `SharpFormAutocompleteLocalField`):
+```diff
+class PostForm extends SharpForm
+{
+ // ...
+ public function rules(): array
+ {
+ return [
+- 'editor.text' => 'required',
++ 'editor' => 'required',
+- 'authors.id' => 'required',
++ 'authors' => 'required',
+ ];
+ }
+}
+```
+
+**If you decide not to migrate just now**, you should ensure that the `\Code16\Sharp\Http\Middleware\Api\BindSharpValidationResolver` middleware in added to the `api` group:
+
+either in the (deprecated) config file:
+```php
+// config/sharp.php
+
+return [
+ 'middleware' => [
+ //...
+ 'api' => [
+ // ...
+ \Code16\Sharp\Http\Middleware\Api\BindSharpValidationResolver::class,
+ ],
+ ],
+]
+```
+
+... or in the shinny new config builder:
+```php
+class MySharpServiceProvider extends SharpAppServiceProvider
+{
+ protected function configureSharp(SharpConfigBuilder $config): void
+ {
+ $config
+ ->appendToMiddlewareApiGroup(
+ \Code16\Sharp\Http\Middleware\Api\BindSharpValidationResolver::class
+ )
+ // ...
+ }
+}
+```
+
+## Localization feature was removed for `SharpFormSelectField`, `SharpFormTagsField` and `SharpFormAutocompleteField` fields
+
+Those fields could be localized in 8.x in a weird way: **labels** were localized, but not **values**. This was really misleading, so we decided to remove entirely this behavior in 9.x. The only real impact should be to remove setLocalized() calls in your code for these fields.
+
+## `SharpFormGeolocationField` using Google Maps API must now provide a Map ID
+
+Sharp 9.x now uses Advanced Markers which requires a [Map ID](https://developers.google.com/maps/documentation/get-map-id), register it with the following method of the field :
+
+```php
+class PostForm extends SharpForm
+{
+ public function buildFormFields(FieldsContainer $formFields): void
+ {
+ $formFields->addField(
+ SharpFormGeolocationField::make('position')
+ ->setMapsProvider('gmaps')
+ ->setApiKey('...')
+ ->setGoogleMapsMapId('...') // new method
+ );
+ }
+}
+```
+
+## `SharpFormAutocompleteFormField` was rewritten and need to be migrated
+
+First, the `SharpFormAutocompleteFormField` class was split into two classes: `SharpFormAutocompleteLocalField` and `SharpFormAutocompleteRemoteField`, to clearly separate these two different use cases.
+
+Second, Vue templates must be migrated to Blade templates (similar to the `SharpWidgetPanel` or Page Alerts migrations). You can either pass a view name or a blade template directly to the newly named `setListItemTemplate()` and `setResultItemTemplate()` methods (the old `setListItemInlineTemplate()`, `setListItemTemplatePath()`, `setResultItemInlineTemplate()` and `setResultItemTemplatePath()` were removed).
+
+The `setAdditionalTemplateData()` method was also removed, in favor of a more straightforward way to pass additional data to the template.
+
+Example in 8.x:
+
+```php
+class PostForm extends SharpForm
+{
+ public function buildFormFields(FieldsContainer $formFields): void
+ {
+ $formFields
+ ->addField(
+ SharpFormAutocompleteField::make('author_id', 'remote')
+ ->setRemoteEndpoint('/api/admin/users')
+ ->setListItemInlineTemplate('{{name}}')
+ ->setResultItemInlineTemplate('{{name}}')
+ )
+ ->addField(
+ SharpFormAutocompleteField::make('category_id', 'local')
+ ->setLocalValues([
+ 1 => 'Category 1',
+ 2 => 'Category 2',
+ 3 => 'Category 3',
+ ])
+ )
+ ->addField(
+ // ...
+ );
+ }
+
+ // ...
+}
+```
+
+In 9.x:
+
+```php
+class PostForm extends SharpForm
+{
+ public function buildFormFields(FieldsContainer $formFields): void
+ {
+ $formFields
+ ->addField(
+ SharpFormAutocompleteRemoteField::make('author_id')
+ ->setRemoteEndpoint('/api/admin/users')
+ ->setListItemTemplate('{{$name}}')
+ )
+ ->addField(
+ SharpFormAutocompleteLocalField::make('category_id')
+ ->setLocalValues([
+ 1 => 'Category 1',
+ 2 => 'Category 2',
+ 3 => 'Category 3',
+ ])
+ )
+ ->addField(
+ // ...
+ );
+ }
+
+ // ...
+}
+```
+
+Finally, there is a big evolution which concerns the remote autocomplete endpoint: your 8.x implementation should still work, but you should note that:
+- you can now directly write the autocomplete endpoint as a callback closure in the field (no need to use a dedicated route + controller),
+- external endpoint URLs aren’t supported anymore (you must write a wrapper around this external endpoint, either as a route + controller or via the new callback option).
+
+Example in 8.x:
+
+```php
+class PostForm extends SharpForm
+{
+ public function buildFormFields(FieldsContainer $formFields): void
+ {
+ $formFields
+ ->addField(
+ SharpFormAutocompleteField::make('author_id', 'remote')
+ ->setRemoteEndpoint('/api/admin/users')
+ ->setListItemInlineTemplate('{{name}}')
+ ->setResultItemInlineTemplate('{{name}}')
+ );
+ }
+
+ // ...
+}
+```
+
+In 9.x:
+
+```php
+class PostForm extends SharpForm
+{
+ public function buildFormFields(FieldsContainer $formFields): void
+ {
+ $formFields
+ ->addField(
+ SharpFormAutocompleteRemoteField::make('author_id')
+ ->setRemoteCallback(function ($search) {
+ return User::where('name', 'like', "%$search%")->get();
+ })
+ ->setListItemTemplate('{{$name}}')
+ );
+ }
+
+ // ...
+}
+```
+
+## `SharpFormUploadField`’s image related methods were renamed
+
+This isn't a breaking change, since the old methods are still available, but deprecated. You should migrate to the new methods:
+
+- `setFileFilterImage()` -> `setImageOnly()`
+- `setCropRatio()` = `setImageCropRatio()`
+- `shouldOptimizeImage()` = `setImageOptimize()`
+- `setTransformable()` = `setImageTransformable()`
+- `setCompactThumbnail()` = `setImageCompactThumbnail()`
+
+and in addition:
+
+- `setFilterFilter()` -> `setAllowedExtensions()`
+
+See [full documentation here](../form-fields/upload.md).
+
+## The API for embedded uploads in Editor field was rewritten
+
+The `SharpFormEditorField` no longer has all the upload-related methods directly in the class. Instead, you must use a new `SharpFormEditorUpload` builder class, passed as a parameter to the `allowUploads()` method.
+
+In 8.x:
+
+```php
+// in a SharpForm
+public function buildFormFields(FieldsContainer $formFields): void
+{
+ $formFields->addField(
+ SharpFormEditorField::make('content')
+ ->setMaxLength(1000)
+ ->setToolbar([
+ SharpFormEditorField::B,
+ SharpFormEditorField::A,
+ SharpFormEditorField::UPLOAD,
+ ])
+ ->setStorageDisk('local')
+ ->setStorageBasePath('data/posts/{id}/embed'),
+ )
+ );
+}
+```
+
+In 9.x:
+
+```php
+// in a SharpForm
+public function buildFormFields(FieldsContainer $formFields): void
+{
+ $formFields->addField(
+ SharpFormEditorField::make('content')
+ ->setMaxLength(1000)
+ ->setToolbar([
+ SharpFormEditorField::B,
+ SharpFormEditorField::A,
+ SharpFormEditorField::UPLOAD,
+ ])
+ ->allowUploads(
+ SharpFormEditorUpload::make()
+ ->setStorageDisk('local')
+ ->setStorageBasePath('data/posts/{id}/embed')
+ );
+ );
+}
+```
+
+See [full documentation here](../form-fields/editor.md).
+
+## New markup for Embedded uploads (in Editor field)
+
+If you are using `SharpFormEditorField` uploads, you will need migrate `` and `` elements in the content, meaning in the database. Sharp provides a helper trait intended to be used in your migration like this:
+
+```php
+use Code16\Sharp\Form\Eloquent\Migrations\MigrateEditorContentsForSharp9;
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Support\Facades\DB;
+
+new class extends Migration
+{
+ use MigrateEditorContentsForSharp9;
+
+ public function up(): void
+ {
+ $this->updateEditorContentOf(DB::table('posts'), ['content']);
+ }
+}
+```
+
+## Editor embeds has now blade templates
+
+Like Autocomplete / Dashboard Widget panel, Editor embeds must now be blade inline string or a `view('...')` :
+
+### Inline templates
+
+Inline templates in 8.x :
+
+```php
+public function buildEmbedConfig(): void
+{
+ $this
+ ->configureFormInlineTemplate('
{{ title }}
')
+ ->configureShowInlineTemplate('
{{ title }}
');
+}
+```
+
+Inline templates in 9.x :
+
+```php
+public function buildEmbedConfig(): void
+{
+ $this
+ // if only one template is defined (for both form & show)
+ ->configureTemplate('@if($online)
{{ $title }}
@endif')
+
+ // if form & show has 2 different templates
+ ->configureFormTemplate('@if($online)
{{ $title }}
@endif')
+ ->configureShowTemplate('@if($online)
{{ $title }}
@endif');
+}
+```
+
+### Path templates
+
+Path templates in 8.x :
+
+```php
+public function buildEmbedConfig(): void
+{
+ $this
+ ->configureFormTemplatePath('sharp/embed.vue')
+ ->configureShowTemplatePath('sharp/embed.vue');
+}
+```
+
+Path templates in 9.x :
+
+```php
+public function buildEmbedConfig(): void
+{
+ $this
+ // if only one template is defined (for both form & show)
+ ->configureTemplate(view('sharp.embed'))
+
+ // if form & show has 2 different templates
+ ->configureFormTemplate(view('sharp.embed'))
+ ->configureShowTemplate(view('sharp.embed'));
+}
+```
+
+## `SharpFormListField` collapsed items template feature was removed
+
+`setCollapsedItemInlineTemplate()` & `setCollapsedItemTemplatePath()` methods was removed due to limited usage and general migration into blade templates.
+
+## `SharpFormHtmlField` has migrated to blade templates
+
+`setInlineTemplate()` & `setTemplatePath()` must be converted to :
+- `setTemplate('blade template string')` or
+- `setTemplate(view('sharp.form-field'))`.
+
+See [field page](../form-fields/html) for more information.
+
diff --git a/docs/img/readme/v9/command.png b/docs/img/readme/v9/command.png
new file mode 100644
index 000000000..c2a1c2d68
Binary files /dev/null and b/docs/img/readme/v9/command.png differ
diff --git a/docs/img/readme/v9/command.webp b/docs/img/readme/v9/command.webp
new file mode 100644
index 000000000..5c3cf6471
Binary files /dev/null and b/docs/img/readme/v9/command.webp differ
diff --git a/docs/img/readme/v9/dark.png b/docs/img/readme/v9/dark.png
new file mode 100644
index 000000000..55edd785b
Binary files /dev/null and b/docs/img/readme/v9/dark.png differ
diff --git a/docs/img/readme/v9/dark.webp b/docs/img/readme/v9/dark.webp
new file mode 100644
index 000000000..bc28f0eaa
Binary files /dev/null and b/docs/img/readme/v9/dark.webp differ
diff --git a/docs/img/readme/v9/dashboard.png b/docs/img/readme/v9/dashboard.png
new file mode 100644
index 000000000..933a25493
Binary files /dev/null and b/docs/img/readme/v9/dashboard.png differ
diff --git a/docs/img/readme/v9/dashboard.webp b/docs/img/readme/v9/dashboard.webp
new file mode 100644
index 000000000..c04cf83f5
Binary files /dev/null and b/docs/img/readme/v9/dashboard.webp differ
diff --git a/docs/img/readme/v9/form.png b/docs/img/readme/v9/form.png
new file mode 100644
index 000000000..f03841b04
Binary files /dev/null and b/docs/img/readme/v9/form.png differ
diff --git a/docs/img/readme/v9/form.webp b/docs/img/readme/v9/form.webp
new file mode 100644
index 000000000..34facebe9
Binary files /dev/null and b/docs/img/readme/v9/form.webp differ
diff --git a/docs/img/readme/v9/list.png b/docs/img/readme/v9/list.png
new file mode 100644
index 000000000..b1b91608a
Binary files /dev/null and b/docs/img/readme/v9/list.png differ
diff --git a/docs/img/readme/v9/list.webp b/docs/img/readme/v9/list.webp
new file mode 100644
index 000000000..0d6140091
Binary files /dev/null and b/docs/img/readme/v9/list.webp differ
diff --git a/docs/img/readme/v9/login.png b/docs/img/readme/v9/login.png
new file mode 100644
index 000000000..6cd2e4293
Binary files /dev/null and b/docs/img/readme/v9/login.png differ
diff --git a/docs/img/readme/v9/login.webp b/docs/img/readme/v9/login.webp
new file mode 100644
index 000000000..ec6882db1
Binary files /dev/null and b/docs/img/readme/v9/login.webp differ
diff --git a/docs/img/readme/v9/show.png b/docs/img/readme/v9/show.png
new file mode 100644
index 000000000..caf867bb4
Binary files /dev/null and b/docs/img/readme/v9/show.png differ
diff --git a/docs/img/readme/v9/show.webp b/docs/img/readme/v9/show.webp
new file mode 100644
index 000000000..815890b15
Binary files /dev/null and b/docs/img/readme/v9/show.webp differ
diff --git a/docs/index.md b/docs/index.md
index 9e3e233bf..a205259dd 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -15,82 +15,188 @@ hero:
link: https://sharp.code16.fr/sharp
---
-
-
-
-Sharp is a content management framework built for Laravel, a toolset which provides help to build a CMS section in a website, with some rules in mind:
-- the public website **should not have any knowledge of the CMS** — the CMS is a part of the system, not the center of it. In fact, removing the CMS should not have any effect on the project.
-- Content administrators **should work with their data and terminology**, not CMS terms. I mean, if the project is about spaceships, space travels and pilots, why would the CMS talk about articles, categories and tags?
-- Developers **should not have to work on the front-end development for the CMS**. Because life is complicated enough, Sharp takes care of all the responsive / CSS / JS stuff.
-- The CMS **should not have any expectations from the persistence layer**: MySQL is cool — but it's not the perfect tool for every problem. And more important, the DB structure has nothing to do with the CMS.
+Sharp is a content management framework built for Laravel as a package, which provides great help to build a CMS section in a project with a clean UI and DX in mind. Sharp is driven by code: everything is manageable through a clean and documented PHP API, using Laravel conventions and coding style. It intends to avoid code adherence — the project should not have any knowledge of it — and is data-agnostic, meaning it does not have any expectations from the persistence layer.
-## Build complex lists with total control on how the data is presented
+Sharp for Laravel is actively maintained and developed and is used in all kinds of projects, from content-driven websites to e-commerce platforms and API backends.
-
-## Organize forms withs various fields, a customizable layout system and data validation
+# Main features
-You will find a powerful HTML / Markdown editor, autocompletes with templates, lists (repeaters) with custom items, files with bulk upload and image transformation...
+
-
+## Streamlined Lists
-## Optionally create show pages for your resources
+### Customizable columns
+Choose and format the data to display, and allow sorting.
-You can use show page to present an instance and directly embed in it lists for linked data. The breadcrumb will help your users to find their way up.
+### Search and filters
+Define filters for your lists, with various types and options.
-
+### State management
+If your entities have some state, you can manage it easily form here.
-## Add filters, sortable columns and global search to your lists
+
-Filters could be defined required or not, allowing multiple values or not, or presented as a date range.
+
-
+
-## Code individual or bulk commands, with dedicated forms, user confirmation...
+
-A Command is an action presented to the user (with permissions handled via policies, like everywhere in Sharp) which can lead to refreshing data after update, previewing a public page, downloading a file...
-
+
-
+## Powerful Command system
-## Propose a custom global search to users
+### Individual or bulk
+Create commands to act on a single instance or on a selection (filtered list or user choice).
-The search results and their label and link are entirely customizable.
+### Forms
+Easily attach forms to commands, with validation and confirmation.
-
+### Wizards
+Create multi-steps commands with dynamic paths.
-## Present synthetic data, graphs and direct links in dashboards
+
-Various widgets are available, and you can take advantage of filters and commands in dashboards too.
+
-
+
-## Built-in authentication system, with out-of-the-box 2fa
+
-The optional authentication system provides standard features like remember me token and rate limiting, and you can leverage double authentication with a verification based on a notification or on TOTP.
-
+
-## Choose your theme color!
+## Comprehensive Forms
-Choose one color, and the UI will adapt itself.
+### Fields and layout
+Use one of the many fields available, and organize them in a layout that fits your needs.
-
+### Powerful editor with embeds
+Sharp's custom editor really allows to create rich content, and includes a clever system to develop custom embeds.
-## Driven by code, with DX in mind
+### Uploads
+Manage files with bulk uploads, image transformation, disk and path configuration and precise validation.
-Everything in Sharp is manageable through a clean and documented PHP API, using Laravel conventions and coding style. And again: no frontend development is required.
+### Lists
+Create lists (repeaters) of custom items in your form.
-
+
-## Try the online demo
+
-A Sharp instance for a demo project is available online here: **[sharp.code16.fr/sharp/](http://sharp.code16.fr/sharp/)**.
+
+
+
+
+
+
+
+## Detailed Show Pages
+
+### Present an instance
+Create a page to present an instance with a custom layout, with access to commands and state management.
+
+### Embedded lists
+Include lists in your show page to present linked data.
+
+### Breadcrumb
+Help your users to find their way up, allowing hierarchical navigation though embedded lists.
+
+
+
+
+
+
+
+
+
+
+
+
+## Insightful Dashboards
+
+### Widgets
+Use various widgets to present synthetic data, graphs and direct links.
+
+### Filters and commands
+Leverage filters and commands in your dashboards.
+
+
+
+
+
+
+
+
+
+
+
+
+## Authentication and authorizations
+
+### Built-in authentication system
+With fine-grained permissions managed by custom policies.
+
+### Remember me, rate limiting, forgotten password
+And impersonation in dev.
+
+### 2FA
+Out-of-the-box 2FA with TOTP or notification.
+
+
+
+
+
+
+
+
+
+
+
+
+## And more
+
+### Global search
+Propose a custom global search to users.
+
+### Global filters
+Ideal for multi-tenant applications.
+
+### Built-in localization
+Manage translations for your entities.
+
+### Quick creation UI
+Allow your user to efficiently create new instances.
+
+### Toast notifications and page alerts
+To inform your users.
+
+### Dark mode and theme color
+The UI will adapt itself based on your primary color.
+
+### Artisan commands
+With prompts to generate lists, forms, commands, etc.
+
+### Code-driven configuration
+With a clean and documented API.
+
+
+
+
+
+
+
+
+
+# About Sharp
+
+Sharp is a long term project developed by [Code 16](https://code16.fr), a web agency based in France, since 2017. We use it in almost all our projects, and we are committed to maintaining and improving it over time.
+
+Sharp 9 relies on Laravel 11, Tailwind CSS, Inertia, Vue and Alpine.JS.
+
+So far we have not implemented any kind of sponsorship system, but we are open to discussing it in the future.
-(Data of this demo is reset each hour)
-
-
-
-
diff --git a/packages/ui/src/components/index.js b/packages/ui/src/components/index.js
deleted file mode 100644
index 22ef5f46e..000000000
--- a/packages/ui/src/components/index.js
+++ /dev/null
@@ -1,26 +0,0 @@
-export { default as Breadcrumb } from './Breadcrumb.vue';
-export { default as Button } from './Button.vue';
-export { default as ClearButton } from './ClearButton.vue';
-export { default as NavSection } from './nav/NavSection.vue';
-export { default as DataList } from './DataList.vue';
-export { default as DataListRow } from './DataListRow.vue';
-export { default as Dropdown } from './dropdown/Dropdown.vue';
-export { default as DropdownItem } from './dropdown/DropdownItem.vue';
-export { default as DropdownSeparator } from './dropdown/DropdownSeparator.vue';
-export { default as GlobalMessage } from './global-message/GlobalMessage.vue';
-export { default as Grid } from './Grid.vue';
-export { default as Loading } from './loading/Loading.vue';
-export { default as LoadingOverlay } from './loading/LoadingOverlay.vue';
-export { default as Modal } from './Modal.vue';
-export { default as ModalSelect } from './ModalSelect.vue';
-export { default as Multiselect } from './Multiselect.vue';
-export { default as NavItem } from './nav/NavItem.vue';
-export { default as Pagination } from './Pagination.vue';
-export { default as Search } from './Search.vue';
-export { default as SectionTitle } from './section/SectionTitle.vue';
-export { default as StateIcon } from './StateIcon.vue';
-export { default as Tab } from './Tab.vue';
-export { default as TabbedLayout } from './TabbedLayout.vue';
-export { default as Tabs } from './Tabs.vue';
-export { default as TopBar } from './TopBar.vue';
-export { default as Tooltip } from './Tooltip.vue';
diff --git a/packages/ui/src/components/loading/Loading.vue b/packages/ui/src/components/loading/Loading.vue
deleted file mode 100644
index 36fde3af0..000000000
--- a/packages/ui/src/components/loading/Loading.vue
+++ /dev/null
@@ -1,39 +0,0 @@
-
-
-
+
Here's how it can be edited, in Sharp:
-
+
And here's how it could be stored, as a reference:
@@ -28,14 +24,11 @@ The purpose of this class is to define all this: how to present, edit and store
### Required methods
-The class must extend `Code16\Sharp\Form\Fields\Embeds\SharpFormEditorEmbed`; you'll have to implement at least these
-two methods:
+The class must extend `Code16\Sharp\Form\Fields\Embeds\SharpFormEditorEmbed`; you'll have to implement at least these two methods:
### `buildFormFields(FieldsContainer $formFields): void`
-Here you can declare the form fields of the embed; the API is the same as building a standard Form (
-see [Building an Entity Form](building-form.md)). This form will appear in a modal when the use creates a new embed, or
-clicks in the edit button of an existing one.
+Here you can declare the form fields of the embed; the API is the same as building a standard Form (see [Building an Entity Form](building-form.md)). This form will appear in a modal when the use creates a new embed, or clicks in the edit button of an existing one.
::: tip
You can choose to name one (and only one) field `slot`: it will be stored as the component content, rather than in an attribute. This could be easier to handle complex data (an Editor HTML text for instance) this way, in the public site, where you can use the standard `{{ $slot }}` attribute to display it.
@@ -65,10 +58,11 @@ This is not required, but you should implement `buildEmbedConfig(): void`, where
- `configureLabel(string $label): self`: to define the name of the embed (should be short)
- `configureTagName(string $tagName): self`: to define the tag name (typically starting with `x-`)
-- `configureFormInlineTemplate(string $template): self` and `configureFormTemplatePath(string $templatePath): self`: to
- define the .vue template for displaying the embed in the Editor field in the form
-- `configureShowInlineTemplate(string $template): self` and `configureShowTemplatePath(string $templatePath): self`:
- same, but for the show page, only you need to have a different version for it.
+- `configureTemplate(string|View $template): self`: to define the blade as inline string or as a `view('my-template')` for both show & form. If you want to specify different templates between show & form you can use following methods :
+ - `configureShowTemplate(string|View $template): self`
+ - `configureFormTemplate(string|View $template): self`
+- `configureIcon(string $icon): self`: to define an icon used when the embed is placed in the toolbar. The icon is also displayed in the embed header.
+- `configureDisplayEmbedHeader(bool $display = true, ?string $title = null): self`: to hide the default embed header. The title is the label defined in `configureLabel()` but it can be overridden here.
Here's a complete example:
@@ -78,23 +72,27 @@ public function buildEmbedConfig(): void
$this
->configureLabel('Related Post')
->configureTagName('x-related-post')
- ->configureFormInlineTemplate('
-
## Configuration
### `setHasDate($hasDate = true)`
@@ -31,10 +29,6 @@ If set, the time-chooser will be constraint as defined.
Set a time step (in minutes) for the time-chooser. Default is 30.
-### `setDisplayFormat(string $displayFormat)`
-
-Set the date / time display format in the field, as defined by [moment.js](https://momentjs.com/docs/#/parsing/string-format/). Default is `YYYY-MM-DD`.
-
## Formatter
diff --git a/docs/guide/form-fields/editor.md b/docs/guide/form-fields/editor.md
index c767059ae..241b6b9e7 100644
--- a/docs/guide/form-fields/editor.md
+++ b/docs/guide/form-fields/editor.md
@@ -4,9 +4,6 @@ This form field is a rich text editor, with formatting and an optional toolbar.
Class: `Code16\Sharp\Form\Fields\SharpFormEditorField`
-
-
-
## Configuration
### `setHeight(int $height, int|null $maxHeight = null)`
@@ -36,8 +33,6 @@ const A = 'link';
const H1 = 'heading-1';
const H2 = 'heading-2';
const H3 = 'heading-3';
-const UPLOAD_IMAGE = 'upload-image';
-const UPLOAD = 'upload';
const TABLE = 'table';
const IFRAME = 'iframe';
const RAW_HTML = 'html';
@@ -53,14 +48,29 @@ Example:
```php
SharpFormEditorField::make("description")
->setToolbar([
- SharpFormEditorField::B, SharpFormEditorField::I,
- SharpFormEditorField::SEPARATOR,
- SharpFormEditorField::UPLOAD_IMAGE,
+ SharpFormEditorField::B,
+ SharpFormEditorField::I,
SharpFormEditorField::SEPARATOR,
SharpFormEditorField::A,
]);
```
+If you have editor embeds you can add them to the toolbar alongside other buttons (instead of the embeds dropdown) :
+
+```php
+SharpFormEditorField::make("description")
+ ->setToolbar([
+ SharpFormEditorField::B,
+ SharpFormEditorField::I,
+ AuthorEmbed::class,
+ ])
+ ->allowEmbeds([
+ AuthorEmbed::class,
+ ]);
+```
+
+See full [embed docs](../form-editor-embeds.md).
+
### `setRenderContentAsMarkdown(bool $renderAsMarkdown = true)`
If true the front will send the content as markdown to the back, for storage. Default is false.
@@ -83,55 +93,44 @@ Display a character count in the status bar. Default is false.
## Embed images and files in content
-The Editor field can directly embed images or regular files. This works with `UPLOAD_IMAGE` and `UPLOAD` tools from the toolbar. To use this feature, add the tool in the toolbar and configure the environment:
+The Editor field can embed images or regular files. To use this feature, you must first allow the field to handle uploads:
+
+### `allowUploads(SharpFormEditorEmbedUpload $formEditorUpload)`
-### `setMaxFileSize(float $sizeInMB)`
+This method allows the user to upload files and images in the editor:
+
+```php
+$formFields->addField(
+ SharpFormEditorField::make('bio')
+ ->allowUploads(
+ SharpFormEditorEmbedUpload::make()
+ ->setStorageBasePath('posts/embeds')
+ ->setStorageDisk('local')
+ )
+);
+```
-Max file size allowed.
+The `SharpFormEditorEmbedUpload` can be configured with the same API as the `SharpFormUploadField`: `setMaxFileSize()`, `setImageOnly()`, `setAllowedExtensions()`, ... ([see full documentation](../form-fields/upload.md))
-### `setTransformable(bool $transformable = true, bool $transformKeepOriginal = true)`
+### A note on `setImageTransformable(bool $transformable = true, bool $transformKeepOriginal = true)`
-Allow the user to crop or rotate a visual, after the upload.
+As for a regular upload field, you can allow the user to crop or rotate the visual, after the upload.
With `$transformKeepOriginal` set to true, the original file will remain unchanged, meaning the transformations will be stored directly in the `
+This feature allows to embed any structured data in the content. A common use case is to embed a reference to another instance, like for example: in a blog post, you want to insert a reference to another post, that would be rendered as a “read also” block / link in the public section.
-In practice, the Editor field can allow custom embeds, which defines how the data is stored in the field (as HTML
-attributes), and how it is edited in the UI, via a full-featured form.
+In practice, the Editor field can allow custom embeds, which defines how the data is stored in the field (as HTML attributes), and how it is edited in the UI, via a full-featured form.
### `allowEmbeds(array $embeds)`
-This method expects an array of embeds that could be inserted in the content, declared as full class names. An embed
-class must extend `Code16\Sharp\Form\Fields\Embeds\SharpFormEditorEmbed`.
+This method expects an array of embeds that could be inserted in the content, declared as full class names. An embed class must extend `Code16\Sharp\Form\Fields\Embeds\SharpFormEditorEmbed`.
The [documentation on how to write an Embed class is available here](../form-editor-embeds.md).
diff --git a/docs/guide/form-fields/geolocation.md b/docs/guide/form-fields/geolocation.md
index 8e98e029c..c21569a78 100644
--- a/docs/guide/form-fields/geolocation.md
+++ b/docs/guide/form-fields/geolocation.md
@@ -4,23 +4,6 @@ A map-based field to pick a precise location and return its coordinates (latitud
Class: `Code16\Sharp\Form\Fields\SharpFormGeolocationField`
-
-
-
-
## General configuration
-First, in order to get the upload part working, you have to define a "tmp" path where files will be stored until they are moved to the final folder. Here's the default:
+You can define the temp disk and directory where files will be stored until they are moved to the final folder, as well as a global max file size (which can be overriden by each field). Here are the default values:
```php
-// in config/sharp.php
-
-'uploads' => [
- 'tmp_disk' => env('SHARP_UPLOADS_TMP_DISK', 'local'),
- 'tmp_dir' => env('SHARP_UPLOADS_TMP_DIR', 'tmp'),
-]
+class SharpServiceProvider extends SharpAppServiceProvider
+{
+ protected function configureSharp(SharpConfigBuilder $config): void
+ {
+ $config
+ ->configureUploads(
+ uploadDisk: 'local',
+ uploadDirectory: 'tmp',
+ globalMaxFileSize: 5,
+ keepOriginalImageOnTransform: true
+ )
+ // [...]
+ }
+}
```
-This `tmp_dir` path is relative to the `uploads.tmp_disk` filesystem defined.
+The fourth argument, `keepOriginalImageOnTransform`, is a boolean that defines if the original image should be kept when a transformation is applied on it (meaning that transformations are stored and applied on-the-fly: this is transparent when using Sharp’s [built-in way to handle uploads](../sharp-uploads.md). It can be overriden by each field (see below).
## Field Configuration
-### `setMaxFileSize(float $sizeInMB)`
-
-Max file size allowed.
+### `setStorageDisk(string $storageDisk)`
-### `setTransformable(bool $transformable = true, ?bool $transformKeepOriginal = null)`
+Set the destination storage disk (as configured in Laravel’s `config/filesystem.php` config file).
-Allow the user to crop or rotate the visual, after the upload.
-The argument `$transformKeepOriginal` overrides the following config which is `true` by default.
-```php
-// config/sharp.php
+### `setStorageBasePath(string|Closure $storageBasePath)`
-'uploads' => [
- 'transform_keep_original_image' => true,
-]
-```
-With `$transformKeepOriginal` set to true, the original file will remain unchanged, meaning the transformations will be stored apart: using the [built-in way to handle uploads](../sharp-uploads.md), it's transparent. Otherwise, see the Formatter part below.
+Set the destination base storage path.
-### `setCropRatio(string $ratio, array $croppableFileTypes = null)`
+::: warning
+If you want to use a `{id}` special placeholder to add the instance id in the path (for instance: `$field->setStorageBasePath('/users/{id}/avatar')`), you must be the Eloquent case, leveraging `Code16\Sharp\Form\Eloquent\WithSharpFormEloquentUpdater` (see [Eloquent form](../building-form#eloquent-case-where-the-magic-happens))
+:::
-Set a ratio constraint to uploaded images, formatted like this: `width:height`. For instance: `16:9`, or `1:1`.
+### `setAllowedExtensions(string|array $allowedExtensions)`
-When a crop ratio is set, any uploaded picture will be auto-cropped (centered).
+Define the allowed file extensions.
-The second argument, `$croppableFileTypes`, provide a way to limit the crop configuration to a list of image files extensions. For instance, it can be useful to define a crop for jpg and png, but not for gif because it will destroy animation.
+For instance: `$field->setAllowedExtensions(['pdf', 'zip'])`
-### `setStorageDisk(string $storageDisk)`
+## Field Configuration in image case
-Set the destination storage disk (as configured in Laravel's `config/filesystem.php` config file).
+### `setImageOnly(bool $imageOnly = true)`
-### `setStorageBasePath(string|Closure $storageBasePath)`
+When an upload field is configured to accept only images:
+- the field will be forced to accept only images (allowed extensions set to "jpg, png, gif, svg, webp, bmp" by default),
+- the uploaded file will be validated as an image (see below for more options),
+- a thumbnail will be generated for the uploaded image.
-Set the destination base storage path.
+### `setImageTransformable(bool $transformable = true, ?bool $transformKeepOriginal = null)`
-You can use the `{id}` special placeholder to add the instance id in the path, which can be useful sometimes; **be sure to read the “Delayed creation” section, at the end of this page if you do.**
+Allow the user to crop or rotate the visual, after the upload.
+The argument `$transformKeepOriginal` overrides the global config (which is `true` by default).
-For instance:
-`$field->setStorageBasePath('/users/{id}/avatar')`
+With `$transformKeepOriginal` set to true, the original file will remain unchanged, meaning the transformations will be stored apart: using the [built-in way to handle uploads](../sharp-uploads.md), it's transparent. Otherwise, see the Formatter part below.
-### `setFileFilter($fileFilter)`
+### `setImageCropRatio(string $ratio, array $croppableFileTypes = null)`
-Set the allowed file extensions. You can pass either an array or a comma-separated list.
+Set a ratio constraint to uploaded images, formatted like this: `width:height`. For instance: `16:9`, or `1:1`.
-### `setFileFilterImages()`
+When a crop ratio is set, any uploaded picture will be auto-cropped (centered).
-Just a `setFileFilter(['.jpg','.jpeg','.gif','.png'])` shorthand.
+The second argument, `$croppableFileTypes`, provide a way to limit the crop configuration to a list of image files extensions. For instance, it can be useful to define a crop for jpg and png, but not for gif because it will destroy animation.
-### `setCompactThumbnail(bool $compactThumbnail = true)`
+### `setImageCompactThumbnail(bool $compactThumbnail = true)`
If true and if the upload has a thumbnail, it is limited to 60px high (to compact in a list item, for instance).
-### `shouldOptimizeImage(bool $shouldOptimizeImage = true)`
+### `setImageOptimizeImage(bool $imageOptimize = true)`
If true, some optimization will be applied on the uploaded images (in order to reduce files weight). It relies on spatie's [image-optimizer](https://github.com/spatie/image-optimizer). Please note that you will need some of these packages on your system:
- [JpegOptim](http://freecode.com/projects/jpegoptim)
@@ -83,6 +85,20 @@ If true, some optimization will be applied on the uploaded images (in order to r
Check their documentation for [more instructions](https://github.com/spatie/image-optimizer#optimization-tools) on how to install.
+## Validation
+
+Notice that `setAllowedExtensions()` and `setImageOnly()` already are basic validation rules that Sharp will use both on the front-end and in the back-end.
+
+But there are a few more rules available:
+
+### `setMaxFileSize(int $maxFileSizeInMB)` and `setMinFileSize(int $minFileSizeInMB)`
+
+Set the maximum and minimum (even if this is a rare use-case) file size in MB.
+
+### `setImageDimensionConstraints(Illuminate\Validation\Rules\Dimensions $dimensions)`
+
+Set image dimension constraints, leveraging the dedicated Laravel validation rule (see [the documentation](https://laravel.com/docs/validation#rule-dimensions)).
+
## Formatter
First, let's mention that Sharp provides an Eloquent built-in solution for uploads with the `SharpUploadModel` class, as [detailed here](../sharp-uploads.md), which greatly simplify the work (to be clear: it will handle everything from storage to image transformations).
@@ -126,15 +142,13 @@ function find($id): array
'name' => basename($product->picture->name),
'path' => $product->picture->name,
'disk' => 's3',
- 'thumbnail' => [...],
+ 'thumbnail' => /* thumbnail URL */,
'size' => $product->picture->size,
'filters' => $product->picture->filters
];
}
)
- ->transform(
- Product::findOrFail($id)
- );
+ ->transform(Product::find($id));
}
```
@@ -146,14 +160,14 @@ There are four cases:
#### newly uploaded file
-The formatter will store the file on the configured location, and return an array like this:
+The formatter must return an array like this:
```php
[
- 'file_name' => '', // Relative file path
+ 'file_name' => '', // Target file path (relative)
'size' => x, // File size in bytes
'mime_type' => '', // File mime type
- 'disk' => '', // Storage disk name
+ 'disk' => '', // Target storage disk name
'filters' => [ // Transformations applied to the (image) file
'crop' => [
'x' => x,
@@ -183,9 +197,9 @@ function update($id, array $data)
}
```
-#### existing transformed file
+#### existing transformed image
-In this case, the file was already stored in a previous post, and was then transformed (cropped, or rotated). The formatter will simply return and array with one `filters` key:
+In this case, the image was already handled in a previous post, and was then transformed (cropped, or rotated). The formatter will simply return and array with one `filters` key:
```php
[
@@ -213,54 +227,23 @@ The formatter will return `null` (note that the file **will not** be deleted fro
The formatter will return **an empty array**.
-## Delayed creation
-
-As described in the `setStorageBasePath()` section of this document, you can configure the file storage path with an `{id}` placeholder, meaning that `/users/{id}/avatar` will be converted (by the field formatter) in `/users/1/avatar` for instance.
-
-But in order to do this in a creation case, when there is no id yet, Sharp will need your instance to be stored first. To do so, the `update()` method of your Form will be called twice:
-
-- one first time without any upload which needs the `{id}`,
-- and one second time only with these fields, using the new id returned by `update()`.
+## Configure files jobs
-This is usually OK, but in some cases this could lead to unexpected errors. Consider this code where we handle `Products` with a `picture` configured with an `{id}` placeholder in its path:
+Sharp handle files in jobs (copy / move and transformation). You can configure how these job should be dispatched:
```php
-class ProductForm extends SharpForm
+class SharpServiceProvider extends SharpAppServiceProvider
{
- // [...]
-
- public function buildFormFields(FieldsContainer $formFields): void
+ protected function configureSharp(SharpConfigBuilder $config): void
{
- // [...]
-
- $formFields
- ->addField(
- SharpFormUploadField::make('picture')
- ->setLabel('Picture')
- ->setFileFilterImages()
- ->setStorageDisk('local')
- ->setStorageBasePath('data/products/{id}'),
- );
- }
-
- function update($id, array $data)
- {
- $instance = $id ? Product::findOrFail($id) : new Product();
-
- $this->save($instance, $data);
-
- if(($data['price']) >= 1000) {
- $this->notify('Yay, this is an expensive product...');
- }
-
- return $instance->id;
+ $config
+ ->configureUploads(
+ fileHandingQueue: 'default',
+ fileHandlingQueueConnection: 'sync',
+ )
+ // [...]
}
}
```
-Here we're using the `notify()` feature to display a message back to the user, and it's working, excepted in one case: on a Product creation with a picture, Sharp will delay the upload handling and call this method twice, because the picture field needs the product {id} it the storage base path. On the second pass (for the upload), This code will crash on the `if(($data['price']) ...)` condition, because `$data['price']` is not set (only the `picture` upload field would be set on this second pass). This has to be addressed, and a working solution (among others) could be to replace this line with:
-```php
-if(($data['price'] ?? 0) >= 1000) {
- [...]
-}
-```
+Queue and connection should be [properly configured](https://laravel.com/docs/queues).
\ No newline at end of file
diff --git a/docs/guide/global-search.md b/docs/guide/global-search.md
index 889a29696..a982e8377 100644
--- a/docs/guide/global-search.md
+++ b/docs/guide/global-search.md
@@ -2,20 +2,20 @@
This feature allows the user to globally search across a selected set of entities of your application.
-
+
## Configuration
```php
-// In config/sharp.php
-return [
- // ...
- 'search' => [
- 'enabled' => true,
- 'placeholder' => 'Search for anything...',
- 'engine' => \App\Sharp\MySearchEngine::class,
- ],
-];
+class SharpServiceProvider extends SharpAppServiceProvider
+{
+ protected function configureSharp(SharpConfigBuilder $config): void
+ {
+ $config
+ ->enableGlobalSearch(\App\Sharp\MySearchEngine::class, 'Search for anything...')
+ // ...
+ }
+}
```
## Write the class
@@ -28,10 +28,7 @@ class MySearchEngine extends SharpSearchEngine
public function searchFor(array $terms): void
{
$resultSet = $this
- ->addResultSet(
- label: 'Posts',
- icon: 'fa-file-o',
- );
+ ->addResultSet('Posts');
$builder = Post::query();
@@ -74,10 +71,7 @@ class MySearchEngine extends SharpSearchEngine
public function searchFor(array $terms): void
{
$resultSet = $this
- ->addResultSet(
- label: 'Posts',
- icon: 'fa-file-o',
- );
+ ->addResultSet('Posts');
if (! $resultSet->validateSearch(
['string', 'min:3'],
@@ -95,6 +89,21 @@ class MySearchEngine extends SharpSearchEngine
As you can see in this example, the `validateSearch()` method accepts an array of regular Laravel validation rules, and an optional array of custom validation messages. Sharp will not display results if the validation fails, but a good practice is to return early in this case, to avoid unnecessary queries.
+### Authorization
+You may need to enable global search only for a subset of your users. You can do so by overriding the `authorize()` method in your search engine class:
+
+```php
+class MySearchEngine extends SharpSearchEngine
+{
+ // ...
+
+ public function authorize(): bool
+ {
+ return auth()->user()->isAdministrator();
+ }
+}
+```
+
## Use the search field
-The search field is available in the top bar of Sharp, and can be called with these pretty standard keyboard shortcuts: `Ctrl+K`, `Cmd+K` (Mac) or simply `/`.
\ No newline at end of file
+The search field is available in the top bar of Sharp, and can be called with these pretty standard keyboard shortcuts: `Ctrl+K`, `Cmd+K` (Mac) or simply `/`.
diff --git a/docs/guide/how-to-transform-data.md b/docs/guide/how-to-transform-data.md
index 3a994f6cd..34f31d5e9 100644
--- a/docs/guide/how-to-transform-data.md
+++ b/docs/guide/how-to-transform-data.md
@@ -11,7 +11,7 @@ Note that transformers need your data models to allow direct access to their att
In an Entity List, a Show Page or a Form, you can use the `transform()` function which will:
- apply all custom transformers on your list (see below),
-- transform the given model(s) into an array, handling pagination if a `LengthAwarePaginator` is provided.
+- transform the given model(s) into an array, handling pagination if a `Paginator` is provided.
Eloquent example in an Entity List:
@@ -105,7 +105,7 @@ class ProductEntityList extends SharpEntityList
function buildList(EntityListFieldsContainer $fields): void
{
- $fieldsContainer->addField(
+ $fields->addField(
EntityListDataContainer::make('author:name')
->setLabel('Author')
);
diff --git a/docs/guide/img/breadcrumb-v8.png b/docs/guide/img/breadcrumb-v8.png
deleted file mode 100644
index e05ebf6a3..000000000
Binary files a/docs/guide/img/breadcrumb-v8.png and /dev/null differ
diff --git a/docs/guide/img/embed-editor.png b/docs/guide/img/embed-editor.png
deleted file mode 100644
index b3e44616f..000000000
Binary files a/docs/guide/img/embed-editor.png and /dev/null differ
diff --git a/docs/guide/img/embed-form.png b/docs/guide/img/embed-form.png
deleted file mode 100644
index 8c6fc3f18..000000000
Binary files a/docs/guide/img/embed-form.png and /dev/null differ
diff --git a/docs/guide/img/form-localization-v8.png b/docs/guide/img/form-localization-v8.png
deleted file mode 100644
index c5b169681..000000000
Binary files a/docs/guide/img/form-localization-v8.png and /dev/null differ
diff --git a/docs/guide/img/global-filters.png b/docs/guide/img/global-filters.png
deleted file mode 100644
index dada7ebee..000000000
Binary files a/docs/guide/img/global-filters.png and /dev/null differ
diff --git a/docs/guide/img/global-search.png b/docs/guide/img/global-search.png
deleted file mode 100644
index e37bf8a7e..000000000
Binary files a/docs/guide/img/global-search.png and /dev/null differ
diff --git a/docs/guide/img/menu-v8.png b/docs/guide/img/menu-v8.png
deleted file mode 100644
index e5690e48a..000000000
Binary files a/docs/guide/img/menu-v8.png and /dev/null differ
diff --git a/docs/guide/img/page-alert-v8.png b/docs/guide/img/page-alert-v8.png
deleted file mode 100644
index 2a07bcb5e..000000000
Binary files a/docs/guide/img/page-alert-v8.png and /dev/null differ
diff --git a/docs/guide/img/v9/embed-editor.png b/docs/guide/img/v9/embed-editor.png
new file mode 100644
index 000000000..d95197eb4
Binary files /dev/null and b/docs/guide/img/v9/embed-editor.png differ
diff --git a/docs/guide/img/v9/embed-form.png b/docs/guide/img/v9/embed-form.png
new file mode 100644
index 000000000..b0c619f28
Binary files /dev/null and b/docs/guide/img/v9/embed-form.png differ
diff --git a/docs/guide/img/v9/global-search.png b/docs/guide/img/v9/global-search.png
new file mode 100644
index 000000000..e2c67c324
Binary files /dev/null and b/docs/guide/img/v9/global-search.png differ
diff --git a/docs/guide/img/v9/page-alert.png b/docs/guide/img/v9/page-alert.png
new file mode 100644
index 000000000..c948f4cab
Binary files /dev/null and b/docs/guide/img/v9/page-alert.png differ
diff --git a/docs/guide/img/v9/wizard-command.gif b/docs/guide/img/v9/wizard-command.gif
new file mode 100644
index 000000000..0939fbfbd
Binary files /dev/null and b/docs/guide/img/v9/wizard-command.gif differ
diff --git a/docs/guide/img/wizard-command.gif b/docs/guide/img/wizard-command.gif
deleted file mode 100644
index b664b7111..000000000
Binary files a/docs/guide/img/wizard-command.gif and /dev/null differ
diff --git a/docs/guide/index.md b/docs/guide/index.md
index 6e9cece95..eebaead21 100644
--- a/docs/guide/index.md
+++ b/docs/guide/index.md
@@ -1,13 +1,13 @@
-# Getting started
+# Getting started and installation
## Terminology, general concept
In Sharp, we handle `entities`; an `entity` is simply a data structure which has a meaning in the application context. For instance, a `Person`, a `Post` or an `Order`. In the Eloquent world, for which Sharp is optimized, it's typically a Model — but it's not necessarily a 1-1 relationship, a Sharp `entity` can represent a portion of a Model, or several Models.
-Each instance of an `entity` is called... an `instance`.
+An instance of an `entity` is simply called an `instance`.
Each `entity` in Sharp can be displayed:
-- in an `Entity List`, which is the list of all the `instances` for this `entity`: with some configuration and code, the user can sort the data, add filters, pagination, and perform searches. From there we also gain access to applicative `commands` applied either to an `instance` or to the whole (filtered) list, and to a simple `state` changer (the published state of an Article, for instance). All of that is described below.
+- in an `Entity List`, which is the list of all the `instances` for this `entity`: with some configuration and code, the user can sort the data, add filters, pagination, and perform searches. From there we also gain access to applicative `commands` applied either to any particular `instance` or to the whole (filtered) list, and to a simple `state` changer (the published state of an Article, for instance). All of that is described below.
- In a `Show Page`, optionally, to display an `instance` details.
- And in a `Form`, either to update or create a new `instance`.
@@ -35,45 +35,39 @@ Finally, **orders**, must be listed, detailed and updatable, and we also need to
- 