From f124d6e9bf1b255d50b00416cd409ab1a2e07700 Mon Sep 17 00:00:00 2001 From: Orbitale Date: Thu, 30 Jul 2015 15:21:38 +0200 Subject: [PATCH] Update and improve documentation --- README.md | 213 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 144 insertions(+), 69 deletions(-) diff --git a/README.md b/README.md index 791cefa..58dcbb3 100644 --- a/README.md +++ b/README.md @@ -12,9 +12,13 @@ * [View pages](#view-pages) * [Generate a route based on a single page](#generate-a-route-based-on-a-single-page) * [Change homepage](#change-homepage) -* [Using different layouts](#using-different-layouts) +* [Page restriction based `host` and/or `locale`](#page-restriction) +* [Design](#design) + * [Using different layouts](#using-different-layouts) * [Advanced layout configuration](#advanced-layout-configuration) + * [Changing the "breadcrumbs" look](#breadcrumbs) * [Setup EasyAdminBundle to manage pages and categories in its back-end](#easyadmin) +* [Configuration reference](#configuration-reference) * [Changelog](#changelog) # Orbitale CMS Bundle @@ -57,21 +61,31 @@ public function registerBundles() Import the necessary routing files. *Warning:* - Both `Page` and `Category` controllers have to be "alone" in their routing path, because there is a "tree" routing - management. If you set the prefix as "/" or any other path you are already using, you may have some unexpected "404" - or other errors, depending on the routes priority. + Both `Page` and `Category` controllers have to be "alone" in their routing path, + because there is a "tree" routing management. If you set the prefix as "/" + or any other path you are already using, make sure that `OrbitaleCmsBundle` + routes are loaded **at the end of your routing file**, or you may have some + unexpected "404" or other errors, depending on the routes priority.
+ This is why we recommend you to **load the `CategoryController` _before_ the + `PageController`**, and let both routes config be **the last ones** of your + `routing.yml` file.
+ **Note:** In technical terms, the whole URI is scanned, not a simple part of it, + this is why it can analyze very deep URIs like + `/home/blog/parent-link/child-link/element`, and check all pages/categories. + +Example: ```yml # app/config/routing.yml -orbitale_cms_page: - resource: "@OrbitaleCmsBundle/Controller/PageController.php" - type: annotation - prefix: /page/ - orbitale_cms_category: resource: "@OrbitaleCmsBundle/Controller/CategoryController.php" type: annotation prefix: /category/ + +orbitale_cms_page: + resource: "@OrbitaleCmsBundle/Controller/PageController.php" + type: annotation + prefix: /page/ ``` Update your database by executing this command from your Symfony root directory: @@ -84,45 +98,58 @@ $ php app/console doctrine:schema:update --force ### Manage pages -To manage your pages, you should use any back-end solution, like [EasyAdmin](https://github.com/javiereguiluz/EasyAdminBundle/) -(which we suggest) or [SonataAdmin](https://sonata-project.org/bundles/admin), or any else. -You must have configured it to manage at least the `Orbitale\Bundle\CmsBundle\Entity\Page` entity. +To manage your pages, you should use any back-end solution, like +[EasyAdmin](https://github.com/javiereguiluz/EasyAdminBundle/) (which we suggest) +or [SonataAdmin](https://sonata-project.org/bundles/admin), or any other backend +solution that can operate CRUD actions on entities. +You must have configured it to manage at least the +`Orbitale\Bundle\CmsBundle\Entity\Page` entity. ### View pages -The `PageController` handles some methods to view pages with a single `indexAction()`, and the `CategoryController` -uses its route to show all pages within a specified `Category`. +The `PageController` handles some methods to view pages with a single +`indexAction()`, and the `CategoryController` uses its route to show all pages +within a specified `Category`. The URI for both is simply `/{slug}` where `slug` is the... page or category slug. -If your page or category has one `parent`, then the URI is the following: `/{parentSlug}/{slug}`. +If your page or category has one `parent`, then the URI is the following: +`/{parentSlug}/{slug}`. + You can notice that we respect the pages hierarchy in the generated url. -You can navigate through a complex list of pages or categories, as long as they're related as `parent` and `child`. + +You can navigate through a complex list of pages or categories, as long as they +are related as `parent` and `child`. + This allows you to have such urls like this one : -`http://www.mysite.com/about/company/team/members` for instance, will show only the `members` page, but its parent has -a parent, that has a parent, and so on, until you reach the "root" parent. And it's the same behavior for categories. -*Note:* this behavior is the precise reason why you have to use a specific prefix for your controllers routing import, -unless you may have many "404" errors. +`http://www.mysite.com/about/company/team/members` for instance, will show only +the `members` page, but its parent has a parent, that has a parent, and so on, +until you reach the "root" parent. And it's the same behavior for categories. + +*Note:* this behavior is the precise reason why you have to use a specific rules +for your routing, unless you may have many "404" errors. ### Generate a route based on a single page *Note:* This behavior also works for categories. -If you have a `Page` object in a view or in a controller, you can get the whole arborescence by using the `getTree()` -method, which will navigate through all parents and return a string based on a separator argument (default `/`, for urls). +If you have a `Page` object in a view or in a controller, you can get the whole +arborescence by using the `getTree()` method, which will navigate through all +parents and return a string based on a separator argument (default `/`, for urls). Let's get an example with this kind of tree: ``` / - Home (root url) -├─ /welcome - Welcome page (set as "homepage", so "Home" will be the same) +├─ /welcome - Welcome page (set as "homepage", so "Home" will be the same) │ ├─ /welcome/our-company - Our company │ ├─ /welcome/our-company/financial - Financial │ └─ /welcome/our-company/team - Team └─ Contact ``` -Imagine we want to generate the url for the "Team" page. You have this `Page` object in your view/controller. +Imagine we want to generate the url for the "Team" page. You have this `Page` +object in your view/controller. ```twig {# Page : "Team" #} @@ -142,16 +169,20 @@ With this, you have a functional tree system for your CMS! ## Change homepage -The homepage is always the first `Page` object with its `homepage` attribute set to true. Be sure to have only one -element defined as homepage, or you may have unexpected results. +The homepage is always the first `Page` object with its `homepage` attribute set +to true. Be sure to have only one element defined as homepage, or you may have +unexpected results. + +You can have multiple homepages if you add them restrictions based on host and +locale (see [next chapter](#page-restriction)). ## Page restriction based `host` and/or `locale` -If you are hosting your application in a multi-domain platform, you can use the `host` attribute in your page -to restrict the view only to the specified host. +If you are hosting your application in a multi-domain platform, you can use the +`host` attribute in your page to restrict the view only to the specified host. -It's great for example if you want to have different articles on different domains like `blog.mydomain.com` -and `www.mydomain.com`. +It's great for example if you want to have different articles on different +domains like `blog.mydomain.com` and `www.mydomain.com`. If you want to restrict by `locale`, you can specify the locale in the page. The best conjointed use is with prefixed routes in the routing file: @@ -161,17 +192,24 @@ The best conjointed use is with prefixed routes in the routing file: orbitale_cms_page: resource: "@OrbitaleCmsBundle/Controller/PageController.php" type: annotation - # Add the locale to the prefix for if the page's locale is specified and is not - # equal to request locale, the app will return a 404 error. + # Add the locale to the prefix for if the page's locale is specified and is + # not equal to request locale, the app will return a 404 error. prefix: /{_locale}/page/ ``` +## Design + +`OrbitaleCmsBundle` has some options to customize the design of your simple CMS. + +Mostly, you will take care of the `layouts` option (see +[next chapter](#using-different-layouts)), or the `design` option. -## Using different layouts +### Using different layouts Obviously, the default layout has no style. -To change the layout, simply change the OrbitaleCmsBundle configuration to add your own layout: +To change the layout, simply change the OrbitaleCmsBundle configuration to add +your own layout: ```yaml # app/config/config.yml @@ -182,48 +220,63 @@ orbitale_cms: Without overriding anything, you can easily change the layout for your CMS! -Take a look at the [default layout](Resources/views/default_layout.html.twig) to see which Twig blocks are mandatory to -render correctly the pages. +Take a look at the [default layout](Resources/views/default_layout.html.twig) +to see which Twig blocks are mandatory to render correctly the pages. ### Advanced layout configuration -Here is the global configuration reference for the layouts: +The basic configuration for a layout is to specify a template to extend. -```yaml -orbitale_cms: - layouts: - # One layout prototype - name: - resource: ~ # Required. - assets_css: [] - assets_js: [] - pattern: ^/ -``` +But if you look at the [Configuration reference](#configuration-reference) you + will see that there are many other parameters you can use to define a layout: -Explanation: -* *name* (attribute used as key for the layouts list):
- The name of your layout. Simply for readability issues, and maybe to get it directly from the config. -* *resource*:
+Prototype of a layout configuration: +* **name** (attribute used as key for the layouts list):
+ The name of your layout. Simply for readability issues, and maybe to get it + directly from the config (if you need it). +* **resource**:
The Twig template used to render all the pages (see the [above](#using-different-layouts) section) -* *assets_css* and *assets_js*:
- Any asset to send to the Twig `asset()` function. The CSS is rendered in the `stylesheets` block, and js in the - `javascripts` block. -* *pattern*:
- The regexp of the URI path you want to match for this layout. - It's nice if you want to use a different layout for categories and pages. You can use it this way for this kind of - behavior: +* **assets_css** and *assets_js*:
+ Any asset to send to the Twig `asset()` function. The CSS is rendered in the + `stylesheets` block, and js in the `javascripts` block. +* **host**:
+ The exact domain name you want the layout to match with. +* **pattern**:
+ The regexp of the path you want to match with for this layout. + It's nice if you want to use a different layout for categories and pages. For + example, you can specify a layout for the `^/page/` pattern, and another for + `^/category/`. + If you specify a very deep pattern, you can even change the layout for a single + page! + +Take another look on the [config reference](#configuration-reference) if you +need to get the prototype defaults. - ```yaml - # app/config/config.yml - orbitale_cms: - layouts: - page: - resource: @App/layout_page.html.twig - pattern: ^/page/ - category: - resource: @App/layout_category.html.twig - pattern: ^/category/ - ``` +### Changing the "breadcrumbs" look + +Under the `design` option, you have some that you can use to optimize the +rendering of the breadcrumbs. + +Basically, it will look like this: + +[Homepage](#breadcrumbs) > [Parent page](#breadcrumbs) > Current page + +**Note:** The breadcrumbs wrapper already has `id="breadcrumbs"` on its tag. + +* **breadcrumbs_class**:
+ Changes the class of the breadcrumbs wrapper. +* **breadcrumbs_link_class**:
+ Changes the class of any link in the breadcrumbs. +* **breadcrumbs_current_class**:
+ Changes the class of the current page in the breadcrumbs (which is not a link). +* **breadcrumbs_separator** *(default: ">")*:
+ Changes the default separator used. You can use anything, but mostly we see `>`, + `/`, `|` or `*` on the web.
+ **Note:** This character is escaped in twig, so do not use things like `←` + or the `&` sign will be replaced with `&` (as well as other characters). +* **breadcrumbs_separator_class**:
+ You can specify a class for the separator (which is wrapped by a `` tag), + if you want to use special design or interaction on it. ## Setup EasyAdminBundle to manage pages and categories in its back-end @@ -256,6 +309,28 @@ easy_admin: fields: [ name, slug, description, parent, enabled ] ``` +## Configuration reference + +```yml +# app/config/config.yml +orbitale_cms: + layouts: + # Prototype + name: + name: ~ # Optional, it's automatically set from the key + resource: ~ # Required, must be a valid twig template + assets_css: [] # Used with the `asset()` twig function + assets_js: [] # Used with the `asset()` twig function + pattern: ~ # Regexp + host: ~ # Exact value + design: + breadcrumbs_class: "breadcrumb" # The default value automatically suits to Bootstrap + breadcrumbs_link_class: "" + breadcrumbs_current_class: "" + breadcrumbs_separator: ">" + breadcrumbs_separator_class: "breadcrumb-separator" +``` + ## Changelog Go to the [releases](https://github.com/Orbitale/CmsBundle/releases) page to see what are the changes between each