Create a new Joomla! Category

After instantiating the object, you only need to call the create method, by passing:

  • the Content Type you wish to use: 'category', 'blog_category', or any other content type based on the Joomla! Category Object
  • an array of properties $data for your Content Item.
$content = new JCckContentCategory;
$data      = array(
                      'parent_id'=>2,
                      'published'=>1,
                      'title'=>'My Category 01'
                  );
$content->create( $content_type, $data );

You've just created your 1st Category using JCckContent !

$content = new JCckContentCategory;
$data      = array(
                      'parent_id'=>2,
                      'published'=>1,
                      'title'=>'My Category 01'
                  );

if ( $content->create( $content_type, $data )->isSuccessful() ) {
    // Do something
    echo $content->getPk();
}

Assuming you need to execute some custom code after creating a category, you should make sure everything went ok before doing it.
Calling the getPk method will return the newly created Primary Key (of the "base" table).

$content = new JCckContentCategory;
$data      = array(
                      'parent_id'=>2,
                      'color'=>'blue',
                      'snippet'=>'Lorem ipsum dolor sit amet, consectetur adipiscing elit.',
                      'published'=>1,
                      'title'=>'My Category 01'
                  );

if ( $content->create( $content_type, $data )->isSuccessful() ) {
    // Do something
}

Creating a category with both standard properties and custom properties is as easy as [eating a] pie.
You just need to complete the $data array with the column names of your custom fields, without specifying to which table instance they actually belong. JCckContent will automatically dispatch the properties across the suitable table instances.

Additional note: the create method will keep a static version of the object, in case it needs to be reused later on.



Load an existing Joomla! Category

Various calls of the static method getInstance give you the ability to load an existing Category. Argument depends of the class used.

$content = JCckContentCategory::getInstance( $pk );

OR

$content = JCckContent::getInstance( array( 'joomla_category', $pk ) );

OR

$content = JCckContent::getInstance( $id );

All the above is identical, but the 1st one is the most straightforward. Using the subclass, simply pass the Primary Key of your category, as the Object is already known (in opposition of the 3rd one which takes the SEBLOD IDentifier).


Additional note: the getInstance method will keep a static version of the object, in case it needs to be reused later on.
It means that if you call again a getInstance with a known identifier, it will return the object directly without reloading everything.

$content = new JCckContentCategory;
$content->load( $pk );

An alternative way of loading a Content Item is to use the load method, after instantiating the object.
This can be useful to load items within a loop, or when you need to call more than one "starting" method from a single place.

Additional note: the load method doesn't keep a static version of the object, neither uses a static version while loading an item.

if ( !$content->isSuccessful() ) {
    return;
}
// Do something

OR

if ( $content->isSuccessful() ) {
    // Do something
}

After loading an item, you may need to execute some custom code. It may not always be needed (depending on what you'll do next), but we recommend to make sure everything went ok before continuing (cf above).
So what should you do next ?

// Do something
echo $content->getProperty( 'title' );

You could retrieve the title of your Category.

// Do something
echo $content->getProperty( 'parent_id' );

You could retrieve another standard property (from the "base" table)...

// Do something
echo $content->getProperty( 'snippet' );

... or any other custom property (from any other table instance).

Additional resources:  List of all "get" and "set" methods



Delete an existing Joomla! Category

One call of the  delete method will remove everything related to the Category.

$content->delete();

Assuming you have already loaded an Content Item in the previous section, that is all you need !

$content = new JCckContentCategory;
$content->delete( $pk );

If you start from nothing, after instantiating the object, make sure to pass the Primary Key of the Category you wish to delete.



Update an existing Joomla! Category

After loading an existing item, updating it will consist most of the time in calling both the  setProperty method (once or more than once), and then the store method. As JCckContent class supports method chaining, you can chain all calls.

$content->setProperty( 'title', 'My Title' )
             ->setProperty( 'snippet', 'My Snippet' )
             ->store();

This will set (or change) the value of two properties within the current instance, and then update the DB.

Additional note: the store method will actually call the store function of each table instance (where properties have been changed).

if ( $content->setProperty( 'title', 'My Title' )->store() ) {
    // Ok

For now, all methods performing an update (in DB) of an existing content item DO NOT support method chaining. So you can't use the isSuccessful method to test if everything went ok, you will need to test the return of the store method (boolean: true/false).



Update an existing Joomla! Category: object-specific tasks

After loading an existing item, some specific tasks are available through the  call method. For the Joomla! Category object:

  • tag
  • untag
  • updateAlias
$content->dump( 'callable' ); @ SEBLOD 3.16.1

You can easily verify which tasks are available with this call.

Additional resources: Various debugging methods

tag

if ( $content->call( 'tag', $tag_id )->isSuccessful() ) {
    // Ok
}

OR

if ( $content->call( 'tag', $tag_ids )->isSuccessful() ) {
    // Ok
} @ SEBLOD 3.16.1

This will simply tag the content item with one (int) or many (array) tags. Existing tags are kept.

if ( $content->call( 'tag', $tag_id, true )->isSuccessful() ) {
    // Ok
}

OR

if ( $content->call( 'tag', $tag_ids, true )->isSuccessful() ) {
    // Ok
} @ SEBLOD 3.16.1

This will simply tag the content item with one (int) or many (array) tags. Existing tags are removed.

untag

if ( $content->call( 'untag', $tag_id )->isSuccessful() ) {
    // Ok
}

OR

if ( $content->call( 'untag', $tag_ids )->isSuccessful() ) {
    // Ok
} @ SEBLOD 3.16.1

This will simply untag one (int) or many (array) tags.

if ( $content->call( 'untag' )->isSuccessful() ) {
    // Ok
@ SEBLOD 3.16.1

This will simply untag all tags associated with the content item.

updateAlias
if ( $content->setProperty( 'title', 'My New Title' )->store() ) {
    $content->call( 'updateAlias' ); 
@ SEBLOD 3.17.0

After updating the title of your Category, you may need to update the alias accordingly. The above will do it for you.