• Join Now
  • Sign In
  • Cart
  • Instant Setup
  • Download
Logo
  • About
    • For Developers
    • For Agencies
    • For Designers
    • For Anyone
    • Testimonials
    • Showcase
    • Our Philosophy
    • Blog
    • Instant Setup
  • Community
    • Members
    • Forums
    • Chat
    • Karma
    • International
    • Jobs
    • eNewsletters
  • Developers
    • Download concrete5
    • Join Beta Team
    • Translate concrete5
    • Bug Tracker
    • Submit to Marketplace
    • Code Submissions
    • News
    • Community Leaders
    • Related Projects
  • Marketplace
    • Add-Ons
    • Themes
    • Hosting
    • Training
    • Add-on Installation
    • Deal Of The Day
    • Swag
  • Enterprise
  • Documentation
    • Getting Started
    • Editor's Guide
    • Learn concrete5
    • Developers Index
    • How-Tos
  • How-Tos

Change Things Without Hurting Anything : Overrides

Posted byGregJoyce in Developers on Nov 15, 2011.
24 people like this.

Generally, changing the look and feel of the user experience in concrete5 is possible either through creating new pages in your theme or adding templates for the different blocks your page uses. Here are some good resources on creating templates:

  • This how to,
  • Another how to
  • and this forum post

Why Override?

Sometimes, you need to change a page type or single page that is included in a package or part of core. Other times, it just isn't enough to change how something looks: you need to have extra data fields, or you want to do different calculations on some data. In this case the best choice is to use concrete5's override feature.

Creating an override is a way to change one part of an add-on or the base CMS without modifying any files that are in the core folder or the add-on's folder. This way, it is possible to perform an update without losing your changes.

Possibly the best reason: if you look in your site's environment info on the dashboard, you will see a list of all overrides. This will let you know at a glance where you have changed things, which is much more helpful than having to dig through your site, remembering all your changes.

Basic Override Structure

The basic override structure works like this: Copy any file in your [site root]/concrete/ or [site root]/packages/packaged_add_on/ folder --where packaged_add_on is the name of the package-- up to its equivalent path in your site root.  Concrete5 will now use this file in favor of the one in its default location.   

Two simple override examples:

core functionality: public_html/concrete/single_pages/login.php --> public_html/single_pages/login.php

NOTE for concrete 5.6 and later: You will notice that if you copy any kind of model, library, etc. up, the contents of the class will be blank. You can add any new functions you need. The original version will be in concrete/core/(model, libraries, etc) if you need a reference for what you're extending.

See the following how-to for more information:
Overriding Core Files and Extending Core Classes in concrete5.6 and later

package functionality: public_html/packages/packaged_add_on/models/some/data/model.php --> public_html/models/some/data/model.php

 

That's it.  Now you can upgrade both concrete5's core and any add-on and your modified code will still be in place.  Keep in mind your modifications will not always be compatible with upgrades, so it is a good idea to set up a stage copy of your site, move your customizations out of the way temporarily, test the upgrade, then move them back in place to test before upgrading your live site.

Exceptions To The Rule

1. Helpers

Helper files do not override like regular files. When you copy them up you need to rename the class with "Site" prefixed. So concrete/helpers/url.php you would copy up to helpers/url.php but then class UrlHelper becomes class SiteUrlHelper in the class declaration at the top of the file.

2. Packaged Tools

To override a packaged tool the tool needs to be moved into folder with the add-on's name. So if you have a package in packages/add_on/ you will copy packages/add_on/tools/some_tool.php up to tools/some_tool.php and make your changes there.

3.Themes

You can not override a theme by copying the theme from its packaged directory up to the themes/ folder. If you modify a theme's description.txt you can install it as a new theme from your dashboard. Also, a page within your active theme will take precedence over one within your site's page_types/ folder. So for example, putting something in page_types/default.php will have no effect on your site.

4. Package Elements

Packaged elements do not override right now. The reason you would need to override an element would be the case where you might have a view.php that looks like this:

 <div class="first_thing">
 Loader::packageElement('some_element','add_on');
 </div>
 <div class="second_thing">
 Loader::packageElement('other_element','add_on');
 </div>

Elements and package elements are both very useful because they let you reuse code, and if you change some data display in that one file you can reference it anywhere else and it will show up identically without rewriting anything. However, this is frustrating when you do not want to it to look the same in a certain place.

The bad option here is to create a template for your block, or override the page_type /single_page and actually paste all of the code from that element into your view at the line where the element is called. This will make your file big and messy which elements are meant to avoid.

Using the view above as an example, we are going to "override" 'some_element' by not using it anymore. Create override the page or create a template for the block and then change the line

 Loader::packageElement('some_element','add_on');

to be

 Loader::element('my_some_element');

Now your custom view will no longer be looking for the element inside the packages/ folder, which is what we want anyway. Everywhere else the add-on is used, it will be pulling in the default element.

Now copy packages/add_on/elements/some_element.php/ up to elements/my_some_element.php. That file will be used by your template / page override instead. Any edits you make here won't be reflected anywhere else.

This technique is useful for modifying complicated add-ons such as the eCommerce add-on without messing with any of its core functionality, allowing you to upgrade without any problems.

For more information on this technique, check out this example in the eCommerce documentation.

How-To Tags

controller, templates, Model, overrides, view

Related How-Tos

None.

  • Documentation
  • How-Tos
  • Developers
  • Change Things Without Hurting Anything : Overrides

Do you have questions

  • What are users saying?
  • Who is using concrete5?
  • What makes concrete5 easy?
  • Why develop on concrete5?
 

We’re on “The Twitter”

RT @concrete5: Check out the new lower prices on 3 of the #concrete5 Core Team add-ons. And 2 more are now Free. http://t.co/suCKapEfQd

Follow concrete5

About

  • For Developers
  • For Agencies
  • For Designers
  • For Anyone
  • Testimonials
  • Showcase
  • Our Philosophy
  • Blog
  • Instant Setup

Community

  • Members
  • Forums
  • Chat
  • International
  • Jobs
  • eNewsletters

Developers

  • Download concrete5
  • Join Beta Team
  • Translate concrete5
  • Bug Tracker
  • Beta
  • Submit to Marketplace
  • Code Submissions
  • News
  • Community Leaders
  • User Doc Group
  • Related Projects

Marketplace

  • Add-Ons
  • Themes
  • Hosting
  • Training
  • Add-on Installation
  • Deal Of The Day
  • Swag

Documentation

  • Getting Started
  • Editor's Guide
  • Learn concrete5
  • Developers Index
  • How-Tos

Legal

  • Privacy Policy
  • Terms of Use
  • Refund Policy
  • Contact Us
© 2008 to 2013 Concrete CMS Inc. All Rights Reserved.

Sign In?

You must have a user account and be signed to perform this action.

  • Sign In
  • Register