Best way to include CSS/JS files in my custom extension

Question

If I need to include CSS or JS files in my custom extensions, what would be the best and safest way to achieve this:

1. Should I put them i a specific folder in my extension zip file?
2. How should I declare the files in my XML manifest?
3. How do I include the files in the Joomla header (only when needed)?

Answer 1

The best way would be to use the media folder. So, you will firstly need to create a folder called media in your module folder.

Note: This folder should be created before installing, not after.

The inside the media folder, create 2 sub folders, css and js. This isn't required but it's just nicer to keep things separate.

Then add the following to your XML file:

<media folder="media" destination="mod_EXAMPLE">
    <folder>css</folder>
    <folder>js</folder>
</media>

Change mod_EXAMPLE to whatever your module is.

Upon installation, the media folder will automatically be moved and you will end up with the following:

JOOMLA_ROOT/media/mod_EXAMPLE/js

and

JOOMLA_ROOT/media/mod_EXAMPLE/css

I know so far I have been referring to a module but the same applies for components too.

To call the file, you can add the following code to your default.php file for your extension:

JHtml::_('stylesheet', JUri::root() . 'media/mod_EXAMPLE/css/style.css');  // For CSS files
JHtml::_('script', JUri::root() . 'media/mod_EXAMPLE/js/script.js');       // For JS files

Hope this helps

Answer 2

1. I assume that your extension is a component. The best way is to create a media directory beside admin and site directories. Then put js, css and img files inside separate directories like this:

   index.html
   YOUR_COMPONENT_NAME.xml
   [+] admin
   [+] site
   [-] media
      [-] js
         main.js
         index.html
      [+] css
      [+] img
   

   Note that any folder should have an empty index.html file.

2. In your XML manifest (YOUR_COMPONENT_NAME.xml), you can declare media file like this:

   <media destination="com_YOUR_COMPONENT_NAME" folder="media">
       <filename>index.html</filename>
       <folder>css</folder>
       <folder>js</folder>
       <folder>img</folder>
   </media>
   

3. Edit the default view (default.php) and add these lines to include the files in the Joomla! head:

   $document = JFactory::getDocument();
   $document->addStyleSheet(JUri::base() . 'media/com_YOUR_COMPONENT_NAME/css/main.css');
   $document->addScript(JUri::base() . 'media/com_YOUR_COMPONENT_NAME/js/main.js');
   $test_image_url = JUri::base() . 'media/com_YOUR_COMPONENT_NAME/img/test.jpg';