Skip to content

Commit ff8f259

Browse files
sethphillipssethphillips
authored
Merge pull request #7 from trms/complete-docs-phase-1
complete docs for initial release
2 parents 28e6622 + 5009233 commit ff8f259

1 file changed

Lines changed: 218 additions & 16 deletions

File tree

‎README.md‎

Lines changed: 218 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -24,15 +24,23 @@ composer install trms/carousel
2424
[Model Requests](#modelrequest)
2525

2626
[File Upload Requests](#fileuploadrequest)
27+
28+
[Bulletin Order Requests](#bulletinorderrequest)
2729
## Models
2830
[Templates](#template)
2931

3032
[Bulletins](#bulletin)
3133

3234
[Groups](#group)
3335

36+
[Media](#media)
37+
3438
[Zones](#zone)
3539

40+
[Tags](#tags)
41+
42+
[Bulletin Sorting](#bulletin-sorting)
43+
3644
## Basic Useage Examples
3745

3846
### Creating a server instance
@@ -102,7 +110,9 @@ $media = $server->upload($request);
102110
## Servers and Requests
103111
### API
104112
`TRMS\Carousel\Server\API`
105-
### Methods
113+
114+
This represents the Carousel server itself
115+
#### Methods
106116
|Method|Parameters|Returns|Description|
107117
|------|----------|-------|-----------|
108118
|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://)|
@@ -115,41 +125,233 @@ $media = $server->upload($request);
115125

116126
### ModelRequest
117127
`TRMS\Carousel\Requests\ModelRequest`
118-
### Methods
128+
129+
Model requests are used to get models from the server.
130+
#### Methods
119131
|Method|Parameters|Returns|Description|
120132
|------|----------|-------|-----------|
121133
|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])|
122134

123135
### FileUploadRequest
124136
`TRMS\Carousel\Requests\FileUploadRequest`
125-
### Methods
137+
138+
File upload requests are used to post images video or audio to the server in order to create content with it either as Media assets or as Bulletins.
139+
#### Methods
126140
|Method|Parameters|Returns|Description|
127141
|------|----------|-------|-----------|
128142
|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)|
129143
|addFile|string|self - chainable|The URL or filepath of the file to upload to the server|
130144

145+
### BulletinOrderRequest
146+
`TRMS\Carousel\Requests\BulletinOrderRequest`
147+
148+
Bulletin order requests are used to get the Group/Bulletin order for a given Zone. A ZoneID is required as a parameter when creating the request. For more information see the section on [bulletin sorting](#bulletin-sorting) below.
149+
#### Methods
150+
|Method|Parameters|Returns|Description|
151+
|------|----------|-------|-----------|
152+
|constructor|associative array|Request Object|Pass this an associative array of values to filter the request with. (ie:['ZoneID'=>'5'])|
153+
131154
## Models
155+
156+
### Bulletin
157+
`TRMS\Carousel\Models\Bulletin`
158+
159+
A Bulletin is a piece of content displayed in Carousel. The closest analogy would be a slide in a power point deck.
160+
#### Methods
161+
|Method|Parameters|Returns|Description|
162+
|------|----------|-------|-----------|
163+
|constructor|associative array|Zone Object|Constructor for the class, properties passed to it will be used to define the Bulletin.|
164+
|fromTemplate (static)|Template Object|Bulletin Object|Create a new unsaved bulletin from a template.|
165+
|**Relationships**|
166+
|setBackground|Media Object|self - chainable|Sets the background Media to be used in this model.|
167+
|getBackground|none|Media Object|Gets the related background Media model.|
168+
|addBlock|Block Object|self - chainable|Add a Block relationship to the model.|
169+
|removeBlock|Block Object|self - chainable|Remove a Block relationship from the model.|
170+
|setGroup|Group Object|self - chainable|Sets the Group for this bulletin|
171+
|getGroup|none|Group Object|Gets the group for this bulletin|
172+
|addTag|Tag Object|self - chainable|Add a Tag relationship to the model.|
173+
|removeTag|Tag Object|self - chainable|Remove a Tag relationship from the model.|
174+
|setUser|User Object|self - chainable|Sets the User to be used in this model.|
175+
|getUser|none|User Object|Gets the related User model.|
176+
|**Scheduling**|
177+
|resetScheduled|none|self - chainable|Resets the `DateTimeOn` and `DateTimeOff` to today and `IsScheduled` to false.|
178+
|setSchedule|DateTime, DateTime|self - chainable|Sets the `DateTimeOn` and `DateTimeOff` properties|
179+
|setDateTimeOn|DateTime|self - chainable|Sets the `DateTimeOn` property.|
180+
|setDateTimeOff|DateTime|self - chainable|Sets the `DateTimeOff` property.|
181+
|resetCycleTimes|none|self - chainable|Resets the `CycleTimeOn` and `CycleTimeOff` to be 'on all day'.|
182+
|setCycleTimes|DateTime, DateTime|self - chainable|Sets the `CycleTimeOn` and `CycleTimeOff` propterties.|
183+
|setCycleTimeOn|DateTime|self - chainable|Sets the `CycleTimeOn` property.|
184+
|setCycleTimeOff|DateTime|self - chainable|Sets the `CycleTimeOff` property.|
185+
|setDaysOnAll|boolean (default true)|self - chainable|Sets display property for all days.|
186+
|setDaysOnWeekend|boolean (default true)|self - chainable|Sets display property for weekends.|
187+
|setDaysOnWeekdays|boolean (default true)|self - chainable|Sets display property for weekdays.|
188+
|setDaysOn{Dayname}|boolean (default true)|self - chainable|Sets display property for a single day of the week (ie: `setDaysOnSaturday()`).|
189+
#### Properties
190+
|Property|type|Description|
191+
|--------|----|-----------|
192+
|id|string|This is set by the server and not editable.|
193+
|Blocks|array|An array of Block objects|
194+
|Description|string|The description of the Bulletin|
195+
|DwellTime|int|How long the bulletin displays each rotation.|
196+
|UseSystemDwellTime|boolean|Should the system decide how long this bulletin displays each rotation, if false use the defined dwell time.|
197+
|IsAlert|boolean|Is this Bulletin an alert bulletin? Alerts will override any non-alert content in a zone.|
198+
|IsDeleted|boolean|Soft deletion property, soft deleted bulletins will be cleaned up and permenantly deleted after a time.|
199+
|IsScheduled|boolean|Does this bulletin respect the DateTimeOn and DateTimeOff values|
200+
|DateTimeIOn|string|The date and time the bulletin will begin playing. (there are helper methods for setting this value)|
201+
|DateTimeIOff|string|The date and time the bulletin will stop playing. (there are helper methods for setting this value)|
202+
|CycleTimeIOn|string|The time the bulletin will begin playing each day it is scheduled Only the time portion of this is used by the server. (there are helper methods for setting this value)|
203+
|CycleTimeIOn|string|The time the bulletin will begin playing each day it is scheduled Only the time portion of this is used by the server. (there are helper methods for setting this value)|
204+
|WeekdayOnOff|int|A bitfield representation of the days of the week that this bulletin will play during its schedule. (there are helper methods for setting this value)|
205+
|WeekdayOnOffDescription|string (read only)|A human readable representation of the WeekdayOnOff value.|
206+
|IsRepeating|boolean|Does this bulletin repeat playback every Nth bulletin.|
207+
|RepeatInterval|int|How often a repeating bulletin repeats.|
208+
|LastUpdate|string|Date and time of the last rendering of this bulletin.|
209+
|LastError|string|The last error encountered when rendering this bulletin|
210+
|PartialBulletin|boolean (read only)|Getting bulletins from the server via any query other than `id` will result in a partial bulletin. Partial bulletins do not contain Blocks and are not saveable entities.|
211+
|Status|enumerable (read only)|One of the following values: Current, Queued, Hold, Old, Saved, Current-Null (no dynamic content), Current-Error|
212+
|Tags|array |An Array of Tag Objects|
213+
|TrackImpressions|boolean|Should the service track each time this bulletin is played on a player|
214+
|ImpressionCount|int|The number of times a tracked bulletin has played on a player|
215+
|Type|enumerable|The type of bulletin, Bulletins created from templates are `Standard`. There are several dynamic Bulletin types that all have their own set of properties related to the dynamic content. (future updates may outline these better)|
216+
|PreviewImageUrl|string|A low resolution rendering of the template|
217+
|FullImageUrl|string|A full resolution rendering of the template|
218+
219+
### Template
220+
`TRMS\Carousel\Models\Template`
221+
222+
A template is the starting point for a standard Bulletin and is comprised of a background image and a series of content Blocks.
223+
#### Methods
224+
|Method|Parameters|Returns|Description|
225+
|------|----------|-------|-----------|
226+
|constructor|associative array|Zone Object|Constructor for the class, properties passed to it will be used to define the Template.|
227+
|setBackground|Media Object|self - chainable|Sets the background Media to be used in this model|
228+
|getBackground|none|Media Object|Gets the related background Media model|
229+
|addBlock|Block Object|self - chainable|Add a Block relationship to the model|
230+
|removeBlock|Block Object|self - chainable|Remove a Block relationship from the model|
231+
|setUser|User Object|self - chainable|Sets the User to be used in this model|
232+
|getUser|none|User Object|Gets the related User model|
233+
|setZone|Zone Object|self - chainable|Sets the Zone to be used in this model|
234+
|getZone|none|Zone Object|Gets the related Zone model|
235+
#### Properties
236+
|Property|type|Description|
237+
|--------|----|-----------|
238+
|id|string|This is set by the server and not editable.|
239+
|Name|string|The name of the template|
240+
|Tags|array |An Array of Tag Objects|
241+
|IsPublic|boolean|Is this template viewable by all users in the Carousel UI|
242+
|Blocks|array|An array of Block objects|
243+
|PreviewImageUrl|string|A low resolution rendering of the template|
244+
|FullImageUrl|string|A full resolution rendering of the template|
245+
246+
### Group
247+
`TRMS\Carousel\Models\Group`
248+
249+
A group is a container for Bulletins that allows for easier viewing sorting and ordering. Of important note is that every Bulletin is contained in a Group and must have a saved Group assigned before saving.
250+
(full support of editing groups is a work in progress for this package.)
251+
#### Methods
252+
|Method|Parameters|Returns|Description|
253+
|------|----------|-------|-----------|
254+
|constructor|associative array|Group Object|Constructor for the class, properties passed to it will be used to define the Group.|
255+
|setZone|Zone Object|self - chainable|Sets the Zone to be used in this model|
256+
|getZone|none|Zone Object|Gets the related Zone model|
257+
258+
#### Properties
259+
|Property|type|Description|
260+
|--------|----|-----------|
261+
|id|string|This is set by the server and not editable.|
262+
|Description|string|The name of the Group|
263+
|Bulletins|array|An array of Bulletin Objects|
264+
265+
### Media
266+
`TRMS\Carousel\Models\Media`
267+
268+
Media represents audio, video images and backgrounds to be used in Bulletins and Templates. This content is Zone specific for Carousel UI users. When uploading backgrounds the media type must be specified or the system will assume that it is an image. Backgrounds should also be sized for the Zone they are intended for to avoid distorting the image. Video content should be mp4.
269+
#### Methods
270+
|Method|Parameters|Returns|Description|
271+
|------|----------|-------|-----------|
272+
|constructor|associative array|Media Object|Constructor for the class, properties passed to it will be used to define the Media.|
273+
|setUser|User Object|self - chainable|Sets the User to be used in this model|
274+
|getUser|none|User Object|Gets the related User model|
275+
|addTag|Tag Object|self - chainable|Add a Tag relationship to the model.|
276+
|removeTag|Tag Object|self - chainable|Remove a Tag relationship from the model.|
277+
|setZone|Zone Object|self - chainable|Sets the Zone to be used in this model|
278+
|getZone|none|Zone Object|Gets the related Zone model|
279+
#### Properties
280+
|Property|type|Description|
281+
|--------|----|-----------|
282+
|id|string|This is set by the server and not editable.|
283+
|Name|string|The name of the Media|
284+
|Type|enumerable|The type of media it is: `Background`,`Picture`,`Sound`,`Video`|
285+
|Tags|array |An Array of Tag Objects|
286+
|IsDeleted|boolean|Soft deletion property, soft deleted media will remain on the system until no Bulletins or Templates use it.|
287+
|IsPublic|boolean|Is this media viewable by all users in the Carousel UI|
288+
|PreviewImageUrl|string|A low resolution rendering of the Media. For video and audio this is simply an icon.|
289+
|FullUrl|string|The url of the asset|
290+
132291
### Zone
133292
`TRMS\Carousel\Models\Zone`
134-
### Methods
293+
294+
A Zone is an area of real estate on screen where bulletins are displayed. The screen (Channel) can be comprised of one or more Zones.
295+
#### Methods
135296
|Method|Parameters|Returns|Description|
136297
|------|----------|-------|-----------|
137298
|constructor|associative array|Zone Object|Constructor for the class, properties passed to it will be used to define the Zone.|
138-
|addTag|Tag Object|self - chainable|Add a Tag relationship to the model|
139-
|removeTag|Tag Object|self - chainable|Remove a Tag relationship from the model|
140-
141-
### Properties
299+
|addTag|ZoneTag Object|self - chainable|Add a Tag relationship to the model|
300+
|removeTag|ZoneTag Object|self - chainable|Remove a Tag relationship from the model|
301+
#### Properties
142302
|Property|type|Description|
143303
|--------|----|-----------|
144304
|id|string|This is set by the server and not editable.|
145-
|ZoneName|string|The name of the Zone|
146-
|GraphicsWidth|integer|The width of the Zone in pixels|
147-
|GraphicsHeight|integer|The height of the Zone in pixels|
305+
|AlertsActive|boolean (read only)|Are there active alerts in this zone.|
148306
|DaylightSavings|boolean|Is daylight savings time respected|
149-
|ZoneType|enumerable|The zone type: 'Bulletin','Crawl' or 'FullAlert'. More information can be found in Carousel Help|
307+
|DefaultTransition|string|the id of the default transition used in this zone (future updates may make this a model relationship)|
150308
|Description|string|The description of the Zone.|
151-
|TimezoneID|string|The id of the timezone used by this Zone future updates may make this a model|
152-
|Tags|array |An Array of Tag Objects|
153-
|Pacing|float|A number from 0 to 1 that represents the relative pacing of bulletins when the system decides dwell time.|
154-
|ForceMonitorOn|boolean|Should the monitor be forced on during full screen alerts.|
155309
|ExcludedWords|string|A comma separated list of words that shouldnt be allowed to be shown in the Zone.|
310+
|ForceMonitorOn|boolean|Should the monitor be forced on during full screen alerts.|
311+
|GraphicsHeight|integer|The height of the Zone in pixels|
312+
|GraphicsWidth|integer|The width of the Zone in pixels|
313+
|Pacing|float|A number from 0 to 1 that represents the relative pacing of bulletins when the system decides dwell time.|
314+
|Tags|array|An array of ZoneTag objects|
315+
|TimezoneID|string|The id of the timezone used by this Zone (future updates may make this a model relationship)|
316+
|ZoneName|string|The name of the Zone|
317+
|ZoneType|enumerable|The zone type: 'Bulletin','Crawl' or 'FullAlert'. More information can be found in Carousel Help|
318+
319+
## Tags
320+
Tags are metadata that can be added to the associated model. They are used for searching and sorting content in Carousel.
321+
### BulletinTag
322+
`TRMS\Carousel\Models\BulletinTag`
323+
### MediaTag
324+
`TRMS\Carousel\Models\MediaTag`
325+
### ZoneTag
326+
`TRMS\Carousel\Models\ZoneTag`
327+
#### Methods
328+
|Method|Parameters|Returns|Description|
329+
|------|----------|-------|-----------|
330+
|constructor|associative array|BulletinTag Object|Constructor for the class, properties passed to it will be used to define the Tag.|
331+
#### Properties
332+
|Property|type|Description|
333+
|--------|----|-----------|
334+
|id|string|This is set by the server and not editable.|
335+
|TagName|string|The text of the tag|
336+
337+
## Bulletin Sorting
338+
These objects are used for ordering the Bulletins in a Zone.
339+
### BulletinOrder
340+
`TRMS\Carousel\Models\BulletinOrder`
341+
342+
This represents the order of the Groups in a Zone. Each BulletinOrderEntry represents a Group. The order of the `OrderEntries` array will be the order of the Groups in the Zone.
343+
#### Properties
344+
|Property|type|Description|
345+
|--------|----|-----------|
346+
|id|string|This is set by the server and not editable.|
347+
|OrderEntries|array|An ordered array of BulletinOrderEntry objects. Their order represents the order of Groups in a Zone.|
348+
349+
### BulletinOrderEntry
350+
`TRMS\Carousel\Models\BulletinOrderEntry`
351+
352+
This represents a Group and the order of its Bulletins. The order of the `Bulletins` array will be the order of the Bulletins in the Group.
353+
#### Properties
354+
|Property|type|Description|
355+
|--------|----|-----------|
356+
|id|string|This is set by the server and not editable.|
357+
|Bulletins|array|An ordered array of Bulletin ids. Their order represents the order of Bulletins in the Group.|

0 commit comments

Comments
 (0)