README

1. Installation
2. Data Setup
3. Usage
4. Search Indexing

1. Installation

Require the package in Composer, by running composer require bozboz/jam
Add Larasoft\Jam\Providers\JamServiceProvider::class to the providers array config/app.php
Run php artisan vendor:publish && php artisan migrate

2. Data Setup

2.1. Types

Entity types are the top level of the jam schema. They can essentially be thought of as models, or a logical grouping of models since the templates actually have the fields. Types are defined in service providers. Jam comes with a "Pages" type out of the box since most apps are going to need one.

When you register a type you can give it a report, link builder, menu builder, search handler and entity. If any are left blank the default will be used.

If you require nested sorting you should use the NestedType.

report Admin report class for listing. Generally this won't ever need to be changed unless you're going for something completely custom. The NestedType automatically switches the default to NestedReport.

Default Larasoft\Admin\Reports\Report
link_builder This is the class responsible for knowing what paths/URLs the type it's responsible for should generate. By default a type won't generate paths since it's not assumed that every entity is a standalone page. If you need your type to generate paths you may use Larasoft\Jam\Entities\LinkBuilder which will generate a single path based on the nesting of the current entity and update the paths of any descendant entities. For more complex entities that need to exist under more than 1 URL you can extend the LinkBuilder class and add your own path generation logic. The main path generated from the entity nest will be used as the canonical path for any additional paths.

Default Larasoft\Jam\Entities\LinksDisabled
menu_builder
Handles where to put the type in the admin menu. Types won't display in the menu until they have a template to base the entity on.
- Larasoft\Jam\Types\Menu\Hidden don't display in menu
- Larasoft\Jam\Types\Menu\Content display in content dropdown
- Larasoft\Jam\Types\Menu\Standalone display as a top level menu item
Default Larasoft\Jam\Types\Menu\Content
search_handler Jam has some basic support for Elastic Search built in but is disabled by default. See 4. Search Indexing.
entity There are a few different types of entity classes in Jam that dictate sorting options. The normal Larasoft\Jam\Entities\Entity isn't sortable and will be sorted by name. Larasoft\Jam\Entities\SortableEntity is manually sortable but alone will only allow sibling sorting. If nested sorting is required then it must be used in conjunction with the Larasoft\Jam\Types\NestedType type. Finally there's the Larasoft\Jam\Entities\Post entity that will sort the entities by date published.

Default Larasoft\Jam\Entities\Entity

2.2. Templates

Once you've got some types you need to give them some templates. A template dictates what data the entity has. Types can have as many templates as you like. To add a template log in to the admin, click on "Jam" then pick a type to edit.

When adding a template you must give it a name and view but the listing view and max_uses values are optional. The view field will be used in the default render method to pick what view to actually render. The implementation of listing_view is largely down to the requirements but its intention is that you could have multiple templates in a type that require different views in a listing. Once you've created a template the admin menu will acknowledge the type and display it in the the menu wherever the configured menu_builder dictates. max_uses allows you to limit the number of times a template may be used e.g. setting it to 1 will hide the option to create a new entity with that template after 1 is created.

2.3. Fields

A template is made up of a list of fields. Jam comes with the following field types:

Text
Standard singe line text input.
Textarea
Standard multiline text input with a checkbox option to make it a WYSIWYG HTML editor.
Image
Single media library field.
Gallery
Multiselect media library field.
Date
Date & Time
Toggle
Checkbox for toggling a boolean value.
Entity List
Allows creation of multiple child entities. Useful repeated content structures like slider slides, call out boxes, etc.
In order to use this field type you must first set up another entity type that this field can link to using the Larasoft\Jam\Types\EntityList type.
e.g.

`php <?php $mapper = $this->app['EntityMapper'];

$mapper->register([
```
  'callout-boxes' => new \Larasoft\Jam\Types\EntityList('Callout Boxes'),
```
]); `
Belongs To
Allows you to link one entity to another.

en in the create/edit form and all entities created will have the selected parent. Selecting only a type or template will give the user the option of selecting the parent entity from entities from the selected type/templates.

You may also select whether or not entities with this field become nested under the related entity as child pages.

NOTE: This should not be used with sortable entities that don't display in the same listing as resorting them can potentially lead to unexpected tree manipulation.
Belongs To Many
Provides the entity form with an option to select from many entities to relate to. As with Belongs To the options in the dropdown will be limited to the type and template selected when adding the field to the template.
Inverse Belongs To Many (read-only)
The reverse of the relationship defined in a Belongs To Many field, providing a read-only view to the related entities.
Hidden
Allows you to add a hidden field to the create/edit form of entities that will save the value entered when the field is created.

If you needed any functionality not listed above (eg. to define a relationship between an entity template and an app's custom model not stored in Jam) you may create any number of custom field types by extending the Larasoft\Jam\Fields\Field class and registering the field type in a service provider using the FieldMapper registered in the service container.

2.4. Entities

Generally you won't need more than the default functionality in the package and you shouldn't interact directly with the Entity class itself. See 2.4. Entities for info on how to use different entity classes and 3.2. EntityRepository for info on how to fetch entities.

2.5. Revisions

Every time you save an entity it will create a revision in the entity_revisions table and a new set of values. This allows you to track changes across entities or revert back to previous states.

3. Usage

3.1. Catchall Route

Jam doesn't have any frontend routes set up by default but it does have a controller that your app can point some routes at.

Generally you'll want to add a catchall route right at the end of your routes file which will handle most if not all of your entity routing. This will use the paths table to lookup the entity based on the request path and serve it up in the view its template has configured.

<?php
Route::get('{entityPath}', [
    'as' => 'entity',
    'uses' => '\Larasoft\Jam\Http\Controllers\EntityController@forPath'
])->where('entityPath', '(.+)?');

3.2. EntityRepository

Manual retrieval of entities should be done using the forType method on the Larasoft\Jam\Repositories\EntityRepository class. This will return a new query builder for the correct entity class registered to the type and limited to entities of that type.

3.3. Listings & Other Data

Some pages will require more data than just the entity so you will need to create a view composer for the current view. These should be added to app/Http/ViewComposers and registered in the boot method of a ComposerServiceProvider service provider.

3.4. Canonical Paths

Every entity with a link builder will have a canonical path which most of the time will be the path you'll want to use when linking to it from other pages/menus. When querying entities you should use the withCanonicalPath scope in order to eager load it or when working with a collection use the loadCanonicalPath method to lazy load it. Use $entity->canonical_path to output it.

3.5. Value Retrieval

Just querying the entities will only give you the data from the entities table, in order to load the values you must call the loadValues method on either a single or collection of entities. The method takes a list of fields to load or will load all fields if no arguments given.

e.g.

<?php
$pages = $entityRepository->forType('page')->get()->loadFields('content', 'image');

4. Search Indexing

Jam supports indexing entities via elastic search but each type needs to be set up with a search handler, see 2.1. Types. If all you need to be indexed is the name of the entity then you can just use the base Larasoft\Jam\Entities\Indexer class. In the likely event that you need more than that each type will need a handler written for it. When setting up a search handler class for an entity type it should extend the bas Indexer class and override the getPreviewData and getSearchableData methods.

The purpose of getPreviewData is to transform the entity in to a suitable format for your search results view and getSearchableData is for returning all the values you want to be searchable as one long string.