esperanto-cms Documentation

Transcription

1 esperanto-cms Documentation Release 0.2 Gerhard Seidel July 02, 2015

2

3 Contents 1 Contents Installation AdminBundle ContentBundle DownloadBundle Configuration Convention Hook Cookbook i

4 ii

5 CHAPTER 1 Contents 1.1 Installation To create a project with the esperanto-cms, you just need the following composer command. composer create-project esperanto/esperanto-cms-project project-name dev-master 1.2 AdminBundle Installation here some word about how to install the admin bundle 1

6 1.2.2 Introduction What is the AdminBundle Routing App Route Before you use the app route, you should know what we understand under actions and blocks. The app route is responsible to display these to kinds of abstraction. It is fully independent on any data model. On this Picture you can see how the app route could render them. Actions Actions are something like buttons. If you click on these buttons, there will be executed something. Normally just an overlay will be displayed. The overlay will provide a form, where the user can change data. 2 Chapter 1. Contents

7 Blocks A block is small unit with its own logic. It could also provide some clickable events. But the focus is to presented some information. Route Here is an example route esperanto_app_index: path: /esperanto/app/index methods: [GET] defaults: _controller: esperanto_admin.controller.resource:indexaction _sylius: template: esperantoappbundle:app:index.html.twig _viewer: type: app parameters: name: value blocks: table: type: esperanto_page_page_table parameters: table_route: esperanto_page_page_table update_route: esperanto_page_page_update actions: create: type: overlay route: esperanto_page_page_create icon: plus label: label.create Index Route The index extends from the standard app route, but is bind to resource. The advantage is, that we only need a short route definition, but it is as extendable as the app route. Here you can see the minimum route definition: esperanto_app_resource_index: path: /esperanto/app/resource/index methods: [GET] defaults: _controller: esperanto_reference.controller.reference:indexaction _sylius: template: esperantoadminbundle:resource:index.html.twig This is really short, isn t it? Here you can see the full standard definition, which is made automatically by the viewer and controller. esperanto_app_resource_index: path: /esperanto/app/resource/index methods: [GET] defaults: _controller: esperanto_app.controller.resource:indexaction 1.2. AdminBundle 3

8 _sylius: template: esperantoadminbundle:resource:index.html.twig _viewer: type: index blocks: table: type: esperanto_page_page_table parameters: table_route: esperanto_page_page_table update_route: esperanto_page_page_update actions: create: type: overlay route: esperanto_page_page_create icon: plus label: label.create Create Route esperanto_page_page_create: path: /admin/esperanto/page/page/create methods: [GET,POST] options: expose: true defaults: _controller: esperanto_page.controller.page:createaction _sylius: template: esperantoadminbundle:resource:create.html.twig _viewer: type: create parameters: param1: value1 param2: value2 tabs: page: label: page template: esperantopagebundle:tab:page.html.twig content: label: Content template: esperantopagebundle:tab:content.html.twig seo: label: Seo template: esperantopagebundle:tab:seo.html.twig buttons: cancel: route: display: true role: ~ label: label.cancel icon: close save: route: ~ display: true role: ~ label: label.save icon: check preview: 4 Chapter 1. Contents

9 route: esperanto_page_page_preview display: true role: ~ label: label.preview icon: eye form: template: esperantoadminbundle:view:tab.html.twig theme: ~ action: esperanto_page_page_create Update Route esperanto_page_page_update: options: expose: true path: /admin/esperanto/page/page/update/id methods: [GET,POST] defaults: _controller: esperanto_page.controller.page:updateaction _sylius: template: esperantoadminbundle:resource:update.html.twig _viewer: type: edit parameters: param1: value1 param2: value2 tabs: page: label: page template: esperantopagebundle:tab:page.html.twig content: label: Content template: esperantopagebundle:tab:content.html.twig seo: label: Seo template: esperantopagebundle:tab:seo.html.twig buttons: cancel: route: display: true role: ~ label: label.cancel icon: close save: route: ~ display: true role: ~ label: label.save icon: check preview: route: esperanto_page_page_preview display: true role: ~ label: label.preview icon: eye delete: route: 1.2. AdminBundle 5

10 display: true role: ~ label: label.delete icon: trash form: template: esperantoadminbundle:view:tab.html.twig theme: ~ action: esperanto_page_page_update delete: esperanto_page_page_delete Delete Route esperanto_page_page_delete: path: /admin/esperanto/page/page/delete/id defaults: _controller: esperanto_page.controller.page:deleteaction Table Route esperanto_app_table: path: /admin/esperanto/app/resource/index methods: [GET] defaults: _controller: app.controller.user:createaction _sylius: template: App:Backend/User:show.html.twig criteria: username: $username enabled: true repository: method: findonewithfriends arguments: [$username] sortable: true sorting: score: desc paginate: 5 limit: 3 _viewer type: table parameters: param1: value1 param2: value2 table: width: 5 columns: id: title: ID field: id width: 1 title: title: ID field: id width: 1 public: label: public 6 Chapter 1. Contents

11 property: public widget: esperantoadminbundle:widget:boolean.html.twig Dynamic routing It is also possible to use dynamic routing for the entities. For the implementation we use the SymfonyCMF RoutingBundle. Usually dynamic routing is used in the frontend to have a nice seo url. This following example will show you how to add a url field to your entity and how you map it to a controller action. Relation First we need to tell our application that an entity has a manytoone relation to a route. We use yaml for the meta data. manytoone: route: cascade: ['persist', 'refresh', 'remove'] targetentity: esperanto\adminbundle\entity\route Note: The relation between the entity and route should be onetoone, but we have some problems with the owning entity in this case, so it is better to use the manytoone relation, so the owning side is clear. Here is the php source for the meta data. <?php /** \esperanto\adminbundle\entity\route */ private $route; /** \esperanto\adminbundle\entity\route */ public function getroute() return $this->route; /** \esperanto\adminbundle\entity\route $route */ public function setroute($route) $this->route = $route; Service Did you wonder why we don t add relation informations on the route side? This is because we have a dynamic relation. The content of a route could be any entity. So this is we just save some type information. And if a route wants to have his content, we load it on demand. For this we need to tell to application some mapping informations. These will be done by a service AdminBundle 7

12 An entity should be configurable by the SymfonyCMF RoutingBundle. If it is we have a some parameters and services, added by sylius. So that we can configure it one place, we just pass the parameters to our service. parameters: esperanto_page.page.route_content_loader.class: esperanto\adminbundle\route\routecontentloader services: esperanto_page.page.route_content_loader: class: %esperanto_page.page.route_content_loader.class% arguments: - 'esperanto_page.page' - %esperanto_page.model.page.class% - 'esperanto_page.repository.page' tags: - name: esperanto_route_content_loader Note: The third argument is the name of the service, but not the service directly. here is missing, because we need some lazy load for getting the service. If we don t do this, we have some loops in our dependencies. Form To add an url field in our form we just use this simple snippet. There is already a form type esperanto_route, which handle all we need. Also the contraints, so we use a clean and unique url. <?php $builder->add('route', 'esperanto_route'); If you render your form manually, you shouln t forget to add it in your template file. form_row(form.route) Controller And last but not least, we have to define our controller, and add some mapping information to the SymfonyCMF RoutingBundle. The mapping contains the class name of our entity and the action which should be called for it. cmf_routing: dynamic: controllers_by_class: esperanto\projectbundle\entity\page: esperantoprojectbundle:main:page In our yaml we use esperantoprojectbundle:main:page as action, so we also have to add this to our Controller. <?php public function pageaction(page $contentdocument) return $this->render('esperantoprojectbundle:page:page.html.twig', array( 'page' => $contentdocument )); Note: The first parameter name for the action must be named $contentdocument. Otherwise you will get some 8 Chapter 1. Contents

13 errors. here is the text about routing CRUD Routing generator We implement a short routing generator, which create the minimal routing definition to CRUD your resource. app/console esperanto:generate:routing app resource Block what are blocks and how to use them Viewer viewer concept Menu Menu The main menu in the admin is configurable over the esperanto_admin.menu. You don t need to add the logout button. It will be added automatically. esperanto_admin: menu: user: label: label.user route: esperanto_user_user_index role: ROLE_ESPERANTO_USER_USER_INDEX group: label: label.group route: esperanto_user_group_index role: ROLE_ESPERANTO_USER_GROUP_INDEX Hook You can hook the menu with the event esperanto_admin.menu before it will be rendered. Note, that by default there is already a hook, which is responsible for the logout button, permissions and style. If you want to be sure to hook after the default hook, you need to increase your order number. namespace esperanto\projectbundle\eventlistener; use esperanto\adminbundle\menu\menuevent; class MenuEventListener public function onmenu(menuevent $event) $menu = $event->getmenu(); 1.2. AdminBundle 9

14 foreach($menu->getchildren() as $child) $menu->setattribute('class', 'menu'); esperanto_project.menu_event_listener: class: esperanto\projectbundle\eventlistener\menueventlistener tags: - name: kernel.event_listener, event: esperanto_admin.menu, method: onmenu This section will introduce you, how you can add menu to the AdminBundle Form Wysiwyg This section explain how you can configure your wysiwyg editor system wide and in some special cases. The esperanto-cms use the TinyMCE editor, if you are familiar with its settings you can easily configure it, otherwise you should also read the TinyMCE docs for configuration. Configuration You can find the system wide configuration under app/config/wysiwyg.yml. All settings here a equivalent to the TinyMCE configuration, mentioned above. Note that this is a yaml file and the TinyMCE configuration is a Javascript Object or JSON, but yaml can be translated one to one JSON. This configuration are available: height toolbarn style_formats formats content_css height: 150 toolbar1: "undo redo bold italic underline strikethrough subscript superscript removeformat link toolbar2: "table alignleft aligncenter alignright alignjustify bullist numlist outdent indent c style_formats: - title: 'Bold text', inline: 'b' - title: 'Red text', inline: 'span', styles: color: '#ff0000' - title: 'Red header', block: 'h1', styles: color: '#ff0000' - title: 'Example 1', inline: 'span', classes: 'example1' - title: 'Example 2', inline: 'span', classes: 'example2' - title: 'Table styles' - title: 'Table row 1', selector: 'tr', classes: 'tablerow1' formats: alignleft: selector: 'p,h1,h2,h3,h4,h5,h6,td,th,div,ul,ol,li,table,img', classes: 'left' aligncenter: selector: 'p,h1,h2,h3,h4,h5,h6,td,th,div,ul,ol,li,table,img', classes: 'center' 10 Chapter 1. Contents

15 alignright: selector: 'p,h1,h2,h3,h4,h5,h6,td,th,div,ul,ol,li,table,img', classes: 'right' alignfull: selector: 'p,h1,h2,h3,h4,h5,h6,td,th,div,ul,ol,li,table,img', classes: 'full' bold: inline: 'span', 'classes': 'bold' italic: inline: 'span', 'classes': 'italic' underline: inline: 'span', 'classes': 'underline', exact: true strikethrough: inline: 'del' customformat: inline: 'span', styles: color: '#00ff00', fontsize: '20px', attributes: title content_css: ~ #read the text below content_css For the content_css, we need assets/assetics so you need to use syntax #multiple files content_css: - '@esperantoprojectbundle/resources/public/css/styleone.css' - '@esperantoprojectbundle/resources/public/css/styletwo.css' #single file content_css: '@esperantoprojectbundle/resources/public/css/styleone.css' FormType If you need a special configuration just for one form, you can override or filter some settings in the FormType option array. formats: Needs an array, where you can list the formats which should be shown. height: Overwrite the height toolbar1: Overwrite the toolbar1 toolbar2: Overwrite the toolbar2 content_css: Overwrite the content_css, this could be an array or a string Syntax) $builder->add('text', 'wysiwyg', array( 'formats' => array('bold text', 'Red text'), 'height' => 300, 'toolbar1' => '', 'toolbar2' => '' 'content_css' => array( '@esperantoprojectbundle/resources/public/css/styleone.css' ) ); Installation Introduction Menu Form Menu Routing Wysiwyg App Route 1.2. AdminBundle 11

16 Index Route Create Route Update Route Table Route Delete Route Dynamic routing 1.3 ContentBundle Add content type If you follow this step, you can add any content type easily to the cms. 1. Create an Entity 2. Create a FormType 3. Create a template file 4. Add configuration In the following we add an example content type called youtube. In our case youtube type contains these three parameter: url, title and author Entity An entity must implement the ItemTypeInterface. Remember that a entity should be a really doctrine entity. Cause the ContentBundle will call persists to this object. If you use a non doctrine entity, then you will receive errors while trying to save the content. <?php namespace esperanto\projectbundle\entity; use esperanto\contentbundle\item\itemtypeinterface; class Youtube implements ItemTypeInterface private $id; private $url; private $title; private $author; public function getid() return $this->id; public function geturl() return $this->url; 12 Chapter 1. Contents

17 public function seturl($url) $this->url = $url; return $this; //...setter and getter for title and author FormType A FormType should extend from ItemFormType. <?php namespace esperanto\projectbundle\form\type; use esperanto\contentbundle\item\itemformtype; use Symfony\Component\Form\FormBuilderInterface; use Symfony\Component\OptionsResolver\OptionsResolverInterface; class YoutubeType extends ItemFormType public function buildform(formbuilderinterface $builder, array $options) $builder->add('url', 'text'); $builder->add('title', 'text'); $builder->add('author', 'text'); public function setdefaultoptions(optionsresolverinterface $resolver) $resolver->setdefaults(array( 'data_class' => 'esperanto\projectbundle\entity\youtube' )); public function getname() return 'esperanto_content_item_youtube'; If you want to change the style in your form you have to add a new block in separate twig file. #fields.html.twig % block esperanto_content_item_youtube_widget % <div class="padding"> form_widget(form.url) </div> <div class="padding"> form_widget(form.title) </div> <div class="padding"> form_widget(form.author) </div> % endblock % 1.3. ContentBundle 13

18 And this file, here fields.html.twig, need to be add to the config. twig: form: resources: - 'esperantoprojectbundle:form:fields.html.twig' Template Just create a simple twig file somewhere in your bundle. This template will be used the render this type in your application. The entity which is connected to this type will be passed to the template as the parameter data. In our case this will be an object from the Youtube class. # esperantoprojectbundle:itemtype:youtube.html.twig # <h2> data.title <h2> <iframe width="560" height="315" src=" data.url " frameborder="0" allowfullscreen></iframe> <div>by data.author </div> Configuration Finally you need to add the youtube type to the configuration under the section esperanto_content.items. The option label is optional and is used in the context menu where you can add a new item to your content. esperanto_content: items: youtube: model: esperanto\projectbundle\entity\youtube form: esperanto\projectbundle\form\type\youtubetype repository: esperantoprojectbundle:youtube template: esperantoprojectbundle:itemtype:youtube.html.twig label: Youtube Use in form You add the form type esperanto_content in your form. $builder->add('content', 'esperanto_content'); Option Types $builder->add('content', 'esperanto_content', array( 'types' => array( array('type' => 'text', 'label' => 'Text'), array('type' => 'picture', 'label' => 'Bild'), array('type' => 'video') ) )); If it is empty all items will be loaded. But if you want you can set explicit the types which should be available. The parameter label is optional and if its not set the standard label will be used, which is also configured in the configuration. 14 Chapter 1. Contents

19 1.3.3 Rendering Now you want to render your content? This is a very easy task. Just use the twig function content_render. This function has got two parameter. The first one is the content data, which you should pass to the template. The second one is optional and is used to render a different template set. For further information read the section Render sets If you use the content_render with one parameter, then the template for the item is rendered which is defined in your configuration. content_render(content) # render with specific set # content_render(content, 'page') Render sets If you are in the situation that you have two render to different templates for the same item type in your application, then the render sets will help you to implement this. In your configuration you can define a render set. Here we call it page. Now we can define for each item a new template. If you don t define a template for an item under this set, then the standard template will be used. esperanto_content: render: sets: page: picture: esperantoprojectbundle:itemtype:page/picture.html.twig text: esperantoprojectbundle:itemtype:page/text.html.twig 1.4 DownloadBundle Download Content Type The DownloadBundle has a content item, which can be activated. This article show how you do this. Just add the item to esperanto_content. esperanto_content: items: download: model: esperanto\downloadbundle\entity\downloaditem form: esperanto\downloadbundle\form\type\downloaditemtype repository: esperantodownloadbundle:downloaditem template: esperantodownloadbundle:item:download.html.twig label: Download And the fields.html into the twig config. twig: form: resources: - 'esperantodownloadbundle:item:fields.html.twig' 1.4. DownloadBundle 15

20 1.5 Configuration esperanto_admin: permission_check: false stylesheets: esperanto_app_style: resource: depends: ~ javascripts: esperanto_app_bootstrap: resource: '@esperantoappbundle/resource/public/js/bootstrap.css' depends: jquery menu: homepage: title: Homepage route: esperanto_homepage role: HOMEPAGE_ROLE download: title: Download route: esperanto_download_index role: DOWNLOAD_ROLE 1.6 Convention Route name Don t use camel case, use underscore instead For example you have a bundle called esperantoappbundle, and a action called index then you have to name your route like this esperanto_app_index. A route should contain the following information devide by an underscore: 1. Company name 2. Bundle name 3. Entity name (optional) 4. Action name Bundle One menu is one app One app should be one Bundle Only in the Project Bundle you can add more then one app 1.7 Hook Menu To overwrite the menu list you can use the esperanto_admin.menu hook. 16 Chapter 1. Contents

21 function onmenu($menuevent) $menu = $menuevent->getmenu() $menu->add(); $menu->delete(); $menu->disable(); 1.8 Cookbook Adding new Bundle to esperanto-cms 1. Push to git Repo to github 2. Add package in packagist 3. Add Api hook from packagist into github 4. Add remote URL from git repo to the esperanto-cms repo 5. add this subtree with remote URL which you added before 6. pull this repo 7. push to esperanto-cms 8. add bundle to esperanto-cms-project and composer.json and push 1.8. Cookbook 17