Package er.taggable

ERTaggable is a fairly direct port of the acts_as_taggable Rails mixin to EOF, the framework provides a very easy method of integrating delicious-style tagging support into arbitrary entities in your applications.

See: Description

Interface Summary

Interface	Description
ERTagNormalizer	ERTagNormalizer provides an interface for processing tags to clean them up prior to persisting them.

Class Summary

Class	Description
ERDefaultTagNormalizer	ERDefaultTagNormalizer trims and lowercases all tags.
ERTaggable<T extends ERXGenericRecord>	ERTaggable provides a wrapper around a taggable EO, extending it with tagging-related methods.
ERTaggableEntity<T extends ERXGenericRecord>	ERTaggableEntity provides entity-level tag management and fetching methods.
ERTaggablePrincipal	ERTaggable Framework Principal

Package er.taggable Description

ERTaggable is a fairly direct port of the acts_as_taggable Rails mixin to EOF, the framework provides a very easy method of integrating delicious-style tagging support into arbitrary entities in your applications.

Quick Start

Lets take the example where your model "MyModel" has a "Person" entity that you want to support tagging on.

1. Create a migration using the helper superclass:

   public class MyModel0 extends ERTaggableEntity0 {
           public MyModel0() {
                   super(Person.ENTITY_NAME);
           }
   }
                   

2. Register the taggable in your Application constructor or framework principal:

   ERTaggableEntity.registerTaggable(Person.ENTITY_NAME);
                   

3. Add convenience methods onto your Person class (optional, but handy):

   public ERTaggable<Person> taggable() {
           return ERTaggable.taggable(this);
   }
   
   public static ERTaggableEntity<Person> taggableEntity() {
           return ERTaggableEntity.taggableEntity(Person.ENTITY_NAME);
   }
       

4. Tag like the wind:

   Person mike = Person.createPerson(editingContext, "Mike Schrag");
   ERTaggable<Person> taggableMike = mike.taggable();
   taggableMike.addTags("mike employee important");
   
   NSArray<Person> matchingPeople = Person.taggableEntity().fetchTaggedWith(editingContext, "employee");
           
   NSDictionary<EOEntity, NSArray<? extends ERXGenericRecord>> matchingItems = ERTaggableEntity.fetchAllTaggedWith(editingContext, "mike");
                   

Nitty Gritty

If you choose to deviate from the "magical" route described above, you can provide several override hooks:

• By default all entities share the same corpus of tag names. For any entity, you can register a custom ERTag subclass that stores in a separate table instead. This is generally only an issue if you need to provide tag completion and you want to restrict the set of completion offerings. Note that hooking to a custom ERTag table also requires that you use the optional constructor on the migration superclass to specify the name of that entity.
• By default, tags are normalized by trimming and lowercasing them. You can override the tag normalizer that is used by setting it on your ERTaggableEntity.
• You MUST register your taggable entities prior to attempting any tagging operations. The framework will throw an exception scolding you if you do not.
• By default, your EOModels are modified on-the-fly to inject tagging support into them. If you don't like magic, you can instead manually create the join entity between your entity and the ERTag entity. You MUST also create a flattened to-many relationship from your entity to the ERTag table through your join entity. If you name that relationship anything other than "tags" (or you use a custom ERTag entity), you must specify the relationship name when you register the entity.
• Tags are unique and shared. To ensure this, ERTag commits new tag names in a separate transaction. This can lead to a potentially undesirable (yet mostly harmless) side effect where new tag names may be committed even though you roll back your editing context. Only tag names have this behavior, not tag relationships on your entities.
• If you don't want to use the migration, you need to create a join table that contains a "your entity id" (named item_[your pk column name] for each pk attribute) and an ERTagID foreign key (named tag_id). You can name the columns whatever you want if you also manually create the join entity in your EOModel.