-
Notifications
You must be signed in to change notification settings - Fork 3
/
Copy pathindex.html
751 lines (557 loc) · 41 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1" />
<title>eZ Exceed guide</title>
<link type="text/css" rel="stylesheet" href="assets/css/01-bootstrap.min.css" />
<link type="text/css" rel="stylesheet" href="assets/css/02-bootstrap-responsive.min.css" />
<link type="text/css" rel="stylesheet" href="assets/css/03-prism.css" />
<link type="text/css" rel="stylesheet" href="assets/css/04-screen.css" />
<link rel="icon" href="assets/gfx/favicon.png" type="image/png" />
<link rel="shortcut icon" href="assets/gfx/favicon.png" type="image/png" />
</head>
<body>
<div id="ezexceed-docs" class="container">
<div class="row">
<div class="toc span3">
<div class="well">
<h2>Ezexceed</h2>
<ul>
<li><a href="#license">License</a>
</li>
<li><a href="#download">Download</a>
</li>
</ul>
<h2>Installing</h2>
<ul>
<li><a href="#installing-common">Common</a>
</li>
<li><a href="#installing-upgrading">Upgrading</a>
</li>
</ul>
<h2>Site-configuration</h2>
<ul>
<li><a href="#site-configuration-content-types">ContentTypes</a>
</li>
<li><a href="#site-configuration-field-definition-setup">FieldDefinition setup</a>
</li>
<li><a href="#site-configuration-text-editor">Text editor</a>
</li>
<li><a href="#site-configuration-preview-url">Shareable preview URLs</a>
</li>
<li><a href="#site-configuration-push-notifications">Push notifications for the eZ Exceed iOS app</a>
</li>
<li><a href="#site-configuration-ezflow-pencil">eZ Flow pencil</a>
</li>
<li><a href="#site-configuration-ezflow-timeline">eZ Flow Timeline</a>
</li>
</ul>
<h2>Disclaimers</h2>
<ul>
<li><a href="#disclaimers-supported-web-browsers">Supported web browsers</a>
</li>
<li><a href="#disclaimers-extensions">Extensions</a>
</li>
</ul>
<h2>Important-concepts</h2>
<ul>
<li><a href="#important-concepts-core-principles">Core principles</a>
</li>
<li><a href="#important-concepts-the stack">The Stack</a>
</li>
</ul>
<h2>Extensibility</h2>
<ul>
<li><a href="#extensibility-building-a-datatype">Building a FieldType for eZ Exceed</a>
</li>
<li><a href="#extensibility-creating-an-app">Creating an app</a>
</li>
<li><a href="#extensibility-apis">APIs</a>
</li>
<li><a href="#extensibility-api-stack">Stack</a>
</li>
<li><a href="#extensibility-api-shared">Shared classes</a>
</li>
</ul>
<h2>Contributing</h2>
<ul>
<li><a href="#contributing-submitting-an-issue">Submitting an issue</a>
</li>
<li><a href="#contributing-translations">Translations</a>
</li>
<li><a href="#contributing-patches">Patches</a>
</li>
<li><a href="#contributing-technologies">Technologies</a>
</li>
<li><a href="#contributing-coding-standard">Coding standard</a>
</li>
</ul>
<h2>Faq</h2>
<ul>
<li><a href="#frequently-asked-questions-editors">Editors</a>
</li>
<li><a href="#frequently-asked-questions-developers">Developers</a>
</li>
</ul>
</div>
</div>
<div class="content span9 offset3">
<h1>eZ Exceed</h1>
<p>– A fresh and modern CMS interface built on top of eZ Publish</p>
<h2><a id="license" href="#license"></a> License</h2>
<h2><a id="download" href="#download"></a> Download</h2>
<p><a href="https://github.com/KeyteqLabs/ezexceed" title="eZ Exceed at GitHub">Download from GitHub</a>
</p>
<h1>Installing the eZ Exceed extension</h1>
<h2><a id="installing-common" href="#installing-common"></a> Common</h2>
<ol>
<li>
<p>Ensure dependencies are met:</p>
<ul>
<li>eZ Publish version <strong>4.7</strong> or higher
<ul>
<li>4.6 <em>might</em> work, but it's not a target</li>
<li>We are working on proper support for eZ Publish 5</li>
</ul>
</li>
<li><a href="http://projects.ez.no/ezjscore" title="ezjscore at eZ Projects">ezjscore</a> <strong>1.3.0</strong> or higher</li>
<li><a href="https://github.com/ezsystems/ezwt" title="ezwt at GitHub">ezwt</a> <strong>1.4.0</strong> or higher</li>
<li>Apache version <strong>1.3</strong> or <strong>2.x</strong> in <strong>prefork</strong> mode</li>
<li>PHP version <strong>5.3</strong> or higher, 5.4 is recommended</li>
<li>Database server: MySQL <strong>5</strong> (UTF-8 is required)</li>
</ul>
</li>
<li>
<p>Install extension into <code>/my/ez/extension/ezexceed</code>
</p>
<pre><code class="lang-bash"> cd /my/ez/extension
git clone [email protected]:KeyteqLabs/ezexceed.git
cd ezexceed</code></pre>
<p>eZ Exceed is currently only available as an <em>extension</em>. If you are running on eZ Publish 5, you have to enable legacy mode and install the eZ Exceed extension in your <code>/ezpublish_legacy/extension/</code> folder.</p>
</li>
<li>
<p>Run the included SQL script to add eZ Exceed specifics to your database</p>
<pre><code class="lang-bash"> mysql -h host -u user -D my-database-name -p < sql/mysql/schema.sql</code></pre>
</li>
<li>
<p>Activate the eZ Exceed extension along with its SiteDesign in every siteaccess where you want eZ Exceed enabled. In <code>siteaccess/yourdesign/site.ini.append.php</code>:</p>
<pre><code class="lang-ini"> # Activates the extension itself:
[ExtensionSettings]
ActiveAccessExtensions[]=ezexceed
# Activate eZ Exceed's design; toolbars and overlays:
[DesignSettings]
AdditionalSiteDesignList[]=ezexceed</code></pre>
</li>
<li>
<p>Clear your caches and refresh!</p>
</li>
</ol>
<h2><a id="installing-upgrading" href="#installing-upgrading"></a> Upgrading</h2>
<p>You can safely upgrade your installation without experiencing any breaking changes inside of major versions. So going from 2.0 to 2.1 should just work. There might be breaking changes introduced when going from a 2.x to a 3.x version.</p>
<h3>Running from git</h3>
<p>If you are using eZ Exceed directly from git you will notice that every version is tagged using <a href="http://semver.org/">semver</a>. You can upgrade to the latest stable release by simply pulling the latest <code>master</code>
</p>
<pre><code class="lang-bash">git checkout master
git pull</code></pre>
<p>Upgrading to a specific version i.e. v2.0.0-rc.1 to v2.0.0-rc.3 can be done by checking out a specific tag</p>
<pre><code class="lang-bash">git fetch origin master
git checkout v2.0.0-rc.3</code></pre>
<h1>Site configuration</h1>
<h2><a id="site-configuration-content-types" href="#site-configuration-content-types"></a> ContentTypes</h2>
<h3>Clean up</h3>
<p>Only keep the ContentTypes relevant for your site. Either move the ones you don't use out of the ContentTypeGroup <em>Content</em>, or delete them altogether. Less complexity gives better usability and thus faster editing.</p>
<h3>Separate technical and editable ContentTypes</h3>
<p>Put content you want the editor to be able to edit inside the ContentTypeGroup <em>Content</em> – it will then get a more prominent place in the design. Put ContentTypes that are used in a technical manner, for settings or otherwise, inside a ContentTypeGroup
of its own to hide it. This makes for a clearer interface for the editor.</p>
<h3>ContentType icons</h3>
<p>In order to make it even easier to identify the different ContentTypes and tell them apart, assign unique icons to them. Unique icons for each ContentType makes for a much clearer interface, and editors will be more efficient if you set an icon, so please
do.</p>
<p>Create or edit the global <code>override/icon.ini.append.php</code>:</p>
<pre><code class="lang-ini">[ClassIcons]
ClassMap[recipe]=Food.png
ClassMap[cookbook]=Book.png
ClassMap[pin]=Pushpin.png</code></pre>
<!-- [Full overview of the available icons](src/03/01-icons-available.md). -->
<h2><a id="site-configuration-field-definition-setup" href="#site-configuration-field-definition-setup"></a> FieldDefinition setup</h2>
<h3>Naming</h3>
<p>Take care in naming FieldDefinitions, descriptions and states. Make it crystal clear and easy to understand. This makes up a good part of the experience – make it great.</p>
<h3>Righty tighty</h3>
<p>In order to make the Content edit layout tighter and more user friendly, consider editing <code>contenteditor.ini.append.php</code> inside the eZ Exceed extension to make many or most of the FieldDefinitions use only half of the available width and thus
render side by side other less space consuming FieldDefinitions:</p>
<pre><code class="lang-ini">[ByType]
fieldid=half
# or
[ByClassIdentifier]
contentclass[fieldname]=half</code></pre>
<h3>Order of FieldDefinitions</h3>
<p>Make the attributes order follow the order it displays on the page. E.g a footer text FieldDefinition should reside at the bottom of the edit area, if it sits at the bottom of the page. This is called 'cognitive mapping' and makes it easy for
the editor to relate to the Content she's editing.</p>
<h3>Make use of FieldDefinitionGroups</h3>
<p>Group FieldDefinitions (e.g meta information) enabling the editor to open or close a group of FieldDefinitions. Another example for grouping is global attributes, e.g footer information, or other static information. You can create FieldDefinitionGroups
in <code>override/content.ini.append.php</code>:</p>
<pre><code class="lang-ini">[ClassAttributeSettings]
CategoryList[footer]=Footer fields</code></pre>
<h2><a id="site-configuration-text-editor" href="#site-configuration-text-editor"></a> Text editor</h2>
<h3>eZ Exceed improved link</h3>
<p>eZ Exceed provides a better way to link to <em>Locations</em> – not only <em>Contents</em>. This is an editor plugin, and needs to be activated in the override settings, in <code>override/ezoe.ini.append.php</code>. Remember to add the button to all the
editor layouts where you want it available:</p>
<pre><code class="lang-ini">[EditorSettings]
Plugins[]=ezexceedlink
[EditorLayout]
Buttons[]=ezexceedlink
[EditorLayout_minimal]
Buttons[]=ezexceedlink</code></pre>
<p>If configured correctly, the button will show up and look something like this:</p>
<p>
<img src="assets/img/02-improved-link.png" alt="eZ Exceed improved link">
</p>
<h2><a id="site-configuration-preview-url" href="#site-configuration-preview-url"></a> Shareable preview URLs</h2>
<p>In order to make it possible for anyone to preview a user's draft, the desired groups of users must be granted access to eZ Exceed's preview module, <code>ezexceed/preview</code>.</p>
<p>You also need some settings; create or edit <code>override/ezexceed.ini.append.php</code>:</p>
<pre><code class="lang-ini">[eZExceedPushNotification]
SignKey=<yoursignkey></code></pre>
<p>Pushing the toolbar's Preview button will now yield a shareable URL you can share with whomever you want, and it will look something like this:</p>
<p>
<img src="assets/img/03-shareable-preview-url.png" alt="Shareable preview URL">
</p>
<p><a href="mailto:[email protected]" title="Send email to [email protected]">Contact Keyteq</a> to obtain your SignKey.</p>
<h2><a id="site-configuration-push-notifications" href="#site-configuration-push-notifications"></a> Push notifications for <a href="https://itunes.apple.com/app/id567405821" title="Exceed at iTunes App Store">the eZ Exceed iOS app</a></h2>
<p>To be able to send Push Notifications to the users' iOS devices, you need both an ID and a SignKey. <a href="mailto:[email protected]" title="Send email to [email protected]">Contact Keyteq</a> to obtain this info.</p>
<p>Create or edit <code>override/ezexceed.ini.append.php</code> in the level that suit your needs best – override or siteaccess. Add the following block:</p>
<pre><code class="lang-ini">[eZExceedPushNotification]
SignKey=<yoursignkey>
ID=<yourid></code></pre>
<h2><a id="site-configuration-ezflow-pencil" href="#ite-configuration-ezflow-pencil"></a> eZ Flow pencil</h2>
<p>With eZ Exceed, you can have pencils right where your content is. This is also true for eZ Flow blocks. For the pencils to be added for each block, you have to do some minor modifications to your zone templates;</p>
<h3>eZ Publish 4.x</h3>
<pre><code class="lang-smarty">...
{if $zone.blocks|count()|gt(0)}
{foreach $zone.blocks as $block}
...
{if or($validblocks, $blockshascontent, and($manualaddingdisabled, $notfetching))}
{include uri='design:parts/zone_block_top.tpl'}
{block_view_gui block=$block node=$node pathids=$pathids view_parameters=$view_parameters}
{include uri='design:parts/zone_block_bottom.tpl'}
{else}
{skip}
{/if}
{/foreach}
{/if}</code></pre>
<h3>eZ Publish 5.x</h3>
<p>This requires that you activate the <a href="https://github.com/KeyteqLabs/eZExceedBundle">eZExceedBundle</a>.</p>
<pre><code class="lang-twig">{% for zone in zones %}
{% if zone.blocks %}
{% for block in zone.blocks %}
{{ pencil(block) }}
{{ render(controller('ez_page:viewBlock', { 'block': block } )) }}
{% endfor %}
{% endif %}
{% endfor %}</code></pre>
<h2><a id="site-configuration-ezflow-timeline" href="site-configuration-ezflow-timeline"></a> eZ Flow Timeline</h2>
<p>For updating of the ezflow blocks using the Preview -> Timeline tool, you need to wrap your rendered block like this:</p>
<pre><code class="lang-html"><div id="address-{{block.zoneId}}-{{block.id}}">
{{ render(controller('ez_page:viewBlock', { 'block': block } )) }}
</div></code></pre>
<p>This makes it possible for eZ Exceed to determine what part of the DOM to update. Using the #address- prefixed id is required for eZ Exceed 2.0.x.</p>
<h1>Disclaimers</h1>
<h2><a id="disclaimers-supported-web-browsers" href="#disclaimers-supported-web-browsers"></a> Supported web browsers</h2>
<ul>
<li>Latest Google Chrome</li>
<li>Latest Mozilla Firefox</li>
<li>Internet Explorer 8 or higher</li>
<li>Apple Safari 5 or higher</li>
</ul>
<p>Make sure that JavaScript support is enabled in your web browser.</p>
<p>Note: IE 8 & 9 are only supported functionally; issues that only cause visual artifacts will not be prioritized unless they're easy to fix and does not limit the capabilities of modern browsers.</p>
<hr>
<p>Keeping your install outside of root (<code>/</code>) can cause errors inside the eZ Online Editor (<code>ezoe</code>).</p>
<h2><a id="disclaimers-extensions" href="#disclaimers-extensions"></a> Extensions</h2>
<h3>eZ Tags</h3>
<p>You do not have to disable the extension, but we do not support editing of the eZ Tags Field yet.</p>
<h3>eZ Form token</h3>
<p>If you're running eZ Publish 5, deactivate your eZ Form token legacy extension and disable the form token in ez Publish 5.</p>
<h3>eZ Demo design</h3>
<p>If the eZ Demo design has higher priority than the eZ Exceed design it will overwrite, and break, the datetime FieldType.</p>
<h1>Important concepts</h1>
<p>There are a few important concepts in eZ Exceed you need to grasp in order to use it, implement for it and customize it.</p>
<h2><a id="important-concepts-core-principles" href="#important-concepts-core-principles"></a> Core principles</h2>
<ul>
<li>Touch first</li>
<li>Stay in context</li>
<li>Forward-leaning</li>
</ul>
<h2><a id="important-concepts-the stack" href="#important-concepts-the-stack"></a> The Stack</h2>
<p>The main interaction pattern in eZ Exceed is the stack:</p>
<p>
<img src="assets/img/01-stack.png" alt="The Stack">
</p>
<p>The stack allows editors to work with layered content without leaving the initial context. As the example screenshot shows the stack has a context path with <code>Sitemap -> Object edit -> Add location</code> and it makes it easy to see this <em>breadcrumb</em> as
well as jump in it.</p>
<p>The uniqueness of the stack is that everything you try to do in eZ Exceed simply opens a new level in the stack, meaning you never leave the page and have to juggle multiple tabs to keep sane.</p>
<p>When an editor clicks an action inside eZ Exceed it <strong>pushes</strong> a stack level with some UI, and when the editor is done using that stack level a context is passed back to the overarching stack level — the initiator — with enough data to store
the users interaction. For example clicking <em>Add location</em> pushes a <em>Sitemap</em> UI and it returns one, or several <code>locationId</code>s.</p>
<h1>Extensibility</h1>
<h2><a id="extensibility-building-a-datatype" href="#extensibility-building-a-datatype"></a> Building a FieldType for eZ Exceed</h2>
<p>Building FieldTypes that supports the eZ Exceed interface can require a custom design implementation for eZ Exceed. If your interface only requires basic controls like <code>input</code> fields this is supported out of the box, but if you have custom interaction
in your FieldType you are required to implement this in a custom <code>ezexceed</code> design.</p>
<h3>Boilerplate markup</h3>
<p>First you need to map your JavaScript namespace for AMD modules in <code>ezexceed.ini.append.php</code> like this:</p>
<pre><code class="lang-ini">[AMD]
NS[myextension]=/extension/myextension/design/ezexceed/src</code></pre>
<p>In your <code>content/datatype/edit/mytype.tpl</code> you can wrap your code in a <code><div></code> like this in order to instruct eZ Exceed to load a JavaScript module:</p>
<pre><code class="lang-markup"><div class="attribute-base"
data-handler='myextension/main'
data-url-root='{"/"|ezurl("no")}'>
<!-- My attributes markup -->
</div></code></pre>
<p>The previous code basically instructs <em>eZ Exceed</em> to load a JavaScript module named <code>mytype/main.js</code> using <strong>Require.js</strong>. We will get to how you need to implement this JavaScript module in a second.</p>
<h3>Boilerplate JavaScipt</h3>
<p>We build JavaScript modules for eZ Exceed using <strong>Backbone.js</strong> and your <strong>handler</strong> needs to extend/quack like the module <code>edit/datatypes/base</code>:</p>
<pre><code class="lang-javascript">define(['shared/datatype'], function(Datatype)
{
return Datatype.extend({
render: function() { return this; },
parseEdited: function() { return []; }
});
});</code></pre>
<p>See its <a href="#extensibility-api-shared">API-documentation</a>
</p>
<h2><a id="extensibility-creating-an-app" href="#extensibility-creating-an-app"></a> Creating an app</h2>
<p>It is possible to create custom <strong>apps</strong> that will reside in the toolbar. This can range from a simple app that loads some content into the stack, to complete JavaScript applications running in eZ Exceed. This section will quickly walk you
through building simple applications.</p>
<h3>Configuring the application</h3>
<p>All configuration happens through overriding <code>ezexceed.ini</code> on a pr app/button level. This example will render a popover once clicked, this popover will contain an iframe including our twitter widget. You can see this code in the <a href="https://github.com/KeyteqLabs/ezexceed-examples">ezexceed-examples</a> repository.</p>
<pre><code class="lang-ini">[Toolbar]
Buttons[]=twitter
[Toolbar_twitter]
Name=Tweets
Icon=Share
URL=/extension/ezexceed-examples/design/ezexceed/lib/twitter/widget.html
Type=popover</code></pre>
<p>Lets look at the configuration keys:</p>
<ul>
<li><code>Name</code> This is the name that will be used in the toolbar as well as the popover/stack heading</li>
<li><code>Icon</code> Refers to the file name of a Helveticon. This Icon will be used in the toolbar + in the stack</li>
<li><code>URL</code> Any URL that will work and serve up content to an iframe will work here. Static html, ez modules or external services.</li>
<li><code>Type</code> You can choose between <em>stack</em> and <em>popover</em> depending on how much space your content requires.</li>
<li><code>Module</code> Optional key that allows you to specify an AMD JS module that will be loaded and used. This requires more work on your part while also offers full flexibility.</li>
</ul>
<h3>Configuring an advanced application</h3>
<pre><code class="lang-ini">[AMD]
NS[ezexceed-examples]=/extension/ezexceed-examples/design/ezexceed/src
[Toolbar]
Buttons[]=clouds
[Toolbar_clouds]
Name=Clouds
Icon=Cloud
Module=ezexceed-examples/clouds</code></pre>
<h3>Writing a basic JavaScript module</h3>
<p>eZ Exceed JavaScript modules are really just <a href="https://github.com/amdjs/amdjs-api/wiki/AMD">AMD modules</a> loaded by <a href="http://requirejs.org">Require.js</a>. The gist of it is that the <code>ezexceed-examples/clouds</code> module will be resolved
to <code>/extension/ezexceed-examples/design/ezexceed-examples/javascript/clouds.js</code>, and this file is in turn supposed to serve up a valid Module by using the <code>define()</code> function, like this:</p>
<pre><code class="lang-javascript">define(['backbone', 'jquery-safe'], function(Backbone, $)
{
return Backbone.View.extend({
render: function()
{
this.$el.html('Hello world');
return this;
}
});
});</code></pre>
<p>As you can see, the module takes a set of dependencies and in the callback it simply returns a <code>Backbone.View</code> <em>class</em> that eZ Exceed in due time will render into the configured container (stack/popover). You should check out the <a href="http://backbonejs.org">Backbone.js documentation</a> for
more information on Backbone, most things you want will be specifics to Backbone. Read on to get to what sort of APIs eZ Exceed itself provides to make your life simpler.</p>
<h2><a id="extensibility-apis" href="#extensibility-apis"></a> APIs</h2>
<p>These are the openly shared APIs you can use in your application</p>
<h3><a id="extensibility-api-stack" href="#extensibility-api-stack"></a> Stack</h3>
<h4>push(<code>view</code>, <code>options</code>, <code>context</code>)</h4>
<p>Push a view constructor that will be rendered as a new stack item.</p>
<pre><code class="lang-javascript">var options = {
render: true
};
var context = {
heading: 'My Stack item',
icon: 'Cloud'
};
eZExceed.stack.push(Backbone.View, options, context);</code></pre>
<p>The <strong>options</strong> argument will be passed as the options object to Backbone.View. Notice that the following values are overriden:</p>
<ul>
<li><code>el</code> This will be the stack item your view can fill</li>
<li><code>heading</code> A reference to the heading text element so you can update it</li>
</ul>
<p>The <strong>context</strong> argument contains data that will be sent into the stacks template that initally renders its header. It supports the following keys:</p>
<ul>
<li><code>heading</code> Text string that will be translated from the <code>eze</code> context, and then set as heading</li>
<li><code>icon</code> Is a filename, without fileending, being one of the included Helveticon icons.</li>
<li><code>autosave</code> You can disable the autosave control that by default is rendered and active in the heading. Setting this to false will make sure autosave can't happen in your stack item.</li>
</ul>
<h4>pop([<code>arg</code>, ...])</h4>
<p>Pop the current stack item, in time showing the underlying item. Notice that its possible to pass an arbitrary number of arguments to pop, this will make those arguments propagate into any event listeners for the pop. By default, when passing zero arguments,
the <code>this.model</code> of the view will be sent.</p>
<p>You would normally use <code>pop</code> inside a view if some action should force it to close from within.</p>
<h3>eZExceed.stack Events</h3>
<p>There are two events you can listen to:</p>
<h4>destruct</h4>
<p>Called when a view destructs, this can be handy when you push a helper view to for example make a selection, and need to pass values back from that view:</p>
<pre><code class="lang-javascript">// Inside View#1
var context = {heading:'Make a selection',icon:'Select'};
var selectView = eZExceed.stack.push(SelectionView, {render:true}, context);
selectView.once('destruct', this.saveSelection);</code></pre>
<h4>push</h4>
<p>You can also listen to new views getting pushed on the stack in general.</p>
<pre><code class="lang-javascript">eZExceed.stack.on('push', doSomething);</code></pre>
<h3><a id="extensibility-api-shared" href="#extensibility-api-shared"></a> Shared classes</h3>
<p>eZ Exceed provides a bunch of javascript classes you can inherit from to both speed up development as well as making sure everything looks and feels good. There are move goodness under <code>shared/</code> but you should refrain to use anything that is
not documented as the APIs aren't entirely stable.</p>
<h4>shared/view</h4>
<p>Instead of using Backbone.View directly, you should always default to using this view as your base. It provides some conveniences:</p>
<ul>
<li><code>click</code> events are translated to fast taps on touch devices</li>
<li>You get <a href="http://nervetattoo.github.io/backbone.keys/">backbone.keys</a> enabled on desktops</li>
<li>You can more easily render the Exceed loader by using the _loader method: <strong>this._loader(options)</strong>
</li>
<li>Hiding/showing the entire element is done by <code>this.hide()</code> and <code>this.show()</code>, or for sub elements by passing them as argument.</li>
</ul>
<h4>shared/datatype</h4>
<p>This is the view you should inherit for creating FieldType interface handlers If your fieldtype consists of just textboxes, this default implementation should suffice, but if its more complex you need to override.</p>
<p>Methods:</p>
<h5>render</h5>
<p>This method will be called when it's time for your GUI to display itself. Make sure you return <code>this</code> for chaining support.</p>
<h5>parseEdited</h5>
<p>This method is called when autosave is triggered for your Field, and it needs to return exactly what should be sent to the <code>content/save</code> module in eZ Publish. Looking at the <strong>objectrelationlist</strong> FieldType explains how we can save
something more complex:</p>
<pre><code class="lang-javascript">parseEdited : function()
{
var values = [];
// Helper to create the name of the <input> attribute with pre/postfix
var inputName = this.buildName('data_object_relation_list');
if (this.collection.length > 0) {
// Return an object for each id:
// {...data_object_relation_list... : id}
// Which will be an array [obj,obj,obj]
values = this.collection.map(function(model)
{
//return model.id;
var obj = {};
obj[inputName] = model.id;
return obj;
});
}
else {
// Theres a special syntax for empty values
var value = {};
value[inputName] = 'no_relation';
values = [value];
}
return values;
}</code></pre>
<h4>shared/selectable</h4>
<p>Turn any select box into an upgraded version:</p>
<pre><code class="lang-javascript">define(['shared/view', 'shared/selectable'], function(View, selectable) {
return View.extend({
render: function() {
selectable(this.$('select'));
return this
}
});
});</code></pre>
<h4>shared/funky</h4>
<p>A fp utilty library for writing functional code: Consider these examples:</p>
<pre><code class="lang-javascript">// Truthy
locations.filter(Funky.truthyProp('canCreate'));
// Equality
locations.filter(Funky.equalProp('id', this.subtree.id));
// Toggling
this.mutable = false;
var toggle = Funky.toggleProp('mutable');
toggle(); // true
toggle(); // false</code></pre>
<h1>Contributing</h1>
<h2><a id="contributing-submitting-an-issue" href="#contributing-submitting-an-issue"></a> Submitting an issue</h2>
<p>You can submit issues in our <a href="https://github.com/KeyteqLabs/ezexceed/issues">GitHub project</a>, but make sure you've read our <a href="https://github.com/KeyteqLabs/ezexceed/blob/dev/CONTRIBUTING.md">contributor documentation</a>
</p>
<h2><a id="contributing-translations" href="#contributing-translations"></a> Translations</h2>
<p>We are very interested in simple translation pull requests to cover the most important languages:</p>
<ul>
<li>Spanish</li>
<li>French</li>
<li>German</li>
<li>Italian</li>
</ul>
<h2><a id="contributing-patches" href="#contributing-patches"></a> Patches</h2>
<p>Contributing with Pull Requests for bug fixes and / or new features is very welcommed, but please make sure you've read our <a href="https://github.com/KeyteqLabs/ezexceed/blob/dev/CONTRIBUTING.md">contributor documentation</a>. If you are adding
new, or changing existing functionality, please register this as an issue before you start coding so you know that the patch will be accepted before you undergo a lot of work.</p>
<h2><a id="contributing-technologies" href="#contributing-technologies"></a> Technologies</h2>
<p>Technologies used in eZ Exceed include, but are not limited to:</p>
<ul>
<li>Backbone.js (1.0)</li>
<li>Lo-Dash (1.2.1)</li>
<li>jQuery (1.9)</li>
<li>jQuery UI</li>
<li>moment.js</li>
<li>Handlebars.js</li>
<li>Require.js</li>
</ul>
<h2><a id="contributing-coding-standard" href="#contributing-coding-standard"></a> Coding standard</h2>
<p>We follow the PHP Framework Interoperability Group's <a href="https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md">coding standard</a>, and any submissions must comply.</p>
<h1>Frequently Asked Questions</h1>
<h2><a id="frequently-asked-questions-editors" href="#frequently-asked-questions-editors"></a> Editors</h2>
<h3>I can't see any changes even though I have published them. Why?</h3>
<p>Very often this is because a site is configured with two translation languages where one is the default used for editing, and the other is the one actually being displayed. Ensure you are editing the correct translation, and if both languages are not
used, make sure it is removed from the installation.</p>
<p>If this doesn't solve your problem, overly eager cache blocks are often to blame.</p>
<h3>I can't see my changes without publishing. Why?</h3>
<p>This most likely implies you are running eZ Publish 4.6 where previews of unpublished content is not supported</p>
<h2><a id="frequently-asked-questions-developers" href="#frequently-asked-questions-developers"></a> Developers</h2>
<h3>I followed all the steps to install eZ Exceed, but the toolbar isn't showing up. Why?</h3>
<p>Ensure that your pagelayout template is rendering the toolbar. This is only necessary if you are overriding with your own custom pagelayout (eZ Publish 4.x) or if you are running eZ Publish 5.x.</p>
<h4>eZ Publish 4.x:</h4>
<pre><code class="lang-smarty">{include uri="design:parts/website_toolbar.tpl" current_node_id=$module_result.node_id}</code></pre>
<h4>eZ Publish 5.x:</h4>
<pre><code class="lang-twig">{% if location is defined %}
{% include "design:parts/website_toolbar.tpl" with {current_node_id: location.id } %}
{% endif %}</code></pre>
<p>Also, your editor users need the right set of permissions and policies. We do not require any special permissions over what eZ Publish would normally require, but do make sure the settings are indeed intact.</p>
<p>For a normal editor you should assign the following permissions:</p>
<ul>
<li><code>ezexceed/use</code>
</li>
<li><code>content/create</code>
</li>
<li><code>content/edit</code>
</li>
<li><code>content/manage_locations</code>
</li>
<li><code>ezoe/edit</code>
</li>
</ul>
<p>This should be sufficient for normal everyday use. For the best possible experience, permissions for <code>content/create</code> and <code>content/edit</code> should be limited to a specific <em>subtree</em>, as well as a limited subset of ContentTypes the
group in question should be able to edit.</p>
<p>If you are going to be using the Shareable preview URLs feature, make sure to also grant the desired user groups the following policy:</p>
<ul>
<li><code>ezexceed/preview</code>
</li>
</ul>
<h3>My jQuery plugins are gone / jQuery is overwritten. Why?</h3>
<p>This is due to how eZ Exceed supports the <code>ezie</code> extension. Specify your jQuery dependency through <code>ezjscore</code> and the
<code>ezjsc::jquery</code> loading strategy to solve this.</p>
<pre><code class="lang-ini">[eZJSCore]
ExternalScripts[jquery]=://ajax.googleapis.com/ajax/libs/jquery/2.0.0/jquery.min.js</code></pre>
<pre><code class="lang-smarty">{ezscript_require(array('ezjsc::jquery'))}</code></pre>
<h3>TinyMCE breaks from time to time in Internet Explorer. Why?</h3>
<p>This could be due to an awkward bug in IE where only 30 stylesheets can be loaded, and any stylesheets more than that will silently not load. The simplest way to get around this is to enable the packer in <code>ezjscore</code>.</p>
<p>Turn on this in <code>settings/override/ezjscore.ini.append.php</code>
</p>
<pre><code class="lang-ini">[eZJSCore]
Packer=enabled
[Packer]
AppendLastModifiedTime=enabled</code></pre>
</div>
</div>
</div>
<script type="text/javascript" src="assets/js/prism.js"></script>
<script type="text/javascript" src="assets/js/prism-ini.js"></script>
<script type="text/javascript" src="assets/js/prism-smarty.js"></script>
<script type="text/javascript" src="assets/js/prism-twig.js"></script>
</body>
</html>