Scald CR(U)D

Scald Atom Shorthand ( SAS )

The SAS version of an atom is the way we use the filtering system to put atoms in textarea:
Any instance of Scald Atom Shorthand (SAS) will be replaced with a rendered Scald Atom. SAS can take any of the following formats: [scald=SID], [scald=SID:context], or [scald=SID:context context-options]. SID is the Scald ID, context is a context-slug, and context-options are additional formatting clues to give to the Context.
Without a Wysiwyg you can include Scald Atom Shorthand such as [scald=12]

Scald Actions and licences

Scald Actions are defined arbitrarily. The possible Actions that a given User can perform on a given Atom are determined by Action bitstrings. Each action has a position (arbitrarily-defined) in the bitstring. Due to PHP limitations, there is an upper bound of 31 Actions. The high bit in any actions Bitstring is the "admin bit" which, when set, means that the comparison is "OR", rather than "AND". Typically a user's Action bitstring (which is an OR-ing of all the Role Action bitstrings which the User is a part of) is AND-ed with the Atom's Action bitstring. However, if the Admin Bit is set, then a user's Action bitstring is *OR*-ed with the Atom's Action bitstring. Careful assignment of Action bitstrings to roles and roles to users should result in a fairly complete set of possibilities.

Scald Display contexts and rendering

Scald Core implements an input filter to allow for the inclusion of Scald Atoms in textareas in Drupal. When defining an input format, care should be taken to ensure that the rendered Scald Atoms (probably rendered in XHTML) are not subsequently processed into oblivion by other input filters. In other words, make sure that the Scald Atom Shorthand (SAS) Filter is *after* filters which strip tags.
The display context are defined thru the hook hook_scald_contexts. We define some in the library module like per example:

Loading Scald atoms in code

Loading atoms can be done with the scald_atom_load($sid) function, where $sid is the entity id of the Scald Atom Entity. The returned object will have all the attributes of the atom, including the title.
The scald_atom_load function will take permissions into account, and will not load the atom if the current user does not have access permissions to the atom.
The base_entity and base_id attributes usually contains the file object and the file id for file based providers. However generally providers can store anything in those attributes.

Scald hooks available to other modules

hook_scald_fetch
Used in scald_fetch(), we get the entity from the database then we have the provider put the default information thru this hook.

hook_scald_prerender
We initialize the $atom object in scald_prerender() then we pass it thru:

Comments

Scald Actions are defined arbitrarily. The possible Actions that a given User can perform on a given Atom are determined by Action bitstrings. Each action has a position (arbitrarily-defined) in the bitstring. Due to PHP limitations, there is an upper bound of 31 Actions. The high bit in any actions Bitstring is the "admin bit" which, when set, means that the comparison is "OR", rather than "AND". Typically a user's Action bitstring (which is an OR-ing of all the Role Action bitstrings which the User is a part of) is AND-ed with the Atom's Action bitstring. However, if the Admin Bit is set, then a user's Action bitstring is *OR*-ed with the Atom's Action bitstring. Careful assignment of Action bitstrings to roles and roles to users should result in a fairly complete set of possibilities.

I've been looking into this for a project and learned some, so hope to help out. This is somewhat complicated, but at a high level what happens is that each atom has the possibility of 4 actions by default - Fetch, Edit, View and Delete. Providers can define additional actions to allow, which then trickle down to the permissions system. The combination of actions that an individual atom has available is stored in the scald_atoms table as an integer (using bitmasking (you can search Stack Overflow or just google this for a deeper understanding).

Now, each atom can be given a default set of "Openly Available Actions" on the /admin/structure/scald/[atom_type] page. Each atom created from that point on will get that set of actions set. This can be overridden on a per-atom basis though, so you can (if you have permission) edit the atom, open it up to deletion, for instance, and then any user who can "Delete any atom marked as Deletable" can then delete it.

The admin portion of the description above is basically saying that anyone with a permission to edit ANY atom will always get that option. I may be mistaken on exactly how this part works, but that should give you a better interpretation of this admittedly cryptic description of the Scald actions system.

I would just update the docs, but would like some sort of validation from the Scald team whether this is an accurate description or not. I'm sure it could be improved, certainly from its current form above...