Difference between revisions of "Silme:Tutorial:Entity"
Zbraniecki (talk | contribs) |
Zbraniecki (talk | contribs) |
||
| (6 intermediate revisions by the same user not shown) | |||
| Line 8: | Line 8: | ||
<code lang="python"> | <code lang="python"> | ||
| − | from | + | from silme.core import Entity |
entity = Entity('id','value') | entity = Entity('id','value') | ||
| Line 19: | Line 19: | ||
<code lang="python"> | <code lang="python"> | ||
| − | from | + | from silme.core import Entity |
entity = Entity('id','value') | entity = Entity('id','value') | ||
| − | entity. | + | entity.params['author'] = 'Ben' |
| − | |||
</code> | </code> | ||
| Line 31: | Line 30: | ||
<code lang="python"> | <code lang="python"> | ||
| − | from | + | from silme.core import Entity, EntityList |
| − | + | entitylist = EntityList() | |
entity1 = Entity('example.id','Test value') | entity1 = Entity('example.id','Test value') | ||
| − | + | entitylist.add_entity(entity1) | |
entity2 = Entity('example.id2','Test value2') | entity2 = Entity('example.id2','Test value2') | ||
| − | + | entitylist.add_entity(entity2, pos=0) # second argument allows you to define on which position an entity should be added | |
</code> | </code> | ||
| Line 45: | Line 44: | ||
<code lang="python"> | <code lang="python"> | ||
| − | from | + | from silme.core import EntityList |
| − | + | entitylist = EntityList() | |
| − | entity1 = | + | entity1 = entitylist[0] # returns a first entity from the list |
| − | entities = | + | entities = entitylist.get_entities() # returns a list of entities |
| − | + | entity_id_list = entitylist.get_entity_ids() # returns a list of ids from the entitylist | |
</code> | </code> | ||
| Line 59: | Line 58: | ||
<code lang="python"> | <code lang="python"> | ||
| − | from | + | from silme.core import EntityList |
| − | + | entitylist = EntityList() | |
| − | + | entitylist.change_entity('entity id', 'new value') | |
| − | + | entitylist.remove_entity('entity id') | |
</code> | </code> | ||
| − | + | You may assume that the functionality of the Entity and EntityList classes is very basic. Later you'll notice that it makes the use of the library much easier. | |
| − | == Advanced == | + | An important difference between having a list of Entity objects and having an EntityList object is that in case of EntityList you may define parameters that are defined for the whole list. Another reason is that you may use, and it's preferred, a set of methods to manipulate on the list instead of touching the list directly. The last one is that your code will stay untouched if we'll switch to dictionary as a base class for EntityList in the future. |
| + | |||
| + | == Example == | ||
| + | |||
| + | Below is a bit more complex example of using those two classes | ||
| + | |||
| + | <code lang="python"> | ||
| + | from silme.core import Entity, EntityList | ||
| + | |||
| + | entitylist = EntityList() | ||
| + | |||
| + | entity1 = Entity('myproject.id1', 'This is an example message') | ||
| + | entity2 = Entity('myproject.title', 'App title') | ||
| + | entity2.params['type'] = 'Window title' | ||
| + | |||
| + | entitylist.add_entity(entity1) | ||
| + | entitylist.add_entity(entity2) | ||
| + | |||
| + | for entity in entitylist: | ||
| + | print entity.value | ||
| + | |||
| + | entitylist.change_entity('myproject.id1', 'Changed entity') | ||
| + | entitylist.remove_entity('myproject.id1') | ||
| + | </code> | ||
| + | |||
| + | |||
| + | == Advanced topics == | ||
You may decide to extend Entity class or just add your own properties to the Entity object. | You may decide to extend Entity class or just add your own properties to the Entity object. | ||
| + | |||
| + | It would benefit performance and code sleekness to assume that the ID is unique across an EntityList, but the reality is different | ||
Latest revision as of 11:54, 13 February 2009
Contents
Entity
The basic unit we use in the localization world is an entity. Entity is a simple object made of ID and a value. ID is a somehow unique identifier of the entity, and the value is an actual string that you want to present to the user.
In Verbatim creating a new Entity looks like this:
from silme.core import Entity
entity = Entity('id','value')
This simple object is the most atomic unit in every localization format, be it DTD, Gettext, XLIFF or L20n. It's an abstract representation of a row in the l10n array in SQL or it represents a single string in HTML file (in this case ID has to be a unique identifier of the string position in the file).
Of course Entity may be much more complex than that. In some cases you can have a meta data for the single entity, or a comment that is tied to the entity. Because of how popular those two cases are among l10n formats, Entity object has predefined dictionary objects for those two:
from silme.core import Entity
entity = Entity('id','value')
entity.params['author'] = 'Ben'
EntityList
EntityList is a simplest possible class used to store the sequence of entities.
from silme.core import Entity, EntityList
entitylist = EntityList()
entity1 = Entity('example.id','Test value')
entitylist.add_entity(entity1)
entity2 = Entity('example.id2','Test value2')
entitylist.add_entity(entity2, pos=0) # second argument allows you to define on which position an entity should be added
You can operate on the EntityList to get either all Entities as a new list or just ids of the entities as a new list
from silme.core import EntityList
entitylist = EntityList()
entity1 = entitylist[0] # returns a first entity from the list
entities = entitylist.get_entities() # returns a list of entities
entity_id_list = entitylist.get_entity_ids() # returns a list of ids from the entitylist
If you want, you can also change entity or remove it:
from silme.core import EntityList
entitylist = EntityList()
entitylist.change_entity('entity id', 'new value')
entitylist.remove_entity('entity id')
You may assume that the functionality of the Entity and EntityList classes is very basic. Later you'll notice that it makes the use of the library much easier.
An important difference between having a list of Entity objects and having an EntityList object is that in case of EntityList you may define parameters that are defined for the whole list. Another reason is that you may use, and it's preferred, a set of methods to manipulate on the list instead of touching the list directly. The last one is that your code will stay untouched if we'll switch to dictionary as a base class for EntityList in the future.
Example
Below is a bit more complex example of using those two classes
from silme.core import Entity, EntityList
entitylist = EntityList()
entity1 = Entity('myproject.id1', 'This is an example message')
entity2 = Entity('myproject.title', 'App title')
entity2.params['type'] = 'Window title'
entitylist.add_entity(entity1)
entitylist.add_entity(entity2)
for entity in entitylist:
print entity.value
entitylist.change_entity('myproject.id1', 'Changed entity')
entitylist.remove_entity('myproject.id1')
Advanced topics
You may decide to extend Entity class or just add your own properties to the Entity object.
It would benefit performance and code sleekness to assume that the ID is unique across an EntityList, but the reality is different
