Skip to content

Commit fd53b58

Browse files
sethphillipssethphillips
committed
update readme
1 parent 73ff793 commit fd53b58

File tree

1 file changed

+149
-1
lines changed

1 file changed

+149
-1
lines changed

‎README.md‎

Lines changed: 149 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,149 @@
1-
This package is under development and will evolve. Documentation is soon to come so bear with us. Feel free to reach out to me directly in the meantime if you want to use the package and have questions.
1+
# PHP Package for the Carousel API
2+
This package is designed to be a fluent interface for Tightrope Media Systems' Carousel API. For more information on TRMS and the Carousel software please visit [www.trms.com](https://www.trms.com).
3+
4+
## Carousel API
5+
This package requires ownership of Carousel software version 7 or greater. General information about the Carousel API can be found on your carousel server at `your_carousel_server/carouselapi`.
6+
7+
## Package Installation
8+
This package should be installed with composer and requires PHP 7+
9+
```bash
10+
composer install trms/carousel
11+
```
12+
## Instructions
13+
[Basic Useage Examples](#basic-useage-examples)
14+
15+
## Servers and Requests
16+
[The Server Instance](#api)
17+
18+
[Model Requests](#modelrequest)
19+
20+
[File Upload Requests](#fileuploadrequest)
21+
## Models
22+
[Templates](#template)
23+
24+
[Bulletins](#bulletin)
25+
26+
[Groups](#group)
27+
28+
[Zones](#zone)
29+
30+
## Basic Useage Examples
31+
32+
### Creating a server instance
33+
Server methods that return more than one object will return a [collection](https://github.com/tightenco/collect), which can be treated like an array.
34+
```php
35+
use TRMS\Carousel\Server\API;
36+
37+
$server = new Server();
38+
$server->connect('http://my_carousel_server.com', 'username', 'password');
39+
```
40+
41+
### Requsting Carousel Resources
42+
All of the requests for Carousel resources are created by instantiating a `ModelRequest` with the appropriate `Model` class name and passing that to the server's `get` method. Passing an array of parameters to the `ModelRequest` is also important so that your query is limited to the items you want to get.
43+
44+
For example, to get a set of bulletins in a given zone:
45+
```php
46+
use TRMS\Carousel\Requests\ModelRequest;
47+
use TRMS\Carousel\Models\Bulletin;
48+
49+
$request = new ModelRequest(Bulletin::class, ['ZoneID'=>'5','IsDeleted'=>false]);
50+
$bulletins = $server->get($request);
51+
```
52+
53+
### Saving a Resource
54+
New or exisiting resources can be saved by passing them to the `save` method on a server instance.
55+
56+
```php
57+
use TRMS\Carousel\Models\BulletinTag;
58+
59+
$new_tag = new BulletinTag(['TagName'=>'My New Tag']);
60+
$server->save($new_tag);
61+
```
62+
63+
### Creating a Bulletin From A Template
64+
Usually you will be creating new bulletins from existing templates. More information on [Templates](#template) can be found below. Please note that **all bulletins must belong to a group** and this group must be created and related to the bulletin first when saving a newly created bulletin. More information on this can be found in the section on [Bulletins](#bulletin) below.
65+
```php
66+
use TRMS\Carousel\Requests\ModelRequest;
67+
use TRMS\Carousel\Models\Bulletin;
68+
use TRMS\Carousel\Models\Group;
69+
use TRMS\Carousel\Models\Template;
70+
71+
72+
$templates = $server->get(new ModelRequest(Template::class, ['ZoneID'=>'5','IsDeleted'=>false]));
73+
$template = $templates->first(); // the server returns a laravel collection.
74+
$bulletin = Bulletin::fromTemplate($templates->first());
75+
// here you would likely modify the bulletin's 'Blocks' to alter content
76+
$group = new Group(['ZoneID'=>'5']);
77+
$server->save($group);
78+
$bulletin->setGroup($group);
79+
$server->save($bulletin);
80+
```
81+
82+
### Creating Content from File Uploads
83+
You can create new Media and Bulletins by uploading a file to the Carousel Server. This is done by instantiating a `FileUploadRequest` with the appropriate `Model` class name and an array of parameters passed to the request. `ZoneID` is required. You will then add the files you wish to upload by chaining `addFile` methods and then pass the request to the server's `upload` method. This will return an array of models, one for each file that was added.
84+
```php
85+
use TRMS\Carousel\Request\FileUploadRequest;
86+
use TRMS\Carousel\Model\Media;
87+
88+
$request = new FileUploadRequest(Media::class, ['ZoneID'=>'5']);
89+
$request->addFile('/path/to/local/file.jpg')->addFile('http://path/to/remote/file');
90+
91+
$media = $server->upload($request);
92+
```
93+
94+
# Entities
95+
96+
## Servers and Requests
97+
### API
98+
`TRMS\Carousel\Server\API`
99+
### Methods
100+
|Method|Parameters|Returns|Description|
101+
|------|----------|-------|-----------|
102+
|connect|server origin, username, password|self - chainable|Connect to the server with a url and authentication information. be sure to include the scheme (ie:http://)|
103+
|whoAmI|none|User Object|Gets the currently connected user.|
104+
|get|ModelRequest|Model or Collection of Models|Get a specified resource or set of resources from the server|
105+
|save|Model|null|Save a model|
106+
|delete|Model|null|Delete a model. Note that most resources in Carousel are soft deleted on the server and the result will be the property `IsDeleted` will be set to true.|
107+
|upload|FileUploadRequest|Collection of Models|Upload a file or set of files to the server to create content with.|
108+
109+
110+
### ModelRequest
111+
`TRMS\Carousel\Requests\ModelRequest`
112+
### Methods
113+
|Method|Parameters|Returns|Description|
114+
|------|----------|-------|-----------|
115+
|constructor|Model ClassName, associative array|Request Object|Pass this the class name of the Model you would like to retrieve (ie: Bulletin::class) and an associative array of values to filter the request with. (ie: either [id=>'some_id_value'] or ['ZoneID'=>'5',IsDeleted=>false])|
116+
117+
### FileUploadRequest
118+
`TRMS\Carousel\Requests\FileUploadRequest`
119+
### Methods
120+
|Method|Parameters|Returns|Description|
121+
|------|----------|-------|-----------|
122+
|constructor|Model ClassName, associative array|Request Object|Pass this the class name of the Model you would like to retrieve (ie: Bulletin::class) and an associative array that determines the values to create the resource with. (ie: ['ZoneID'=>'5']) (currently only ZoneID is supported and its also required)|
123+
|addFile|string|self - chainable|The URL or filepath of the file to upload to the server|
124+
125+
## Models
126+
### Zone
127+
`TRMS\Carousel\Models\Zone`
128+
### Methods
129+
|Method|Parameters|Returns|Description|
130+
|------|----------|-------|-----------|
131+
|constructor|associative array|Zone Object|Constructor for the class, properties passed to it will be used to define the Zone.|
132+
|addTag|Tag Object|self - chainable|Add a Tag relationship to the model|
133+
|removeTag|Tag Object|self - chainable|Remove a Tag relationship from the model|
134+
135+
### Properties
136+
|Property|type|Description|
137+
|--------|----|-----------|
138+
|id|string|This is set by the server and not editable.|
139+
|ZoneName|string|The name of the Zone|
140+
|GraphicsWidth|integer|The width of the Zone in pixels|
141+
|GraphicsHeight|integer|The height of the Zone in pixels|
142+
|DaylightSavings|boolean|Is daylight savings time respected|
143+
|ZoneType|enumerable|The zone type: 'Bulletin','Crawl' or 'FullAlert'. More information can be found in Carousel Help|
144+
|Description|string|The description of the Zone.|
145+
|TimezoneID|string|The id of the timezone used by this Zone future updates may make this a model|
146+
|Tags|array |An Array of Tag Objects|
147+
|Pacing|float|A number from 0 to 1 that represents the relative pacing of bulletins when the system decides dwell time.|
148+
|ForceMonitorOn|boolean|Should the monitor be forced on during full screen alerts.|
149+
|ExcludedWords|string|A comma separated list of words that shouldnt be allowed to be shown in the Zone.|

0 commit comments

Comments
 (0)