doc/howtos/themes.rst

   1 .. highlight:: xml
   2
   3 ===============
   4 Building Themes
   5 ===============
   6
   7 Basic set up
   8 ============
   9
  10 Create a basic theme module with :command:`odoo.py scaffold` and the ``theme``
  11 template: from the root odoo folder, use
  12
  13 .. code-block:: console
  14
  15     $ ./odoo.py scaffold -t theme "Dummy Theme" addons
  16
  17 this should create a new folder ``dummy_theme`` in the ``addons`` directory
  18 with the structure:
  19
  20 .. code-block:: text
  21
  22     addons/dummy_theme
  23     |-- __init__.py
  24     |-- __openerp__.py
  25     |-- static
  26     |   `-- style
  27     |       `-- custom.less
  28     `-- views
  29         |-- options.xml
  30         |-- pages.xml
  31         `-- snippets.xml
  32
  33 ``static/styles`` contains your stylesheet(s), ``views`` contains the various
  34 XML files describing the theme and theme features to Odoo.
  35
  36 Static Page
  37 -----------
  38
  39 Creating a new template
  40 '''''''''''''''''''''''
  41
  42 Create a new file :file:`odoo/addons/theme_dummy/views/pages.xml` and open it.
  43
  44 In odoo, a page means a new template. You don't need special skills, simply
  45 copy paste the lines::
  46
  47   <template id="website.hello" name="Homepage" page="True">
  48       <t t-call="website.layout">
  49           <div id="wrap" class="oe_structure oe_empty">
  50           </div>
  51       </t>
  52   </template>
  53
  54 Refresh the page and feel the hit.
  55
  56 Editing content on a page
  57 '''''''''''''''''''''''''
  58
  59 You can now add your content! You should always use the Bootstrap structure as
  60 below::
  61
  62     <template id="website.hello" name="Homepage" page="True">
  63         <t t-call="website.layout">
  64             <div id="wrap" class="oe_structure oe_empty">
  65                 <section>
  66                     <div class="container">
  67                         <div class="row">
  68                             <h1>This is Your Content</h1>
  69                             <p>Isn't amazing to edit everything inline?</p>
  70                             <hr/>
  71                         </div>
  72                     </div>
  73                 </section>
  74             </div>
  75         </t>
  76     </template>
  77
  78 Adding new item in the menu
  79 '''''''''''''''''''''''''''
  80
  81 Adding these few more lines will put the new page in your menu::
  82
  83   <record id="hello_menu" model="website.menu">
  84       <field name="name">Hello</field>
  85       <field name="url">/page/hello</field>
  86       <field name="parent_id" ref="website.main_menu"/>
  87       <field name="sequence" type="int">20</field>
  88   </record>
  89
  90 Congrats! It's online! Now drag and drop some snippets on the page and let's
  91 style!
  92
  93 Pimp Your Theme
  94 ---------------
  95
  96 Easy styling with less
  97 ''''''''''''''''''''''
  98
  99 In ``odoo/addons/theme_dummy/static`` create a new folder and name it
 100 ``style``. In the new folder ``odoo/addons/theme_dummy/static/style`` create a
 101 file and name it ``custom.less``. Open ``custom.less`` in the text editor and
 102 modify these lines as below:
 103
 104
 105 .. code-block:: css
 106
 107    .h1 {
 108        color: #215487;
 109    }
 110    .span {
 111        border: 2px solid black;
 112        background-color: #eee;
 113    }
 114
 115 Refresh the page and feel the hit.
 116
 117 Get the most of the dom
 118 '''''''''''''''''''''''
 119
 120 Right-Click, inspect element. You can go deeper by styling the main layout
 121 container. Here we try with the 'wrapwrap' id.
 122
 123 .. code-block:: css
 124
 125    #wrapwrap {
 126         background-color: #222;
 127         width: 80%;
 128         margin: 0 auto;
 129    }
 130
 131 Easy layout with bootstrap
 132 ''''''''''''''''''''''''''
 133
 134 Open :file:`odoo/addons/theme_dummy/views/pages.xml` and add a new section::
 135
 136   <section>
 137       <div class="container">
 138           <div class="row">
 139               <div class="alert alert-primary" role="alert">
 140                   <a href="#" class="alert-link">...</a>
 141               </div>
 142               <div class="col-md-6 bg-blue">
 143                   <h2>BLUE it!</h2>
 144               </div>
 145               <div class="col-md-6 bg-green">
 146                   <h2>GREEN THAT!</h2>
 147               </div>
 148           </div>
 149       </div>
 150   </section>
 151
 152 Refresh the page and check how it looks.
 153
 154 The background of the alert component is the default Bootstrap primary color.
 155 The two other div your created have no custom styles applied yet.  Open
 156 :file:`odoo/addons/theme_dummy/static/style/custom.less` and add these lines:
 157
 158 .. code-block:: css
 159
 160         @brand-primary: #1abc9c;
 161         @color-blue: #3498db;
 162         @color-green: #2ecc71;
 163
 164         .bg-blue { background: @color-blue; }
 165         .bg-green { background: @color-green; }
 166
 167         .h2 { color: white; }
 168
 169 As you see, the default primary has changed and your new colors are shining!
 170
 171 Build Your First Snippet
 172 ------------------------
 173
 174 Setting up __openerp__.py
 175 '''''''''''''''''''''''''
 176
 177 Open ``__openerp__.py`` and add a new line as below:
 178
 179 .. code-block:: python
 180
 181    {
 182        'name': 'Dummy Theme',
 183        'description': 'Dummy Theme',
 184        'category': 'Website',
 185        'version': '1.0',
 186        'author': 'OpenERP SA',
 187        'depends': ['website'],
 188        'data': [
 189            'views/snippets.xml',
 190        ],
 191        'application': True,
 192    }
 193
 194 In ``odoo/addons/theme_learn/views`` create a new xml file, name it
 195 ``snippets.xml`` and open it in a text editor
 196
 197 Add your snippet in the menu
 198 ''''''''''''''''''''''''''''
 199
 200 Before typing your html code, you need to locate it in the WEBb. drop-down
 201 menu.  In this case, we will add it at the end of the Structure section::
 202
 203   <template id="snippets" inherit_id="website.snippets" name="Clean Theme snippets">
 204     <xpath expr="//div[@id='snippet_structure']" position="inside">
 205     </xpath>
 206   </template>
 207
 208 Now open a new div, do not give it any id or classes. It will contain your
 209 snippet::
 210
 211     <xpath expr="//div[@id='snippet_structure']" position="inside">
 212         <div>
 213         </div>
 214     </xpath>
 215
 216 A thumbnail is also needed to create a more attractive link in the menu. You
 217 can use labels to focus on your themes snippets.  Simply add a new div with
 218 the class ``oe_snippet_thumbnail`` and add your thumbnail image (100x79px)::
 219
 220   <xpath expr="//div[@id='snippet_structure']" position="inside">
 221       <div>
 222           <div class="oe_snippet_thumbnail">
 223               <img class="oe_snippet_thumbnail_img" src="/theme_Dummy/static/img/blocks/block_title.png"/>
 224               <span class="oe_snippet_thumbnail_title">SNIP IT!</span>
 225           </div>
 226       </div>
 227   </xpath>
 228
 229 And voila! Your new snippet is now ready to use. Just drag and drop it on your
 230 page to see it in action.
 231
 232 The snippet body
 233 ''''''''''''''''
 234
 235 A snippet has to be in a section with the class ``oe_snippet_body`` to work
 236 correctly.  As Odoo use the Bootstrap framework, you have use containers and
 237 rows to hold your content. Please refer the the Bootstrap documentation::
 238
 239   <xpath expr="//div[@id='snippet_structure']" position="inside">
 240       <div>
 241           <div class="oe_snippet_thumbnail">
 242               <img class="oe_snippet_thumbnail_img" src="/theme_Dummy/static/img/blocks/block_title.png"/>
 243               <span class="oe_snippet_thumbnail_title">SNIP IT!</span>
 244           </div>
 245
 246           <section class="oe_snippet_body fw_categories">
 247               <div class="container">
 248                   <div class="row">
 249                   </div>
 250               </div>
 251           </section>
 252       </div>
 253   </xpath>
 254
 255 Inside your fresh new row, add some bootstraped contents::
 256
 257   <div class="col-md-12 text-center mt32 mb32">
 258       <h2>A great Title</h2>
 259       <h3 class="text-muted ">And a great subtitle too</h3>
 260       <p>Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat. </p>
 261   </div>
 262
 263
 264 Adding images to your snippet
 265 '''''''''''''''''''''''''''''
 266
 267 You can easely add images in your snippets simply by setting up css
 268 backgrounds images.
 269
 270 In ``odoo/addons/theme_dummy/static/`` create a new folder and name it
 271 ``img``. Put your images there, in sub-folders if needed.  Open
 272 :file:`odoo/addons/theme_dummy/static/style/custom.less`, add these lines
 273
 274 .. code-block:: css
 275
 276    @img-01: url("../img/img-boy.png");
 277    .dummy-boy { background-image: @img-01; }
 278
 279    @img-02: url("../img/img-girl.png");
 280    .dummy-girl { background-image: @img-02; }
 281
 282 In :file:`odoo/addons/theme_dummy/views/pages.xml` change the correspondant
 283 lines as below::
 284
 285     <section>
 286         <div class="container">
 287             <div class="row dummy-bg">
 288                 <div class="alert alert-primary" role="alert">
 289                 <a href="#" class="alert-link">...</a>
 290                 </div>
 291                 <div class="col-md-6">
 292                 <h2>BLUE it!</h2>
 293                     <div class="dummy-boy">
 294                     </div>
 295                 </div>
 296                 <div class="col-md-6">
 297                 <h2>GREEN THAT!</h2>
 298                     <div class="dummy-girl">
 299                     </div>
 300                 </div>
 301             </div>
 302         </div>
 303     </section>
 304
 305 Your new snippet is now ready to use. Just drag and drop it on your page to
 306 see it in action.
 307
 308 Advanced Customization
 309 ======================
 310
 311 Defining Your Theme Options
 312 ---------------------------
 313
 314 Understanding XPath
 315 '''''''''''''''''''
 316
 317 As your stylesheets are running on the whole website, giving more option to
 318 your snippets and applying them independently will push your design
 319 forward. In ``odoo/addons/theme_dummy/views/`` create a new file, name it
 320 ``options.xml`` and add these lines::
 321
 322     <template id="gourman_website_options_pattern" inherit_id="website.snippet_options">
 323         <xpath expr="//div[@data-option='dummy_options']//ul" position="after">
 324         </xpath>
 325     </template>
 326
 327 Explain xpath
 328 """""""""""""
 329
 330 .. TODO:: syntax not correct (see website examples)
 331
 332 Your option menu is now correctly set in the database, you can create an new dropdown menu.
 333
 334 Let's say yout want three options which will change the text color and the background.
 335 In option.xml, add these lines inside the xpath::
 336
 337       <li data-check_class="text-purple"><a>YOUR OPTION 1</a></li>
 338       <li class="dropdown-submenu">
 339           <a tabindex="-1" href="#">Your sub option</a>
 340           <ul class="dropdown-menu">
 341             <li data-select_class="bg-yellow"><a>YOUR OPTION 2</a></li>
 342             <li data-select_class="text-light-bg-dark"><a>YOUR OPTION 3</a></li>
 343             <li data-select_class=""><a>None</a></li>
 344           </ul>
 345       <li>
 346
 347 Simple less css options
 348 '''''''''''''''''''''''
 349
 350 In order to see these options in action, you have to write some new css
 351 classes. Open custom.css and add this new lines
 352
 353 .. code-block:: css
 354
 355     @color-purple: #2ecc71;
 356     @color-yellow: #2ecc71;
 357
 358     .text-purple { color: @color-purple; }
 359     .bg-yellow { background-color: @color-yellow;}
 360     .text-light-bg-dark { color: #eee; background-color: #222;}
 361
 362 Refresh the page. Select a snippet and click Customize. Choose one of your new
 363 options apply it.
 364
 365 XPath & inherits
 366 ''''''''''''''''
 367
 368 You can also add images in your variables and use them on certain part of your
 369 pages, snippets or any html element.
 370
 371 In :file:`odoo/addons/theme_dummy/static/style/custom.css` add these new lines
 372
 373 .. code:: css
 374
 375     @bg-01: url("../img/background/bg-blur.jpg");
 376
 377     .bg-01 {
 378         background-image: @bg-01;
 379     }
 380
 381 Now that you have set the background image, you can decide how and where the
 382 user can use it, for example, on a simple div.
 383
 384 Open :file:`odoo/addons/theme_dummy/views/options.xml` and add this new xpath::
 385
 386   <xpath expr="//div[@data-option='background-dummy']//ul" position="after">
 387       <ul class="dropdown-menu">
 388           <li data-value="bg-01">
 389               <a>Image 1</a>
 390           </li>
 391       </ul>
 392   </xpath>
 393
 394 Your option is ready to be applied but you want it to be shown only a certain
 395 part of a snippet.
 396
 397 Open :file:`odoo/addons/theme_dummy/views/snippets.xml` and add a new snippet
 398 with the method we learned previously::
 399
 400     <xpath expr="//div[@id='snippet_structure']" position="inside">
 401         <div>
 402         <!-- Add a Thumbnail in the Website Builder drop-down menu -->
 403             <div class="oe_snippet_thumbnail">
 404                 <img class="oe_snippet_thumbnail_img" src="/theme_Dummy/static/img/blocks/block_title.png"/>
 405                 <span class="oe_snippet_thumbnail_title">Test OPTION</span>
 406             </div>
 407         <!-- Your Snippet content -->
 408             <section class="oe_snippet_body fw_categories">
 409                 <div class="container">
 410                     <div class="row">
 411                         <div class="col-md-6 text-center mt32 mb32">
 412                             <h2>NO OPTION</h2>
 413                             <p>OFF</p>
 414                         </div>
 415                         <div class="col-md-6 text-center mt32 mb32 test-option">
 416                             <h2>OPTION</h2>
 417                             <p>This div has the 'test-option' class</p>
 418                         </div>
 419                     </div>
 420                 </div>
 421             </section>
 422         </div>
 423     </xpath>
 424
 425 As you see, the second ``col-md`` has a class named ``test-option``.  We are
 426 going to specify where this option can be turned on by adding the
 427 ``data-selector`` attribute.
 428
 429 Go back to your ``options.xml`` files, add these new lines::
 430
 431   <xpath expr="//div[@data-option='background-dummy']" position="attributes">
 432       <attribute name="data-selector">test-option</attribute>
 433   </xpath>
 434
 435 Refresh your browser. You should now be able to add your image background on
 436 the left div only.  The option is now available on each section but also on
 437 the left div with the custom class.
 438
 439 The Image Database
 440 ------------------
 441
 442 Modifying the image database
 443 ''''''''''''''''''''''''''''
 444
 445 Odoo provides its own image library but you certainly want to adapt it to your
 446 design.  Do not use the Media Manager uploading Tool to add image in your
 447 theme. The images url's will be lost on reload!  Instead of uploading your
 448 images, you can create your own library and disable the old ones.
 449
 450 In ``odoo/addons/theme_dummy/views/`` create a new file, name it
 451 ``images.xml`` and add these lines::
 452
 453   <record id="image_bg_blue" model="ir.attachment">
 454       <field name="name">bg_blue.jpg</field>
 455       <field name="datas_fname">bg_blue.jpg</field>
 456       <field name="res_model">ir.ui.view</field>
 457       <field name="type">url</field>
 458       <field name="url">/theme_clean/static/img/library/bg/bg_blue.jpg</field>
 459   </record>
 460
 461 Your images is now available in your Media Manager.  And your Theme has a
 462 total new look.
 463
 464 Theme Selector
 465 ==============
 466
 467 Set Up
 468 ------
 469
 470 Understanding theme variants
 471 ''''''''''''''''''''''''''''
 472
 473 Combining theme variants
 474 ''''''''''''''''''''''''